.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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::WebDBSeqI 3pm"
.TH Bio::DB::WebDBSeqI 3pm "2020-10-28" "perl v5.30.3" "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::WebDBSeqI \- Object Interface to generalize Web Databases
for retrieving sequences
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&   # get a WebDBSeqI object somehow
\&   # assuming it is a nucleotide db
\&   my $seq = $db\->get_Seq_by_id(\*(AqROA1_HUMAN\*(Aq)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides core set of functionality for connecting to a web based
database for retrieving sequences.
.PP
Users wishing to add another Web Based Sequence Dabatase will need to
extend this class (see Bio::DB::SwissProt or Bio::DB::NCBIHelper for
examples) and implement the get_request method which returns a
HTTP::Request for the specified uids (accessions, ids, etc depending
on what query types the database accepts).
.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 "get_Seq_by_id"
.IX Subsection "get_Seq_by_id"
.Vb 6
\& Title   : get_Seq_by_id
\& Usage   : $seq = $db\->get_Seq_by_id(\*(AqROA1_HUMAN\*(Aq)
\& Function: Gets a Bio::Seq object by its name
\& Returns : a Bio::Seq object
\& Args    : the id (as a string) of a sequence
\& Throws  : "id does not exist" exception
.Ve
.SS "get_Seq_by_acc"
.IX Subsection "get_Seq_by_acc"
.Vb 6
\& Title   : get_Seq_by_acc
\& Usage   : $seq = $db\->get_Seq_by_acc(\*(AqX77802\*(Aq);
\& Function: Gets a Bio::Seq object by accession number
\& Returns : A Bio::Seq object
\& Args    : accession number (as a string)
\& Throws  : "acc does not exist" exception
.Ve
.SS "get_Seq_by_gi"
.IX Subsection "get_Seq_by_gi"
.Vb 6
\& Title   : get_Seq_by_gi
\& Usage   : $seq = $db\->get_Seq_by_gi(\*(Aq405830\*(Aq);
\& Function: Gets a Bio::Seq object by gi number
\& Returns : A Bio::Seq object
\& Args    : gi number (as a string)
\& Throws  : "gi does not exist" exception
.Ve
.SS "get_Seq_by_version"
.IX Subsection "get_Seq_by_version"
.Vb 6
\& Title   : get_Seq_by_version
\& Usage   : $seq = $db\->get_Seq_by_version(\*(AqX77802.1\*(Aq);
\& Function: Gets a Bio::Seq object by sequence version
\& Returns : A Bio::Seq object
\& Args    : accession.version (as a string)
\& Throws  : "acc.version does not exist" exception
.Ve
.SS "get_request"
.IX Subsection "get_request"
.Vb 5
\& Title   : get_request
\& Usage   : my $url = $self\->get_request
\& Function: returns a HTTP::Request object
\& Returns :
\& Args    : %qualifiers = a hash of qualifiers (ids, format, etc)
.Ve
.SS "get_Stream_by_id"
.IX Subsection "get_Stream_by_id"
.Vb 6
\&  Title   : get_Stream_by_id
\&  Usage   : $stream = $db\->get_Stream_by_id( [$uid1, $uid2] );
\&  Function: Gets a series of Seq objects by unique identifiers
\&  Returns : a Bio::SeqIO stream object
\&  Args    : $ref : a reference to an array of unique identifiers for
\&                   the desired sequence entries
.Ve
.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 "get_Stream_by_gi"
.IX Subsection "get_Stream_by_gi"
.Vb 7
\&  Title   : get_Stream_by_gi
\&  Usage   : $seq = $db\->get_Stream_by_gi([$gi1, $gi2]);
\&  Function: Gets a series of Seq objects by gi numbers
\&  Returns : a Bio::SeqIO stream object
\&  Args    : $ref : a reference to an array of gi numbers for
\&                   the desired sequence entries
\&  Note    : For GenBank, this just calls the same code for get_Stream_by_id()
.Ve
.SS "get_Stream_by_version"
.IX Subsection "get_Stream_by_version"
.Vb 7
\&  Title   : get_Stream_by_version
\&  Usage   : $seq = $db\->get_Stream_by_version([$version1, $version2]);
\&  Function: Gets a series of Seq objects by accession.versions
\&  Returns : a Bio::SeqIO stream object
\&  Args    : $ref : a reference to an array of accession.version strings for
\&                   the desired sequence entries
\&  Note    : For GenBank, this is implemented in NCBIHelper
.Ve
.SS "get_Stream_by_query"
.IX Subsection "get_Stream_by_query"
.Vb 8
\&  Title   : get_Stream_by_query
\&  Usage   : $stream = $db\->get_Stream_by_query($query);
\&  Function: Gets a series of Seq objects by way of a query string or oject
\&  Returns : a Bio::SeqIO stream object
\&  Args    : $query :   A string that uses the appropriate query language
\&            for the database or a Bio::DB::QueryI object.  It is suggested
\&            that you create the Bio::DB::Query object first and interrogate
\&            it for the entry count before you fetch a potentially large stream.
.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 "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 "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 "url_base_address"
.IX Subsection "url_base_address"
.Vb 6
\& Title   : url_base_address
\& Usage   : my $address = $self\->url_base_address or
\&           $self\->url_base_address($address)
\& Function: Get/Set the base URL for the Web Database
\& Returns : Base URL for the Web Database
\& Args    : $address \- URL for the WebDatabase
.Ve
.SS "proxy"
.IX Subsection "proxy"
.Vb 9
\& Title   : proxy
\& Usage   : $httpproxy = $db\->proxy(\*(Aqhttp\*(Aq)  or
\&           $db\->proxy([\*(Aqhttp\*(Aq,\*(Aqftp\*(Aq], \*(Aqhttp://myproxy\*(Aq )
\& Function: Get/Set a proxy for use of proxy
\& Returns : a string indicating the proxy
\& Args    : $protocol : an array ref of the protocol(s) to set/get
\&           $proxyurl : url of the proxy to use for the specified protocol
\&           $username : username (if proxy requires authentication)
\&           $password : password (if proxy requires authentication)
.Ve
.SS "authentication"
.IX Subsection "authentication"
.Vb 5
\& Title   : authentication
\& Usage   : $db\->authentication($user,$pass)
\& Function: Get/Set authentication credentials
\& Returns : Array of user/pass
\& Args    : Array or user/pass
.Ve
.SS "retrieval_type"
.IX Subsection "retrieval_type"
.Vb 6
\& Title   : retrieval_type
\& Usage   : $self\->retrieval_type($type);
\&           my $type = $self\->retrieval_type
\& Function: Get/Set a proxy for retrieval_type (pipeline, io_string or tempfile)
\& Returns : string representing retrieval type
\& Args    : $value \- the value to store
.Ve
.PP
This setting affects how the data stream from the remote web server is
processed and passed to the Bio::SeqIO layer. Three types of retrieval
types are currently allowed:
.PP
.Vb 4
\&   pipeline  Perform a fork in an attempt to begin streaming
\&             while the data is still downloading from the remote
\&             server.  Disk, memory and speed efficient, but will
\&             not work on Windows or MacOS 9 platforms.
\&
\&   io_string Store downloaded database entry(s) in memory.  Can be
\&             problematic for batch downloads because entire set
\&             of entries must fit in memory.  Alll entries must be
\&             downloaded before processing can begin.
\&
\&   tempfile  Store downloaded database entry(s) in a temporary file.
\&             All entries must be downloaded before processing can
\&             begin.
.Ve
.PP
The default is pipeline, with automatic fallback to io_string if
pipelining is not available.
.SS "url_params"
.IX Subsection "url_params"
.Vb 6
\& Title   : url_params
\& Usage   : my $params = $self\->url_params or
\&           $self\->url_params($params)
\& Function: Get/Set the URL parameters for the Web Database
\& Returns : url parameters for Web Database
\& Args    : $params \- parameters to be appended to the URL for the WebDatabase
.Ve
.SS "ua"
.IX Subsection "ua"
.Vb 6
\& Title   : ua
\& Usage   : my $ua = $self\->ua or
\&           $self\->ua($ua)
\& Function: Get/Set a LWP::UserAgent for use
\& Returns : reference to LWP::UserAgent Object
\& Args    : $ua \- must be a LWP::UserAgent
.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
\& 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 "delay"
.IX Subsection "delay"
.Vb 5
\& Title   : delay
\& Usage   : $secs = $self\->delay([$secs])
\& Function: get/set number of seconds to delay between fetches
\& Returns : number of seconds to delay
\& Args    : new value
.Ve
.PP
\&\s-1NOTE:\s0 the default is to use the value specified by \fBdelay_policy()\fR.
This can be overridden by calling this method, or by passing the
\&\-delay argument to \fBnew()\fR.
.SS "delay_policy"
.IX Subsection "delay_policy"
.Vb 5
\& Title   : delay_policy
\& Usage   : $secs = $self\->delay_policy
\& Function: return number of seconds to delay between calls to remote db
\& Returns : number of seconds to delay
\& Args    : none
.Ve
.PP
\&\s-1NOTE:\s0 The default delay policy is 0s.  Override in subclasses to
implement delays.  The timer has only second resolution, so the delay
will actually be +/\- 1s.
.SS "_sleep"
.IX Subsection "_sleep"
.Vb 5
\& Title   : _sleep
\& Usage   : $self\->_sleep
\& Function: sleep for a number of seconds indicated by the delay policy
\& Returns : none
\& Args    : none
.Ve
.PP
\&\s-1NOTE:\s0 This method keeps track of the last time it was called and only
imposes a sleep if it was called more recently than the \fBdelay_policy()\fR
allows.
.SS "mod_perl_api"
.IX Subsection "mod_perl_api"
.Vb 5
\& Title   : mod_perl_api
\& Usage   : $version = self\->mod_perl_api
\& Function: Returns API version of mod_perl being used based on set env. variables
\& Returns : mod_perl API version; if mod_perl isn\*(Aqt loaded, returns 0
\& Args    : none
.Ve