Provided by: libgo-perl_0.15-9_all bug

NAME

       GO::Model::Term - a term or concept in an ontology

SYNOPSIS

         # From a file
         use GO::Parser;
         my $parser = new GO::Parser({handler=>'obj'}); # create parser object
         $parser->parse("gene_ontology.obo"); # parse file -> objects
         my $graph = $parser->handler->graph;  # get L<GO::Model::Graph> object
         my $term = $graph->get_term("GO:0001303");   # fetch a term by ID
         printf "Term %s %s\n", $term->name, $term->acc;

         # From a GO Database (requires go-db-perl)
         my apph = GO::AppHandle->connect(-dbname=>$dbname);
         my $term = $apph->get_term({acc=>00003677});
         printf "Term:%s (%s)\nDefinition:%s\nSynonyms:%s\n",
           $term->name,
           $term->public_acc,
           $term->definition,
           join(", ", @{$term->synonym_list});

DESCRIPTION

       Represents an Ontology term; the same class is used for process, compartment and function

       currently, a Term is not aware of its Relationships; to find out how a term is related to
       other terms, use the a GO::Model::Graph object, which will give you the
       GO::Model::Relationship objects; for example

         $rels = $graph->get_parent_relationships($term->acc);

SEE ALSO

       GO::Model::Relationship GO::Model::Graph GO::Model::Xref GO::Model::Association

