README.md

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