← Back to branch summary

~ubuntu-branches/ubuntu/trusty/bioperl/trusty

« back to all changes in this revision

Viewing changes to Bio/Tools/EUtilities/Info.pm

  • Committer: Package Import Robot
  • Author(s): Charles Plessy
  • Date: 2013-09-22 13:39:48 UTC
  • mfrom: (3.1.11 sid)
  • Revision ID: package-import@ubuntu.com-20130922133948-c6z62zegjyp7ztou
Tags: 1.6.922-1
http://bugs.debian.org/722910
* New upstream release.
* Replaces and Breaks grinder (<< 0.5.3-3~) because of overlaping contents.
  Closes: #722910
* Stop Replacing and Breaking bioperl ( << 1.6.9 ): not needed anymore. 

Show diffs side-by-side

added added

removed removed

Lines of Context:
Bio/Tools/EUtilities/Info.pm
1
 
#
2
 
# BioPerl module for Bio::Tools::EUtilities::Info
3
 
#
4
 
# Please direct questions and support issues to <bioperl-l@bioperl.org> 
5
 
#
6
 
# Cared for by Chris Fields
7
 
#
8
 
# Copyright Chris Fields
9
 
#
10
 
# You may distribute this module under the same terms as perl itself
11
 
#
12
 
# POD documentation - main docs before the code
13
 
# 
14
 
# Part of the EUtilities BioPerl package
15
 
 
16
 
=head1 NAME
17
 
 
18
 
Bio::Tools::EUtilities::Info - interface class for storing einfo data
19
 
 
20
 
=head1 SYNOPSIS
21
 
 
22
 
  #### should not create instance directly; Bio::Tools::EUtilities does this ####
23
 
 
24
 
  my $info = Bio::Tools::EUtilities->new(-eutil => 'einfo',
25
 
                                         -file => 'einfo.xml');
26
 
  # can also use '-response' (for HTTP::Response objects) or '-fh' (for filehandles)
27
 
 
28
 
  # print available databases (if data is present)
29
 
 
30
 
  print join(', ',$info->get_available_databases),"\n";
31
 
 
32
 
  # get database info
33
 
 
34
 
  my $db = $info->get_database; # in case you forgot...
35
 
  my $desc = $info->get_description;
36
 
  my $nm = $info->get_menu_name;
37
 
  my $ct = $info->get_record_count;
38
 
  my $dt = $info->get_last_update;
39
 
 
40
 
  # EUtilDataI interface methods
41
 
 
42
 
  my $eutil = $info->eutil;
43
 
  my $type = $info->datatype;
44
 
 
45
 
  # iterate through Field and Link objects
46
 
 
47
 
  while (my $field = $info->next_Field) {
48
 
      print "Field code: ",$field->get_field_code,"\n";
49
 
      print "Field name: ",$field->get_field_name,"\n";
50
 
      print "Field desc: ",$field->get_field_description,"\n";
51
 
      print "DB  : ",$field->get_database,"\n";
52
 
      print "Term ct   : ",$field->get_term_count,"\n";
53
 
      for my $att (qw(is_date is_singletoken is_hierarchy is_hidden is_numerical)) {
54
 
          print "\tField $att\n" if $field->$att;
55
 
      }
56
 
  }
57
 
 
58
 
  my @fields = $info->get_Fields; # grab them all (useful for grep)
59
 
 
60
 
  while (my $link = $info->next_LinkInfo) {
61
 
      print "Link name: ",$link->get_link_name,"\n";
62
 
      print "Link desc: ",$link->get_link_description,"\n";
63
 
      print "DBFrom: ",$link->get_dbfrom,"\n"; # same as get_database()
64
 
      print "DBTo: ",$link->get_dbto,"\n"; # database linked to
65
 
  }
66
 
 
67
 
  my @links = $info->get_LinkInfo; # grab them all (useful for grep)
68
 
 
69
 
  $info->rewind(); # rewinds all iterators
70
 
  $info->rewind('links'); # rewinds Link iterator
71
 
  $info->rewind('fields'); # rewinds Field iterator
72
 
 
73
 
=head1 DESCRIPTION
74
 
 
75
 
This class handles data output (XML) from einfo.
76
 
 
77
 
Einfo is capable of returning two types of information:
78
 
 
79
 
=over 3
80
 
 
81
 
=item * A list of all available databases (when called w/o parameters)
82
 
 
83
 
=item * Information about a specific database.
84
 
 
85
 
=back
86
 
 
87
 
The latter information includes the database description, record count, and
88
 
date/time stamp for the last update, among other things. It also includes a list
89
 
of fields (indices by which record data is stored which can be used in queries)
90
 
and links (crossrefs between related records in other databases at NCBI). Data
91
 
from the latter two are stored in two small subclasses (FieldInfo and LinkInfo)
92
 
which can be iterated through or retrieved all at once, as demonstrated above.
93
 
NOTE: Methods described for the LinkInfo and FieldInfo subclasses are unique to
94
 
those classes (as they retrieve data unique to those data types).
95
 
 
96
 
Further documentation for Link and Field subclass methods is included below.
97
 
 
98
 
For more information on einfo see:
99
 
 
100
 
   http://eutils.ncbi.nlm.nih.gov/entrez/query/static/einfo_help.html
101
 
 
102
 
=head1 FEEDBACK
103
 
 
104
 
=head2 Mailing Lists
105
 
 
106
 
