.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::DB::NCBIHelper 3pm"
.TH Bio::DB::NCBIHelper 3pm "2023-12-17" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::DB::NCBIHelper \- A collection of routines useful for queries to
NCBI databases.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # Do not use this module directly.
\&
\& # get a Bio::DB::NCBIHelper object somehow
\& my $seqio = $db\->get_Stream_by_acc([\*(AqJ00522\*(Aq]);
\& foreach my $seq ( $seqio\->next_seq ) {
\&     # process seq
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides a single place to setup some common methods for querying \s-1NCBI\s0
web databases.  This module just centralizes the methods for
constructing a \s-1URL\s0 for querying \s-1NCBI\s0 GenBank and \s-1NCBI\s0 GenPept and the
common \s-1HTML\s0 stripping done in postprocess_data().
.PP
The base \s-1NCBI\s0 query \s-1URL\s0 used is:
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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.
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Jason Stajich"
.IX Header "AUTHOR - Jason Stajich"
Email jason@bioperl.org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the
object methods. Internal methods are usually
preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 5
\& Title   : new
\& Usage   :
\& Function: the new way to make modules a little more lightweight
\& Returns :
\& Args    :
.Ve
.SS "get_params"
.IX Subsection "get_params"
.Vb 6
\& Title   : get_params
\& Usage   : my %params = $self\->get_params($mode)
\& Function: returns key,value pairs to be passed to NCBI database
\&           for either \*(Aqbatch\*(Aq or \*(Aqsingle\*(Aq sequence retrieval method
\& Returns : a key,value pair hash
\& Args    : \*(Aqsingle\*(Aq or \*(Aqbatch\*(Aq mode for retrieval
.Ve
.SS "default_format"
.IX Subsection "default_format"
.Vb 5
\& Title   : default_format
\& Usage   : my $format = $self\->default_format
\& Function: returns default sequence format for this module
\& Returns : string
\& Args    : none
.Ve
.SS "get_request"
.IX Subsection "get_request"
.Vb 5
\& Title   : get_request
\& Usage   : my $url = $self\->get_request
\& Function: HTTP::Request
\& Returns :
\& Args    : %qualifiers = a hash of qualifiers (ids, format, etc)
.Ve
.SS "get_seq_stream"
.IX Subsection "get_seq_stream"
.Vb 6
\& 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
.Ve
.SS "get_Stream_by_batch"
.IX Subsection "get_Stream_by_batch"
.Vb 9
\&  Title   : get_Stream_by_batch
\&  Usage   : $seq = $db\->get_Stream_by_batch($ref);
\&  Function: Retrieves Seq objects from Entrez \*(Aqen masse\*(Aq, 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.
.Ve
.SS "get_Stream_by_query"
.IX Subsection "get_Stream_by_query"
.Vb 10
\&  Title   : get_Stream_by_query
\&  Usage   : $seq = $db\->get_Stream_by_query($query);
\&  Function: Retrieves Seq objects from Entrez \*(Aqen masse\*(Aq, 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.
.Ve
.SS "postprocess_data"
.IX Subsection "postprocess_data"
.Vb 8
\& Title   : postprocess_data
\& Usage   : $self\->postprocess_data ( \*(Aqtype\*(Aq => \*(Aqstring\*(Aq,
\&                                                             \*(Aqlocation\*(Aq => \e$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:
\&
\&           \*(Aqtype\*(Aq can be \*(Aqstring\*(Aq or \*(Aqfile\*(Aq
\&           \*(Aqlocation\*(Aq either file location or string reference containing data
.Ve
.SS "request_format"
.IX Subsection "request_format"
.Vb 9
\& 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
.Ve
.SS "redirect_refseq"
.IX Subsection "redirect_refseq"
.Vb 9
\& 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  : \*(Aqunparseable output exception\*(Aq
\& Note    : This replaces \*(Aqno_redirect\*(Aq as a more straightforward flag to
\&           redirect possible RefSeqs to use Bio::DB::RefSeq (EBI interface)
\&           instead of retrieving the NCBI records
.Ve
.SS "complexity"
.IX Subsection "complexity"
.Vb 7
\& 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
.Ve
.SS "strand"
.IX Subsection "strand"
.Vb 8
\& 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\*(Aqs use of strand: 1 = plus, \-1 = minus 0 = not relevant.
\&           We should probably add in some functionality to convert over in the future.
.Ve
.SS "seq_start"
.IX Subsection "seq_start"
.Vb 6
\& 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
.Ve
.SS "seq_stop"
.IX Subsection "seq_stop"
.Vb 6
\& 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
.Ve
.SS "email"
.IX Subsection "email"
.Vb 9
\& Title   : email
\& Usage   : $db\->email(\*(Aqfoo@bar.edu\*(Aq)
\& 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.
.Ve
.SS "Bio::DB::WebDBSeqI methods"
.IX Subsection "Bio::DB::WebDBSeqI methods"
Overriding WebDBSeqI method to help newbies to retrieve sequences
.SS "get_Stream_by_acc"
.IX Subsection "get_Stream_by_acc"
.Vb 7
\&  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()
.Ve
.SS "delay_policy"
.IX Subsection "delay_policy"
.Vb 8
\&  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 \*(Aqdelay()\*(Aq 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
.Ve
.SS "cookie"
.IX Subsection "cookie"
.Vb 7
\& 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
.Ve
.SS "_parse_response"
.IX Subsection "_parse_response"
.Vb 7
\& 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  : \*(Aqunparseable output exception\*(Aq
.Ve
.SS "no_redirect"
.IX Subsection "no_redirect"
.Vb 8
\& 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 \*(Aqredirect_refseq\*(Aq
.Ve