Bio::Index::Abstract

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 AT bioperl DOT 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 AT bioperl DOT 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:

https://github.com/bioperl/bioperl-live/issues

AUTHOR - Ewan Birney, James Gilbert

Email - birney AT sanger DOT ac DOT uk, jgrg AT sanger DOT ac DOT 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 whether 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 won't 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 : $first_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