Bio::Tools::EUtilities::Summary::Item.3pm

Langue: en

Version: 2010-05-19 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

NAME

Bio::Tools::EUtilities::Summary::Item - simple layered object for DocSum item data

SYNOPSIS

   # Items can be nested up to three levels at this time. These levels can be
   # accessed via Item, ListItem, or StructureItem methods:
 
   while (my $item = $docsum->next_Item) {
      print "Name: ",$item->get_name,"\n";
      print "Data: ",$item->get_content,"\n";
      print "Type: ",$item->get_type,"\n";
      while (my $ls = $item->next_ListItem) {
         # do same here
         while (my $struct = $ls->next_StructureItem) {
            # do more stuff here
         }
      }
   }
 
 

DESCRIPTION

DocSum data, as returned from esummary, normally is a simple list of item-content-content_type groups. However, items can also contain nested data to represent more complex data (such as structural data). Up to three nested layers may appear in any document summary.

This class contains methods to access data that can appear in a docsum for any individual item as well as describes methods to traverse the hierarchy of items present in a document summary.

The unique name for items are accessed via get_name(), the content by get_content() (if present), and the data type by get_type(). Items can have ListItems (Item objects with a datatype() 'list'), which in turn can have StructureItems (Item objects with a datatype of 'structure'). Items are initially traversed via a DocSum object using next_Item() or obtained all at once with get_Items(). Similarly, nested Items can be accessed by using next_ListItem/get_ListItems and next_StructureItem/get_StructureItem. A flattened list of items can be accessed with get_all_Items().

FEEDBACK

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.
   bioperl-l@lists.open-bio.org               - General discussion
   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
 
 

Support

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

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.

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.
   http://bugzilla.open-bio.org/
 
 

AUTHOR Chris Fields

Email cjfields at bioperl dot org

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new

  Title    : new
  Usage    : 
  Function : 
  Returns  : 
  Args     :
 
 

get_ids

  Title    : get_ids
  Usage    : my ($id) = $item->get_ids;
  Function : returns array or array ref with id
  Returns  : array or array ref
  Args     : none
  Note     : the behavior of this method is to remain consistent with other 
             implementations of get_ids(). To retrieve the single DocSum ID use
             get_id()
 
 

get_id

  Title    : get_id
  Usage    : my ($id) = $item->get_id;
  Function : returns UID of record
  Returns  : integer
  Args     : none
 
 

next_ListItem

  Title    : next_ListItem
  Usage    : while (my $ls = $item->next_ListItem) {...}
  Function : iterates through ListItems (nested layer of Item)
  Returns  : single ListItem
  Args     : none
 
 

get_ListItems

  Title    : get_ListItems
  Usage    : my @ls = $item->get_ListItems
  Function : returns list of, well, List Items
  Returns  : array of List Items
  Args     : none
 
 

next_StructureItem

  Title    : next_StructureItem
  Usage    : while (my $struc = $ls->next_StructureItem) {...}
  Function : iterates through StructureItems (nested layer of ListItem)
  Returns  : single StructureItems
  Args     : none
 
 

get_StructureItems

  Title    : get_StructureItems
  Usage    : my @structs = $ls->get_StructureItems
  Function : returns list of Structure Items
  Returns  : array of StructureItems
  Args     : none
 
 

next_subItem

  Title    : next_subItem
  Usage    : while (my $it = $ls->next_subItem) {...}
  Function : iterates through the next layer of Items
  Returns  : single Item
  Args     : none
  Notes    : unlike next_ListItem and next_StructureItem, this generically
             accesses any sub Items (useful for recursive calls, for example)
 
 

get_subItems

  Title    : get_subItems
  Usage    : my @items = $ls->get_subItems
  Function : returns list of sub Items
  Returns  : array of Items
  Args     : none
  Notes    : unlike get_ListItems and get_StructureItems, this generically
             accesses any sub Items (useful for recursive calls, for example)
 
 

get_name

  Title    : get_name
  Usage    : my $nm = $ls->get_name
  Function : retrieves Item/ListItem/StructureItem name for this Item
  Returns  : string
  Args     : none
 
 

get_type

  Title    : get_type
  Usage    : my $type = $ls->get_type
  Function : retrieves Item/ListItem/StructureItem type 
  Returns  : string
  Args     : none
  Note     : this is not the same as the datatype(), which describes the
             group this Item object belongs to
 
 

get_content

  Title    : get_content
  Usage    : my $data = $ls->get_content
  Function : retrieves Item/ListItem/StructureItem content (if any)
  Returns  : string
  Args     : none
 
 

rewind

  Title    : rewind
  Usage    : $item->rewind()
  Function : rewinds iterators
  Returns  : none
  Args     : [optional] No arg - only rewinds current layer
            'all' - rewind all DocSum object layers
                 (Items, ListItems, StructureItems)
 
 

ItemContainerI methods

next_Item

  Title    : next_Item
  Usage    : while (my $item = $docsum->next_Item) {...}
  Function : iterates through Items (nested layer of Item)
  Returns  : single Item
  Args     : [optional] single arg (string)
             'flatten' - iterates through a flattened list ala
                           get_all_DocSum_Items()
 
 

get_Items

  Title    : get_Items
  Usage    : my @items = $docsum->get_Items
  Function : returns list of, well, Items
  Returns  : array of Items
  Args     : none
 
 

get_all_Items

  Title    : get_all_Items
  Usage    : my @items = $docsum->get_all_Items
  Function : returns flattened list of all Item objects (Items, ListItems,
             StructureItems)
  Returns  : array of Items
  Args     : none
  Note     : items are added top-down (similar order to using nested calls)
             in original list order.
 
              1         2        7        8
            Item  -   Item  -  Item  -  Item ...
                      |
                     | 3        6
                  ListItem - ListItem
                    |
                   | 4          5
                Structure - Structure
 
 

get_all_names

  Title    : get_all_names
  Usage    : my @names = get_all_names()
  Function : Returns an array of names for all Item(s) in DocSum.
  Returns  : array of unique strings
  Args     : none
 
 

get_Items_by_name

  Title    : get_Items_by_name
  Usage    : my @items = get_Items_by_name('CreateDate')
  Function : Returns named Item(s) in DocSum (indicated by passed argument)
  Returns  : array of Item objects
  Args     : string (Item name)
 
 

get_contents_by_name

  Title    : get_contents_by_name
  Usage    : my ($data) = get_contents_by_name('CreateDate')
  Function : Returns content for named Item(s) in DocSum (indicated by
             passed argument)
  Returns  : array of values (type varies per Item)
  Args     : string (Item name)
 
 

get_type_by_name

  Title    : get_type_by_name
  Usage    : my $data = get_type_by_name('CreateDate')
  Function : Returns data type for named Item in DocSum (indicated by
             passed argument)
  Returns  : scalar value (string) if present
  Args     : string (Item name)
 
 

to_string

  Title    : to_string
  Usage    : $foo->to_string()
  Function : converts current object to string
  Returns  : none
  Args     : (optional) simple data for text formatting.  This implementation
             passes an argument for layering Items/subItems
  Note     : Used generically for debugging and print_DocSums methods