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