← Back to branch summary

~ubuntu-branches/ubuntu/raring/bioperl/raring

« back to all changes in this revision

Viewing changes to doc/howto/sgml/Flat_Databases.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Charles Plessy
  • Date: 2008-03-18 14:44:57 UTC
  • mfrom: (4 hardy)
  • mto: This revision was merged to the branch mainline in revision 6.
  • Revision ID: james.westby@ubuntu.com-20080318144457-1jjoztrvqwf0gruk
http://bugs.debian.org/448890
* debian/control:
  - Removed MIA Matt Hope (dopey) from the Uploaders field.
    Thank you for your work, Matt. I hope you are doing well.
  - Downgraded some recommended package to the 'Suggests' priority,
    according to the following discussion on Upstream's mail list.
    http://bioperl.org/pipermail/bioperl-l/2008-March/027379.html
    (Closes: #448890)
* debian/copyright converted to machine-readable format.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/howto/sgml/Flat_Databases.sgml
1
 
<!DOCTYPE article  PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2
 
  <article lang="en">
3
 
    <articleinfo>
4
 
      <title>Flat Databases HOWTO</title>
5
 
 
6
 
    <author>
7
 
      <firstname>Lincoln</firstname>
8
 
      <surname>Stein</surname>
9
 
      <affiliation>
10
 
        <orgname>
11
 
          <ulink url="http://www.cshl.org">Cold Spring Harbor Laboratory</ulink>
12
 
        </orgname>
13
 
        <address>
14
 
          <email>lstein-at-cshl.org</email>
15
 
        </address>
16
 
      </affiliation>
17
 
    </author>
18
 
    <author>
19
 
      <firstname>Brian</firstname>
20
 
      <surname>Osborne</surname>
21
 
      <authorblurb>
22
 
        <para>Bioperl contributor</para>
23
 
      </authorblurb>
24
 
      <affiliation>
25
 
        <orgname><ulink url="http://www.cognia.com">Cognia Corporation</ulink></orgname>
26
 
        <address>
27
 
          <email>brian-at-cognia.com</email>
28
 
        </address>
29
 
      </affiliation>
30
 
    </author>
31
 
    <author>
32
 
      <firstname>Heikki</firstname>
33
 
      <surname>Lehv�slaiho</surname>
34
 
      <authorblurb>
35
 
        <para>Bioperl contributor</para>
36
 
      </authorblurb>
37
 
      <affiliation>
38
 
        <orgname>
39
 
          <ulink url="http://www.ebi.ac.uk">European Bioinformatics Institute</ulink>
40
 
        </orgname>
41
 
        <address>
42
 
          <email>heikki-at-ebi.co.uk</email>
43
 
        </address>
44
 
      </affiliation>
45
 
    </author>
46
 
 
47
 
    <pubdate>2003-02-26</pubdate>
48
 
 
49
 
      <revhistory>
50
 
        <revision>
51
 
          <revnumber>1.0</revnumber>
52
 
          <date>2003-02-26</date>
53
 
          <authorinitials>LS</authorinitials>
54
 
          <revremark>First version</revremark>
55
 
        </revision>
56
 
        <revision>
57
 
          <revnumber>1.1</revnumber>
58
 
          <date>2003-10-17</date>
59
 
          <authorinitials>BS</authorinitials>
60
 
          <revremark>fom text into howto</revremark>
61
 
        </revision>
62
 
        <revision>
63
 
          <revnumber>1.2</revnumber>
64
 
          <date>2003-10-17</date>
65
 
          <authorinitials>HL</authorinitials>
66
 
          <revremark>fom txt reformatted into SGML</revremark>
67
 
        </revision>
68
 
       </revhistory>
69
 
 
70
 
       <legalnotice>
71
 
         <para>This document is copyright Lincoln Stein, 2002.  For
72
 
           reproduction other than personal use please contact lstein at cshl.org
73
 
         </para>
74
 
       </legalnotice>
75
 
 
76
 
      <abstract>
77
 
        <para>
78
 
          The Open Biological Database Access (OBDA) standard
79
 
          specifies a way of generating indexes for entry-based
80
 
          sequence files (e.g. FASTA, EMBL) so that the entries can be
81
 
          looked up and retrieved quickly.  These indexes are created
82
 
          and accessed using the <classname>Bio::DB::Flat</classname>
83
 
          module.
84
 
        </para>
85
 
      </abstract>
86
 
    </articleinfo>
87
 
<section id="intro">
88
 
<title>Creating OBDA-Compliant Indexed Sequence Files</title>
89
 
 
90
 
  <para>
91
 
    <classname>Bio::DB::Flat</classname> has the same functionality as
92
 
    the various <classname>Bio::Index</classname> modules.  The main
93
 
    reason to use it is if you want to use the BioSequence Registry
94
 
    system (see the OBDA Access HOWTO at <ulink
95
 
    url="http://bioperl.org/HOWTOs">http://bioperl.org/HOWTOs</ulink>),
96
 
    or if you want to share the same indexed files among scripts
97
 
    written in other languages, such as those written with BioJava or
98
 
    BioPython.
99
 
  </para>
100
 
 
101
 
  <para>
102
 
    There are four steps to creating a
103
 
    <classname>Bio::DB::Flat</classname> database:
104
 
  </para>
105
 
 
106
 
  <orderedlist>
107
 
    <listitem>
108
 
      <para>Select a Root Directory</para>
109
 
 
110
 
  <para>
111
 
    Select a directory in which the flat file indexes will be stored.
112
 
    This directory should be writable by you, and readable by everyone
113
 
    who will be running applications that access the sequence data.
114
 
  </para>
115
 
    </listitem>
116
 
    <listitem><para>Move the Flat Files Into a Good Location</para>
117
 
 
118
 
  <para>
119
 
    The indexer records the path to the source files (e.g. FASTA, or
120
 
    local copies of GenBank, Embl or SwissProt).  This means that you
121
 
    must not change the location or name of the source files after
122
 
    running the indexer.  Pick a good stable location for the source
123
 
    files and move them there.
124
 
  </para>
125
 
    </listitem>
126
 
 
127
 
    <listitem><para>Choose a Symbolic Name for the Database</para>
128
 
 
129
 
  <para>
130
 
    Choose a good symbolic name for the database.  For example, if you
131
 
    are mirroring GenBank, "genbank" might be a good choice.  The
132
 
    indexer will create files in a subdirectory by this name located
133
 
    underneath the root directory.
134
 
  </para>
135
 
    </listitem>
136
 
    <listitem><para>Run the bioflat_index.pl script to load the
137
 
        sequence files into the database.</para>
138
 
 
139
 
        <para>
140
 
          The final step is to run the bioflat_index.PLS script.  This
141
 
          script is located in the BioPerl distribution, under scripts/DB.
142
 
          For convenience, you are offered the option to copy it to
143
 
          /usr/bin or another system-wide directory on 'make install' (and
144
 
          its name will be changed to bioflat_index.pl).
145
 
        </para>
146
 
      </listitem>
147
 
    </orderedlist>
148
 
 
149
 
 </section>
150
 
 
151
 
 <section id="options">
152
 
      <title>Choosing Your Options</title>
153
 
 
154
 
  <para>
155
 
     The first time you run the script, the typical usage is as
156
 
     follows:
157
 
    <programlisting>
158
 
     bioflat_index.pl -c -l /usr/share/biodb -d genbank -i bdb -f fasta data/*.fa
159
 
    </programlisting>
160
 
 
161
 
     The following command line options are required:
162
 
 
163
 
       <table>
164
 
        <title></title>
165
 
        <tgroup cols="2">
166
 
          <thead>
167
 
             <row>
168
 
                <entry>Option</entry>
169
 
                <entry>Describtion</entry>
170
 
             </row>
171
 
         </thead>
172
 
         <tbody>
173
 
              <row>
174
 
                 <entry>-c</entry>
175
 
                 <entry>create a new index</entry>
176
 
              </row>
177
 
              <row>
178
 
                 <entry>-l</entry>
179
 
                 <entry>path to the root directory</entry>
180
 
              </row>
181
 
              <row>
182
 
                 <entry>-d</entry>
183
 
                 <entry>symbolic name for the new database</entry>
184
 
              </row>
185
 
              <row>
186
 
                 <entry>-i</entry>
187
 
                 <entry>indexing scheme (discussed below)</entry>
188
 
              </row>
189
 
              <row>
190
 
                 <entry>-f</entry>
191
 
                  <entry>source file format</entry>
192
 
              </row>
193
 
          </tbody>
194
 
         </tgroup>
195
 
        </table>
196
 
 
197
 
  </para>
198
 
 
199
 
  <para>
200
 
    The <parameter>-c</parameter> option must be present to create the
201
 
    database.  If the database already exists,
202
 
    <parameter>-c</parameter> will reinitialize the index, wiping out
203
 
    its current contents.
204
 
  </para>
205
 
 
206
 
  <para>
207
 
    The <parameter>-l</parameter> option specifies the root directory
208
 
    for the database indexes.
209
 
  </para>
210
 
 
211
 
  <para>
212
 
    The <parameter>-d</parameter> option chooses the symbolic name for
213
 
    the new database.  If the <parameter>-c</parameter> option is
214
 
    specified, this will cause a new directory to be created
215
 
    underneath the root directory.
216
 
  </para>
217
 
 
218
 
    <para>
219
 
      The <parameter>-i</parameter> option selects the indexing scheme.  
220
 
      Currently there are two indexing schemes supported: "bdb" and
221
 
      "flat."  "bdb" selects an index based on the Berkeley DB library.  
222
 
      It is generally the faster of the two, but it requires that the
223
 
      Berkeley DB library (from Linux RPM or from www.sleepycat.com, 
224
 
      version 2 or higher) and the Perl BerkeleyDB module be installed 
225
 
      on your system. The Perl DB_File module will not work.
226
 
    </para>
227
 
    <para>
228
 
      "flat" is a sorted text-based index that uses a binary search algorithm to
229
 
      rapidly search for entries.  Although not as fast as bdb, the flat
230
 
      indexing system has good performance for even large databases, and
231
 
      it has no requirements beyond Perl itself.  Once an indexing
232
 
      scheme has been selected there is no way to change it other than
233
 
      recreating the index from scratch using the
234
 
      <parameter>-c</parameter> option.
235
 
  </para>
236
 
 
237
 
  <para>
238
 
    The <parameter>-f</parameter> option specifies the format of the
239
 
    source database files.  It must be one of the many formats that BioPerl
240
 
    supports, including "genbank", "swiss", "embl" or "fasta".
241
 
    Consult the <classname>Bio::SeqIO</classname> documentation for
242
 
    the complete list.  All files placed in the index must share the
243
 
    same format.
244
 
  </para>
245
 
 
246
 
  <para>
247
 
    The indexing script will print out a progress message every 1000
248
 
    entries, and will report the number of entries successfully
249
 
    indexed at the end of its run.
250
 
  </para>
251
 
 
252
 
  <para>
253
 
    To update an existing index run bioflat_index.pl without the
254
 
    <parameter>-c</parameter> option and list the files to be added or
255
 
    reindexed.  The <parameter>-l</parameter> and
256
 
    <parameter>-d</parameter> options are required, but the indexing
257
 
    scheme and source file format do not have to be specified for
258
 
    updating as they will be read from the existing index.
259
 
  </para>
260
 
 
261
 
  <para>
262
 
    For your convenience, bioflat_index.pl will also take default values
263
 
    from the following environment variables:
264
 
 
265
 
       <table>
266
 
        <title></title>
267
 
        <tgroup cols="2">
268
 
          <thead>
269
 
             <row>
270
 
                <entry>ENV variable</entry>
271
 
                <entry>description</entry>
272
 
             </row>
273
 
         </thead>
274
 
         <tbody>
275
 
              <row>
276
 
                 <entry>OBDA_FORMAT</entry>
277
 
                 <entry>format of sequence file (<parameter>-f</parameter>)
278
 
                 </entry>
279
 
              </row>
280
 
              <row>
281
 
                 <entry>OBDA_LOCATION</entry> <entry>path to directory
282
 
                 in which index files are stored
283
 
                 (<parameter>-l</parameter>)
284
 
                 </entry>
285
 
              </row>
286
 
              <row>
287
 
                 <entry>OBDA_DBNAME</entry>
288
 
                 <entry>name of database (-d)</entry>
289
 
              </row>
290
 
              <row>
291
 
                 <entry>OBDA_INDEX</entry>
292
 
                 <entry>type of index to create (<parameter>-i</parameter>)</entry>
293
 
              </row>
294
 
          </tbody>
295
 
         </tgroup>
296
 
        </table>
297
 
  </para>
298
 
 </section>
299
 
 
300
 
  <section id="files">
301
 
      <title>Moving Database Files</title>  
302
 
  <para>
303
 
    If you must change the location of the source sequence files after
304
 
    you create the index, there is a way to do so.  Inside the root
305
 
    directory you will find a subdirectory named after the database,
306
 
    and inside that you will find a text file named "config.dat."  An
307
 
    example config.dat is shown here:
308
 
    <programlisting>
309
 
     index      flat/1
310
 
     fileid_0   /share/data/alnfile.fasta       294
311
 
     fileid_1   /share/data/genomic-seq.fasta   171524
312
 
     fileid_2   /share/data/hs_owlmonkey.fasta  416
313
 
     fileid_3   /share/data/test.fasta  804
314
 
     fileid_4   /share/data/testaln.fasta       4620
315
 
     primary_namespace  ACC
316
 
     secondary_namespaces       ID
317
 
     format     URN:LSID:open-bio.org:fasta
318
 
    </programlisting>
319
 
  </para>
320
 
 
321
 
  <para>
322
 
    For each source file you have moved, find its corresponding
323
 
    "fileid" line and change the path.  Be careful not to change
324
 
    anything else in the file or to inadvertently replace tab
325
 
    characters with spaces.
326
 
  </para>
327
 
 </section id="more">
328
 
  <title>More information</title>
329
 
  <section>
330
 
    <para>
331
 
      For more information on using your indexed flat files please see the 
332
 
      <ulink url="http://bioperl.org/HOWTOs/html/OBDA_Access.html">
333
 
      OBDA Access HOWTO</ulink>.
334
 
     </para>
335
 
  </section>
336
 
</article>