Bio/Tools/EUtilities/Info/FieldInfo.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tools::EUtilities::Info
   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::Tools::EUtilities::Info::FieldInfo - class for storing einfo field data
  18
  19 =head1 SYNOPSIS
  20
  21     #### should not create instance directly; Bio::Tools::EUtilities does this ####
  22
  23     my $info = Bio::Tools::EUtilities->new(-eutil => 'einfo',
  24                                            -file => 'einfo.xml');
  25     # can also use '-response' (for HTTP::Response objects) or '-fh' (for filehandles)
  26
  27     # print available databases (if data is present)
  28     print join(', ',$info->get_available_databases),"\n";
  29
  30     # get database info
  31     my $db = $info->get_database; # in case you forgot...
  32     my $desc = $info->get_description;
  33     my $nm = $info->get_menu_name;
  34     my $ct = $info->get_record_count;
  35     my $dt = $info->get_last_update;
  36     # EUtilDataI interface methods
  37     my $eutil = $info->eutil;
  38     my $type = $info->type;
  39
  40     # iterate through Field and Link objects
  41     while (my $field = $info->next_Field) {
  42         print "Field code: ",$field->get_field_code,"\n";
  43         print "Field name: ",$field->get_field_name,"\n";
  44         print "Field desc: ",$field->get_field_description,"\n";
  45         print "DB  : ",$field->get_database,"\n";
  46         print "Term ct   : ",$field->get_term_count,"\n";
  47         for my $att (qw(is_date is_singletoken is_hierarchy is_hidden is_numerical)) {
  48             print "\tField $att\n" if $field->$att;
  49         }
  50     }
  51
  52     my @fields = $info->get_Fields; # grab them all (useful for grep)
  53
  54     while (my $link = $info->next_Link) {
  55         print "Link name: ",$link->get_link_name,"\n";
  56         print "Link desc: ",$link->get_link_description,"\n";
  57         print "DBFrom: ",$link->get_dbfrom,"\n"; # same as get_database()
  58         print "DBTo: ",$link->get_dbto,"\n"; # database linked to
  59     }
  60
  61     my @links = $info->get_Links; # grab them all (useful for grep)
  62
  63     $info->rewind(); # rewinds all iterators
  64     $info->rewind('links'); # rewinds Link iterator
  65     $info->rewind('fields'); # rewinds Field iterator
  66
  67 =head1 DESCRIPTION
  68
  69 This class handles data output (XML) from einfo.
  70
  71 einfo is capable of returning two types of information: 1) a list of all
  72 available databases (when called w/o parameters) and 2) information about a
  73 specific database. The latter information includes the database description,
  74 record count, and date/time stamp for the last update, among other things. It
  75 also includes a list of fields (indices by which record data is stored which can
  76 be used in queries) and links (crossrefs between related records in other
  77 databases at NCBI). Data from the latter two are stored in two small subclasses
  78 (Field and Link) which can be iterated through or retrieved all at once, as
  79 demonstrated above. NOTE: Methods described for the Link and Field subclasses
  80 are unique to those classes (as they retrieve data unique to those data types).
  81
  82 Further documentation for Link and Field subclass methods is included below.
  83
  84 For more information on einfo see:
  85
  86    http://eutils.ncbi.nlm.nih.gov/entrez/query/static/einfo_help.html
  87
  88 =head1 FEEDBACK
  89
  90 =head2 Mailing Lists
  91
  92 User feedback is an integral part of the evolution of this and other Bioperl
  93 modules. Send your comments and suggestions preferably to one of the Bioperl
  94 mailing lists. Your participation is much appreciated.
  95
  96   bioperl-l@lists.open-bio.org               - General discussion
  97   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  98
  99 =head2 Reporting Bugs
 100
 101 Report bugs to the Bioperl bug tracking system to help us keep track the bugs
 102 and their resolution. Bug reports can be submitted via the web.
 103
 104   http://bugzilla.open-bio.org/
 105
 106 =head1 AUTHOR
 107
 108 Email cjfields at uiuc dot edu
 109
 110 =head1 APPENDIX
 111
 112 The rest of the documentation details each of the object methods. Internal
 113 methods are usually preceded with a _
 114
 115 =cut
 116
 117 # Let the code begin...
 118
 119 package Bio::Tools::EUtilities::Info::FieldInfo;
 120 use base qw(Bio::Root::Root Bio::Tools::EUtilities::EUtilDataI);
 121 use strict;
 122 use warnings;
 123
 124 =head2 new
 125
 126  Title    : new
 127  Note     : *** should not be called by end-users ***
 128  Usage    : my $ct = Bio::Tools::EUtilities::Info::FieldInfo;
 129  Function : returns new FieldInfo instance
 130  Returns  : Bio::Tools::EUtilities::Info::FieldInfo instance
 131  Args     : none (all data added via _add_data, most methods are getters only)
 132
 133 =cut
 134
 135 sub new {
 136     my ($class, @args) = @_;
 137     my $self = $class->SUPER::new(@args);
 138     $self->eutil('einfo');
 139     $self->datatype('fieldinfo');
 140     return $self;
 141 }
 142
 143 =head2 term_count
 144
 145  Title    : term_count
 146  Usage    : my $ct = $field->term_count;
 147  Function : returns number of terms for field
 148  Returns  : integer
 149  Args     : none
 150
 151 =cut
 152
 153 sub get_term_count { return shift->{'_termcount'} }
 154
 155 =head2 get_field_name
 156
 157  Title    : get_field_name
 158  Usage    : my $nm = $field->get_field_name;
 159  Function : returns the full name of the field
 160  Returns  : string
 161  Args     : none
 162
 163 =cut
 164
 165 sub get_field_name { return shift->{'_fullname'} }
 166
 167 =head2 get_full_name
 168
 169  Title    : get_full_name
 170  Note     : alias of get_field_name()
 171
 172 =cut
 173
 174 *get_full_name = \&get_field_name;
 175
 176 =head2 get_field_code
 177
 178  Title    : get_field_code
 179  Usage    : $field->get_field_code()
 180  Function : returns field code (abbreviation) used for queries
 181  Returns  : string
 182  Args     : none
 183
 184 =cut
 185
 186 sub get_field_code { return shift->{'_name'} }
 187
 188 =head2 get_field_description
 189
 190  Title    : get_field_description
 191  Usage    : $field->get_field_description
 192  Function : returns field description
 193  Returns  : string
 194  Args     : none
 195  Note     : alias of get_description()
 196
 197 =cut
 198
 199 sub get_field_description { return shift->{'_description'} }
 200
 201 =head2 is_date
 202
 203  Title    : is_date
 204  Usage    : if ($field->is_date) {...}
 205  Function : returns true if field contains date information
 206  Returns  : Boolean
 207  Args     : none
 208
 209 =cut
 210
 211 sub is_date {
 212     my $self = shift;
 213     ($self->{'_isdate'} && $self->{'_isdate'} eq 'Y') ? return 1 : return 0;
 214 }
 215
 216 =head2 is_singletoken
 217
 218  Title    : is_singletoken
 219  Usage    : if ($field->is_singletoken) {...}
 220  Function : returns true if field has single value in docsums
 221  Returns  : Boolean
 222  Args     : none
 223
 224 =cut
 225
 226 sub is_singletoken {
 227     my $self = shift;
 228     ($self->{'_singletoken'} && $self->{'_singletoken'} eq 'Y') ? return 1 : return 0;
 229 }
 230
 231 =head2 is_hierarchy
 232
 233  Title    : is_hierarchy
 234  Usage    : if ($field->is_hierarchy) {...}
 235  Function : returns true if field contains hierarchal values
 236  Returns  : Boolean
 237  Args     : none
 238
 239 =cut
 240
 241 sub is_hierarchy {
 242     my $self = shift;
 243     ($self->{'hierarchy'} && $self->{'hierarchy'} eq 'Y') ? return 1 : return 0;
 244 }
 245
 246 =head2 is_hidden
 247
 248  Title    : is_hidden
 249  Usage    : if ($field->is_hidden) {...}
 250  Function : returns true if field is hidden in docsums
 251  Returns  : Boolean
 252  Args     : none
 253
 254 =cut
 255
 256 sub is_hidden {
 257     my $self = shift;
 258     ($self->{'_ishidden'} && $self->{'_ishidden'} eq 'Y') ? return 1 : return 0;
 259 }
 260
 261 =head2 is_numerical
 262
 263  Title    : is_numerical
 264  Usage    : if ($field->is_numerical) {...}
 265  Function : returns true if field contains a numerical value
 266  Returns  : Boolean
 267  Args     : none
 268
 269 =cut
 270
 271 sub is_numerical {
 272     my $self = shift;
 273     ($self->{'_isnumerical'} && $self->{'_isnumerical'} eq 'Y') ? return 1 : return 0;
 274 }
 275
 276 # private EUtilDataI method
 277
 278 sub _add_data {
 279     my ($self, $simple) = @_;
 280     map { $self->{'_'.lc $_} = $simple->{$_} unless ref $simple->{$_}} keys %$simple;
 281 }
 282
 283 =head2 to_string
 284
 285  Title    : to_string
 286  Usage    : $foo->to_string()
 287  Function : converts current object to string
 288  Returns  : none
 289  Args     : (optional) simple data for text formatting
 290  Note     : Used generally for debugging and for various print methods
 291
 292 =cut
 293
 294 sub to_string {
 295     my $self = shift;
 296     #        order     method                     name
 297     my %tags = (1 => ['get_field_code'        => 'Field Code'],
 298                 2 => ['get_field_name'        => 'Field Name'],
 299                 3 => ['get_field_description' => 'Description'],
 300                 4 => ['get_term_count'        => 'Term Count']);
 301     my $string;
 302     for my $tag (sort {$a <=> $b} keys %tags) {
 303         my ($m, $nm) = ($tags{$tag}->[0], $tags{$tag}->[1]);
 304         $string .= sprintf("%-20s%s\n", $nm,
 305             $self->_text_wrap('', ' 'x20 .':', ":".$self->$m));
 306     }
 307     $string .= sprintf("%-20s%s\n", "Attributes",
 308         $self->_text_wrap('', ' 'x20 .':', ":".join(',', grep {$self->$_} qw(is_date
 309                is_singletoken is_hierarchy is_hidden is_numerical))));
 310     return $string;
 311 }
 312
 313 1;
 314