/ 
Bio-Phylo-0.17_RC7
River stage two • 8 direct dependents • 17 total dependents
/ Bio::Phylo::Annotation

NAME

Bio::Phylo::Annotation - Segment in an object to annotate other objects with.

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::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 604 2008-09-05 17:32:28Z rvos $