README.md

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