# $Id: INSTALL,v 1.17 2006/12/06 14:17:27 sendu Exp $

bioperl-db INSTALLATION

INSTALL THE RIGHT BIOPERL

You need at least the corresponding version of Bioperl. Since this
is bioperl-db 1.5.2, you will need bioperl 1.5.2.

INSTALL BIOSQL

The bioperl-db package is designed to work with the BioSQL database.
Install the BioSQL package by following the instructions in its
INSTALL file. You can obtain the BioSQL package at www.open-bio.org. 
BioSQL requires a relational database, either Mysql, Oracle, or 
Postgres.


INSTALLATION

Installation instructions at the following address apply here:
http://www.bioperl.org/wiki/Installing_Bioperl_for_Unix
The next 2 sections summarize the essential points from there.


CPAN INSTALLATION

To install using CPAN you will need a recent version (v1.8802 has
been tested) of it and your prefer_installer conf set to 'MB':

  >cpan
  cpan>o conf prefer_installer MB
  cpan>o conf commit
  cpan>q

Ensure that you have installed BioSQL properly prior to attempting
an installation. You will also probably need root privileges.
Find the name of the bioperl-db version you want:

  >cpan
  cpan>d /bioperl-db/
  Database was generated on Mon, 20 Nov 2006 05:24:36 GMT
  Distribution S/SE/SENDU/bioperl-db-1.5.2_100.tar.gz
  
Now install:

 cpan>install S/SE/SENDU/bioperl-db-1.5.2_100.tar.gz

If you've installed everything perfectly then you may pass all the tests
run in the './Build test' phase.
It's also possible that you may fail some tests. Possible explanations:
problems with local Perl installation, previously undetected bug in
Bioperl, flawed test script and so on. A few failed tests may not affect
your usage of bioperl-db.

If you decide that the failed tests will not affect how you intend to use
bioperl-db and you'd like to install anyway do:

 cpan>force install S/SE/SENDU/bioperl-db-1.5.2_100.tar.gz

This is what most experienced Bioperl users would do. However, if you're
concerned about a failed test and need assistance or advice then contact
bioperl-l@bioperl.org.
  

MANUAL INSTALLATION

Download the bioperl-db archive, then extract its contents. Example:

  >gunzip bioperl-db-<release-version>.tar.gz
  >tar xvf bioperl-db-<release-version>.tar
  >cd bioperl-db

where <release-version> is the current release.

Issue the following command from within bioperl-db/:

  >perl Build.PL

You can run regression tests and install bioperl-db using the
following commands:

  >./Build test  
  >./Build install

NOTE: bioperl-db tests require that the BioSQL database you configure
does NOT have NCBI taxonomy loaded. Also, the './Build install' step
may require that you have root privileges.


INSTALLING bioperl-db ON WINDOWS

The following page on the BioPerl website has up-to-date
instructions on how to install bioperl-db on Windows:

http://www.bioperl.org/wiki/Installing_Bioperl_on_Windows

(the instructions are aimed at bioperl-core, but apply
equally to bioperl-db)


LOAD THE NCBI TAXONOMY

You should pre-load the NCBI taxonomy database using the
scripts/load_ncbi_taxonomy.pl script in the BioSQL package. 
Otherwise you will see errors from mis-parsed organisms when you 
attempt to load sequences.


LOAD SEQUENCE DATA

Most people will want to load sequence data into their BioSQL
databases. Use scripts/biosql/load_seqdatabase.pl in the bioperl-db
package to load sequences from sequence files. Do:

  >perldoc scripts/biosql/load_seqdatabase.pl

or

  >scripts/biosql/load_seqdatabase.pl --help

for more information.

This script has many options to flexibly deal with various update
scenarios. Do read the POD before running an update.


LOAD ONTOLOGIES

Use scripts/biosql/load_ontology.pl in the bioperl-db
package to load ontologies from flat files. Do:

  >perldoc scripts/biosql/load_ontology.pl

or

  >scripts/biosql/load_ontology.pl --help

for more information.

This script has many options to flexibly deal with various update
scenarios. Do read the POD before running an update. Also, some
ontologies maintain obsoleted terms, for instance the Gene
Ontology. Read the POD for possible options to deal with obsoleted
terms; this is relevant even when you load the ontology the first
time, as you may choose to keep obsoleted terms out of the database
from the start.


FEEDBACK

Write down any problems or praise and send them to 
bioperl-l@bioperl.org  ;-)