[Bioperl-l] Feature/Annotation rollback(update)

[Hilmar Lapp]

The thing that I actually never quite understood (and predates the  
API changes) is why $ann->as_text() needs to include explanatory text  
such as 'Direct database link to blah in database foo.' I would have  
said that "TSC:TSC0000030" is human readable enough, unless you  
present it without any context so that one would have no clue that it  
is a database cross-reference.

The as_text() method shouldn't be meant for the sole purpose of  
debugging annotation collections. However, I'm not sure for what else  
you could use it for, given that there are no guidelines for what to  
expect.

In fact, I do use as_text() a lot for a real purpose, namely as a  
surrogate unique key. For example, making a collection of dblinks  
unique is quite simple using the as_text() method:

	my %dbhash = map { ($_->as_text(), $_) } $anncoll->remove_Annotations 
('dblink');
	$anncoll->add_Annotation('dblink',$_) foreach (values %dbhash);

This is a common task when harvesting annotation from various places  
and then integrating it. However, there is nothing in the API  
documentation that suggests that this might be a reliable or even  
expected property such that you could omit the 'dblink' tag above.

I agree that having a conceptual equivalent to $feature->display_name  
and $seq->display_id would be good, but these methods have no claim  
to returning something that's unique in any way.

I guess I've now raised more questions than I answered (in fact I  
didn't answer any). Sorry 'bout that.

	-hilmar

On Aug 26, 2007, at 3:22 PM, Chris Fields wrote:

> I managed to find your comments (as well as ones from Ewan, Jason,  
> and a few others) on the mail list archives, so I'll link to them.   
> The problem will be fixing the several places where overloading is  
> assumed but no longer exists (i.e. in write_* methods), but we can  
> probably pinpoint those by throwing or warning when overloading is  
> assumed.
>
> My thought is to either modify as_text() or add a new display_text 
> () method to all AnnotationI that explicitly does what the  
> overloading implied (print the annotation in a specified or assumed  
> way).  We could then delegate to that in the stringification  
> overload (with appropriate deprecation warnings) until 1.6, where  
> we remove it completely.  Something like:
>
> my $link1 = Bio::Annotation::DBLink->new(-database => 'TSC',
>                                         -primary_id => 'TSC0000030',
>                                         -tagname => "tag2);
>
> # either
> print $link1->display_text(),"\n";
> # or ...
> print $link1->as_text("display"),"\n";
> # prints "TSC:TSC0000030"
>
> # default human readable
> print $link1->as_text(),"\n";
> # prints "Direct database link to TSC0000030 in database TSC"
>
> print "$link1\n";
> # gets a deprecation warning for now, removed completely for 1.6
>
> chris
>
> On Aug 25, 2007, at 11:58 PM, Hilmar Lapp wrote:
>
>> The reason was to provide for backward compatibility with the  
>> original API in which tag values were scalars, not objects. The  
>> idea was that if someone relied on that and treats the object as a  
>> scalar (comparison, printing, etc), the operator overloading would  
>> take care of that.
>>
>> So by going back to the original API the overloading should become  
>> obsolete, at least theoretically.
>>
>> The overloading can cause some very subtle issues that I pointed  
>> out in an earlier email. It's one of those really "clever" tricks  
>> that just make it very hard for newcomers to understand what's  
>> going on in their code.
>>
>> 	-hilmar
>>
>> On Aug 25, 2007, at 6:12 PM, Chris Fields wrote:
>>
>>> I have finished rolling back most of the specific changes made prior
>>> to the 1.5 release and have relevant tests passing:
>>>
>>> http://www.bioperl.org/wiki/Feature_Annotation_rollback#First_round
>>>
>>> Operator overloading of Bio::Annotation objects will be trickier to
>>> debug as tons of tests fail when the overloading is removed:
>>>
>>> http://www.bioperl.org/wiki/Feature_Annotation_rollback#Second_round
>>>
>>> I'll start looking into fixes.  I don't like overloads from a
>>> personal standpoint (problems w/ long-term code maintenance), but  
>>> was
>>> there a more specific reason for removing them?
>>>
>>> chris
>>> _______________________________________________
>>> Bioperl-l mailing list
>>> Bioperl-l at lists.open-bio.org
>>> http://lists.open-bio.org/mailman/listinfo/bioperl-l
>>
>> -- 
>> ===========================================================
>> : Hilmar Lapp  -:-  Durham, NC  -:-  hlapp at gmx dot net :
>> ===========================================================
>>
>>
>>
>>
>>
>
> Christopher Fields
> Postdoctoral Researcher
> Lab of Dr. Robert Switzer
> Dept of Biochemistry
> University of Illinois Urbana-Champaign
>
>

-- 
===========================================================
: Hilmar Lapp  -:-  Durham, NC  -:-  hlapp at gmx dot net :
===========================================================