Bio/Tools/EUtilities/Summary/DocSum.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::DB::EUtilities::Summary::DocSum
   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::Summary::DocSum - data object for document summary data
  18 from esummary
  19
  20 =head1 SYNOPSIS
  21
  22 =head1 DESCRIPTION
  23
  24 =head1 FEEDBACK
  25
  26 =head2 Mailing Lists
  27
  28 User feedback is an integral part of the
  29 evolution of this and other Bioperl modules. Send
  30 your comments and suggestions preferably to one
  31 of the Bioperl mailing lists. Your participation
  32 is much appreciated.
  33
  34   bioperl-l@lists.open-bio.org               - General discussion
  35   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  36
  37 =head2 Reporting Bugs
  38
  39 Report bugs to the Bioperl bug tracking system to
  40 help us keep track the bugs and their resolution.
  41 Bug reports can be submitted via the web.
  42
  43   http://bugzilla.open-bio.org/
  44
  45 =head1 AUTHOR Chris Fields
  46
  47 Email cjfields at uiuc dot edu
  48
  49 =head1 APPENDIX
  50
  51 The rest of the documentation details each of the
  52 object methods. Internal methods are usually
  53 preceded with a _
  54
  55 =cut
  56
  57 # Let the code begin...
  58
  59 package Bio::Tools::EUtilities::Summary::DocSum;
  60
  61 use strict;
  62 use warnings;
  63 use base qw(Bio::Root::Root Bio::Tools::EUtilities::EUtilDataI);
  64
  65 use Bio::Tools::EUtilities::Summary::Item;
  66
  67 =head2 new
  68
  69  Title    : new
  70  Usage    :
  71  Function :
  72  Returns  :
  73  Args     :
  74
  75 =cut
  76
  77 sub new {
  78     my ($class, @args) = @_;
  79     my $self = $class->SUPER::new(@args);
  80     my ($type) = $self->_rearrange(['DATATYPE'],@args);
  81     $type ||= 'docsum';
  82     $self->eutil('esummary');
  83     $self->datatype($type);
  84     return $self;
  85 }
  86
  87 =head2 get_ids
  88
  89  Title    : get_ids
  90  Usage    : my ($id) = $item->get_ids;
  91  Function : returns array or array ref with id
  92  Returns  : array or array ref
  93  Args     : none
  94  Note     : the behavior of this method remains consistent with other
  95             implementations of get_ids(). To retrieve the single DocSum ID
  96             use get_id()
  97
  98 =cut
  99
 100 sub get_ids {
 101     my $self = shift;
 102     return wantarray ? $self->{'_id'} : [$self->{'_id'}];
 103 }
 104
 105 =head2 get_id
 106
 107  Title    : get_id
 108  Usage    : my ($id) = $item->get_id;
 109  Function : returns UID of record
 110  Returns  : integer
 111  Args     : none
 112
 113 =cut
 114
 115 sub get_id {
 116     my $self = shift;
 117     return $self->{'_id'};
 118 }
 119
 120 =head2 next_Item
 121
 122  Title    : next_Item
 123  Usage    : while (my $item = $docsum->next_Item) {...}
 124  Function : iterates through Items (nested layer of Item)
 125  Returns  : single Item
 126  Args     : [optional] single arg (string)
 127             'flatten' - iterates through a flattened list ala
 128                           get_all_DocSum_Items()
 129
 130 =cut
 131
 132 sub next_Item {
 133     my ($self, $request) = @_;
 134     unless ($self->{"_items_it"}) {
 135         #my @items = $self->get_Items;
 136         my @items = ($request && $request eq 'flatten') ?
 137                     $self->get_all_Items :
 138                     $self->get_Items ;
 139         $self->{"_items_it"} = sub {return shift @items}
 140     }
 141     $self->{'_items_it'}->();
 142 }
 143
 144 =head2 get_Items
 145
 146  Title    : get_Items
 147  Usage    : my @items = $docsum->get_Items
 148  Function : returns list of, well, Items
 149  Returns  : array of Items
 150  Args     : none
 151
 152 =cut
 153
 154 sub get_Items {
 155     my $self = shift;
 156     return ref $self->{'_items'} ? @{ $self->{'_items'} } : return ();
 157 }
 158
 159 =head2 get_all_Items
 160
 161  Title    : get_all_Items
 162  Usage    : my @items = $docsum->get_all_Items
 163  Function : returns flattened list of all Item objects (Items, ListItems,
 164             StructureItems)
 165  Returns  : array of Items
 166  Args     : none
 167  Note     : items are added top-down (similar order to using nested calls)
 168             in original list order.
 169
 170              1         2        7        8
 171            Item  -   Item  -  Item  -  Item ...
 172                      |
 173                     | 3        6
 174                  ListItem - ListItem
 175                    |
 176                   | 4          5
 177                Structure - Structure
 178
 179 =cut
 180
 181 sub get_all_Items {
 182     my $self = shift;
 183     unless ($self->{'_ordered_items'}) {
 184         for my $item ($self->get_Items) {
 185             push @{$self->{'_ordered_items'}}, $item;
 186             for my $ls ($item->get_ListItems) {
 187                 push @{$self->{'_ordered_items'}}, $ls;
 188                 for my $st ($ls->get_StructureItems) {
 189                     push @{$self->{'_ordered_items'}}, $st;
 190                 }
 191             }
 192         }
 193     }
 194     return @{$self->{'_ordered_items'}};
 195 }
 196
 197 =head2 get_all_names
 198
 199  Title    : get_all_names
 200  Usage    : my @names = get_all_names()
 201  Function : Returns an array of names for all Item(s) in DocSum.
 202  Returns  : array of unique strings
 203  Args     : none
 204
 205 =cut
 206
 207 sub get_all_names {
 208     my ($self) = @_;
 209     my %tmp;
 210     my @data = grep {!$tmp{$_}++}
 211         map {$_->get_name} $self->get_all_Items;
 212     return @data;
 213 }
 214
 215 =head2 get_Items_by_name
 216
 217  Title    : get_Items_by_name
 218  Usage    : my @items = get_Items_by_name('CreateDate')
 219  Function : Returns named Item(s) in DocSum (indicated by passed argument)
 220  Returns  : array of Item objects
 221  Args     : string (Item name)
 222
 223 =cut
 224
 225 sub get_Items_by_name {
 226     my ($self, $key) = @_;
 227     return unless $key;
 228     my @data = grep {$_->get_name eq $key}
 229         $self->get_all_Items;
 230     return @data;
 231 }
 232
 233 =head2 get_contents_by_name
 234
 235  Title    : get_contents_by_name
 236  Usage    : my ($data) = get_contents_by_name('CreateDate')
 237  Function : Returns content for named Item(s) in DocSum (indicated by
 238             passed argument)
 239  Returns  : array of values (type varies per Item)
 240  Args     : string (Item name)
 241
 242 =cut
 243
 244 sub get_contents_by_name {
 245     my ($self, $key) = @_;
 246     return unless $key;
 247     my @data = map {$_->get_content}
 248         grep {$_->get_name eq $key}
 249         $self->get_all_Items;
 250     return @data;
 251 }
 252
 253 =head2 get_type_by_name
 254
 255  Title    : get_type_by_name
 256  Usage    : my $data = get_type_by_name('CreateDate')
 257  Function : Returns data type for named Item in DocSum (indicated by
 258             passed argument)
 259  Returns  : scalar value (string) if present
 260  Args     : string (Item name)
 261
 262 =cut
 263
 264 sub get_type_by_name {
 265     my ($self, $key) = @_;
 266     return unless $key;
 267     my ($it) = grep {$_->get_name eq $key} $self->get_all_Items;
 268     return $it->get_type;
 269 }
 270
 271 =head2 rewind
 272
 273  Title    : rewind
 274  Usage    : $docsum->rewind();
 275  Function : rewinds DocSum iterator
 276  Returns  : none
 277  Args     : [optional]
 278            'recursive' - rewind all DocSum object layers
 279                          (Items, ListItems, StructureItems)
 280
 281 =cut
 282
 283 sub rewind {
 284     my ($self, $request) = @_;
 285     if ($request && $request eq 'all') {
 286         map {$_->rewind('all') } $self->get_Items;
 287     }
 288     delete $self->{"_items_it"};
 289 }
 290
 291 # private EUtilDataI method
 292
 293 sub _add_data {
 294     my ($self, $data) = @_;
 295     if ($data->{Item}) {
 296         $self->{'_id'} = $data->{Id} if exists $data->{Id};
 297         for my $sd (@{ $data->{Item} } ) {
 298             $sd->{Id} = $data->{Id} if exists $data->{Id};
 299             my $subdoc =
 300                 Bio::Tools::EUtilities::Summary::Item->new(-datatype => 'item',
 301                                                   -verbose => $self->verbose);
 302             $subdoc->_add_data($sd);
 303             push @{ $self->{'_items'} }, $subdoc;
 304         }
 305     }
 306     $self->{'_id'} = $data->{Id} if exists $data->{Id};
 307 }
 308
 309 =head2 to_string
 310
 311  Title    : to_string
 312  Usage    : $foo->to_string()
 313  Function : converts current object to string
 314  Returns  : none
 315  Args     : (optional) simple data for text formatting
 316  Note     : Used generally for debugging and for various print methods
 317
 318 =cut
 319
 320 sub to_string {
 321     my $self = shift;
 322     my $string = sprintf("%-20s%s\n",'UID', ':'.$self->get_id);
 323     while (my $item = $self->next_Item)  {
 324         $string .= $item->to_string;
 325     }
 326     return $string;
 327 }
 328
 329 1;