NAME

Bio::Phylo::Annotation - Single key/value annotation, used within dictionary

SYNOPSIS

 use Bio::Phylo::Factory;
 my $fac = Bio::Phylo::Factory->new;
 # there are several data types: string, integer, float, uri, any, etc.
 # refer to nexml.org for a complete list
 my $dic = $fac->create_dictionary( -tag => 'string' );
 my $ann = $fac->create_annotation( -value => 'This is a description' );
 $dic->insert( $ann );
 print $dic->to_xml;

 # prints: <dict><string id="string2">This is a description</string></dict>

DESCRIPTION

To comply with the NeXML standard (http://www.nexml.org), Bio::Phylo implements dictionary annotations, which consist conceptually of key/value pairs where the key is an xml id (which is either autogenerated or can be set using the set_xml_id method) and the value is the containing element (whose name specifies the data type of its text contents, i.e. string, integer, float and so on).

This class implements a single key/value pair, of which multiples can be inserted in a dictionary to create a data structure that is serialized to something akin to a hash. The dictionary can be attached to any of the subclasses of Bio::Phylo::Util::XMLWritable.

Of note is the fact that annotations can has different xml tag names, where the name specifies the data type of the annotation text content. For example, if you set the tag name to 'string' (i.e. $ann->set_tag('string')) then the value is interpreted to be a string (i.e. $ann->set_value('some kind of string')). Also, a common tag name is 'any', which means that the value is any kind of xml structure, which can be provided as a raw string, or as an xml element tree object of one of the following distributions: XML::DOM, XML::GDOME, XML::LibXML, XML::Twig, XML::DOM2, XML::DOMBacked, XML::Handler, XML::Element, XML::API, XML::Code or XML::XMLWriter. Alternatively, you can provide a RDF::Core::Model for semantic annotations or a Bio::Phylo::Dictionary to create recursively nested dictionaries.

METHODS

CONSTRUCTOR

new()

 Type    : Constructor
 Title   : new
 Usage   : my $anno = Bio::Phylo::Annotation->new;
 Function: Initializes a Bio::Phylo::Annotation object.
 Returns : A Bio::Phylo::Annotation object.
 Args    : optional constructor arguments are key/value
                   pairs where the key corresponds with any of
                   the methods that starts with set_ (i.e. mutators) 
                   and the value is the permitted argument for such 
                   a method. The method name is changed such that,
                   in order to access the set_value($val) method
                   in the constructor, you would pass -value => $val

MUTATORS

set_value()

Sets the annotation value, e.g. for an annotation with tag 'string', this would be a free form string, such as a description.

 Type    : Mutator
 Title   : set_value
 Usage   : $anno->set_value('this is a description');
 Function: Sets the annotation value
 Returns : Modified object.
 Args    : A valid argument is whatever is valid for the annotation
           data type.

ACCESSORS

get_value()

Gets invocant's value.

 Type    : Accessor
 Title   : get_value
 Usage   : my $val = $anno->get_value;
 Function: Gets invocant's value.
 Returns : The specified value, whose data type depends on the 
           xml tag name.
 Args    : NONE

SERIALIZERS

to_xml()

Serializes object to an xml string

 Type    : Serializer
 Title   : to_xml()
 Usage   : print $ann->to_xml();
 Function: Serializes object to xml string
 Returns : String 
 Args    : None
 Comments:

SEE ALSO

Bio::Phylo::Dictionary

Annotation objects are combined into a dictionary.

Bio::Phylo::Util::XMLWritable

This object inherits from Bio::Phylo::Util::XMLWritable, so methods defined there are also applicable here.

Bio::Phylo::Manual

Also see the manual: Bio::Phylo::Manual and http://rutgervos.blogspot.com.

REVISION

 $Id: Annotation.pm 1040 2009-05-28 04:26:49Z rvos $