← Back to branch summary

~ubuntu-branches/ubuntu/raring/bioperl/raring

« back to all changes in this revision

Viewing changes to Bio/DB/EUtilities/epost.pm

  • Committer: Bazaar Package Importer
  • Author(s): Charles Plessy
  • Date: 2008-03-18 14:44:57 UTC
  • mfrom: (4 hardy)
  • mto: This revision was merged to the branch mainline in revision 6.
  • Revision ID: james.westby@ubuntu.com-20080318144457-1jjoztrvqwf0gruk
http://bugs.debian.org/448890
* debian/control:
  - Removed MIA Matt Hope (dopey) from the Uploaders field.
    Thank you for your work, Matt. I hope you are doing well.
  - Downgraded some recommended package to the 'Suggests' priority,
    according to the following discussion on Upstream's mail list.
    http://bioperl.org/pipermail/bioperl-l/2008-March/027379.html
    (Closes: #448890)
* debian/copyright converted to machine-readable format.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Bio/DB/EUtilities/epost.pm
 
1
# $Id: epost.pm,v 1.7.4.3 2006/11/10 16:48:09 cjfields Exp $
 
2
#
 
3
# BioPerl module for Bio::DB::EUtilities::epost
 
4
#
 
5
# Cared for by Chris Fields
 
6
#
 
7
# Copyright Chris Fields
 
8
#
 
9
# You may distribute this module under the same terms as perl itself
 
10
#
 
11
# POD documentation - main docs before the code
 
12
# 
 
13
# Part of the EUtilities BioPerl package
 
14
 
 
15
=head1 NAME
 
16
 
 
17
Bio::DB::EUtilities::epost - posting IDs on the remote NCBI server for batch
 
18
retrieval and chained queries
 
19
 
 
20
=head1 SYNOPSIS
 
21
 
 
22
    my $epost = Bio::DB::EUtilities->new(
 
23
                                          -eutil    => 'epost',
 
24
                                          -id       => \@ids,
 
25
                                          -db       => 'protein',
 
26
                                          );
 
27
 
 
28
    $epost->get_response;
 
29
 
 
30
=head1 DESCRIPTION
 
31
 
 
32
B<WARNING>: Please do B<NOT> spam the Entrez web server with multiple requests.
 
33
 
 
34
The EUtility EPost is used to post a list of primary IDs to the NCBI EUtilities
 
35
server for retrieval by L<EFetch|Bio::DB::EUtilities::efetch> or for using in
 
36
futher searches using L<ELink|Bio::DB::EUtilities::elink> or
 
37
L<ESearch|Bio::DB::EUtilities::esearch>.  The data is posted using:
 
38
 
 
39
    $epost->get_response;
 
40
 
 
41
When not used in void context, this will also return a
 
42
L<HTTP::Response|HTTP::Response> object for further processing.  This is not
 
43
necessary, as any posts made will automatically generate a
 
44
L<Cookie|Bio::DB::EUtilities::Cookie>,
 
45
which can be used to retrieve the posted information using
 
46
L<EFetch|Bio::DB::EUtilities::efetch>.
 
47
 
 
48
Using EPost is recommended for retrieving large lists of primary IDs and is
 
49
capable, when used repeatedly and in combination with EFetch, of retrieving
 
50
thousands of database entries.  
 
51
 
 
52
=head2 Parameters
 
53
 
 
54
The following are a general list of parameters that can be used to take
 
55
advantage of EPost.  Up-to-date help for EPost is available at this URL
 
56
(the information below is a summary of the options found there):
 
57
 
 
58
  http://eutils.ncbi.nlm.nih.gov/entrez/query/static/epost_help.html
 
59
 
 
60
=over 3
 
61
 
 
62
=item C<db>
 
63
 
 
64
The name of an Entrez database available through EUtilities. 
 
65
 
 
66
=item C<id>
 
67
 
 
68
a list of primary ID's
 
69
 
 
70
Below are a list of IDs which can be used with EPost:
 
71
 
 
72
B<PMID> (pubmed), B<MEDLINE UI> (NIH MedLine), B<MIM number> (omim),
 
73
B<GI number> (nucleotide, protein), B<MMDB-ID> (structure), B<TAXID> (taxonomy)
 
74
 
 
75
=back
 
76
 
 
77
=head1 FEEDBACK
 
78
 
 
79
=head2 Mailing Lists
 
80
 
 
81
User feedback is an integral part of the
 
82
evolution of this and other Bioperl modules. Send
 
83
your comments and suggestions preferably to one
 
84
of the Bioperl mailing lists. Your participation
 
85
is much appreciated.
 
86
 
 
87
  bioperl-l@lists.open-bio.org               - General discussion
 
88
  http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
 
89
 
 
90
=head2 Reporting Bugs
 
91
 
 
92
Report bugs to the Bioperl bug tracking system to
 
93
help us keep track the bugs and their resolution.
 
94
Bug reports can be submitted via the web.
 
95
 
 
96
  http://bugzilla.open-bio.org/
 
97
 
 
98
=head1 AUTHOR 
 
99
 
 
100
Email cjfields at uiuc dot edu
 
101
 
 
102
=head1 APPENDIX
 
103
 
 
104
The rest of the documentation details each of the
 
105
object methods. Internal methods are usually
 
106
preceded with a _
 
107
 
 
108
=cut
 
109
 
 
110
# Let the code begin...
 
111
 
 
112
package Bio::DB::EUtilities::epost;
 
113
use strict;
 
114
use warnings;
 
115
use Bio::DB::EUtilities::Cookie;
 
116
use XML::Simple;
 
117
#use Data::Dumper;
 
118
 
 
119
use base qw(Bio::DB::EUtilities);
 
120
 
 
121
our $EUTIL = 'epost';
 
122
our $RETMODE = 'xml';
 
123
 
 
124
sub _initialize {
 
125
    my ($self, @args) = @_;
 
126
    $self->SUPER::_initialize(@args);
 
127
    # set by default
 
128
    $self->_eutil($EUTIL);
 
129
    $self->retmode($RETMODE);
 
130
}
 
131
 
 
132
=head2 parse_response
 
133
 
 
134
 Title   : parse_response
 
135
 Usage   : $db->_parse_response($content)
 
136
 Function: parse out response for cookie
 
137
 Returns : empty
 
138
 Args    : none
 
139
 Throws  : 'unparseable output exception'
 
140
 
 
141
=cut
 
142
 
 
143
sub parse_response {
 
144
    my $self    = shift;
 
145
    my $response = shift if @_;
 
146
    if (!$response || !($response->isa("HTTP::Response"))) {
 
147
        $self->throw("Need HTTP::Response object");
 
148
    }
 
149
    my $xs = XML::Simple->new();
 
150
    my $simple = $xs->XMLin($response->content);
 
151
    #$self->debug("Response dumper:\n".Dumper($simple));
 
152
    # check for errors
 
153
    if ($simple->{ERROR}) {
 
154
        $self->throw("NCBI epost nonrecoverable error: ".$simple->{ERROR});
 
155
    }
 
156
    if ($simple->{InvalidIdList}) {
 
157
        $self->warn("NCBI epost error: Invalid ID List".$simple->{InvalidIdList});
 
158
    }
 
159
    my $db = $self->db;
 
160
    my $webenv    = $simple->{WebEnv};
 
161
    my $querykey  = $simple->{QueryKey};
 
162
    my $cookie = Bio::DB::EUtilities::Cookie->new(-webenv   => $webenv,
 
163
                                                  -querykey => $querykey,
 
164
                                                  -eutil    => 'epost',
 
165
                                                  -database => $db,
 
166
                                                  );
 
167
    $self->add_cookie($cookie);
 
168
    return $response;
 
169
}
 
170
 
 
171
1;
 
172
__END__
 
 
b'\\ No newline at end of file'