Bio::Index::Abstract.3pm

Langue: en

Version: 2010-05-19 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

NAME

Bio::Index::Abstract - Abstract interface for indexing a flat file

SYNOPSIS

You should not be using this module directly

USING DB_FILE

To use DB_File and not SDBM for this index, pass the value:
     -dbm_package => 'DB_File'
 
 

to new (see below).

DESCRIPTION

This object provides the basic mechanism to associate positions in files with names. The position and filenames are stored in DBM which can then be accessed later on. It is the equivalent of flat file indexing (eg, SRS or efetch).

This object is the guts to the mechanism, which will be used by the specific objects inheriting from it.

FEEDBACK

Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.
   bioperl-l@bioperl.org                  - General discussion
   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 
 

Support

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible.

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via the web:
   http://bugzilla.open-bio.org/
 
 

AUTHOR - Ewan Birney, James Gilbert

Email - birney@sanger.ac.uk, jgrg@sanger.ac.uk

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with an ``_'' (underscore).

new

   Usage   : $index = Bio::Index::Abstract->new(
                 -filename    => $dbm_file,
                 -write_flag  => 0,
                 -dbm_package => 'DB_File',
                 -verbose     => 0);
   Function: Returns a new index object.  If filename is
             specified, then open_dbm() is immediately called. 
             Bio::Index::Abstract->new() will usually be called
             directly only when opening an existing index.
   Returns : A new index object
   Args    : -filename    The name of the dbm index file.
             -write_flag  TRUE if write access to the dbm file is
                          needed.
             -dbm_package The Perl dbm module to use for the
                          index.
             -verbose     Print debugging output to STDERR if
                          TRUE.
 
 

filename

  Title   : filename
  Usage   : $value = $self->filename();
            $self->filename($value);
  Function: Gets or sets the name of the dbm index file.
  Returns : The current value of filename
  Args    : Value of filename if setting, or none if
            getting the value.
 
 

write_flag

  Title   : write_flag
  Usage   : $value = $self->write_flag();
            $self->write_flag($value);
  Function: Gets or sets the value of write_flag, which
            is wether the dbm file should be opened with
            write access.
  Returns : The current value of write_flag (default 0)
  Args    : Value of write_flag if setting, or none if
            getting the value.
 
 

dbm_package

  Usage   : $value = $self->dbm_package();
            $self->dbm_package($value);
 
  Function: Gets or sets the name of the Perl dbm module used. 
            If the value is unset, then it returns the value of
            the package variable $USE_DBM_TYPE or if that is
            unset, then it chooses the best available dbm type,
            choosing 'DB_File' in preference to 'SDBM_File'. 
            Bio::Abstract::Index may work with other dbm file
            types.
 
  Returns : The current value of dbm_package
  Args    : Value of dbm_package if setting, or none if
            getting the value.
 
 

db

   Title   : db
   Usage   : $index->db
   Function: Returns a ref to the hash which is tied to the dbm
             file.  Used internally when adding and retrieving
             data from the database.
   Example : $db = $index->db();
             $db->{ $some_key } = $data
             $data = $index->db->{ $some_key };
   Returns : ref to HASH
   Args    : NONE
 
 

get_stream

  Title   : get_stream
  Usage   : $stream = $index->get_stream( $id );
  Function: Returns a file handle with the file pointer
            at the approprite place
 
            This provides for a way to get the actual
            file contents and not an object 
 
            WARNING: you must parse the record deliminter
            *yourself*. Abstract wont do this for you 
            So this code
 
            $fh = $index->get_stream($myid);
            while( <$fh> ) {
               # do something
            }
            will parse the entire file if you don't put in
            a last statement in, like
 
            while( <$fh> ) {
               /^\/\// && last; # end of record
               # do something
            }
 
  Returns : A filehandle object
  Args    : string represents the accession number
  Notes   : This method should not be used without forethought
 
 

cachesize

   Usage   : $index->cachesize(1000000)
   Function: Sets the dbm file cache size for the index.
             Needs to be set before the DBM file gets opened.
   Example : $index->cachesize(1000000)
   Returns : size of the curent cache
 
 

ffactor

   Usage   : $index->ffactor(1000000)
   Function: Sets the dbm file fill factor.
                         Needs to be set before the DBM file gets opened.
 
   Example : $index->ffactor(1000000)
   Returns : size of the curent cache
 
 

open_dbm

   Usage   : $index->open_dbm()
   Function: Opens the dbm file associated with the index
             object.  Write access is only given if explicitly
             asked for by calling new(-write => 1) or having set
             the write_flag(1) on the index object.  The type of
             dbm file opened is that returned by dbm_package(). 
             The name of the file to be is opened is obtained by
             calling the filename() method.
 
   Example : $index->_open_dbm()
   Returns : 1 on success
 
 

