1 This is the README file for the BioPerl central distribution.
5 Please see the the INSTALL or INSTALL.WIN documents for installation
10 BioPerl is a package of public domain Perl tools for computational
13 Our website, http://bioperl.org/, provides an online resource of
14 modules, scripts, and web links for developers of Perl-based software
15 for life science research.
19 BioPerl mailing list: bioperl-l@bioperl.org
21 Project website : http://bioperl.org/
23 Bug reports : https://github.com/bioperl/bioperl-live/issues
25 Please send us bugs, in particular about documentation which you
26 think is unclear or problems in installation. We are also very
27 interested in functions which don't work the way you think they
30 o The directory structure
32 The BioPerl directory structure is organized as follows:
34 - Bio/ - BioPerl modules
36 - deobfuscator/ - Code for tracing OOP relationships
38 - examples/ - Scripts demonstrating the many uses of BioPerl
40 - ide/ - files for developing BioPerl using an IDE
42 - maintenance/ - BioPerl housekeeping scripts
44 - models/ - DIA drawing program generated OO UML for BioPerl classes
45 (these are quite out-of-date)
47 - scripts/ - Useful production-quality scripts with POD documentation
49 - t/ - Perl built-in tests, tests are divided into subdirectories
50 based on the specific classes being tested
52 - t/data/ - Data files used for the tests, provides good example data
54 - travis_scripts/ - script to customize Travis
59 For documentation on BioPerl see the HOWTO documents at
60 http://www.bioperl.org/wiki/HOWTOs.
62 Useful documentation in the form of example code can also be found in
63 the examples/ and scripts/ directories. The current collection
64 includes scripts that run BLAST, index flat files, parse PDB
65 structure files, make primers, retrieve ESTs based on tissue, align
66 protein to nucleotide sequence, run GENSCAN on multiple sequences,
67 and much more! See bioscripts.pod for a complete listing.
69 Individual *.pm modules have their own embedded POD documentation as
70 well. A complete set of hyperlinked POD, or module, documentation is
71 available at http://www.bioperl.org/.
73 Remember that 'perldoc' is your friend. You can use it to read any
74 file containing POD formatted documentation without needing any type
75 of translator (e.g. 'perldoc Bio::SeqIO').
77 If you used the Build.PL installation, and depending on your
78 platform, you may have documentation installed as man pages, which
79 can be accessed in the usual way.
83 BioPerl releases are always available from the website at
84 http://www.bioperl.org/DIST or in CPAN. The latest code can be found
85 at https://github.com/bioperl.
87 BioPerl formerly used a numbering scheme to indicate stable release
88 series vs. development release series. A release number is a three
89 digit number like 1.2.0. The first digit indicates the major release
90 - the idea being that all the API calls in a major release are
91 reasonably consistent. The second number is the release series. This
92 is probably the most important number.
94 From the 1.0 release until the 1.6 release, even numbers (1.0, 1.2
95 etc) indicated stable releases. Stable releases were well tested and
96 recommended for most uses. Odd numbers (1.1, 1.3 etc) were development
97 releases which one would only use if one were interested in the
98 latest and greatest features. The final number (e.g. 1.2.0, 1.2.1) is
99 the bug fix release. The higher the number the more bug fixes has
100 been incorporated. In theory you can upgrade from one bug fix release
101 to the next with no changes to your own code (for production cases,
102 obviously check things out carefully before you switch over).
104 The 1.6 release will be the last release series to utilize the
105 alternating 'stable'/'developer' convention. Starting immediately
106 after the 1.6 branch, we will start splitting BioPerl into several
107 smaller easier-to-manage distributions, including a developer
108 distribution for cutting-edge (in development) code, untested
109 modules, and alternative implementations.
111 o Caveats and warnings
113 When you run the tests ("./Build test") some tests may issue warnings
114 messages or even fail. Sometimes this is because we didn't have
115 anyone to test the test system on the combination of your operating
116 system, version of perl, and associated libraries and other modules.
117 Because BioPerl depends on several outside libraries we may not be
118 able to test every single combination so if there are warnings you
119 may find that the package is still perfectly useful.
121 If you install the bioperl-run system and run tests when you don't
122 have the program installed you'll get messages like 'program XXX not
123 found, skipping tests'. That's okay, BioPerl is doing what it is
124 supposed to do. If you wanted to run the program you'd need to
127 Not all scripts in the examples/ directory are correct and up-to-date.
128 We need volunteers to help maintain these so if you find they do not
129 submit a bug report to https://github.com/bioperl/bioperl-live/issues
130 and consider helping out in their maintenance.
132 If you are confused about what modules are appropriate when you try
133 and solve a particular issue in bioinformatics we urge you to look at
134 HOWTO documents first.
136 o A simple module summary
138 Here is a quick summary of many of the useful modules and how the
141 All modules are in the Bio/ namespace,
143 - Perl is for newbies and gives a functional interface to the main
146 - Seq is for Sequences (protein and DNA).
147 o Bio::PrimarySeq is a plain sequence (sequence data + identifiers)
148 o Bio::Seq is a PrimarySeq plus it has a Bio::Annotation::Collection
149 and Bio::SeqFeatureI objects attached
150 (via Bio::FeatureHolderI).
151 o Bio::Seq::RichSeq is all of the above plus it has slots for
152 extra information specific to GenBank/EMBL/SwissProt files.
153 o Bio::Seq::LargeSeq is for sequences which are too big for
156 - SeqIO is for reading and writing Sequences, it is a front end
157 module for separate driver modules supporting the different
160 - SeqFeature - start/stop/strand annotations of sequences
161 o Bio::SeqFeature::Generic is basic catchall
162 o Bio::SeqFeature::Similarity a similarity sequence feature
163 o Bio::SeqFeature::FeaturePair a sequence feature which is pairwise
164 such as query/hit pairs
166 - SearchIO is for reading and writing pairwise alignment reports like
169 - Search is where the alignment objects are defined
170 o Bio::Search::Result::GenericResult is the result object (a blast
171 query is a Result object)
172 o Bio::Search::Hit::GenericHit is the Hit object (a query will have
173 0 -> many hits in a database)
174 o Bio::Search::HSP::GenericHSP is the High-scoring Segment Pair
175 object defining the alignment(s) of the query and hit.
177 - SimpleAlign is for multiple sequence alignments
179 - AlignIO is for reading and writing multiple sequence alignment
182 - Assembly provides the start of an infrastructure for assemblies and
183 Assembly::IO IO converters for them
185 - DB is the namespace for all the database query objects
186 o Bio::DB::GenBank/GenPept are two modules which query NCBI entrez
188 o Bio::DB::SwissProt/EMBL query various EMBL and SwissProt
189 repositories for a sequences
190 o Bio::DB::GFF is Lincoln Stein's fast, lightweight feature and
191 sequence database which is the backend to his GBrowse system (see
193 o Bio::DB::Flat is a fast implementation of the OBDA flat-file
194 indexing system (cross-language and cross-platform supported by
195 O|B|F projects see http://obda.open-bio.org).
196 o Bio::DB::BioFetch/DBFetch for OBDA, Web (HTTP) access to remote
198 o Bio::DB::InMemoryCache/FileCache (fast local caching of sequences
199 from remote dbs to speed up your access).
200 o Bio::DB::Registry interface to the OBDA specification for remote
202 o Bio::DB::Biblio for access to remote bibliographic databases.
203 o Bio::DB::EUtilities is the initial set of modules used for
204 generic queried using NCBI's eUtils.
206 - Annotation collection of annotation objects (comments, DBlinks,
207 References, and misc key/value pairs)
209 - Coordinate is a system for mapping between different coordinate
210 systems such as DNA to protein or between assemblies
212 - Index is for locally indexed flatfiles with BerkeleyDB
214 - Tools contains many miscellaneous parsers and function for
215 different bioinformatics needs
216 o Gene prediction parser (Genscan, MZEF, Grail, Genemark)
217 o Annotation format (GFF)
218 o Enumerate codon tables and valid sequences symbols (CodonTable,
220 o Phylogenetic program parsing (PAML, Molphy, Phylip)
222 - Map genetic and physical map representations
224 - Structure - parse and represent protein structure data
226 - TreeIO is for reading and writing Tree formats
228 - Tree is the namespace for all the associated Tree objects
229 o Bio::Tree::Tree is the basic tree object
230 o Bio::Tree::Node are the nodes which make up the tree
231 o Bio::Tree::Statistics is for computing statistics for a tree
232 o Bio::Tree::TreeFunctionsI is where specific tree functions are
233 implemented (like is_monophyletic and lca)
235 - Bio::Biblio is where bibliographic data and database access objects
238 - Variation represent sequences with mutations and variations applied
239 so one can compare and represent wild-type and mutation versions of
242 - Root, basic objects for the internals of BioPerl
244 o Upgrading from an older version
246 If you have a previously installed version of BioPerl on your system
247 some of these notes may help you.
249 Some modules have been removed because they have been superceded by
250 new development efforts. They are documented in the DEPRECATED file
251 that is included in the release. In addition some methods, or the
252 Application Programming Interface (API), have changed or been
253 removed. You may find that scripts which worked with BioPerl 1.4 may
254 give you warnings or may not work at all (although we have tried very
255 hard to minimize this!). Send an email to the list and we'll be happy
256 to give you pointers.