Bio::D...IHelper(3pm)

📦
version 1.7.8 · 2 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Bio::DB::NCBIHelper 💖

okay bestie, so this is Bio::DB::NCBIHelper from the User Contributed Perl Documentation, and it's literally a whole collection of routines that are useful for queries to NCBI databases. no cap.

✨ NAME ✨

Bio::DB::NCBIHelper — a collection of routines useful for queries to NCBI databases. 🧬

🌸 SYNOPSIS 🌸

bestie please do NOT use this module directly, i'm begging 🙈
# Do not use this module directly.

# get a Bio::DB::NCBIHelper object somehow
my $seqio = $db->get_Stream_by_acc(['J00522']);
foreach my $seq ( $seqio->next_seq ) {
    # process seq
}

🦋 DESCRIPTION 🦋

okay so this module is the one single place where all the common methods for querying NCBI web databases get set up. it's giving centralization energy. 💅

basically it pulls together the methods for:

  • constructing a URL for querying NCBI GenBank and NCBI GenPept
  • the common HTML stripping that happens inside postprocess_data()

the base NCBI query URL used is:

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi

so yeah, that's the whole vibe. 🌈

📬 FEEDBACK 📬

💌 Mailing Lists

user feedback is an integral part of the evolution of this and other Bioperl modules — fr fr, they actually want to hear from you. send your comments and suggestions preferably to one of the Bioperl mailing lists. your participation is much appreciated, bestie 🫶

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 responsive experts will be able to 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. the more detail the better, that's the assignment. ✨

🐛 Reporting Bugs

report bugs to the Bioperl bug tracking system to help them keep track of the bugs and their resolution. bug reports can be submitted via the web.

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

👑 AUTHOR - Jason Stajich 👑

Email jason@bioperl.org

📖 APPENDIX 📖

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ (iykyk 👀)

🎀 new

Title   : new
Usage   :
Function: the new way to make modules a little more lightweight
Returns :
Args    :

🎀 get_params

Title   : get_params
Usage   : my %params = $self->get_params($mode)
Function: returns key,value pairs to be passed to NCBI database
          for either 'batch' or 'single' sequence retrieval method
Returns : a key,value pair hash
Args    : 'single' or 'batch' mode for retrieval

🎀 default_format

Title   : default_format
Usage   : my $format = $self->default_format
Function: returns default sequence format for this module
Returns : string
Args    : none

🎀 get_request

Title   : get_request
Usage   : my $url = $self->get_request
Function: HTTP::Request
Returns :
Args    : %qualifiers = a hash of qualifiers (ids, format, etc)

🎀 get_seq_stream

Title   : get_seq_stream
Usage   : my $seqio = $self->get_seq_stream(%qualifiers)
Function: builds a url and queries a web db
Returns : a Bio::SeqIO stream capable of producing sequence
Args    : %qualifiers = a hash qualifiers that the implementing class
          will process to make a url suitable for web querying

🎀 get_Stream_by_batch

 Title   : get_Stream_by_batch
 Usage   : $seq = $db->get_Stream_by_batch($ref);
 Function: Retrieves Seq objects from Entrez 'en masse', rather than one
           at a time.  For large numbers of sequences, this is far superior
           than get_Stream_by_id or get_Stream_by_acc.
 Example :
 Returns : a Bio::SeqIO stream object
 Args    : $ref : either an array reference, a filename, or a filehandle
           from which to get the list of unique ids/accession numbers.

           NOTE: deprecated API.  Use get_Stream_by_id() instead.
⚠️ bestie, this one is a deprecated API — use get_Stream_by_id() instead. 💀

🎀 get_Stream_by_query

 Title   : get_Stream_by_query
 Usage   : $seq = $db->get_Stream_by_query($query);
 Function: Retrieves Seq objects from Entrez 'en masse', rather than one
           at a time.  For large numbers of sequences, this is far superior
           to get_Stream_by_id and get_Stream_by_acc.
 Example :
 Returns : a Bio::SeqIO stream object
 Args    : An Entrez query string or a Bio::DB::Query::GenBank object.
           It is suggested that you create a Bio::DB::Query::GenBank object and get
           the entry count before you fetch a potentially large stream.

🎀 postprocess_data

Title   : postprocess_data
Usage   : $self->postprocess_data ( 'type' => 'string',
                                                                    'location' => \$datastr );
Function: Process downloaded data before loading into a Bio::SeqIO. This
          works for Genbank and Genpept, other classes should override
          it with their own method.
Returns : void
Args    : hash with two keys:

          'type' can be 'string' or 'file'
          'location' either file location or string reference containing data

🎀 request_format

Title   : request_format
Usage   : my ($req_format, $ioformat) = $self->request_format;
          $self->request_format("genbank");
          $self->request_format("fasta");
Function: Get/Set sequence format retrieval. The get-form will normally not
          be used outside of this and derived modules.
Returns : Array of two strings, the first representing the format for
          retrieval, and the second specifying the corresponding SeqIO format.
Args    : $format = sequence format