_version

   Title   : _version
   Usage   : $type = $index->_version()
   Function: Returns a string which identifes the version of an
             index module.  Used to permanently identify an index
             file as having been created by a particular version
             of the index module.  Must be provided by the sub class
   Example : 
   Returns : 
   Args    : none
 
 

_code_base

  Title   : _code_base
  Usage   : $code = $db->_code_base();
  Function:
  Example :
  Returns : Code package to be used with this 
  Args    :
 
 

_type_and_version

   Title   : _type_and_version
   Usage   : Called by _initalize
   Function: Checks that the index opened is made by the same index
             module and version of that module that made it.  If the
             index is empty, then it adds the information to the
             database.
   Example : 
   Returns : 1 or exception
   Args    : none
 
 

_check_file_sizes

   Title   : _check_file_sizes
   Usage   : $index->_check_file_sizes()
   Function: Verifies that the files listed in the database
             are the same size as when the database was built,
             or throws an exception.  Called by the new()
             function.
   Example : 
   Returns : 1 or exception
   Args    :
 
 

make_index

   Title   : make_index
   Usage   : $index->make_index( FILE_LIST )
   Function: Takes a list of file names, checks that they are
             all fully qualified, and then calls _filename() on
             each.  It supplies _filename() with the name of the
             file, and an integer which is stored with each record
             created by _filename().  Can be called multiple times,
             and can be used to add to an existing index file.
   Example : $index->make_index( '/home/seqs1', '/home/seqs2', '/nfs/pub/big_db' );
   Returns : Number of files indexed
   Args    : LIST OF FILES
 
 

pathtype

   Title   : pathtype
   Usage   : $index->pathtype($pathtype)
   Function: Set the type of the file path
             Only two values are supported, 'relative' or 'absolute'.
             If the user does not give any value, it is set to
             absolute by default. Thus it mimics the default
             behavior of Bio::Index::Abstract module.
   Example : my $index = Bio::Index::Abstract->(-pathtype => 'relative',
                                                -file     => $file.inx,
                                               );
             or
             $index->pathtype('relative');
   Returns : Type of the path.
   Args    : String (relative|absolute)
 
 

_filename

   Title   : _filename
   Usage   : $index->_filename( FILE INT )
   Function: Indexes the file
   Example : 
   Returns : 
   Args    :
 
 

_file_handle

   Title   : _file_handle
   Usage   : $fh = $index->_file_handle( INT )
   Function: Returns an open filehandle for the file
             index INT.  On opening a new filehandle it
             caches it in the @{$index->_filehandle} array.
             If the requested filehandle is already open,
             it simply returns it from the array.
   Example : $fist_file_indexed = $index->_file_handle( 0 );
   Returns : ref to a filehandle
   Args    : INT
 
 

_file_count

   Title   : _file_count
   Usage   : $index->_file_count( INT )
   Function: Used by the index building sub in a sub class to
             track the number of files indexed.  Sets or gets
             the number of files indexed when called with or
             without an argument.
   Example : 
   Returns : INT
   Args    : INT
 
 

add_record

   Title   : add_record
   Usage   : $index->add_record( $id, @stuff );
   Function: Calls pack_record on @stuff, and adds the result
             of pack_record to the index database under key $id.
             If $id is a reference to an array, then a new entry
             is added under a key corresponding to each element
             of the array.
   Example : $index->add_record( $id, $fileNumber, $begin, $end )
   Returns : TRUE on success or FALSE on failure
   Args    : ID LIST
 
 

pack_record

   Title   : pack_record
   Usage   : $packed_string = $index->pack_record( LIST )
   Function: Packs an array of scalars into a single string
             joined by ASCII 034 (which is unlikely to be used
             in any of the strings), and returns it. 
   Example : $packed_string = $index->pack_record( $fileNumber, $begin, $end )
   Returns : STRING or undef
   Args    : LIST
 
 

unpack_record

   Title   : unpack_record
   Usage   : $index->unpack_record( STRING )
   Function: Splits the sting provided into an array,
             splitting on ASCII 034.
   Example : ( $fileNumber, $begin, $end ) = $index->unpack_record( $self->db->{$id} )
   Returns : A 3 element ARRAY
   Args    : STRING containing ASCII 034
 
 

count_records

  Title   : count_records
  Usage   : $recs = $seqdb->count_records()
  Function: return count of all recs in the index 
  Example :
  Returns : a scalar
  Args    : none
 
 

DESTROY

  Title   : DESTROY
  Usage   : Called automatically when index goes out of scope
  Function: Closes connection to database and handles to
            sequence files
  Returns : NEVER
  Args    : NONE