BioPerl.pm

   1 package BioPerl;
   2
   3 use strict;
   4
   5 # At some future point, when we break the current core into more maintainable
   6 # bits, this will have a direct VERSION number, but for now we will be using
   7 # the root version for everything
   8 use Bio::Root::Version;
   9
  10 our $VERSION = $Bio::Root::Version::VERSION;
  11 eval $VERSION;
  12
  13 1;
  14
  15 __END__
  16
  17 =head1 NAME
  18
  19 BioPerl - Perl Modules for Biology
  20
  21 =head1 SYNOPSIS
  22
  23 If you're new to BioPerl, you should start reading the BioPerl tutorial, an
  24 overview of the BioPerl toolkit:
  25
  26 L<http://www.bioperl.org/wiki/BioPerl_Tutorial>
  27
  28 =head2 Current Overview
  29
  30 Core Bioperl documentation has been split up into the following sections:
  31
  32 =over 3
  33
  34 =item * bioperl
  35
  36 BioPerl overview (this document)
  37
  38 =back
  39
  40 We may add more documents in the future, including:
  41
  42 =over 3
  43
  44 =item * biodatabases
  45
  46 How to use databases with BioPerl
  47
  48 =item * biodesign
  49
  50 A guide for authoring a BioPerl module
  51
  52 =item * bioscripts
  53
  54 Description and overview of BioPerl scripts (in the I</scripts> directory)
  55
  56 =back
  57
  58 =head2 Tutorials
  59
  60 =over 3
  61
  62 =item * BioPerl tutorial for beginners
  63
  64 L<http://www.bioperl.org/wiki/BioPerl_Tutorial>
  65
  66 =item * Institut Pasteur BioPerl tutorial (note: for older versions of BioPerl)
  67
  68 L<http://www.pasteur.fr/recherche/unites/sis/formation/bioperl>
  69
  70 =back
  71
  72 =head2 References for Individual Modules
  73
  74 For ease of maintenance and coordination amongst contributors, BioPerl
  75 code is maintained in a modular form, as is the documentation.  Refer to
  76 the documentation for individual modules by using perldoc, i.e.
  77
  78 C<perldoc Bio::Seq>
  79
  80 to get documentation for the Bio::Seq object.
  81
  82 =head1 DESCRIPTION
  83
  84 BioPerl is the product of a community effort to produce Perl code which is
  85 useful in biology. Examples include Sequence objects, Alignment objects and
  86 database searching objects. These objects not only do what they are advertised
  87 to do in the documentation, but they also interact - Alignment objects are made
  88 from the Sequence objects, Sequence objects have access to Annotation and
  89 SeqFeature objects and databases, Blast objects can be converted to Alignment
  90 objects, and so on. This means that the objects provide a coordinated and
  91 extensible framework to do computational biology.
  92
  93 BioPerl development focuses on Perl classes, or code that is used to create
  94 objects representing biological entities. There are scripts provided in the
  95 scripts/ and examples/ directories but scripts are not the main focus of the
  96 BioPerl developers. Of course, as the objects do most of the hard work for you,
  97 all you have to do is combine a number of objects together sensibly to make
  98 useful scripts.
  99
 100 The intent of the BioPerl development effort is to make reusable tools that aid
 101 people in creating their own sites or job-specific applications.
 102
 103 The BioPerl website at L<http://bioperl.org> also attempts to maintain links
 104 and archives of standalone bio-related Perl tools that are not affiliated or
 105 related to the core BioPerl effort. Check the site for useful code ideas and
 106 contribute your own if possible.
 107
 108 =head1 DOCUMENTATION
 109
 110 The Bio::Perl module (not this document) is designed to flatten the learning
 111 curve for newcomers to Perl/Bioperl. This is a good place to start if you want
 112 some simple functionality. We have a cookbook tutorial on-line:
 113
 114 L<http://bioperl.org/wiki/BioPerl_Tutorial>
 115
 116 which has embedded documentation. Start there if learning-by-example suits you
 117 most, or examine the BioPerl online course at:
 118
 119 L<http://www.pasteur.fr/recherche/unites/sis/formation/bioperl>
 120
 121 Make sure to check the documentation in the modules as well - there are over 900
 122 modules in BioPerl, and counting, and there's detail in the modules'
 123 documentation that will not appear in the general documentation.
 124
 125 =head1 INSTALLATION
 126
 127 The BioPerl modules are distributed as a tar file that expands into a standard
 128 perl CPAN distribution. Detailed installation directions can be found in the
 129 distribution INSTALL file. Installing on windows using ActiveState Perl is
 130 covered in the INSTALL.WIN file.  We highly suggest reading the installation
 131 instructions on the BioPerl website:
 132
 133 L<http://www.bioperl.org/wiki/Installing_BioPerl>
 134
 135 =for TODO: Do we want to add biodesign and biodatabases back in?
 136 The BioPerl modules can interact with local flat file and relational databases.
 137 To learn how to set this up, look at the biodatabases.pod documentation
 138 ('perldoc biodatabases.pod' should work once BioPerl has been installed).
 139
 140 Some BioPerl-related distributions such as Bio::Graphics, BioPerl-db,
 141 BioPerl-run, BioPerl-gui, corba-server, BioPerl-ext, BioPerl-pipeline,
 142 BioPerl-microarray and corba-client packages are installed separately from
 143 BioPerl. Please refer to their respective documentation for more information.
 144 Note that only the following are supported at this time with the current API:
 145
 146 =over 3
 147
 148 =item BioPerl-db
 149
 150 =item BioPerl-network
 151
 152 =item BioPerl-run
 153
 154 =item BioPerl-pedigree
 155
 156 =item Bio::Graphics
 157
 158 =back
 159
 160 =head1 GETTING STARTED
 161
 162 A good place to start is by reading the tutorial : L<http://bioperl.org/wiki/BioPerl_Tutorial>
 163
 164 The distribution I<scripts/> directory has working scripts for use with BioPerl,
 165 check the self-described I<examples/> directory as well. You are more than
 166 welcome to contribute your script!
 167
 168 =for TODO Should we add bioscripts back to the distributions?
 169 A list and brief description of all these scripts is found in bioscripts.pod.
 170
 171 If you have installed BioPerl in the standard way, as detailed in the INSTALL in
 172 the distribution, these scripts should work by just running them. If you have
 173 not installed it in a standard way you will have to change the 'use lib' to
 174 point to your installation (see INSTALL for details).
 175
 176 =head1 GETTING INVOLVED
 177
 178 BioPerl is a completely open community of developers. We are not funded and we
 179 don't have a mission statement. We encourage collaborative code, in particular
 180 in Perl. You can help us in many different ways, from just a simple statement
 181 about how you have used BioPerl to doing something interesting to contributing a
 182 whole new object hierarchy. See L<http://bioperl.org> for more information. Here
 183 are some ways of helping us:
 184
 185 =head2 Asking questions and telling us you used it
 186
 187 We are very interested to hear how you experienced using BioPerl. Did it install
 188 cleanly? Did you understand the documentation? Could you get the objects to do
 189 what you wanted them to do? If BioPerl was useless we want to know why, and if
 190 it was great - that too. Post a message to B<bioperl-l@bioperl.org>, the BioPerl
 191 mailing list, where all the developers are.
 192
 193 Only by getting people's feedback do we know whether we are providing anything
 194 useful.
 195
 196 =head2 Writing a script that uses it
 197
 198 By writing a good script that uses BioPerl you both show that BioPerl is useful
 199 and probably save someone elsewhere writing it. If you contribute it to the
 200 'script central' at L<http://bioperl.org> then other people can view and use it.
 201 Don't be nervous if you've never done this sort of work, advice is freely given
 202 and all are welcome!
 203
 204 =head2 Find bugs!
 205
 206 We know that there are bugs in this code. If you find something which you are pretty
 207 sure is a problem, post a bug report using our Bugzilla tracking system:
 208
 209 L<https://redmine.open-bio.org/projects/bioperl/>
 210
 211 Please read the main bug tracking (L<http://www.bioperl.org/wiki/Bugs>) for an
 212 overview of what we expect in a bug report. Specifically, having a code and
 213 data example where appropriate helps tremendously.  We gladly accept all patches
 214 after a quick code review.
 215
 216 =head2 Suggest new functionality
 217
 218 You can suggest areas where the objects are not ideally written and could be
 219 done better. The best way is to find the main developer of the module (each
 220 module was written principally by one person, except for Seq.pm). Talk to him or
 221 her and suggest changes.
 222
 223 =head2 Make your own objects
 224
 225 If you can make a useful object we will happily include it into the core.
 226 Probably you will want to read a lot of the documentation in L<Bio::Root::Root>
 227 and talk to people on the BioPerl mailing list, B<bioperl-l@bioperl.org>.
 228
 229 =for TODO Add biodesign.pod back?
 230 biodesign.pod provides documentation on the conventions and ideas
 231 used in BioPerl, it's definitely worth a read if you would like to be a BioPerl
 232 developer.
 233
 234 =head2 Writing documentation
 235
 236 We appreciate good documentation. It's what tells the world what's in BioPerl,
 237 it's what instructs the user, it's what describes the rationale and inner
 238 workings of the package. Feel free to contribute.
 239
 240 =head1 ACKNOWLEDGEMENTS
 241
 242 For a more detailed history of the BioPerl project, we recommend the History of
 243 BioPerl:
 244
 245 L<http://www.bioperl.org/wiki/History_of_BioPerl>
 246
 247 =head1 COPYRIGHT
 248
 249 Copyright (c) 1996-2009 Georg Fuellen, Richard Resnick, Steven E. Brenner, Chris
 250 Dagdigian, Steve Chervitz, Ewan Birney, James Gilbert, Elia Stupka, and others.
 251 All Rights Reserved. This module is free software; you can redistribute it
 252 and/or modify it under the same terms as Perl itself.
 253
 254 =cut