Provided by: libbio-perl-perl_1.7.2-2_all bug

NAME

       Bio::Cluster::UniGene - UniGene object

SYNOPSIS

               use Bio::Cluster::UniGene;
               use Bio::ClusterIO;

               $stream  = Bio::ClusterIO->new('-file' => "Hs.data",
                                              '-format' => "unigene");
               # note: we quote -format to keep older perl's from complaining.

               while ( my $in = $stream->next_cluster() ) {
                       print $in->unigene_id() . "\n";
                       while ( my $sequence = $in->next_seq() ) {
                               print $sequence->accession_number() . "\n";
                       }
              }

DESCRIPTION

       This UniGene object implements the Bio::Cluster::UniGeneI interface for the representation
       if UniGene clusters in Bioperl. It is returned by the Bio::ClusterIO parser for unigene
       format and contains all the data associated with one UniGene record.

       This class implements several interfaces and hence can be used wherever instances of such
       interfaces are expected. In particular, the interfaces are Bio::ClusterI as the base
       interface for all cluster representations, and in addition Bio::IdentifiableI and
       Bio::DescribableI.

       The following lists the UniGene specific methods that are available (see below for
       details). Be aware next_XXX iterators take a snapshot of the array property when they are
       first called, and this snapshot is not reset until the iterator is exhausted. Hence, once
       called you need to exhaust the iterator to see any changes that have been made to the
       property in the meantime. You will usually want to use the non-iterator equivalents and
       loop over the elements yourself.

       new() - standard new call

       unigene_id() - set/get unigene_id

       title() - set/get title (description)

       gene() - set/get gene

       cytoband() - set/get cytoband

       mgi() - set/get mgi

       locuslink() - set/get locuslink

       homol() - set/get homologene

       gnm_terminus() - set/get gnm_terminus

       scount() - set/get scount

       express() - set/get express, currently takes/returns a reference to an array of expressed
       tissues

       next_express() - returns the next tissue expression from the expressed tissue array

       chromosome() - set/get chromosome, currently takes/returns a reference to an array of
       chromosome lines

       next_chromosome() - returns the next chromosome line from the array of chromosome lines

       sts() - set/get sts, currently takes/returns a reference to an array of sts lines

       next_sts() - returns the next sts line from the array of sts lines

       txmap() - set/get txmap, currently takes/returns a reference to an array of txmap lines

       next_txmap() - returns the next txmap line from the array of txmap lines

       protsim() - set/get protsim, currently takes/returns a reference to an array of protsim
       lines

       next_protsim() - returns the next protsim line from the array of protsim lines

       sequences() - set/get sequence, currently takes/returns a reference to an array of
       references to seq info

       next_seq() - returns a Seq object that currently only contains an accession number

Implemented Interfaces

       This class implementes the following interfaces.

       Bio::Cluster::UniGeneI
           This includes implementing Bio::ClusterI.

       Bio::IdentifiableI
       Bio::DescribableI
       Bio::AnnotatableI
       Bio::Factory::SequenceStreamI

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists. Your
       participation is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution.  Bug reports can be submitted via the web:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Andrew Macgregor

       Email andrew at cbbc.murdoch.edu.au

CONTRIBUTORS

       Hilmar Lapp, hlapp at gmx.net

APPENDIX

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

   new
        Title   : new
        Usage   : used by ClusterIO
        Returns : a new Bio::Cluster::Unigene object