User feedback is an integral part of the evolution of this and other Bioperl
107
 
modules. Send your comments and suggestions preferably to one of the Bioperl
108
 
mailing lists. Your participation is much appreciated.
109
 
 
110
 
  bioperl-l@lists.open-bio.org               - General discussion
111
 
  http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
112
 
 
113
 
=head2 Support 
114
 
 
115
 
Please direct usage questions or support issues to the mailing list:
116
 
 
117
 
I<bioperl-l@bioperl.org>
118
 
 
119
 
rather than to the module maintainer directly. Many experienced and 
120
 
reponsive experts will be able look at the problem and quickly 
121
 
address it. Please include a thorough description of the problem 
122
 
with code and data examples if at all possible.
123
 
 
124
 
=head2 Reporting Bugs
125
 
 
126
 
Report bugs to the Bioperl bug tracking system to help us keep track the bugs
127
 
and their resolution. Bug reports can be submitted via the web.
128
 
 
129
 
  https://redmine.open-bio.org/projects/bioperl/
130
 
 
131
 
=head1 AUTHOR 
132
 
 
133
 
Email cjfields at bioperl dot org
134
 
 
135
 
=head1 APPENDIX
136
 
 
137
 
The rest of the documentation details each of the object methods. Internal
138
 
methods are usually preceded with a _
139
 
 
140
 
=cut
141
 
 
142
 
# Let the code begin...
143
 
 
144
 
package Bio::Tools::EUtilities::Info;
145
 
 
146
 
use strict;
147
 
use warnings;
148
 
use base qw(Bio::Tools::EUtilities Bio::Tools::EUtilities::EUtilDataI);
149
 
 
150
 
use Bio::Tools::EUtilities::Info::LinkInfo;
151
 
use Bio::Tools::EUtilities::Info::FieldInfo;
152
 
 
153
 
=head2 rewind
154
 
 
155
 
 Title    : rewind
156
 
 Usage    : $info->rewind() # rewinds all (default)
157
 
            $info->rewind('links') # rewinds only links
158
 
 Function : 'rewinds' (resets) specified interators (all if no arg)
159
 
 Returns  : none
160
 
 Args     : [OPTIONAL] String: 
161
 
            'all'    - all iterators (default)
162
 
            'linkinfo'  - LinkInfo objects only
163
 
            'fieldinfo' - FieldInfo objects only
164
 
 
165
 
=cut
166
 
 
167
 
 
168
 
# private EUtilDataI method
169
 
 
170
 
sub _add_data {
171
 
    my ($self, $simple) = @_;
172
 
    if (exists $simple->{DbList} &&
173
 
        exists $simple->{DbList}->{DbName}) {
174
 
        $self->{'_available_databases'} = $simple->{DbList}->{DbName};
175
 
    }
176
 
    # start setting internal variables
177
 
    if (exists $simple->{DbInfo}) {
178
 
        for my $key (sort keys %{ $simple->{DbInfo} }) {
179
 
            my $data = 
180
 
            ($key eq 'FieldList') ? $simple->{DbInfo}->{$key}->{Field} :
181
 
            ($key eq 'LinkList' ) ? $simple->{DbInfo}->{$key}->{Link}  :
182
 
            $simple->{DbInfo}->{$key};
183
 
            if ($key eq 'FieldList' || $key eq 'LinkList') {
184
 
                for my $chunk (@{$data}) {
185
 
                    if (exists $simple->{DbInfo}->{DbName}) {
186
 
                        $chunk->{DbFrom} = $simple->{DbInfo}->{DbName};
187
 
                    }
188
 
                    my $type = ($key eq 'FieldList') ? 'FieldInfo' : 'LinkInfo';
189
 
                    my $obj = "Bio::Tools::EUtilities::Info::$type"->new(
190
 
                                           -eutil => 'einfo',
191
 
                                           -type => lc $type,
192
 
                                        -verbose => $self->verbose);
193
 
                    $obj->_add_data($chunk);
194
 
                    push @{ $self->{'_'.lc $type} }, $obj;
195
 
                }
196
 
            } else {
197
 
                $self->{'_'.lc $key} = $data;
198
 
            }
199
 
        }
200
 
    } else {
201
 
        map { $self->{'_'.lc $_} = $simple->{$_} unless ref $simple->{$_}} keys %$simple;
202
 
    }
203
 
}
204
 
 
205
 
=head2 to_string
206
 
 
207
 
 Title    : to_string
208
 
 Usage    : $foo->to_string()
209
 
 Function : converts current object to string
210
 
 Returns  : none
211
 
 Args     : (optional) simple data for text formatting
212
 
 Note     : Used generally for debugging and for various print methods
213
 
 
214
 
=cut
215
 
 
216
 
sub to_string {
217
 
    my $self = shift;
218
 
    my $string = $self->SUPER::to_string;
219
 
    if (my @dbs = $self->get_databases) {
220
 
        $string .= sprintf("%-20s:%s\n\n", 'DB',
221
 
            $self->_text_wrap('', ' 'x20 .':', join(', ',@dbs)));
222
 
    }
223
 
    while (my $fi = $self->next_FieldInfo) {
224
 
        $string .= $fi->to_string."\n";
225
 
    }
226
 
    while (my $li = $self->next_LinkInfo) {
227
 
        $string .= $li->to_string."\n";
228
 
    }
229
 
    return $string;
230
 
}
231
 
 
232
 
1;