--- name: "Bio::DB::Flat::BinarySearch" section: "3pm" platform: "linux" package: "libbio-perl-perl" version: "1.7.8-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Bio::DB::Flat::BinarySearch" --- # Bio::DB::Flat::BinarySearch(3pm) BinarySearch search indexing system for sequence files ## NAME Bio::DB::Flat::BinarySearch - BinarySearch search indexing system for sequence files ## SYNOPSIS ``` TODO: SYNOPSIS NEEDED! ``` ## DESCRIPTION This module can be used both to index sequence files and also to retrieve sequences from existing sequence files. This object allows indexing of sequence files both by a primary key (say accession) and multiple secondary keys (say ids). This is different from the Bio::Index::Abstract (see Bio::Index::Abstract) which uses DBM files as storage. This module uses a binary search to retrieve sequences which is more efficient for large datasets. ### Index creation ``` my $sequencefile; # Some fasta sequence file ``` Patterns have to be entered to define where the keys are to be indexed and also where the start of each record. E.g. for fasta ``` my $start_pattern = '^>'; my $primary_pattern = '^>(\S+)'; ``` So the start of a record is a line starting with a \> and the primary key is all characters up to the first space after the \> A string also has to be entered to defined what the primary key (primary\_namespace) is called. The index can now be created using ``` my $index = Bio::DB::Flat::BinarySearch->new( -directory => "/home/max/", -dbname => "mydb", -start_pattern => $start_pattern, -primary_pattern => $primary_pattern, -primary_namespace => "ID", -format => "fasta" ); my @files = ("file1","file2","file3"); $index->build_index(@files); ``` The index is now ready to use. For large sequence files the perl way of indexing takes a \*long\* time and a \*huge\* amount of memory. For indexing things like dbEST I recommend using the DB\_File indexer, BDB. The formats currently supported by this module are fasta, Swissprot, and EMBL. ### Creating indices with secondary keys Sometimes just indexing files with one id per entry is not enough. For instance you may want to retrieve sequences from swissprot using their accessions as well as their ids. To be able to do this when creating your index you need to pass in a hash of secondary\_patterns which have their namespaces as the keys to the hash. e.g. For Indexing something like ID 1433\_CAEEL STANDARD; PRT; 248 AA. AC P41932; DT 01-NOV-1995 (Rel. 32, Created) DT 01-NOV-1995 (Rel. 32, Last sequence update) DT 15-DEC-1998 (Rel. 37, Last annotation update) DE 14-3-3-LIKE PROTEIN 1. GN FTT-1 OR M117.2. OS Caenorhabditis elegans. OC Eukaryota; Metazoa; Nematoda; Chromadorea; Rhabditida; Rhabditoidea; OC Rhabditidae; Peloderinae; Caenorhabditis. OX NCBI\_TaxID=6239; RN \[1\] where we want to index the accession (P41932) as the primary key and the id (1433\_CAEEL) as the secondary id. The index is created as follows ``` my %secondary_patterns; my $start_pattern = '^ID (\S+)'; my $primary_pattern = '^AC (\S+)\;'; $secondary_patterns{"ID"} = '^ID (\S+)'; my $index = Bio::DB::Flat::BinarySearch->new( -directory => $index_directory, -dbname => "ppp", -write_flag => 1, -verbose => 1, -start_pattern => $start_pattern, -primary_pattern => $primary_pattern, -primary_namespace => 'AC', -secondary_patterns => \%secondary_patterns); $index->build_index($seqfile); ``` Of course having secondary indices makes indexing slower and use more memory. ### Index reading To fetch sequences using an existing index first of all create your sequence object ``` my $index = Bio::DB::Flat::BinarySearch->new( -directory => $index_directory); ``` Now you can happily fetch sequences either by the primary key or by the secondary keys. ``` my $entry = $index->get_entry_by_id('HBA_HUMAN'); ``` This returns just a string containing the whole entry. This is useful is you just want to print the sequence to screen or write it to a file. Other ways of getting sequences are ``` my $fh = $index->get_stream_by_id('HBA_HUMAN'); ``` This can then be passed to a seqio object for output or converting into objects. ``` my $seq = Bio::SeqIO->new(-fh => $fh, -format => 'fasta'); ``` The last way is to retrieve a sequence directly. This is the slowest way of extracting as the sequence objects need to be made. ``` my $seq = $index->get_Seq_by_id('HBA_HUMAN'); ``` To access the secondary indices the secondary namespace needs to be known ``` $index->secondary_namespaces("ID"); ``` Then the following call can be used ``` my $seq = $index->get_Seq_by_secondary('ID','1433_CAEEL'); ``` These calls are not yet implemented ``` my $fh = $index->get_stream_by_secondary('ID','1433_CAEEL'); my $entry = $index->get_entry_by_secondary('ID','1433_CAEEL'); ``` ## 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: ``` https://github.com/bioperl/bioperl-live/issues ``` ## AUTHOR - Michele Clamp Email - michele@sanger.ac.uk ## CONTRIBUTORS Jason Stajich, jason@bioperl.org ## APPENDIX The rest of the documentation details each of the object methods. Internal methods are usually preceded with an "\_" (underscore). ### new ``` Title : new Usage : For reading my $index = Bio::DB::Flat::BinarySearch->new( -directory => '/Users/michele/indices/dbest', -dbname => 'mydb', -format => 'fasta'); For writing my %secondary_patterns = {"ACC" => "^>\\S+ +(\\S+)"} my $index = Bio::DB::Flat::BinarySearch->new( -directory => '/Users/michele/indices', -dbname => 'mydb', -primary_pattern => "^>(\\S+)", -secondary_patterns => \%secondary_patterns, -primary_namespace => "ID"); my @files = ('file1','file2','file3'); $index->build_index(@files); Function: create a new Bio::DB::Flat::BinarySearch object Returns : new Bio::DB::Flat::BinarySearch Args : -directory Root directory for index files -dbname Name of subdirectory containing indices for named database -write_flag Allow building index -primary_pattern Regexp defining the primary id -secondary_patterns A hash ref containing the secondary patterns with the namespaces as keys -primary_namespace A string defining what the primary key is Status : Public ``` ### get\_Seq\_by\_id ``` Title : get_Seq_by_id Usage : $obj->get_Seq_by_id($newval) Function: Example : Returns : value of get_Seq_by_id Args : newvalue (optional) ``` ### get\_entry\_by\_id ``` Title : get_entry_by_id Usage : $obj->get_entry_by_id($newval) Function: Get a Bio::SeqI object for a unique ID Returns : Bio::SeqI Args : string ``` ### get\_stream\_by\_id ``` Title : get_stream_by_id Usage : $obj->get_stream_by_id($id) Function: Gets a Sequence stream for an id Returns : Bio::SeqIO stream Args : Id to lookup by ``` ### get\_Seq\_by\_acc ``` Title : get_Seq_by_acc Usage : $obj->get_Seq_by_acc($acc) Function: Gets a Bio::SeqI object by accession number Returns : Bio::SeqI object Args : string representing accession number ``` ### get\_Seq\_by\_version ``` Title : get_Seq_by_version Usage : $obj->get_Seq_by_version($version) Function: Gets a Bio::SeqI object by accession.version number Returns : Bio::SeqI object Args : string representing accession.version number ``` ### get\_Seq\_by\_secondary ``` Title : get_Seq_by_secondary Usage : $obj->get_Seq_by_secondary($namespace,$acc) Function: Gets a Bio::SeqI object looking up secondary accessions Returns : Bio::SeqI object Args : namespace name to check secondary namespace and an id ``` ### read\_header ``` Title : read_header Usage : $obj->read_header($fhl) Function: Reads the header from the db file Returns : width of a record Args : filehandle ``` ### read\_record ``` Title : read_record Usage : $obj->read_record($fh,$pos,$len) Function: Reads a record from a filehandle Returns : String Args : filehandle, offset, and length ``` ### get\_all\_primary\_ids ``` Title : get_all_primary_ids Usage : @ids = $seqdb->get_all_primary_ids() Function: gives an array of all the primary_ids of the sequence objects in the database. Returns : an array of strings Args : none ``` ### find\_entry ``` Title : find_entry Usage : $obj->find_entry($fh,$start,$end,$id,$recsize) Function: Extract an entry based on the start,end,id and record size Returns : string Args : filehandle, start, end, id, recordsize ``` ### build\_index ``` Title : build_index Usage : $obj->build_index(@files) Function: Build the index based on a set of files Returns : count of the number of entries Args : List of filenames ``` ### \_index\_file ``` Title : _index_file Usage : $obj->_index_file($newval) Function: Example : Returns : value of _index_file Args : newvalue (optional) ``` ### write\_primary\_index ``` Title : write_primary_index Usage : $obj->write_primary_index($newval) Function: Example : Returns : value of write_primary_index Args : newvalue (optional) ``` ### write\_secondary\_indices ``` Title : write_secondary_indices Usage : $obj->write_secondary_indices($newval) Function: Example : Returns : value of write_secondary_indices Args : newvalue (optional) ``` ### new\_secondary\_filehandle ``` Title : new_secondary_filehandle Usage : $obj->new_secondary_filehandle($newval) Function: Example : Returns : value of new_secondary_filehandle Args : newvalue (optional) ``` ### open\_secondary\_index ``` Title : open_secondary_index Usage : $obj->open_secondary_index($newval) Function: Example : Returns : value of open_secondary_index Args : newvalue (optional) ``` ### \_add\_id\_position ``` Title : _add_id_position Usage : $obj->_add_id_position($newval) Function: Example : Returns : value of _add_id_position Args : newvalue (optional) ``` ### make\_config\_file ``` Title : make_config_file Usage : $obj->make_config_file($newval) Function: Example : Returns : value of make_config_file Args : newvalue (optional) ``` ### read\_config\_file ``` Title : read_config_file Usage : $obj->read_config_file($newval) Function: Example : Returns : value of read_config_file Args : newvalue (optional) ``` ### get\_fileid\_by\_filename ``` Title : get_fileid_by_filename Usage : $obj->get_fileid_by_filename($newval) Function: Example : Returns : value of get_fileid_by_filename Args : newvalue (optional) ``` ### get\_filehandle\_by\_fileid ``` Title : get_filehandle_by_fileid Usage : $obj->get_filehandle_by_fileid($newval) Function: Example : Returns : value of get_filehandle_by_fileid Args : newvalue (optional) ``` ### primary\_index\_file ``` Title : primary_index_file Usage : $obj->primary_index_file($newval) Function: Example : Returns : value of primary_index_file Args : newvalue (optional) ``` ### primary\_index\_filehandle ``` Title : primary_index_filehandle Usage : $obj->primary_index_filehandle($newval) Function: Example : Returns : value of primary_index_filehandle Args : newvalue (optional) ``` ### format ``` Title : format Usage : $obj->format($newval) Function: Example : Returns : value of format Args : newvalue (optional) ``` ### write\_flag ``` Title : write_flag Usage : $obj->write_flag($newval) Function: Example : Returns : value of write_flag Args : newvalue (optional) ``` ### dbname ``` Title : dbname Usage : $obj->dbname($newval) Function: get/set database name Example : Returns : value of dbname Args : newvalue (optional) ``` ### index\_directory ``` Title : index_directory Usage : $obj->index_directory($newval) Function: Example : Returns : value of index_directory Args : newvalue (optional) ``` ### record\_size ``` Title : record_size Usage : $obj->record_size($newval) Function: Example : Returns : value of record_size Args : newvalue (optional) ``` ### primary\_namespace ``` Title : primary_namespace Usage : $obj->primary_namespace($newval) Function: Example : Returns : value of primary_namespace Args : newvalue (optional) ``` ### index\_type ``` Title : index_type Usage : $obj->index_type($newval) Function: Example : Returns : value of index_type Args : newvalue (optional) ``` ### index\_version ``` Title : index_version Usage : $obj->index_version($newval) Function: Example : Returns : value of index_version Args : newvalue (optional) ``` ### primary\_pattern ``` Title : primary_pattern Usage : $obj->primary_pattern($newval) Function: Example : Returns : value of primary_pattern Args : newvalue (optional) ``` ### start\_pattern ``` Title : start_pattern Usage : $obj->start_pattern($newval) Function: Example : Returns : value of start_pattern Args : newvalue (optional) ``` ### secondary\_patterns ``` Title : secondary_patterns Usage : $obj->secondary_patterns($newval) Function: Example : Returns : value of secondary_patterns Args : newvalue (optional) ``` ### secondary\_namespaces ``` Title : secondary_namespaces Usage : $obj->secondary_namespaces($newval) Function: Example : Returns : value of secondary_namespaces Args : newvalue (optional) ```