Bio::Cluster::UniGeneI methods

   unigene_id
        Title   : unigene_id
        Usage   : unigene_id();
        Function: Returns the unigene_id associated with the object.
        Example : $id = $unigene->unigene_id or $unigene->unigene_id($id)
        Returns : A string
        Args    : None or an id

   title
        Title   : title
        Usage   : title();
        Function: Returns the title associated with the object.
        Example : $title = $unigene->title or $unigene->title($title)
        Returns : A string
        Args    : None or a title

   gene
        Title   : gene
        Usage   : gene();
        Function: Returns the gene associated with the object.
        Example : $gene = $unigene->gene or $unigene->gene($gene)
        Returns : A string
        Args    : None or a gene

   cytoband
        Title   : cytoband
        Usage   : cytoband();
        Function: Returns the cytoband associated with the object.
        Example : $cytoband = $unigene->cytoband or $unigene->cytoband($cytoband)
        Returns : A string
        Args    : None or a cytoband

   mgi
        Title   : mgi
        Usage   : mgi();
        Function: Returns the mgi associated with the object.
        Example : $mgi = $unigene->mgi or $unigene->mgi($mgi)
        Returns : A string
        Args    : None or a mgi

   locuslink
        Title   : locuslink
        Usage   : locuslink();
        Function: Returns or stores a reference to an array containing locuslink data.
        Returns : An array reference
        Args    : None or an array reference

   homol
        Title   : homol
        Usage   : homol();
        Function: Returns the homol entry associated with the object.
        Example : $homol = $unigene->homol or $unigene->homol($homol)
        Returns : A string
        Args    : None or a homol entry

   restr_expr
        Title   : restr_expr
        Usage   : restr_expr();
        Function: Returns the restr_expr entry associated with the object.
        Example : $restr_expr = $unigene->restr_expr or $unigene->restr_expr($restr_expr)
        Returns : A string
        Args    : None or a restr_expr entry

   gnm_terminus
        Title   : gnm_terminus
        Usage   : gnm_terminus();
        Function: Returns the gnm_terminus associated with the object.
        Example : $gnm_terminus = $unigene->gnm_terminus or
                  $unigene->gnm_terminus($gnm_terminus)
        Returns : A string
        Args    : None or a gnm_terminus

   scount
        Title   : scount
        Usage   : scount();
        Function: Returns the scount associated with the object.
        Example : $scount = $unigene->scount or $unigene->scount($scount)
        Returns : A string
        Args    : None or a scount

   express
        Title   : express
        Usage   : express();
        Function: Returns or stores a reference to an array containing
                  tissue expression data
        Returns : An array reference
        Args    : None or an array reference

   chromosome
        Title   : chromosome
        Usage   : chromosome();
        Function: Returns or stores a reference to an array containing
                  chromosome lines
        Returns : An array reference
        Args    : None or an array reference

   sts
        Title   : sts
        Usage   : sts();
        Function: Returns or stores a reference to an array containing sts lines

        Returns : An array reference
        Args    : None or an array reference

   txmap
        Title   : txmap
        Usage   : txmap();
        Function: Returns or stores a reference to an array containing txmap lines

        Returns : An array reference
        Args    : None or an array reference

   protsim
        Title   : protsim
        Usage   : protsim();
        Function: Returns or stores a reference to an array containing protsim lines
                  This should really only be used by ClusterIO, not directly
        Returns : An array reference
        Args    : None or an array reference

   sequences
        Title   : sequences
        Usage   : sequences();
        Function: Returns or stores a reference to an array containing
                  sequence data.

                  This is mostly reserved for ClusterIO parsers. You should
                  use get_members() for get and add_member()/remove_members()
                  for set.

        Returns : An array reference, or undef
        Args    : None or an array reference or undef

   species
        Title   : species
        Usage   : $obj->species($newval)
        Function: Get/set the species object for this Unigene cluster.
        Example :
        Returns : value of species (a L<Bio::Species> object)
        Args    : on set, new value (a L<Bio::Species> object or
                  the binomial name, or undef, optional)

Bio::ClusterI methods

   display_id
        Title   : display_id
        Usage   :
        Function: Get/set the display name or identifier for the cluster

                  This is aliased to unigene_id().

        Returns : a string
        Args    : optional, on set the display ID ( a string)

   description
        Title   : description
        Usage   : Bio::ClusterI->description("POLYUBIQUITIN")
        Function: get/set for the consensus description of the cluster

                  This is aliased to title().

        Returns : the description string
        Args    : Optional the description string

   size
        Title   : size
        Usage   : Bio::ClusterI->size();
        Function: get for the size of the family,
                  calculated from the number of members

                  This is aliased to scount().

        Returns : the size of the cluster
        Args    :

   cluster_score
        Title   : cluster_score
        Usage   : $cluster ->cluster_score(100);
        Function: get/set for cluster_score which
                  represent the score in which the clustering
                  algorithm assigns to this cluster.

                  For UniGene clusters, there really is no cluster score that
                  would come with the data. However, we provide an
                  implementation here so that you can score UniGene clusters
                  if you want to.

        Returns : a number
        Args    : optionally, on set a number

   get_members
        Title   : get_members
        Usage   : Bio::ClusterI->get_members(($seq1, $seq2));
        Function: retrieve the members of the family by some criteria

                  Will return all members if no criteria are provided.

                  At this time this implementation does not support
                  specifying criteria and will always return all members.

        Returns : the array of members
        Args    :