NOTES

       Like all the GO::Model::* classes, this uses accessor methods to get or set the
       attributes. by using the accessor method without any arguments gets the value of the
       attribute. if you pass in an argument, then the attribuet will be set according to that
       argument.

       for single-valued attributes

         # this sets the value of the attribute
         $my_object->attribute_name("my value");

         # this gets the value of the attribute
         $my_value = $my_object->attribute_name();

       for lists:

         # this sets the values of the attribute
         $my_object->attribute_name(\@my_values);

         # this gets the values of the attribute
         $my_values = $my_object->attribute_name();

   acc
         Usage   - print $term->acc()
         Alias   - public_acc
         Returns -
         Args    -

       accessor: gets/sets GO ID/accession [as an integer]

       throws: exception if you try to pass in a non-integer

       if you want to use IDs in the format GO:0000nnn, then use the method public_acc()

   name
         Usage   - print $term->name;
         Returns -
         Args    -

       accessor: gets/sets "name" attribute

   subset_list
         Usage   - foreach (@{$term->subset_list || []}) { printf " $_\n" }
         Returns - list of strings
         Args    - list of strings [optional]

       List of subset Accs for a term

       Subsets are also known as GO Slims

   in_subset
         Usage   - if ($term->in_subset('goslim_prok');
         Returns - bool
         Args    - subset-name str

       Tests if the term belongs to a subset

   definition
         Usage   - print $term->definition;
         Returns -
         Args    -

       accessor: gets/sets "definition" attribute

   primary_xref
        Title   : primary_xref
        Usage   :
        Function:
        Example :
        Returns : GO::Model::Xref
        Args    :

       The same as acc(), except the ID is returned as a GO::Model::Xref rather than a string

   comment
        Title   : comment
        Usage   : $obj->comment($newval)
        Function:
        Example :
        Returns : value of comment (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   definition_dbxref_list
        Title   : definition_dbxref_list
        Usage   : $obj->definition_dbxref(\@xrefs)
        Function:
        Example :
        Returns : definition_dbxref_list hashlist (of GO::Model::Xref)
        Args    : on set, new values (GO::Model::Xref hashlist)

       GO::Model::Xref

   add_definition_dbxref
         - Usage : $term->add_definition_dbxref($xref);
         - Args  : GO::Term::Xref

       GO::Model::Xref

   has_synonym
         Usage   - if ($term->has_synonym("autotrophy") {...}
         Returns - bool
         Args    - string

   add_synonym
         Usage   - $term->add_synonym("calcineurin");
         Usage   - $term->add_synonym(@synonym_strings);
         Returns -
         Args    -

       Adds a synonym; loses type information (the synonym type in blank)

   synonym_list
         Usage   - my $syn_l = $term->synonym_list;
         Usage   - $term->synonym_list([$syn1, $syn2]);
         Returns - arrayref
         Args    - arrayref [optional]

       accessor: gets/set list of synonyms [array reference]

       each synonym is represented as a string - this method loses synonym typing information. If
       used as a setter, will set the type for each synonym to null

   add_synonym_by_type
         Usage   - $term->add_synonym_by_type('exact', $syn);
         Returns -
         Args    -

   synonyms_by_type
         Usage   - $synstrs = $term->synonyms_by_type('exact');
         Usage   - $term->synonyms_by_type('exact', \@exact_syns);
         Returns - arrayref of strings
         Args    - type string, arrayref of strings [optional]

       in getter mode, gets a list of synonyms of a particular type

       in setter mode, sets a list of synonyms for a particular type

   alt_id_list
         Usage   - my $syn_l = $term->alt_id_list;
         Usage   - $term->alt_id_list([$syn1, $syn2]);
         Returns - arrayref
         Args    - arrayref [optional]

       accessor: gets/set list of synonyms [array reference]

   add_alt_id
         Usage   - $term->add_alt_id('GO:0000001');
         Returns -
         Args    - id string, or list of id strings

   namespace (INHERITED)
         Usage   - print $term->namespace();     # getting the type
         Usage   - $term->namespace("molecular_function"); # setting the type
         Alias   - type
         Alias   - term_type
         Alias   - category
         Alias   - ontology
         Returns - string representing type
         Args    - string represnting type [optional]

       The OBO namespace for the GO::Model::Term or GO::Model::Relationship

       This method is inherited from the superclass

   set_namespace_by_code
         Usage   - $term->set_namespace_by_code("P");
         Returns -
         Args    - String: M, P or C

       Currently the mapping is hardcoded

         ('F'=>'molecular_function',
          'P'=>'biological_process',
          'C'=>'cellular_component');

   get_code_from_namespace
         Usage   - $code = $term->get_code_from_namespace;
         Returns - String: M, P or F
         Args    - String (if omitted will use current namespace)

       Returns the code for the current namespace (or any given namespace if supplied)

   add_dbxref
         - Usage : $term->add_dbxref($xref);
         - Args  : GO::Term::Xref

       GO::Model::Xref

   dbxref_list
         - Usage : $term->dbxref_list($xref);
         - Args  : optional listref of GO::Term::Xref
         - Returns  : listref of GO::Term::Xref

       accessor: gets/sets list of dbxref [array reference]

   is_obsolete
       accessor: gets/set obsolete flag [boolean

   is_root
       accessor: gets/set is_root flag [boolean]

TERM ASSOCIATION METHODS

   association_list
         Usage   - $assoc_l = $term->association_list
         Returns - arrayref of GO::Model::Association
         Args    - arrayref of GO::Model::Association [optional]

       accessor: gets/set list of associations [array reference]

       if this is undefined, the datasource will be queried for the associations

   selected_association_list
         Usage   - $assoc_l = $term->selected_association_list
         Returns - arrayref of GO::Model::Association
         Args    - arrayref of GO::Model::Association [optional]

       accessor: gets list of SELECTED associations [array reference]

       [this method is only of use if you are using it in conjunction with GO::AppHandle in the
       go-db-perl distro]

       this in not the total list of all associations associated with a term; if the term was
       created via a query on products, this will include those associations

       GO::Model::Association

   add_association
         Usage   - $term->add_association($assoc);
         Returns -
         Args    - GO::Model::Association

       GO::Model::Association

   add_selected_association
         Usage   -
         Returns -
         Args    -

       GO::Model::Association

   association_hash
       returns associations as listref of unique GeneProduct objects

       GO::Model::Association

   get_all_associations
         Usage   - my $al = $term->get_all_associations
         Returns - GO::Model::Association list
         Args    -

       returns all associations for the term and the terms beneath it in the GO DAG

       same as $apph->get_all_associations($term)

       GO::Model::Association

   n_associations
         Usage   - my $n = $term->n_associations
         Returns -
         Args    -

   product_list
         Usage   - $prods = $term->product_list
         Returns - L<GO::Model::GeneProduct> listref
         Args    -

       Returns a reference to an array of gene products that are attached directly to this term.

       (if the products have not been fetched, this method will call $term->association_list,
       cache the results, and use the associations to build the product list. succeeding calls of
       product_list to this term will hence be faster)

       See GO::Model::GeneProduct

   deep_product_list
         Usage   -
         Returns - GO::Model::GeneProduct listref
         Args    -

       finds all products attached to this term and all terms below in the graph

       GO::Model::GeneProduct

   n_deep_products
         Usage   - my $count = $term->n_deep_products;
         Returns - int
         Args    - filter (hashref) - or string "recount"

       gets the count for the *dsitinct* number of GO::Model::GeneProduct entries annotated at OR
       BELOW this level. if you have set the filters in GO::AppHandle then these filters will be
       used in determining the count.

       Remember, if you did not explicitly set the filters, then the default filter will be used,
       which is [!IEA] (i.e. curated associations only, see www.geneontology.org for a discussion
       of evidence codes).

       Note: currently only the speciesdb filter is respected. It turns out to be very expensive
       to do the set arithmetic for distinct recursive gene counts with different evidence
       combinations. Because each product belongs to one speciesdb only, the speciesdb counts are
       mutually exclusive, which makes this easier.

         # get the number of gene products that have been annotated
         # as transcription factors in worm and fly discounting
         # uncurated automatic annotations
         $apph->filters({evcodes=>["!IEA"], speciesdbs=>["SGD", "FB"]});
         $term = $apph->get_term({name=>"transcription factor"});
         print $term->n_deep_products;

       The count will be cached, so if you alter the filter parameters be sure to get a recount
       like this:

         my $count = $term->n_deep_products("recount");

       TODO: make the recount automatic if the filter is changed

       PERFORMANCE NOTE 1: When you ask the AppHandle to give you a list of GO::Model::Term
       objects, it may decide to populate this attribute when building the terms in a fast and
       efficient way. Therefore you should avoid setting the filters *after* you have created the
       objects otherwise it will have to refetch all these values slowing things down.

       PERFORMANCE NOTE 2: If you are using the SQL GO::AppHandle implementation, then this call
       will probably involve a query to the *gene_produc_count* table. If you populated the
       database you are using yourself, make sure this table is filled otherwise this will be an
       expensive query.

       GO::Model::GeneProduct

   n_products
         Usage   - as n_deep_products
         Returns -
         Args    -

       see docs for n_deep_products

       gets a count of products AT THIS LEVEL ONLY

       GO::Model::GeneProduct

   loadtime
        Title   : loadtime
        Usage   :
        Function:
        Example :
        Returns : time term was loaded into datasource
        Args    : none