NAME

       Bio::Annotation::Reference - Specialised DBLink object for Literature References

SYNOPSIS

           $reg = Bio::Annotation::Reference->new( -title    => 'title line',
                                                   -location => 'location line',
                                                   -authors  => 'author line',
                                                   -medline  => 998122 );

DESCRIPTION

       Object which presents a literature reference. This is considered to be a specialised form
       of database link. The additional methods provided are all set/get methods to store strings
       commonly associated with references, in particular title, location (ie, journal page) and
       authors line.

       There is no attempt to do anything more than store these things as strings for processing
       elsewhere. This is mainly because parsing these things suck and generally are specific to
       the specific format one is using. To provide an easy route to go format --> object -->
       format without losing data, we keep them as strings. Feel free to post the list for a
       better solution, but in general this gets very messy very fast...

AUTHOR - Ewan Birney

       Email birney@ebi.ac.uk

APPENDIX

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

   new
        Title   : new
        Usage   : $ref = Bio::Annotation::Reference->new( -title => 'title line',
                                  -authors => 'author line',
                                  -location => 'location line',
                                  -medline => 9988812);
        Function:
        Example :
        Returns : a new Bio::Annotation::Reference object
        Args    : a hash with optional title, authors, location, medline, pubmed,
                  start, end, consortium, rp and rg attributes

AnnotationI implementing functions

   as_text
        Title   : as_text
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   display_text
        Title   : display_text
        Usage   : my $str = $ann->display_text();
        Function: returns a string. Unlike as_text(), this method returns a string
                  formatted as would be expected for te specific implementation.

                  One can pass a callback as an argument which allows custom text
                  generation; the callback is passed the current instance and any text
                  returned
        Example :
        Returns : a string
        Args    : [optional] callback

   hash_tree
        Title   : hash_tree
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   tagname
        Title   : tagname
        Usage   : $obj->tagname($newval)
        Function: Get/set the tagname for this annotation value.

                  Setting this is optional. If set, it obviates the need to provide
                  a tag to Bio::AnnotationCollectionI when adding this object. When
                  obtaining an AnnotationI object from the collection, the collection
                  will set the value to the tag under which it was stored unless the
                  object has a tag stored already.
        Example :
        Returns : value of tagname (a scalar)
        Args    : new value (a scalar, optional)

Specific accessors for References

   start
        Title   : start
        Usage   : $self->start($newval)
        Function: Gives the reference start base
        Example :
        Returns : value of start
        Args    : newvalue (optional)

   end
        Title   : end
        Usage   : $self->end($newval)
        Function: Gives the reference end base
        Example :
        Returns : value of end
        Args    : newvalue (optional)

   rp
        Title   : rp
        Usage   : $self->rp($newval)
        Function: Gives the RP line. No attempt is made to parse this line.
        Example :
        Returns : value of rp
        Args    : newvalue (optional)

   rg
        Title   : rg
        Usage   : $obj->rg($newval)
        Function: Gives the RG line. This is Swissprot/Uniprot specific, and
                  if set will usually be identical to the authors attribute,
                  but the swissprot manual does allow both RG and RA (author)
                  to be present for the same reference.

        Example :
        Returns : value of rg (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   authors
        Title   : authors
        Usage   : $self->authors($newval)
        Function: Gives the author line. No attempt is made to parse the author line
        Example :
        Returns : value of authors
        Args    : newvalue (optional)

   location
        Title   : location
        Usage   : $self->location($newval)
        Function: Gives the location line. No attempt is made to parse the location line
        Example :
        Returns : value of location
        Args    : newvalue (optional)

   title
        Title   : title
        Usage   : $self->title($newval)
        Function: Gives the title line (if exists)
        Example :
        Returns : value of title
        Args    : newvalue (optional)

   medline
        Title   : medline
        Usage   : $self->medline($newval)
        Function: Gives the medline number
        Example :
        Returns : value of medline
        Args    : newvalue (optional)

   pubmed
        Title   : pubmed
        Usage   : $refobj->pubmed($newval)
        Function: Get/Set the PubMed number, if it is different from the MedLine
                  number.
        Example :
        Returns : value of medline
        Args    : newvalue (optional)

   database
        Title   : database
        Usage   :
        Function: Overrides DBLink database to be hard coded to 'MEDLINE' (or 'PUBMED'
                  if only pubmed id has been supplied), unless the database has been
                  set explicitly before.
        Example :
        Returns :
        Args    :

   primary_id
        Title   : primary_id
        Usage   :
        Function: Overrides DBLink primary_id to provide medline number, or pubmed
                  number if only that has been defined
        Example :
        Returns :
        Args    :

   optional_id
        Title   : optional_id
        Usage   :
        Function: Overrides DBLink optional_id to provide the PubMed number.
        Example :
        Returns :
        Args    :

   publisher
        Title   : publisher
        Usage   : $self->publisher($newval)
        Function: Gives the publisher line. No attempt is made to parse the publisher line
        Example :
        Returns : value of publisher
        Args    : newvalue (optional)

   editors
        Title   : editors
        Usage   : $self->editors($newval)
        Function: Gives the editors line. No attempt is made to parse the editors line
        Example :
        Returns : value of editors
        Args    : newvalue (optional)

   encoded_ref
        Title   : encoded_ref
        Usage   : $self->encoded_ref($newval)
        Function: Gives the encoded_ref line. No attempt is made to parse the encoded_ref line
           (this is added for reading PDB records (REFN record), where this contains
            ISBN/ISSN/ASTM code)
        Example :
        Returns : value of encoded_ref
        Args    : newvalue (optional)

   doi
        Title   : doi
        Usage   : $self->doi($newval)
        Function: Gives the DOI (Digital Object Identifier) from the International
                  DOI Foundation (http://www.doi.org/), which can be used to resolve
                          URL links for the full-text documents using:

                          http://dx.doi.org/<doi>

        Example :
        Returns : value of doi
        Args    : newvalue (optional)

   consortium
        Title   : consortium
        Usage   : $self->consortium($newval)
        Function: Gives the consortium line. No attempt is made to parse the consortium line
        Example :
        Returns : value of consortium
        Args    : newvalue (optional)

   gb_reference
        Title   : gb_reference
        Usage   : $obj->gb_reference($newval)
        Function: Gives the generic GenBank REFERENCE line. This is GenBank-specific.
                  If set, this includes everything on the reference line except
                          the REFERENCE tag and the reference count.  This is mainly a
                          fallback for the few instances when REFERENCE lines have unusual
                          additional information such as split sequence locations, feature
                          references, etc.  See Bug 2020 in Bugzilla for more information.
        Example :
        Returns : value of gb_reference (a scalar)
        Args    : on set, new value (a scalar or undef, optional)