Please see the the
INSTALL.WIN documents for installation
Note that these documents are gradually being migrated to a specific http://readthedocs.org site.
BioPerl is a package of public domain Perl tools for computational molecular biology.
Our website (http://bioperl.org/) provides an online resource of modules, scripts, and web links for developers of Perl-based software for life science research.
BioPerl mailing list: email@example.com
There's quite a variety of tools available in BioPerl, and more are added all the time. If the tool you're looking for isn't described in the documentation please write us, it could be undocumented or in process.
Please send us bugs, in particular about documentation which you think is unclear or problems in installation. We are also very interested in functions which don't work the way you think they do!
The directory structure
The BioPerl directory structure is organized as follows:
Bio/- BioPerl modules
doc/- Documentation utilities
examples/- Scripts demonstrating the many uses of BioPerl
ide/- files for developing BioPerl using an IDE
maintenance/- BioPerl housekeeping scripts
models/- DIA drawing program generated OO UML for BioPerl classes (these are quite out-of-date)
scripts/- Useful production-quality scripts with POD documentation
t/- Perl built-in tests, tests are divided into subdirectories based on the specific classes being tested
t/data/- Data files used for the tests, provides good example data
For documentation on BioPerl see the HOWTO documents and tutorials online at http://bioperl.org.
Useful documentation in the form of example code can also be found in the
scripts/ directories. The current collection includes
scripts that run BLAST, index flat files, parse PDB structure files, make
primers, retrieve ESTs based on tissue, align protein to nucleotide sequence,
run GENSCAN on multiple sequences, and much more! See
bioscripts.pod for a
*.pm modules have their own embedded POD documentation as well. A
complete set of hyperlinked POD, or module, documentation is available at
Remember that '
perldoc' is your friend. You can use it to read any file
containing POD formatted documentation without needing any type of translator
If you used the Build.PL installation, and depending on your platform, you may have documentation installed as man pages, which can be accessed in the usual way.
BioPerl currently uses a sematic numbering scheme to indicate stable release series vs. development release series. A release number is a three digit number like
- The first digit indicates the major release, the idea being that all the API calls in a major release are reasonably consistent.
- The second number is the release series. This is probably the most important number, and represents added functionality that is backwards-compatible.
- The third number is the point or patch release and represents mainly bug fixes or additional code that doesn't add significant functionality to the code base.
From the 1.0 release until the 1.6 release, even numbers (
1.2, etc) indicated stable releases. Stable releases were well tested and recommended for most uses. Odd numbers (
1.3, etc) were development releases which one would only use if one were interested in the latest and greatest features. The final number (e.g.
1.2.1) is the bug fix release. The higher the number the more bug fixes has been incorporated. In theory you can upgrade from one bug fix release to the next with no changes to your own code (for production cases, obviously check things out carefully before you switch over).
The upcoming 1.7 release will be the last release series to utilize the alternating 'stable'/'developer' convention. Starting immediately after the final 1.6 branch, we will start splitting BioPerl into several smaller easier-to-manage distributions. These will have independent versions, all likely starting with v1.7.0. We do not anticipate major API changes in the 1.7.x release series, merely that the code will be restructured in a way to make maintenance more feasible. We anticipate retaining semantic versioning until the *v2.x release.
Caveats and warnings
When you run the tests ("
./Build test") some tests may issue warnings messages
or even fail. Sometimes this is because we didn't have anyone to test the test
system on the combination of your operating system, version of perl, and
associated libraries and other modules. Because BioPerl depends on several
outside libraries we may not be able to test every single combination so if
there are warnings you may find that the package is still perfectly useful.
If you install the bioperl-run system and run tests when you don't have the
program installed you'll get messages like '
program XXX not found, skipping
tests'. That's okay, BioPerl is doing what it is supposed to do. If you wanted
to run the program you'd need to install it first.
Not all scripts in the
examples/ directory are correct and up-to-date. We need
volunteers to help maintain these so if you find they do not submit a bug report
to https://github.com/bioperl/bioperl-live/issues and consider helping out in
If you are confused about what modules are appropriate when you try and solve a particular issue in bioinformatics we urge you to look at HOWTO documents first.
A simple module summary
Here is a quick summary of many of the useful modules and how the toolkit is laid out:
All modules are in the
Perlis for new users, and gives a functional interface to the main parts of the package.
Seqis for Sequences (protein and DNA).
Bio::PrimarySeqis a plain sequence (sequence data + identifiers)
Bio::Seqis a fancier
PrimarySeq, in that it has annotation (via
Bio::Annotation::Collection) and sequence features (via
Bio::SeqFeatureIobjects, attached via
Bio::Seq::RichSeqis all of the above, plus it has slots for extra information specific to GenBank/EMBL/SwissProt files.
Bio::Seq::LargeSeqis for sequences which are too big for fitting into memory.
SeqIOis for reading and writing Sequences. It is a front end module for separate driver modules supporting the different sequence formats
SeqFeaturerepresent start/stop/strand-based localized annotations (features) of sequences
Bio::SeqFeature::Genericis basic catchall
Bio::SeqFeature::Similaritya similarity sequence feature
Bio::SeqFeature::FeaturePaira sequence feature which is pairwise such as query/hit pairs
SearchIOis for reading and writing pairwise alignment reports, like BLAST or FASTA
Searchis where the alignment objects for
Bio::Search::Result::GenericResultis the result object (a blast query is a
Hitobject (a query will have 0 to many hits in a database)
Bio::Search::HSP::GenericHSPis the High-scoring Segment Pair object defining the alignment(s) of the query and hit.
SimpleAlignis for multiple sequence alignments
AlignIOis for reading and writing multiple sequence alignment formats
Assemblyprovides the start of an infrastructure for assemblies and
Assembly::IOIO converters for them
DBis the namespace for all the database query classes
Bio::DB::GenBank/GenPeptare two modules which query NCBI entrez for sequences
Bio::DB::SwissProt/EMBLquery various EMBL and SwissProt repositories for a sequences
Bio::DB::GFFis Lincoln Stein's fast, lightweight feature and sequence database which is the backend to his GBrowse system (see www.gmod.org)
Bio::DB::Flatis a fast implementation of the OBDA flat-file indexing system (cross-language and cross-platform supported by O|B|F projects see http://obda.open-bio.org).
Bio::DB::BioFetch/DBFetchfor OBDA, Web (HTTP) access to remote databases.
Bio::DB::InMemoryCache/FileCache(fast local caching of sequences from remote dbs to speed up your access).
Bio::DB::Registryinterface to the OBDA specification for remote data sources
Bio::DB::Bibliofor access to remote bibliographic databases.
Bio::DB::EUtilitiesis the initial set of modules used for generic queried using NCBI's eUtils.
Annotationcollection of annotation objects (comments, DBlinks, References, and misc key/value pairs)
Coordinateis a system for mapping between different coordinate systems such as DNA to protein or between assemblies
Indexis for locally indexed flatfiles with BerkeleyDB
Toolscontains many miscellaneous parsers and functions for different bioinformatics needs
- Gene prediction parser (Genscan, MZEF, Grail, Genemark)
- Annotation format (GFF)
- Enumerate codon tables and valid sequences symbols (CodonTable, IUPAC)
- Phylogenetic program parsing (PAML, Molphy, Phylip)
Maprepresents genetic and physical map representations
Structure- parse and represent protein structure data
TreeIOis for reading and writing Tree formats
Treeis the namespace for all associated Tree classes
Bio::Tree::Treeis the basic tree object
Bio::Tree::Nodeare the nodes which make up the tree
Bio::Tree::Statisticsis for computing statistics for a tree
Bio::Tree::TreeFunctionsIis where specific tree functions are implemented (like
Bio::Bibliois where bibliographic data and database access objects are kept
Variationrepresent sequences with mutations and variations applied so one can compare and represent wild-type and mutation versions of a sequence.
Root, basic objects for the internals of BioPerl
Upgrading from an older version
If you have a previously installed version of BioPerl on your system some of these notes may help you.
Some modules have been removed because they have been superceded by new development efforts. They are documented in the
DEPRECATEDfile that is included in the release.
Some methods, or the Application Programming Interface (API), have changed or been removed. You may find that scripts which worked with BioPerl 1.4 may give you warnings or may not work at all (although we have tried very hard to minimize this!). Send an email to the list and we'll be happy to give you pointers.