rework to optimize a bit, again for bug #3172
[bioperl-live.git] / README
blob9948736d43ec3b7861e6b6e268b44e745590b7de
1 # $Id$
3 This is the README file for the BioPerl central distribution.
5 o Version  
7  This is bioperl-live, from the BioPerl GitHub master branch 
9 o Getting Started
11  Thank you for downloading this distribution!
13  Please see the the INSTALL or INSTALL.WIN documents for installation
14  instructions.
16  For tutorials see the BioPerl Tutorial.pl
17  (http://www.bioperl.org/wiki/Bptutorial.pl) or the HOWTO documents
18  and tutorials online at http://bioperl.org. To look at example code
19  browse the scripts/ and examples/ directories
21  For people starting out with Perl and BioPerl, look at the Bio::Perl
22  module (go "perldoc Bio::Perl" from within this directory). This
23  module is designed to flatten the learning curve for newcomers.
25  For a list of OS's and versions that are known to support BioPerl see
26  the PLATFORMS file.
28  For info on BioPerl read on!
30 o About BioPerl
32  BioPerl is a package of public domain Perl tools for computational
33  molecular biology.
35  Our website, http://bioperl.org/, provides an online resource of
36  modules, scripts, and web links for developers of Perl-based software
37  for life science research.
39 o Contact info
41  BioPerl developers: bioperl-l@bioperl.org
43  There's quite a variety of tools available in BioPerl, and more are
44  added all the time. If the tool you're looking for isn't described in
45  the documentation please write us, it could be undocumented or in
46  process.
48  Project website : http://bioperl.org/
50  Project FTP server : bioperl.org (anonymous FTP ok)
52  Bug reports : https://redmine.open-bio.org/projects/bioperl/
54      Please send us bugs, in particular about documentation which you
55      think is unclear or problems in installation. We are also very
56      interested in functions which don't work the way you think they
57      do!
59  Please see the AUTHORS file for the complete list of BioPerl
60  developers and contributors.
62 o About the directory structure
64  The BioPerl directory structure is organized as follows:
66    - Bio/ - BioPerl modules
68    - models/ - DIA drawing program generated OO UML for BioPerl classes
69          (these are quite out-of-date)
71    - t/ - Perl built-in tests
72          tests are divided into subdirectories generally based on the
73          specific classes being tested
75    - t/data/ - Data files used for the tests
76          provides good data examples for those new to bioinformatics data
78    - scripts/ - Useful production-quality scripts with POD documentation
80    - examples/ - Scripts demonstrating the many uses of BioPerl
82    - maintenance/ - BioPerl housekeeping scripts
84 o Documentation
86  The BioPerl Tutorial (http://www.bioperl.org/wiki/Bptutorial.pl)
87  contains useful information for new and existing BioPerl users. This
88  file also contains a number of useful scripts that the student of
89  BioPerl may want to examine.
91  Individual *.pm modules have their own embedded POD documentation as
92  well. A complete set of hyperlinked POD, or module, documentation is
93  available at http://www.bioperl.org/.
95  Remember that 'perldoc' is your friend. You can use it to read any
96  file containing POD formatted documentation without needing any type
97  of translator.
99  If you used the Build.PL installation, and depending on your
100  platform, you may have documentation installed as man pages, which
101  can be accessed in the usual way.
103  There is also an online course written at the Pasteur Institute. See
104  http://www.pasteur.fr/recherche/unites/sis/formation/bioperl.
106  Useful documentation in the form of example code can also be found in
107  the examples/ and scripts/ directories. The current collection
108  includes scripts that run BLAST, index flat files, parse PDB
109  structure files, make primers, retrieve ESTs based on tissue, align
110  protein to nucleotide sequence, run GENSCAN on multiple sequences,
111  and much more! See bioscripts.pod for a complete listing.
113 o Releases
114   
115  BioPerl releases are always available from the website
116  http://www.bioperl.org/ or by FTP from ftp://bioperl.org/ (note that
117  we've had trouble with our new network setup which is not allowing
118  FTP to support passive mode properly, use http://www.bioperl.org/DIST
119  to get a listing of the distribution directory).  Each release is
120  tested with the test suite and cross-tested on a number of different
121  platforms. See the PLATFORMS file for more information on a specific
122  platform. All efforts are made to release a bug-free package, however
123  most major bugs in a release will be documented in the BUGS file. See
124  the Changes file for a listing of what features have been added or
125  what APIs have changed between releases.
127  BioPerl formerly used a numbering scheme to indicate stable release
128  series vs.  development release series. A release number is a three
129  digit number like 1.2.0. The first digit indicates the major release
130  - the idea being that all the API calls in a major release are
131  reasonably consistent. The second number is the release series. This
132  is probably the most important number.
134  From the 1.0 release until the 1.6 release, even numbers (1.0, 1.2
135  etc) indicated stable releases. Stable releases were well tested and
136  recommended for most uses. Odd numbers (1.1, 1.3 etc) were development
137  releases which one would only use if one were interested in the
138  latest and greatest features. The final number (e.g. 1.2.0, 1.2.1) is
139  the bug fix release. The higher the number the more bug fixes has
140  been incorporated. In theory you can upgrade from one bug fix release
141  to the next with no changes to your own code (for production cases,
142  obviously check things out carefully before you switch over).
144  The 1.6 release will be the last release series to utilize the
145  alternating 'stable'/'developer' convention. Starting immediately
146  after the 1.6 branch, we will start splitting BioPerl into several
147  smaller easier-to-manage distributions, including a developer
148  distribution for cutting-edge (in development) code, untested
149  modules, and alternative implementations.
151 o Caveats, warnings, etc
153  When you run the tests ("./Build test") some tests may issue warnings
154  messages or even fail. Sometimes this is because we didn't have
155  anyone to test the test system on the combination of your operating
156  system, version of perl, and associated libraries and other modules.
157  Because BioPerl depends on several outside libraries we may not be
158  able to test every single combination so if there are warnings you
159  may find that the package is still perfectly useful. See the
160  PLATFORMS file for reports of specific issues.
162  If you install the bioperl-run system and run tests when you don't
163  have the program installed you'll get messages like 'program XXX not
164  found, skipping tests'. That's okay, BioPerl is doing what it is
165  supposed to do. If you wanted to run the program you'd need to
166  install it first.
168  Not all scripts in the examples/ directory are correct and
169  up-to-date. We need volunteers to help maintain these so if you find
170  they do not work, submit a bug report to https://redmine.open-bio.org/projects/bioperl/
171  and consider helping out in their maintenance.
173  If you are confused about what modules are appropriate when you try
174  and solve a particular issue in bioinformatics we urge you to look at
175  the BioPerl Tutorial or the HOWTO documents first.
177 o A simple module summary
179  Here is a quick summary of many of the useful modules and how the
180  toolkit is laid out:
182  All modules are in the Bio/ namespace,
184  - Perl is for newbies and gives a functional interface to the main
185    parts of the package
187  - Seq is for Sequences (protein and DNA).
188    o Bio::PrimarySeq is a plain sequence (sequence data + identifiers)
189    o Bio::Seq is a PrimarySeq plus it has a Bio::Annotation::Collection
190      and Bio::SeqFeatureI objects attached
191      (via Bio::FeatureHolderI).
192    o Bio::Seq::RichSeq is all of the above plus it has slots for
193      extra information specific to GenBank/EMBL/SwissProt files.
194    o Bio::Seq::LargeSeq is for sequences which are too big for
195      fitting into memory.
197  - SeqIO is for reading and writing Sequences, it is a front end
198    module for separate driver modules supporting the different
199    sequence formats
201  - SeqFeature - start/stop/strand annotations of sequences
202    o Bio::SeqFeature::Generic is basic catchall
203    o Bio::SeqFeature::Similarity a similarity sequence feature
204    o Bio::SeqFeature::FeaturePair a sequence feature which is pairwise
205      such as query/hit pairs
207  - SearchIO is for reading and writing pairwise alignment reports like
208    BLAST or FASTA
210  - Search is where the alignment objects are defined
211    o Bio::Search::Result::GenericResult is the result object (a blast
212      query is a Result object)
213    o Bio::Search::Hit::GenericHit is the Hit object (a query will have
214      0 -> many hits in a database)
215    o Bio::Search::HSP::GenericHSP is the High-scoring Segment Pair
216      object defining the alignment(s) of the query and hit.
218  - SimpleAlign is for multiple sequence alignments
220  - AlignIO is for reading and writing multiple sequence alignment
221    formats
223  - Assembly provides the start of an infrastructure for assemblies and
224    Assembly::IO IO converters for them
226  - DB is the namespace for all the database query objects
227    o Bio::DB::GenBank/GenPept are two modules which query NCBI entrez
228      for sequences
229    o Bio::DB::SwissProt/EMBL query various EMBL and SwissProt
230      repositories for a sequences
231    o Bio::DB::GFF is Lincoln Stein's fast, lightweight feature and
232      sequence database which is the backend to his GBrowse system (see
233      www.gmod.org)
234    o Bio::DB::Flat is a fast implementation of the OBDA flat-file
235      indexing system (cross-language and cross-platform supported by
236      O|B|F projects see http://obda.open-bio.org).
237    o Bio::DB::BioFetch/DBFetch for OBDA, Web (HTTP) access to remote
238      databases.
239    o Bio::DB::InMemoryCache/FileCache (fast local caching of sequences
240      from remote dbs to speed up your access).
241    o Bio::DB::Registry interface to the OBDA specification for remote
242      data sources
243    o Bio::DB::Biblio for access to remote bibliographic databases.
244    o Bio::DB::EUtilities is the initial set of modules used for
245      generic queried using NCBI's eUtils.
247  - Annotation collection of annotation objects (comments, DBlinks,
248    References, and misc key/value pairs)
250  - Coordinate is a system for mapping between different coordinate
251    systems such as DNA to protein or between assemblies.
253  - Index is for locally indexed flatfiles with BerkeleyDB
255  - Tools contains many miscellaneous parsers and function for
256    different bioinformatics needs
257    o Gene prediction parser (Genscan, MZEF, Grail, Genemark)
258    o Annotation format (GFF)
259    o Enumerate codon tables and valid sequences symbols (CodonTable,
260      IUPAC)
261    o Phylogenetic program parsing (PAML, Molphy, Phylip)
263  - Map genetic and physical map representations
265  - Structure - parse and represent protein structure data
267  - TreeIO is for reading and writing Tree formats
269  - Tree is the namespace for all the associated Tree objects
270    o Bio::Tree::Tree is the basic tree object
271    o Bio::Tree::Node are the nodes which make up the tree
272    o Bio::Tree::Statistics is for computing statistics for a tree
273    o Bio::Tree::TreeFunctionsI is where specific tree functions are
274      implemented (like is_monophyletic and lca)
276  - Bio::Biblio is where bibliographic data and database access objects
277    are kept
279  - Variation represent sequences with mutations and variations applied
280    so one can compare and represent wild-type and mutation versions of
281    a sequence.
283  - Root, basic objects for the internals of BioPerl
285 o Upgrading from an older version
287  If you have a previously installed version of BioPerl on your system
288  some of these notes may help you.
290  Some modules have been removed because they have been superceded by
291  new development efforts. They are documented in the DEPRECATED file
292  that is included in the release. In addition some methods, or the
293  Application Programming Interface (API), have changed or been
294  removed. You may find that scripts which worked with BioPerl 1.4 may
295  give you warnings or may not work at all (although we have tried very
296  hard to minimize this!). Send an email to the list and we'll be happy
297  to give you pointers.