Annotatable view at the object properties

   annotation
        Title   : annotation
        Usage   : $obj->annotation($newval)
        Function: Get/set the L<Bio::AnnotationCollectionI> object for
                  this UniGene cluster.

                  Many attributes of this class are actually stored within
                  the annotation collection object as L<Bio::AnnotationI>
                  compliant objects, so you can conveniently access them
                  through the same interface as you would e.g. access
                  L<Bio::SeqI> annotation properties.

                  If you call this method in set mode and replace the
                  annotation collection with another one you should know
                  exactly what you are doing.

        Example :
        Returns : a L<Bio::AnnotationCollectionI> compliant object
        Args    : on set, new value (a L<Bio::AnnotationCollectionI>
                  compliant object or undef, optional)

Implementation specific methods

        These are mostly for adding/removing to array properties, and for
        methods with special functionality.

   add_member
        Title   : add_member
        Usage   :
        Function: Adds a member object to the list of members.
        Example :
        Returns : TRUE if the new member was successfully added, and FALSE
                  otherwise.
        Args    : The member to add.

   remove_members
        Title   : remove_members
        Usage   :
        Function: Remove the list of members for this cluster such that the
                  member list is undefined afterwards (as opposed to zero members).
        Example :
        Returns : the previous list of members
        Args    : none

   next_locuslink
        Title   : next_locuslink
        Usage   : next_locuslink();
        Function: Returns the next locuslink from an array referred
                  to using $obj->{'locuslink'}

                  If you call this iterator again after it returned undef, it
                  will re-cycle through the list of elements. Changes in the
                  underlying array property while you loop over this iterator
                  will not be reflected until you exhaust the iterator.

        Example :      while ( my $locuslink = $in->next_locuslink() ) {
                                       print "$locuslink\n";
                               }
        Returns : String
        Args    : None

   next_express
        Title   : next_express
        Usage   : next_express();
        Function: Returns the next tissue from an array referred
                  to using $obj->{'express'}

                  If you call this iterator again after it returned undef, it
                  will re-cycle through the list of elements. Changes in the
                  underlying array property while you loop over this iterator
                  will not be reflected until you exhaust the iterator.

        Example :      while ( my $express = $in->next_express() ) {
                                       print "$express\n";
                               }
        Returns : String
        Args    : None

   next_chromosome
        Title   : next_chromosome
        Usage   : next_chromosome();
        Function: Returns the next chromosome line from an array referred
                  to using $obj->{'chromosome'}

                  If you call this iterator again after it returned undef, it
                  will re-cycle through the list of elements. Changes in the
                  underlying array property while you loop over this iterator
                  will not be reflected until you exhaust the iterator.

        Example :      while ( my $chromosome = $in->next_chromosome() ) {
                                       print "$chromosome\n";
                               }
        Returns : String
        Args    : None

   next_protsim
        Title   : next_protsim
        Usage   : next_protsim();
        Function: Returns the next protsim line from an array referred
                  to using $obj->{'protsim'}

                  If you call this iterator again after it returned undef, it
                  will re-cycle through the list of elements. Changes in the
                  underlying array property while you loop over this iterator
                  will not be reflected until you exhaust the iterator.

        Example :      while ( my $protsim = $in->next_protsim() ) {
                                       print "$protsim\n";
                               }
        Returns : String
        Args    : None

   next_sts
        Title   : next_sts
        Usage   : next_sts();
        Function: Returns the next sts line from an array referred
                  to using $obj->{'sts'}

                  If you call this iterator again after it returned undef, it
                  will re-cycle through the list of elements. Changes in the
                  underlying array property while you loop over this iterator
                  will not be reflected until you exhaust the iterator.

        Example :      while ( my $sts = $in->next_sts() ) {
                                       print "$sts\n";
                               }
        Returns : String
        Args    : None

   next_txmap
        Title   : next_txmap
        Usage   : next_txmap();
        Function: Returns the next txmap line from an array
                  referred to using $obj->{'txmap'}

                  If you call this iterator again after it returned undef, it
                  will re-cycle through the list of elements. Changes in the
                  underlying array property while you loop over this iterator
                  will not be reflected until you exhaust the iterator.

        Example :      while ( my $tsmap = $in->next_txmap() ) {
                                       print "$txmap\n";
                               }
        Returns : String
        Args    : None

