README

   1
   2 The bioperl-db package contains interfaces and adaptors that work
   3 with a BioSQL database and serialize and de-serialize Bioperl
   4 objects.
   5
   6 ===================================================================
   7 Information about BioSQL and bioperl-db
   8 ===================================================================
   9
  10 This project was started by Ewan Birney with major work by Elia Stupka
  11 and continued support by Hilmar Lapp and the Bioperl community. It's
  12 purpose is to create a standalone sequence database with little
  13 external dependencies and tight integration with Bioperl. Support for
  14 more databases and bindings in Java and python by Biojava and
  15 Biopython projects is welcomed, and a working prototype was one of
  16 the accomplishments of the February 2002 hackathon in South Africa.
  17 All questions and comments should be directed to the bioperl list
  18 <bioperl-l@bioperl.org> and more information can be found about the
  19 related projects at http://www.bioperl.org and http://www.open-bio.org.
  20
  21 I. Scripts located in the scripts/ directory:
  22
  23 biosql/load_seqdatabase.pl      - a very flexible script to load
  24                                                     sequences into a BioSQL database
  25 biosql/bioentry2flat.pl         - dump sequence data into rich sequence
  26                                               format flatfile from a BioSQL database
  27 biosql/load_ontology.pl         - load GO or SOFA ontology data into
  28                                   a BioSQL database
  29 biosql/merge-unique-ann.pl      - script used by load_seqdatabase.pl,
  30                                   it merges features and annotations
  31 biosql/update-on-new-date.pl    - script used by load_seqdatabase.pl,
  32                                   it will update based on date
  33 biosql/update-on-new-version.pl - script used by load_seqdatabase.pl,
  34                                                     it will update based on version
  35 biosql/cgi-bin/getentry.pl      - example CGI script that fetches from
  36                                   a BioSQL database
  37 biosql/clean_ontology.pl        - "cleans" an ontology in a BioSQL
  38                                   database without foreign keys
  39 biosql/del-assocs-sql.pl        - script used by load-seqdatabase.pl,
  40                                   removes annotations and features
  41 biosql/freshen-annot.pl         - script used by load-seqdatabase.pl,
  42                                   removes annotations and features
  43 biosql/load_interpro.pl         - deprecated
  44 biosql/terms/add-term-annot.pl  - load ontology terms read from a file
  45 biosql/terms/importrelation.pl  - load relations between ontology
  46                                                     terms and bioentries
  47 biosql/terms/interpro2go.pl     - load from interpro2go file
  48 corba/caching_corba_server.pl   - setup a corba sequence caching server
  49 corba/test_bioenv.pl            - test the bioenv of a running server
  50 corba/bioenv_server.pl          - setup a CORBA sequence server
  51
  52 There is also a script called scripts/load_ncbi_taxonomy.pl in the
  53 BioSQL package that loads taxonomic data from NCBI. Most users use
  54 this script to load the NCBI taxonomy into their Biosql databases
  55 before loading sequences with load_seqdatabase.pl.
  56
  57 II. Some background information and how it all works:
  58
  59 The adaptor code in Bio::DB and Bio::DB::BioSQL was completely
  60 refactored and architected from scratch since the previous branch
  61 bioperl-release-1-1-0. Meanwhile almost everything works. The
  62 following things are unsupported or do not work yet:
  63
  64      - sub-seqfeatures
  65      - round-tripping fuzzy locations (they will be stored according
  66              to their Bio::Location::CoordinatePolicyI interpretation)
  67      - Bio::Annotation::DBLink::optional_id
  68
  69 To understand the layout of the API and how you can interact with the
  70 adaptors to formulate your own queries, here is what you should know
  71 and read (i.e., read the PODs of all interfaces and modules named
  72 below).
  73
  74 1) Bio::DB::BioDB acts as a factory of database adaptors, where a
  75 database adaptor encapsulates an entire database, not a specific
  76 object-relational mapping or table. It is similar Bio::SeqIO in
  77 bioperl, where you specify a format and get back a parser for that
  78 format. Here you specify the database and get back a persistence
  79 factory for that database. Note that the only database really
  80 supported right now in this framework is BioSQL.
  81
  82 2) The persistence factory returned by Bio::DB::BioDB->new() will
  83 implement Bio::DB::DBAdaptorI. It allows you to obtain a persistence
  84 adaptor for an object at hand, and to turn an object into a persistent
  85 object.
  86
  87 3) A persistent object will implement Bio::DB::PersistentObjectI. A
  88 persistent object can be updated in and removed from the database. It
  89 also knows about its primary key in the database once it has been
  90 created or found in the database. A persistent object will still
  91 implement all interfaces and all methods that the non-persistent base
  92 object implements. E.g., a persistent sequence object will implement
  93 Bio::DB::PersistentObjectI and Bio::PrimarySeqI (or Bio::SeqI).
  94
  95 4) A persistence adaptor will implement Bio::DB::PersistenceAdaptorI.
  96 Apart from actually implementing all the persistence methods for
  97 persistent objects, a persistence adaptor allows you to locate
  98 objects in the database by key and by query. You can
  99 find_by_primary_key(), find_by_unique_key(), find_by_association(),
 100 and find_by_query(). The latter allows you to formulate object queries
 101 as Bio::DB::Query::BioQuery objects and retrieve the matching objects.
 102
 103 5) The guiding principle for the redesign of the adaptors was to
 104 separate business logic from schema logic. While business logic is
 105 largely driven by the object model (hence, by the bioperl object
 106 model) and therefore is mostly independent from the schema, but
 107 specific to the object model, the schema logic is driven by and
 108 specific to the relational model. The schema logic will therefore need
 109 to differ from one schema to another and even from one schema flavor
 110 to another for very similar relational models, whereas the business
 111 logic is unaffected by this.
 112
 113 This had two consequences. First, the user interacts with the adaptors
 114 without knowing anything about the specific schema behind it. All
 115 interaction takes place in object space. You construct queries by
 116 specifying object slots and the values they should have or
 117 match. Joins and associations are also specified on the object level
 118 (cf. Bio::DB::Query::BioQuery). Internally, the respective drivers for
 119 the particular schema translate those queries into schema-specific SQL
 120 queries.
 121
 122 The second consequence was that every persistence adaptor is divided
 123 into two layers, the persistence adaptor itself which does not contain
 124 a single SQL phrase or query, and its schema-specific driver which
 125 implements those functions which cannot be accomplished without
 126 actually doing the concrete object-relational mapping.
 127
 128 ===================================================================
 129 Information about Bio::DB::Map modules and database interface
 130 ===================================================================
 131
 132 These modules have been deprecated and are no longer in the distribution.
 133