🎀 redirect_refseq

Title   : redirect_refseq
Usage   : $db->redirect_refseq(1)
Function: simple getter/setter which redirects RefSeqs to use Bio::DB::RefSeq
Returns : Boolean value
Args    : Boolean value (optional)
Throws  : 'unparseable output exception'
Note    : This replaces 'no_redirect' as a more straightforward flag to
          redirect possible RefSeqs to use Bio::DB::RefSeq (EBI interface)
          instead of retrieving the NCBI records

🎀 complexity

Title   : complexity
Usage   : $db->complexity(3)
Function: get/set complexity value
Returns : value from 0-4 indicating level of complexity
Args    : value from 0-4 (optional); if unset server assumes 1
Throws  : if arg is not an integer or falls outside of noted range above
Note    : From efetch docs, the complexity regulates the display:

          0 - get the whole blob
          1 - get the bioseq for gi of interest (default in Entrez)
          2 - get the minimal bioseq-set containing the gi of interest
          3 - get the minimal nuc-prot containing the gi of interest
          4 - get the minimal pub-set containing the gi of interest

🎀 strand

Title   : strand
Usage   : $db->strand(1)
Function: get/set strand value
Returns : strand value if set
Args    : value of 1 (plus) or 2 (minus); if unset server assumes 1
Throws  : if arg is not an integer or is not 1 or 2
Note    : This differs from BioPerl's use of strand: 1 = plus, -1 = minus 0 = not relevant.
          We should probably add in some functionality to convert over in the future.

🎀 seq_start

Title   : seq_start
Usage   : $db->seq_start(123)
Function: get/set sequence start location
Returns : sequence start value if set
Args    : integer; if unset server assumes 1
Throws  : if arg is not an integer

🎀 seq_stop

Title   : seq_stop
Usage   : $db->seq_stop(456)
Function: get/set sequence stop (end) location
Returns : sequence stop (end) value if set
Args    : integer; if unset server assumes 1
Throws  : if arg is not an integer

🎀 email

Title   : email
Usage   : $db->email('foo@bar.edu')
Function: get/set email value
Returns : email (string)  or undef
Args    : string with a valid email address; note we do not vallidate this
          currently!
Throws  : if arg is not an integer or falls outside of noted range above
Note    : This is required if you wish to speed up mulltiple requests faster
          than 4s per request.
📧 bestie set your email if you wanna go faster than 4s per request, that's the whole tea ☕

🧚 Bio::DB::WebDBSeqI methods

overriding WebDBSeqI method to help newbies to retrieve sequences 🫶 (yes that's literally the stated purpose, we love an accessible king)

🎀 get_Stream_by_acc

 Title   : get_Stream_by_acc
 Usage   : $seq = $db->get_Stream_by_acc([$acc1, $acc2]);
 Function: gets a series of Seq objects by accession numbers
 Returns : a Bio::SeqIO stream object
 Args    : $ref : a reference to an array of accession numbers for
                  the desired sequence entries
 Note    : For GenBank, this just calls the same code for get_Stream_by_id()

🎀 delay_policy

 Title   : delay_policy
 Usage   : $secs = $self->delay_policy
 Function: NCBI requests a delay of 4 seconds between requests unless email is
           provided. This method implements a 4 second delay; use 'delay()' to
           override, though understand if no email is provided we are not
           responsible for users being IP-blocked by NCBI
 Returns : number of seconds to delay
 Args    : none
🚨 no cap: NCBI wants a 4 second delay between requests unless you give an email. you CAN override with delay(), but if you don't provide an email and get IP-blocked, that's on you bestie, they said it. 💀
Title   : cookie
Usage   : ($cookie,$querynum) = $db->cookie
Function: return the NCBI query cookie, this information is used by
          Bio::DB::GenBank in conjunction with efetch, ripped from
          Bio::DB::Query::GenBank
Returns : list of (cookie,querynum)
Args    : none

🎀 _parse_response

Title   : _parse_response
Usage   : $db->_parse_response($content)
Function: parse out response for cookie, this is a trimmed-down version
          of _parse_response from Bio::DB::Query::GenBank
Returns : empty
Args    : none
Throws  : 'unparseable output exception'

🎀 no_redirect

Title   : no_redirect
Usage   : $db->no_redirect($content)
Function: DEPRECATED - Used to indicate that Bio::DB::GenBank instance retrieves
          possible RefSeqs from EBI instead; default behavior is now to
          retrieve directly from NCBI
Returns : None
Args    : None
Throws  : Method is deprecated in favor of positive flag method 'redirect_refseq'
⚠️ DEPRECATED alert! this one is old news, use the positive flag method redirect_refseq instead. the default behavior now is to retrieve directly from NCBI. periodt. 💅

and that's the whole page bestie!! 🦋 this was perl v5.36.0, dated 2023-12-17, straight from the User Contributed Perl Documentation, Bio::DB::NCBIHelper(3pm) 💖✨ slay, go fetch those sequences responsibly 🧬👑

📦 where this page comes from