[Bioperl-l] Bio::SeqFeature::AnnotationAdaptor

[Hilmar Lapp]

I wrote and committed this. Test is in t/AnnotationAdaptor.t. 
Excerpt from the POD:

=head1 NAME

Bio::SeqFeature::AnnotationAdaptor - integrates SeqFeatureIs annotation

=head1 SYNOPSIS

    use Bio::SeqFeature::Generic;
    use Bio::SeqFeature::AnnotationAdaptor;

    # obtain a SeqFeatureI implementing object somehow
    my $feat = Bio::SeqFeature::Generic->new(-start => 10, -end => 20);

    # add tag/value annotation
    $feat->add_tag_value("mytag", "value of tag mytag");
    $feat->add_tag_value("mytag", "another value of tag mytag");

    # Bio::SeqFeature::Generic also provides annotation(), which 
returns a
    # Bio::AnnotationCollectionI compliant object
    $feat->annotation->add_Annotation("dbxref", $dblink);

    # to integrate tag/value annotation with AnnotationCollectionI
    # annotation, use this adaptor, which also implements
    # Bio::AnnotationCollectionI
    my $anncoll = Bio::SeqFeature::AnnotationAdaptor(-feature => $feat);

    # this will now return tag/value pairs as
    # Bio::Annotation::SimpleValue objects
    my @anns = $anncoll->get_Annotations("mytag");
    # other added before annotation is available too
    my @dblinks = $anncoll->get_Annotations("dbxref");

    # also supports transparent adding of tag/value pairs in
    # Bio::AnnotationI flavor
    my $tagval = Bio::Annotation::SimpleValue->new(-value => "some 
value",
                                                   -tagname => "some 
tag");
    $anncoll->add_Annotation($tagval);
    # this is now also available from the feature's tag/value system
    my @vals = $feat->each_tag_value("some tag");

=head1 DESCRIPTION

L<Bio::SeqFeatureI> defines light-weight annotation of features
through tag/value pairs. Conversely, L<Bio::AnnotationCollectionI>
together with L<Bio::AnnotationI> defines an annotation bag, which is
better typed, but more heavy-weight because it contains every single
piece of annotation as objects. The frequently used base
implementation of Bio::SeqFeatureI, Bio::SeqFeature::Generic, defines
an additional slot for AnnotationCollectionI-compliant annotation.

This adaptor provides a L<Bio::AnnotationCollectionI> compliant,
unified, and integrated view on the annotation of L<Bio::SeqFeatureI>
objects, including tag/value pairs, and annotation through the
annotation() method, if the object supports it. Code using this
adaptor does not need to worry about the different ways of possibly
annotating a SeqFeatureI object, but can instead assume that it
strictly follows the AnnotationCollectionI scheme. The price to pay is
that retrieving and adding annotation will always use objects instead
of light-weight tag/value pairs.

In other words, this adaptor allows us to keep the best of both
worlds. If you create tens of thousands of feature objects, and your
only annotation is tag/value pairs, you are best off using the
features' native tag/value system. If you create a smaller number of
features, but with rich and typed annotation mixed with tag/value
pairs, this adaptor may be for you. Since its implementation is by
double-composition, you only need to create one instance of the
adaptor. In order to transparently annotate a feature object, set the
feature using the feature() method. Every annotation you add will be
added to the feature object, and hence will not be lost when you set
feature() to the next object.

=cut

Comments/suggestions/feedback welcome.

	-hilmar
--
-------------------------------------------------------------
Hilmar Lapp                            email: lapp at gnf.org
GNF, San Diego, Ca. 92121              phone: +1-858-812-1757
-------------------------------------------------------------