3 Please see the the `INSTALL` or `INSTALL.WIN` documents for installation
8 BioPerl is a package of public domain Perl tools for computational molecular
11 Our website (http://bioperl.org/) provides an online resource of modules,
12 scripts, and web links for developers of Perl-based software for life science
17 BioPerl mailing list: bioperl-l@bioperl.org
19 There's quite a variety of tools available in BioPerl, and more are added all
20 the time. If the tool you're looking for isn't described in the documentation
21 please write us, it could be undocumented or in process.
23 * Project website : http://bioperl.org/
25 * Bug reports : https://redmine.open-bio.org/projects/bioperl/
27 Please send us bugs, in particular about documentation which you think is
28 unclear or problems in installation. We are also very interested in functions
29 which don't work the way you think they do!
31 # The directory structure
33 The BioPerl directory structure is organized as follows:
35 * **`Bio/`** - BioPerl modules
37 * **`doc/`** - Documentation utilities
39 * **`examples/`** - Scripts demonstrating the many uses of BioPerl
41 * **`ide/`** - files for developing BioPerl using an IDE
43 * **`maintenance/`** - BioPerl housekeeping scripts
45 * **`models/`** - DIA drawing program generated OO UML for BioPerl classes
46 (these are quite out-of-date)
48 * **`scripts/`** - Useful production-quality scripts with POD documentation
50 * **`t/`** - Perl built-in tests, tests are divided into subdirectories
51 based on the specific classes being tested
53 * **`t/data/`** - Data files used for the tests, provides good example data
57 For documentation on BioPerl see the **HOWTO** documents and tutorials online at
60 Useful documentation in the form of example code can also be found in the
61 **`examples/`** and **`scripts/`** directories. The current collection includes
62 scripts that run BLAST, index flat files, parse PDB structure files, make
63 primers, retrieve ESTs based on tissue, align protein to nucleotide sequence,
64 run GENSCAN on multiple sequences, and much more! See `bioscripts.pod` for a
67 Individual `*.pm` modules have their own embedded POD documentation as well. A
68 complete set of hyperlinked POD, or module, documentation is available at
69 http://www.bioperl.org/.
71 Remember that '`perldoc`' is your friend. You can use it to read any file
72 containing POD formatted documentation without needing any type of translator
73 (e.g. '`perldoc Bio::SeqIO`').
75 If you used the Build.PL installation, and depending on your platform, you may
76 have documentation installed as man pages, which can be accessed in the usual
81 BioPerl releases are always available from the website at
82 http://www.bioperl.org/DIST or in CPAN. The latest code can be found at
83 https://github.com/bioperl.
85 * BioPerl formerly used a numbering scheme to indicate stable release series vs.
86 development release series. A release number is a three digit number like
87 `1.2.0`. The *first digit indicates the major release*, the idea being that all
88 the API calls in a major release are reasonably consistent. The *second number
89 is the release series*. This is probably the most important number. The *third
90 number is the point release* and
92 * From the **1.0 release until the 1.6 release**, even numbers (1.0, 1.2 etc)
93 indicated stable releases. Stable releases were well tested and recommended
94 for most uses. Odd numbers (1.1, 1.3 etc) were development releases which one
95 would only use if one were interested in the latest and greatest features. The
96 final number (e.g. 1.2.0, 1.2.1) is the bug fix release. The higher the number
97 the more bug fixes has been incorporated. In theory you can upgrade from one
98 bug fix release to the next with no changes to your own code (for production
99 cases, obviously check things out carefully before you switch over).
101 * The upcoming **1.7 release** will be the last release series to utilize the
102 alternating 'stable'/'developer' convention. Starting immediately after the
103 final 1.6 branch, we will start splitting BioPerl into several smaller
104 easier-to-manage distributions, including a developer distribution for
105 cutting-edge (in development) code, untested modules, and alternative
106 implementations. These will have independent versions, all likely starting
107 with v1.7.0. *We do not anticipate major API changes in the 1.7.x release
110 # Caveats and warnings
112 When you run the tests ("`./Build test`") some tests may issue warnings messages
113 or even fail. Sometimes this is because we didn't have anyone to test the test
114 system on the combination of your operating system, version of perl, and
115 associated libraries and other modules. Because BioPerl depends on several
116 outside libraries we may not be able to test every single combination so if
117 there are warnings you may find that the package is still perfectly useful.
119 If you install the bioperl-run system and run tests when you don't have the
120 program installed you'll get messages like '`program XXX not found, skipping
121 tests`'. That's okay, BioPerl is doing what it is supposed to do. If you wanted
122 to run the program you'd need to install it first.
124 Not all scripts in the `examples/` directory are correct and up-to-date. We need
125 volunteers to help maintain these so if you find they do not submit a bug report
126 to https://redmine.open-bio.org/projects/bioperl/ and consider helping out in
129 If you are confused about what modules are appropriate when you try and solve a
130 particular issue in bioinformatics we urge you to look at HOWTO documents first.
132 # A simple module summary
134 Here is a quick summary of many of the useful modules and how the toolkit is
137 All modules are in the **`Bio/`** namespace,
139 * **`Perl`** is for *new users*, and gives a functional interface to the main
140 parts of the package.
142 * **`Seq`** is for *Sequences* (protein and DNA).
143 * `Bio::PrimarySeq` is a plain sequence (sequence data + identifiers)
144 * `Bio::Seq` is a fancier `PrimarySeq`, in that it has annotation (via
145 `Bio::Annotation::Collection`) and sequence features (via `Bio::SeqFeatureI` objects, attached via
146 `Bio::FeatureHolderI`).
147 * `Bio::Seq::RichSeq` is all of the above, plus it has slots for extra information specific to GenBank/EMBL/SwissProt files.
148 * `Bio::Seq::LargeSeq` is for sequences which are too big for
151 * **`SeqIO`** is for *reading and writing Sequences*. It is a front end module
152 for separate driver modules supporting the different sequence formats
154 * **`SeqFeature`** represent *start/stop/strand-based localized annotations (features) of sequences*
155 * **`Bio::SeqFeature::Generic`** is basic catchall
156 * **`Bio::SeqFeature::Similarity`** a similarity sequence feature
157 * **`Bio::SeqFeature::FeaturePair`** a sequence feature which is pairwise
158 such as query/hit pairs
160 * **`SearchIO`** is for *reading and writing pairwise alignment reports*, like
163 * **`Search`** is where the *alignment objects for `SearchIO` are defined*
164 * **`Bio::Search::Result::GenericResult`** is the result object (a blast
165 query is a `Result` object)
166 * **`Bio::Search::Hit::GenericHit`** is the `Hit` object (a query will have
167 0 to many hits in a database)
168 * **`Bio::Search::HSP::GenericHSP`** is the High-scoring Segment Pair
169 object defining the alignment(s) of the query and hit.
171 * **`SimpleAlign`** is for *multiple sequence alignments*
173 * **`AlignIO`** is for *reading and writing multiple sequence alignment
176 * **`Assembly`** provides the start of an *infrastructure for assemblies* and
177 **`Assembly::IO`** *IO converters* for them
179 * **`DB`** is the namespace for *all the database query classes*
180 * **`Bio::DB::GenBank/GenPept`** are two modules which query NCBI entrez for
182 * **`Bio::DB::SwissProt/EMBL`** query various EMBL and SwissProt
183 repositories for a sequences
184 * **`Bio::DB::GFF`** is Lincoln Stein's fast, lightweight feature and
185 sequence database which is the backend to his GBrowse system (see
187 * **`Bio::DB::Flat`** is a fast implementation of the OBDA flat-file
188 indexing system (cross-language and cross-platform supported by O|B|F
189 projects see http://obda.open-bio.org).
190 * **`Bio::DB::BioFetch/DBFetch`** for OBDA, Web (HTTP) access to remote
192 * **`Bio::DB::InMemoryCache/FileCache`** (fast local caching of sequences
193 from remote dbs to speed up your access).
194 * **`Bio::DB::Registry`** interface to the OBDA specification for remote
196 * **`Bio::DB::Biblio`** for access to remote bibliographic databases.
197 * **`Bio::DB::EUtilities`** is the initial set of modules used for generic
198 queried using NCBI's eUtils.
200 * **`Annotation`** collection of *annotation objects* (comments, DBlinks,
201 References, and misc key/value pairs)
203 * **`Coordinate`** is a system for *mapping between different coordinate systems*
204 such as DNA to protein or between assemblies
206 * **`Index`** is for *locally indexed flatfiles* with BerkeleyDB
208 * **`Tools`** contains many *miscellaneous parsers and functions* for different
210 * Gene prediction parser (Genscan, MZEF, Grail, Genemark)
211 * Annotation format (GFF)
212 * Enumerate codon tables and valid sequences symbols (CodonTable,
214 * Phylogenetic program parsing (PAML, Molphy, Phylip)
216 * **`Map`** represents *genetic and physical map representations*
218 * **`Structure`** - parse and represent *protein structure data*
220 * **`TreeIO`** is for reading and writing *Tree formats*
222 * **`Tree`** is the namespace for **all associated Tree classes**
223 * **`Bio::Tree::Tree`** is the basic tree object
224 * **`Bio::Tree::Node`** are the nodes which make up the tree
225 * **`Bio::Tree::Statistics`** is for computing statistics for a tree
226 * **`Bio::Tree::TreeFunctionsI`** is where specific tree functions are
227 implemented (like `is_monophyletic` and `lca`)
229 * **`Bio::Biblio`** is where *bibliographic data and database access objects*
232 * **`Variation`** represent *sequences with mutations and variations* applied so
233 one can compare and represent wild-type and mutation versions of a sequence.
235 * **`Root`**, basic objects for the *internals of BioPerl*
237 # Upgrading from an older version
239 If you have a previously installed version of BioPerl on your system some of
240 these notes may help you.
242 * Some modules have been removed because they have been superceded by new
243 development efforts. They are documented in the **`DEPRECATED`** file that is
244 included in the release.
246 * Some methods, or the Application Programming Interface (API), have changed or
247 been removed. You may find that scripts which worked with BioPerl 1.4 may give
248 you warnings or may not work at all (although we have tried very hard to
249 minimize this!). Send an email to the list and we'll be happy to give you