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 Information
  24
  25 * BioPerl mailing list: bioperl-l@bioperl.org
  26
  27 * Project website : http://bioperl.org/
  28
  29 * Bug reports : https://github.com/bioperl/bioperl-live/issues
  30
  31 Please submit bugs, in particular about documentation which you think is
  32 unclear, or about problems in installation. We are also very interested in functions 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 * **`deobfuscator/`** - Code for tracing OOP relationships
  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 * **`travis_scripts/`** - script to customize Travis
  59
  60 # Documentation
  61
  62 For documentation on BioPerl see the **HOWTO** documents online at https://bioperl.github.io/howtos.
  63
  64 Useful documentation in the form of example code can also be found in the
  65 **`examples/`** and **`scripts/`** directories. The current collection includes
  66 scripts that run BLAST, index flat files, parse PDB structure files, make
  67 primers, retrieve ESTs based on tissue, align protein to nucleotide sequence,
  68 run GENSCAN on multiple sequences, and much more! See `bioscripts.pod` for a
  69 complete listing.
  70
  71 Individual `*.pm` modules have their own embedded POD documentation as well. A
  72 complete set of hyperlinked POD, or module, documentation is available at
  73 http://www.bioperl.org/.
  74
  75 Remember that '`perldoc`' is your friend. You can use it to read any file
  76 containing POD formatted documentation without needing any type of translator
  77 (e.g. '`perldoc Bio::SeqIO`').
  78
  79 If you used the Build.PL installation, and depending on your platform, you may
  80 have documentation installed as man pages, which can be accessed in the usual
  81 way.
  82
  83 # Releases
  84
  85 BioPerl releases are always available from the website at http://www.bioperl.org/DIST or in CPAN. The latest code can be found at https://github.com/bioperl.
  86
  87 * BioPerl currently uses a sematic numbering scheme to indicate stable release
  88   series vs. development release series. A release number is a three digit
  89   number like `1.2.0`.
  90   * The *first digit indicates the major release*, the idea being that all the
  91     API calls in a major release are reasonably consistent.
  92   * The *second number is the release series*. This is probably the most
  93     important number, and represents added functionality that is
  94     backwards-compatible.
  95   * The *third number is the point or patch release* and represents mainly bug
  96     fixes or additional code that doesn't add significant functionality to the
  97     code base.
  98
  99 From the **1.0 release until the 1.6 release** even numbers (e.g. `1.4`) indicated stable releases. Stable releases were well tested and recommended for most uses. Odd numbers (e.g. `1.3`) were development releases which one would only use if one were interested in the latest features. The final number (e.g. in `1.2.1`) is the point or patch release. The higher the number the more bug fixes has been incorporated. In theory you can upgrade from one point or patch release to the next with no changes to your own code (for production cases, obviously check things out carefully before you switch over).
 100
 101 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 2.x release.
 102
 103 # Caveats and Warnings
 104
 105 When you run the tests with `./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
 106 outside libraries we may not be able to test every single combination so if
 107 there are warnings you may find that the package is still perfectly useful.
 108
 109 If you install the bioperl-run system and run tests when you don't have the
 110 program installed you'll get messages like `program XXX not found, skipping
 111 tests`. That's okay, BioPerl is doing what it is supposed to do. If you wanted
 112 to run the program you'd need to install it first.
 113
 114 Not all scripts in the `examples/` directory are correct and up-to-date. If you find an issue with a script please submit a bug report to https://github.com/bioperl/bioperl-live/issues and consider helping out in their maintenance.
 115
 116 If you are confused about what modules are appropriate when you try and solve a
 117 particular issue in bioinformatics we urge you to look at HOWTO documents first.
 118
 119 # A simple module summary
 120
 121 Here is a quick summary of many of the useful modules and how the toolkit is
 122 laid out:
 123
 124 All modules are in the **`Bio/`** namespace,
 125
 126 * **`Perl`** is for *new users*, and gives a functional interface to the main
 127   parts of the package.
 128
 129 * **`Seq`** is for *Sequences* (protein and DNA).
 130     * `Bio::PrimarySeq` is a plain sequence (sequence data + identifiers)
 131     * `Bio::Seq` is a fancier `PrimarySeq`, in that it has annotation (via
 132     `Bio::Annotation::Collection`) and sequence features (via `Bio::SeqFeatureI` objects, attached via
 133     `Bio::FeatureHolderI`).
 134     * `Bio::Seq::RichSeq` is all of the above, plus it has slots for extra information specific to GenBank/EMBL/SwissProt files.
 135     * `Bio::Seq::LargeSeq` is for sequences which are too big for
 136     fitting into memory.
 137
 138 * **`SeqIO`** is for *reading and writing Sequences*. It is a front end module
 139   for separate driver modules supporting the different sequence formats
 140
 141 * **`SeqFeature`** represent *start/stop/strand-based localized annotations (features) of sequences*
 142     * **`Bio::SeqFeature::Generic`** is basic catchall
 143     * **`Bio::SeqFeature::Similarity`** a similarity sequence feature
 144     * **`Bio::SeqFeature::FeaturePair`** a sequence feature which is pairwise
 145     such as query/hit pairs
 146
 147 * **`SearchIO`** is for *reading and writing pairwise alignment reports*, like
 148   BLAST or FASTA
 149
 150 * **`Search`** is where the *alignment objects for `SearchIO` are defined*
 151     * **`Bio::Search::Result::GenericResult`** is the result object (a blast
 152     query is a `Result` object)
 153     * **`Bio::Search::Hit::GenericHit`** is the `Hit` object (a query will have
 154     0 to many hits in a database)
 155     * **`Bio::Search::HSP::GenericHSP`** is the High-scoring Segment Pair
 156     object defining the alignment(s) of the query and hit.
 157
 158 * **`SimpleAlign`** is for *multiple sequence alignments*
 159
 160 * **`AlignIO`** is for *reading and writing multiple sequence alignment
 161   formats*
 162
 163 * **`Assembly`** provides the start of an *infrastructure for assemblies* and
 164   **`Assembly::IO`** *IO converters* for them
 165
 166 * **`DB`** is the namespace for *all the database query classes*
 167     * **`Bio::DB::GenBank/GenPept`** are two modules which query NCBI entrez for
 168       sequences
 169     * **`Bio::DB::SwissProt/EMBL`** query various EMBL and SwissProt
 170       repositories for a sequences
 171     * **`Bio::DB::GFF`** is Lincoln Stein's fast, lightweight feature and
 172       sequence database which is the backend to his GBrowse system (see
 173       www.gmod.org)
 174     * **`Bio::DB::Flat`** is a fast implementation of the OBDA flat-file
 175       indexing system (cross-language and cross-platform supported by O|B|F
 176       projects see http://obda.open-bio.org).
 177     * **`Bio::DB::BioFetch/DBFetch`** for OBDA, Web (HTTP) access to remote
 178       databases.
 179     * **`Bio::DB::InMemoryCache/FileCache`** (fast local caching of sequences
 180       from remote dbs to speed up your access).
 181     * **`Bio::DB::Registry`** interface to the OBDA specification for remote
 182       data sources
 183     * **`Bio::DB::Biblio`** for access to remote bibliographic databases.
 184     * **`Bio::DB::EUtilities`** is the initial set of modules used for generic
 185       queried using NCBI's eUtils.
 186
 187 * **`Annotation`** collection of *annotation objects* (comments, DBlinks,
 188   References, and misc key/value pairs)
 189
 190 * **`Coordinate`** is a system for *mapping between different coordinate systems*
 191   such as DNA to protein or between assemblies
 192
 193 * **`Index`** is for *locally indexed flatfiles* with BerkeleyDB
 194
 195 * **`Tools`** contains many *miscellaneous parsers and functions* for different
 196   bioinformatics needs
 197     * Gene prediction parser (Genscan, MZEF, Grail, Genemark)
 198     * Annotation format (GFF)
 199     * Enumerate codon tables and valid sequences symbols (CodonTable,
 200     IUPAC)
 201     * Phylogenetic program parsing (PAML, Molphy, Phylip)
 202
 203 * **`Map`** represents *genetic and physical map representations*
 204
 205 * **`Structure`** - parse and represent *protein structure data*
 206
 207 * **`TreeIO`** is for reading and writing *Tree formats*
 208
 209 * **`Tree`** is the namespace for **all associated Tree classes**
 210     * **`Bio::Tree::Tree`** is the basic tree object
 211     * **`Bio::Tree::Node`** are the nodes which make up the tree
 212     * **`Bio::Tree::Statistics`** is for computing statistics for a tree
 213     * **`Bio::Tree::TreeFunctionsI`** is where specific tree functions are
 214       implemented (like `is_monophyletic` and `lca`)
 215
 216 * **`Bio::Biblio`** is where *bibliographic data and database access objects*
 217   are kept
 218
 219 * **`Variation`** represent *sequences with mutations and variations* applied so one can compare and represent wild-type and mutation versions of a sequence.
 220
 221 * **`Root`**, basic objects for the *internals of BioPerl*
 222
 223 # Upgrading from an older version
 224
 225 If you have a previously installed version of BioPerl on your system some of
 226 these notes may help you.
 227
 228 * Some modules have been removed because they have been superceded by new
 229   development efforts. They are documented in the **`DEPRECATED`** file that is
 230   included in the release.
 231
 232 * Some methods, or the Application Programming Interface (API), have changed or
 233   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
 234   minimize this!). Send an email to the list and we'll be happy to give you
 235   pointers.