This is the README file for the Bioperl central distribution.
# $Id: README,v 1.1 2003/12/22 21:53:58 heikki Exp heikki $
o Version
This is Bioperl release version 1.4, 22 Dec 2004
o Getting Started
Thanks for downloading this distribution!
For tutorials see Bioperl's bptutorial.pl (in this directory) or
howto documents in docs/howto or the online Bioperl tutorial
at http://www.pasteur.fr/recherche/unites/sis/formation/bioperl. For
information on databases and Bioperl see biodatabases.pod. To look at
example code browse the scripts/ directories, and look at
bioscripts.pod for a descriptions of all these scripts. The bioperl.pod file
also gives a overview of the history and purpose of Bioperl. The FAQ
may also be useful if you have a particular question.
For people starting out with Perl and Bioperl, look at the Bio::Perl
module (go perldoc Bio::Perl from the directory you are reading this file
in). This module is designed to flatten the learning curve for newcomers.
For a discussion of issues in design and development please see
biodesign.pod, recommended for those who want to contribute code. And for
a list of OS's and versions that are known to support Bioperl see the
PLATFORMS file.
For info on Bioperl read on!
o About Bioperl
Bioperl is an association of developers of public domain Perl tools
for computational molecular biology.
Our website http://bioperl.org provides an online resource for
modules, scripts, and web links for developers of Perl-based software
for life science research.
o Contact info
Bioperl developers: bioperl-l@bioperl.org
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.
Project website : http://bioperl.org
Project FTP server: bioperl.org (anonymous FTP ok)
Bug reports : http://bugzilla.bioperl.org/
bioperl-bugs@bioperl.org
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!
Please see the AUTHORS file for the complete list of bioperl
developers and contributors.
Please see the the INSTALL or INSTALL.WIN documents for installation
instructions.
o About the directory structure
The bioperl directory structure is organized as follows:
Bio/ - Bioperl modules
models/ - DIA drawing program generated OO UML for bioperl classes
t/ - Perl built-in tests
t/data/ - Data files used for the tests - provides good data
examples for those new to bioinformatics data.
scripts/ - Useful production-quality scripts with POD documentation
examples/ - Scripts demonstrating the many uses of Bioperl
doc/ - "How To" files and the FAQ as XML
maintenance/ - Bioperl housekeeping scripts
o Documentation
The "meta" documentation can be found in the bioperl.pod file.
This should be the starting point for you to read about what
bioperl is, how to use it and who wrote it.
The bptutorial.pl file is a POD formatted tutorial document
that contains useful information for new and existing Bioperl users.
This file also contains a number of useful scripts that the
student of Bioperl may want to examine.
Use your favorite pod2* translator turn it into the format of
choice or view it directly via perldoc.
For example, go
perldoc bioperl
or in this directory go
pod2text bioperl.pod | more
pod2text bptutorial.pl | more
pod2html, which comes with Perl, can be used to create web-browser
navigable documentation files.
Individual *.pm modules have their own embedded POD documentation
as well. A complete set of hyperlinked POD, or module, documentation
is available at http://www.bioperl.org.
Remember 'perldoc' is your friend. You can use this to read any
file containing POD formatted documentation without needing any type
of translator.
There is also an online course written at the Pasteur Institute. See:
http://www.pasteur.fr/recherche/unites/sis/formation/bioperl.
Useful documentation in the form of example code can also be found
in the examples/ directory. 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 complete listing.
o Releases
Bioperl releases are always available from the website
http://www.bioperl.org or by FTP from ftp://bioperl.org. (Note that
we've had trouble with our new network setup which is not allowing
FTP to support passive mode properly: use http://www.bioperl.org/DIST
to get a listing of the distribution directory). Each release is
tested with the test suite and cross-tested on a number of different
platforms. See the PLATFORMS file for more information on a specific
platform. All efforts are made to release a bug-free package,
however most major bugs in a release will be documented in the BUGS
file. See the Changes file for a listing of what features have been
added or what APIs have changed between releases.
Like many internet projects, Bioperl now has a consistent numbering
scheme to indicate stable release series vs development release series.
A release number is a three digit number like 1.2.0 - 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. Even
numbers here (1.0, 1.2 etc) indicate stable releases. Stable releases
are well tested and recommended for most uses. Odd numbers (1.1, 1.3
etc) are development releases which one should only use if you are
interested in the latest and greatest features. The final number (eg,
1.2.0, 1.2.1 etc) 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).
o Caveats, warnings, etc
When you run the tests (make test) often some tests will issue
warnings messages or even fail. Sometimes this is because we didn't
have anyone test the test system on the combination or 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 (mind you, now you've tested
another possible situation and we encourage you to contribute back to
the development process by emailing the list or submitted a bug), so
if there are warnings you will find that in fact many things are not
a big deal. See the PLATFORMS file for reports of specific issues.
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 this 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
work, submit a bug report http://bugzilla.bioperl.org and/or consider
helping out in their maintenance. Don't be dissuaded by a script not
working, often the SYNOPSIS of the module is the best place to start
when trying to learn how to use them.
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
the bptutorial first.
o 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 Bio/ namespace,
- Perl is for newbies and gives a functional interface to the main
parts of the package
- Seq is for Sequences (protein and DNA).
o Bio::PrimarySeq is a plain sequence (sequence data + identifiers)
o Bio::Seq is a PrimarySeq plus it has a Bio::Annotation::Collection
and a Bio::SeqFeatureI objects attached.
o Bio::Seq::RichSeq is all of the above plus it has slots for
extra information specific to GenBank/EMBL/SwissProt files.
o Bio::Seq::LargeSeq is for sequences which are too big for
fitting into memory.
- SeqIO is for reading and writing Sequences, it is a front end
module for separate driver modules supporting the different
sequence formats
- SeqFeature - start/stop/strand annotations of sequences
o Bio::SeqFeature::Generic is basic catchall
o Bio::SeqFeature::Similarity a similarity sequence feature
o Bio::SeqFeature::FeaturePair a sequence feature which is pairwise
such as query/hit pairs
- SearchIO is for reading and writing pairwise alignment reports
like BLAST or FASTA
- Search is where the alignment objects are defined
o Bio::Search::Result::GenericResult is the result object (a blast query
is a Result object)
o Bio::Search::Hit::GenericHit is the Hit object (a query will have
0-> many hits in a database)
o Bio::Search::HSP::GenericHSP is the High-scoring Segment Pair
object defining the alignment(s) of the query and hit.
- SimpleAlign is for multiple sequence alignments
- AlignIO is for reading and writing multiple sequence alignment
formats
- Assembly provides the start of an infrastructure for assemblies
and Assembly::IO IO converters for them
- DB is the namespace for all the database query objects
o Bio::DB::GenBank/GenPept are two modules which query NCBI entrez
for sequences
o Bio::DB::SwissProt/EMBL query various EMBL and SwissProt
repositories for a sequences
o Bio::DB::GFF is Lincoln Stein's fast, lightweight feature and
sequence database which is the backend to his GBrowse system
(see www.gmod.org)
o Bio::DB::Flat is 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).
o Bio::DB::BioFetch/DBFetch for OBDA, Web (HTTP) access to remote
databases.
o Bio::DB::InMemoryCache/FileCache (fast local caching of sequences
from remote dbs to speed up your access).
o Bio::DB::Registry interface to the OBDA specification for remote
data sources
o Bio::DB::XEMBL SOAP access to sequence databases
o Bio::DB::Biblio for access to remote bibliographic databases.
- Annotation collection of annotation objects (comments,
DBlinks, References, and misc key/value pairs)
- Coordinate is a system for mapping between different coordinate
systems such as DNA to protein or between assemblies.
- Index is for locally indexed flatfiles with BerkeleyDB
- Tools contains many misc parsers and function for different
bioinformatics needs
o Gene prediction parser (Genscan, MZEF, Grail, Genemark)
o Annotation format (GFF)
o simulate RE cutting with RestrictionEnzyme
o Enumerate codon tables and valid sequences symbols (CodonTable, IUPAC)
o Phylogenetic program parsing (PAML, Molphy, Phylip)
- Map genetic and physical map representations
- Graphics render a sequence with its features in the standard
'tracks'gram.
- Structure - parse and represent protein structure data
- TreeIO is for reading and writing Tree formats
- Tree is the namespace for all the associated Tree objects
o Bio::Tree::Tree is the basic tree object
o Bio::Tree::Node are the nodes which make up the tree
o Bio::Tree::Statistics is for computing statistics for a tree
o Bio::Tree::TreeFunctionsI is where specific tree functions are
implemented (like is_monophyletic and lca)
- Bio::Biblio is where bibliographic data and database access objects
are kept
- Variation represent 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
o 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 superseded by
new development efforts. They are documented in the DEPRECATED file
that is included in the release. In addition some methods, or the
Application Programming Interface (API), have changed or been
removed. You may find that scripts which worked with bioperl 1.0.2
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.