Bio::IdentifiableI methods

   object_id
        Title   : object_id
        Usage   : $string    = $obj->object_id()
        Function: a string which represents the stable primary identifier
                  in this namespace of this object. For DNA sequences this
                  is its accession_number, similarly for protein sequences

                  This is aliased to unigene_id().

        Returns : A scalar

   version
        Title   : version
        Usage   : $version    = $obj->version()
        Function: a number which differentiates between versions of
                  the same object. Higher numbers are considered to be
                  later and more relevant, but a single object described
                  the same identifier should represent the same concept

                  Unigene clusters usually won't have a version, so this
                  will be mostly undefined.

        Returns : A number
        Args    : on set, new value (a scalar or undef, optional)

   authority
        Title   : authority
        Usage   : $authority    = $obj->authority()
        Function: a string which represents the organisation which
                  granted the namespace, written as the DNS name for
                  organisation (eg, wormbase.org)

        Returns : A scalar
        Args    : on set, new value (a scalar or undef, optional)

   namespace
        Title   : namespace
        Usage   : $string    = $obj->namespace()
        Function: A string representing the name space this identifier
                  is valid in, often the database name or the name
                  describing the collection

        Returns : A scalar
        Args    : on set, new value (a scalar or undef, optional)

Bio::DescribableI methods

   display_name
        Title   : display_name
        Usage   : $string    = $obj->display_name()
        Function: A string which is what should be displayed to the user
                  the string should have no spaces (ideally, though a cautious
                  user of this interface would not assume this) and should be
                  less than thirty characters (though again, double checking
                  this is a good idea)

                  This is aliased to unigene_id().

        Returns : A scalar
        Status  : Virtual

   description()
        Title   : description
        Usage   : $string    = $obj->description()
        Function: A text string suitable for displaying to the user a
                  description. This string is likely to have spaces, but
                  should not have any newlines or formatting - just plain
                  text. The string should not be greater than 255 characters
                  and clients can feel justified at truncating strings at 255
                  characters for the purposes of display

                  This is already demanded by Bio::ClusterI and hence is
                  present anyway.

        Returns : A scalar

Bio::Factory::SequenceStreamI methods

   next_seq
        Title   : next_seq
        Usage   : next_seq();
        Function: Returns the next seq as a Seq object as defined by
                  $seq->sequence_factory(),
                  at present an empty Bio::Seq::RichSeq object with
                  just the accession_number() and pid() set

                  This iterator will not exhaust the array of member
                  sequences. If you call next_seq() again after it returned
                  undef, it will re-cycle through the list of member
                  sequences.

        Example :  while ( my $sequence = $in->next_seq() ) {
                    print $sequence->accession_number() . "\n";
                   }
        Returns : Bio::PrimarySeqI object
        Args    : None

   sequence_factory
        Title   : sequence_factory
        Usage   : $seqio->sequence_factory($seqfactory)
        Function: Get/Set the Bio::Factory::SequenceFactoryI
        Returns : Bio::Factory::SequenceFactoryI
        Args    : [optional] Bio::Factory::SequenceFactoryI

Private methods

   _annotation_value
        Title   : _annotation_value
        Usage   :
        Function: Private method.
        Example :
        Returns : the value (a string)
        Args    : annotation key (a string)
                  on set, annotation value (a string)

   _annotation_value_ary
        Title   : _annotation_value_ary
        Usage   :
        Function: Private method.
        Example :
        Returns : reference to the array of values
        Args    : annotation key (a string)
                  on set, reference to an array holding the values

   _annotation_dblink
        Title   : _annotation_dblink
        Usage   :
        Function: Private method.
        Example :
        Returns : array of accessions for the given database (namespace)
        Args    : annotation key (a string)
                  dbname (a string) (optional on get, mandatory on set)
                  on set, accession or ID (a string), and version

   _remove_dblink
        Title   : _remove_dblink
        Usage   :
        Function: Private method.
        Example :
        Returns : array of accessions for the given database (namespace)
        Args    : annotation key (a string)
                  dbname (a string) (optional)