NAME¶
GO::Model::Graph - a collection of relationships over terms
SYNOPSIS¶
# FETCHING GRAPH FROM FILES
use GO::Parser;
my $parser = new GO::Parser({handler=>'obj'});
$parser->parse("gene_ontology.obo"); # ontology
$parser->parse("gene-associations.sgd"); # gene assocs
# get L<GO::Model::Graph> object
my $graph = $parser->handler->graph;
my $terms = $graph->term_query("/transmembrane/"); # matching terms
foreach my $term (@$terms) {
# find gene products associated to this term
my $assocs = $graph->deep_association_list($term->acc);
printf "Term: %s %s\n", $term->acc, $term->name;
print " Associations (direct and via transitive closure_\n";
foreach my $assoc (@$assocs) {
next if $assoc->is_not;
printf " Assoc evidence: %s to: %s %s\n",
join(';', map {$_->code} @{$assoc->evidence_list}),
$assoc->gene_product->xref->as_str,
$assoc->gene_product->symbol;
}
}
# -- alternatively, use this code... --
# FETCHING FROM DATABASE (requires go-db-perl library)
# pretty-printing a subgraph from "nuclear pore"
$apph = GO::AppHandle->connect(-dbname=>"$dbname");
$term = $apph->get_term({name=>"nuclear pore"});
$graph =
$apph->get_graph_by_terms([$term], $depth);
$it = $graph->create_iterator;
# returns a GO::Model::GraphIterator object
while (my $ni = $it->next_node_instance) {
$depth = $ni->depth;
$term = $ni->term;
$reltype = $ni->parent_rel->type;
printf
"%s %8s Term = %s (%s) // number_of_association=%s // depth=%d\n",
"----" x $depth,
$reltype,
$term->name,
$term->public_acc,
$term->n_associations || 0,
$depth;
}
DESCRIPTION¶
Object containing Nodes (GO::Model::Term objects) and relationships
(:<GO::Model::Relationship> objects)
this may be either the whole ontology tree, or a subgraph, depending on how the
object is instantiated.
ONTOLOGY GRAPH MODEL¶
relationships can be thought of as
statements or sentences of the form
SUBJECT-TERM PREDICATE OBJECT-TERM
for example,
"dog" IS_A "animal"
"G-Protein coupled receptor" IS_A "transmembrane receptor"
Statements have a
subject (i.e. the subject of the sentence/statement), a
predicate/relationship-type and an
object (i.e. the object of the
sentence/statement)
Relationships can also be seen as arcs in a directed graph, with the subject
being equivalent to the child, and the object equivalent to the parent. The
arc is labeled with the predicate/relationship-type.
perl doesnt handle bidirectional links between objects too well, so rather than
having the relationship object know about the terms or the term know about the
realtionships, all the graph info is in the Graph object
the Relationship object gives you the accessions of the related terms, use the
Graph methods to fetch these actual terms.
The idea is to keep the Term & Relationship objects lightweight, and keep
the Graph logic in the Graph object. The Graph object is responsible for stuff
like making sure that a Term object is not instantiated twice if it can be
reached by two different paths.
Currently all graphs are acyclic, cyclic graphs may be allowed in the future
when such relationships are added to GO/OBOA
TRANSITIVE CLOSURES¶
graph object will calculate transitive closures for you - that is it
will follow the path in the graph to the root or to all leafs
ITERATORS¶
Using the create_iterator and iterate methods, you can create
"visitors" that will traverse the graph, performing actions along
the way. Functional-style programming is encouraged, as the
iterature()
method allows for the passing of lexical closures:
$graph->iterate(sub {$term=shift->term;
printf "%s %s\n", $term->acc,$term->name},
{direction=>'up',
acc=>"GO:0008045"})
SEE ALSO¶
go-perl GO::Model::Term GO::Parser GO::AppHandle
new¶
Usage - $g = GO::Model::Graph->new;
Returns - GO::Model::Graph;
Args -
Normally you would not create a graph object yourself - this is typically done
for you by either a GO::Parser object or a GO::AppHandle object
create_iterator¶
Usage - $it = $graph->create_iterator("GO:0003677")
Usage - $it = $graph->create_iterator({acc=>"GO:0008045",
direction=>"up"});
Returns - GO::Model::GraphIterator;
Args - accession no [optional] or GO::Model::Term [optional]
makes a GO::Model::GraphIterator, an object which traverses the graph
iterate¶
Usage - $graph->iterate(sub {$ni=shift;printf "%s\n", $ni->term->name});
Usage - sub mysub {...}; $graph->iterate(\&mysub);
Returns -
Args - CODE
iterates through the graph executing CODE on every GO::Model::GraphNodeInstance
object
term_filter¶
Alias - node_filter
Usage - $terms =
$graph->term_filter(sub {shift->term->name =~ /transmembrane/});
Usage - sub mysub {...}; $graph->iterate(\&mysub);
Returns - ref to an array of GO::Model::Term objects
Args - CODE
iterates through the graph executing CODE on every GO::Model::GraphNodeInstance
object. If CODE returns true, that node will be returned
term_query¶
Usage - $terms = $graph->term_query({name=>'/transmembrane/'});
Usage - $terms = $graph->term_query({acc=>'GO:0008045'});
Usage - $terms = $graph->term_query('/transmembrane/');
Returns - ref to an array of GO::Model::Term objects
Args - hashref of constraints
OR name constraint as string
returns a set of terms matching query constraints. If the constraint value is
enclosed in // a regexp match will be performed
constraints are ANDed. For more complex queries, use
node_filter()
subgraph¶
Usage - my $subgraph = $graph->subgraph({acc=>"GO:0008045"});
Returns - GO::Model::Graph
Args - as term_query()
creates a subgraph of the current graph containing the terms returned by a
term_query() call and all paths to the root
subgraph_by_terms¶
Usage - my $subgraph = $graph->subgraph_by_terms($terms);
Usage - my $subgraph = $graph->subgraph_by_terms($terms,{partial=>1});
Returns - GO::Model::Graph
Args - GO::Model::Term listref
creates a subgraph of the current graph containing the specified terms
The path-to-top will be calculated for all terms and added to the subgraph,
UNLESS the partial option is set; in this case a relationship between
get_all_nodes¶
Usage - my $node_listref = $graph->get_all_nodes();
Synonyms- get_all_terms
Returns - ref to an array of GO::Model::Term objects
Args - none
The returned array is UNORDERED
If you want the returned list ordered (eg breadth first or depth first) use the
create_iterator() method to get a GO::Model::GraphIterator
See also GO::Model::Term
get_term¶
Usage - my $term = $graph->get_term($acc);
Synonyms- get_node
Returns - GO::Model::Term
Args - id
returns a GO::Model::Term object for an accession no.
the term must be in the Graph object
See also GO::Model::Term
get_term_by_name¶
Usage - my $term = $graph->get_term_by_name("blah");
Returns - GO::Model::Term
Args - string
returns a GO::Model::Term object for a name
the term must be in the Graph object
CASE INSENSITIVE
See also GO::Model::Term
get_terms_by_subset¶
Usage - my $term = $graph->get_terms_by_subset("goslim_plant");
Returns - GO::Model::Term
Args - string
returns a GO::Model::Term object for a subset
the term must be in the Graph object
CASE INSENSITIVE
See also GO::Model::Term
get_top_nodes¶
Usage - my $node_listref = $graph->get_top_nodes();
Synonyms- get_top_terms
Returns - ref to an array of GO::Model::Term objects
Args - none
usually returns 1 node - the root term
See also GO::Model::Term
get_leaf_nodes¶
Usage - my $node_listref = $graph->get_top_nodes();
Synonyms- get_leaf_terms
Returns - ref to an array of GO::Model::Term objects
Args - none
See also GO::Model::Term
is_leaf_node¶
Usage - if ($graph->is_leaf_node($acc)) {...}
Returns - bool
Args - accession str
See also GO::Model::Term
seed_nodes¶
Usage - $nodes = $graph->seed_nodes;
Returns - GO::Model::Term listref
Args - GO::Model::Term listref [optional]
gets/sets the "seed" nodes/terms - these are the terms the Graph is
started from, e.g. for building a node ancestory graph, the seed term would be
the leaf of this graph, but not term that are expanded or collpased from the
ancestory graph.
This is mostly relevant if you are fetching your graphs from a database via
go-db-perl
See also GO::Model::Term
focus_nodes¶
Usage - $nodes = $graph->focus_nodes;
Synonyms- focus_terms
Returns - GO::Model::Term listref
Args - GO::Model::Term listref [optional]
gets/sets the "focus" nodes/terms - these are the terms the Graph is
centred around; for instance, if the graph was built around a query to
"endoplasmic*" all the terms matching this string would be focused
This is mostly relevant if you are fetching your graphs from a database via
go-db-perl
See also GO::Model::Term
is_focus_node¶
Usage - if ($g->is_focus_node($term)) {..}
Returns - bool
Args - GO::Model::Term
add_focus_node¶
Usage - $g->add_focus_node($term)
Returns -
Args - GO::Model::Term
See also GO::Model::Term
paths_to_top¶
Usage - my $paths = $graph->paths_to_top("GO:0005045");
Returns - arrayref of GO::Model::Path objects
Args -
See also GO::Model::Path
node_count¶
Usage - my $count = $g->node_count
Synonyms- term_count
Returns - int
Args -
returns the number of terms/nodes in the graph
See also GO::Model::Term
n_associations¶
Usage - my $count = $g->n_associations($acc);
Returns - int
Args -
if you parsed an association file into this graph, this will return the number
of instances attached directly to acc
See also GO::Model::Association See also GO::Model::GeneProduct
n_deep_associations¶
Usage - my $count = $g->n_deep_associations($acc);
Returns - int
Args -
if you parsed an association file into this graph, this will return the number
of instances attached directly to acc OR to a node subsumed by acc
See also GO::Model::Association See also GO::Model::GeneProduct
n_children¶
Usage - $n = $graph->n_children('GO:0003677');
Synonyms- n_sterms, n_subj_terms, n_subject_terms
Returns - int
Args -
returns the number of DIRECT children/subject/subordinate terms beneath this one
n_parents¶
Usage - $n = $graph->n_parents(3677);
Synonyms- n_oterms, n_obj_terms, n_object_terms
Returns - int
Args -
returns the number of DIRECT parent/object/superordinate terms above this one
association_list¶
Usage - $assocs = $g->association_list('GO:0003677')
Returns - listref of GO::Model::Association
Args - acc (string)
returns a list of association objects
directly attached to the specified
term
See also GO::Model::Association
get_direct_associations¶
Usage -
Returns -
Args -
See also GO::Model::Association
deep_association_list¶
Usage - $assocs = $g->association_list('GO:0003677')
Returns - listref of GO::Model::Association
Args - acc (string)
returns a list of association objects
directly and indirectly attached to
the specified term. (ie assocs attached to the term or to terms subsumed by
the specified term).
See also GO::Model::Association
product_list¶
Usage - $prods = $g->product_list('GO:0003677')
Returns - listref of GO::Model::GeneProduct
Args - acc (string)
returns a list of distinct gene product objects
directly attached to the
specified term.
See also GO::Model::GeneProduct
deep_product_list¶
Usage - $prods = $g->deep_product_list('GO:0003677')
Returns - listref of GO::Model::GeneProduct
Args - acc (string)
returns a list of distinct gene product objects
directly and indirectly
attached to the specified term. (ie assocs attached to the term or to terms
subsumed by the specified term).
See also GO::Model::GeneProduct
deep_product_count¶
Usage - $n_prods = $g->deep_product_count('GO:0003677')
Returns - int
Args - acc (string)
returns a count of distinct gene product objects
directly and
indirectly attached to the specified term. performs transitive closure.
will not count gene products twice
See also GO::Model::GeneProduct
get_relationships¶
Usage - my $rel_listref = $graph->get_relationships('GO:0003677');
Returns - ref to an array of GO::Model::Relationship objects
Args - identifier/acc (string)
returns relationships which concern the specified term; the specified term can
be the subject or object term in the relationship (ie child or parent)
See also GO::Model::Relationship
get_parent_relationships¶
Usage - my $rel_listref = $graph->get_parent_relationships('GO:0003677');
Synonym - get_relationships_by_child
Synonym - get_relationships_by_subj
Synonym - get_relationships_by_subject
Synonym - get_obj_relationships
Synonym - get_object_relationships
Returns - ref to an array of GO::Model::Relationship objects
Args - identifier/acc (string)
See also GO::Model::Relationship
get_child_relationships¶
Usage - my $rel_listref = $graph->get_child_relationships('GO:0003677');
Synonym - get_relationships_by_parent
Synonym - get_relationships_by_obj
Synonym - get_relationships_by_object
Synonym - get_subj_relationships
Synonym - get_subject_relationships
Returns - ref to an array of GO::Model::Relationship objects
Args - identifier/acc (string)
See also GO::Model::Relationship
get_all_relationships¶
Usage -
Returns - GO::Model::Relationship list
Args -
returns all the relationships/statements in this graph
See also GO::Model::Relationship
get_parent_terms¶
Usage - my $term_lref = $graph->get_parent_terms($parent_term->acc);
Synonym - get_obj_terms
Synonym - get_object_terms
Returns - ref to array of GO::Model::Term objs
Args - the accession of the query term
See also GO::Model::Term
get_parent_terms_by_type¶
Usage -
Synonym - get_obj_terms_by_type
Synonym - get_object_terms_by_type
Returns - ref to array of GO::Model::Term objs
Args - the accession of the query term
- the type by which to constrain relationships
See also GO::Model::Term
get_recursive_parent_terms¶
Title : get_recursive_parent_terms
Usage :
Synonyms: get_recursive_obj_terms
Synonyms: get_recursive_object_terms
Function:
Example :
Returns :
Args : accession of query term
See also GO::Model::Term
get_recursive_parent_terms_by_type¶
Title : get_recursive_parent_terms_by_type
Usage :
Synonyms: get_recursive_obj_terms_by_type
Synonyms: get_recursive_object_terms_by_type
Function:
Example :
Returns :
Args :
if type is blank, gets all
See also GO::Model::Term
get_reflexive_parent_terms¶
Title : get_reflexive_parent_terms
Usage :
Function:
Example :
Returns :
Args : acc
returns parent terms plus the term (for acc) itself
[reflexive transitive closure of relationships in upward direction]
See also GO::Model::Term
get_reflexive_parent_terms_by_type¶
Title : get_reflexive_parent_terms_by_type
Usage :
Function:
Example :
Returns : listref of terms
Args : acc, type
closure of relationship including the term itself
See also GO::Model::Term
get_child_terms¶
Usage - my $term_lref = $graph->get_child_terms($parent_term->acc);
Synonym - get_subj_terms
Synonym - get_subject_terms
Returns - ref to array of GO::Model::Term objs
Args -
See also GO::Model::Term
get_child_terms_by_type¶
Synonym - get_subj_terms_by_type
Synonym - get_subject_terms_by_type
Returns - ref to array of GO::Model::Term objs
Args - the accession of the query term
- the type by which to constrain relationships
See also GO::Model::Term
get_recursive_child_terms¶
Title : get_recursive_child_terms
Usage :
Synonyms: get_recursive_subj_terms
Synonyms: get_recursive_subject_terms
Function:
Example :
Returns : a reference to an array of L<GO::Model::Term> objects
Args : the accession of the query term
See also GO::Model::Term
get_recursive_child_terms_by_type¶
Title : get_recursive_child_terms_by_type
Usage :
Synonyms: get_recursive_subj_terms_by_type
Synonyms: get_recursive_subject_terms_by_type
Function:
Example :
Returns : a reference to an array of L<GO::Model::Term> objects
Args : accession, type
if type is blank, gets all
See also GO::Model::Term
Title : _get_recursive_related_terms_by_type
Usage :
Function: Obtain all relationships of the given kind and type for the
term identified by its accession, and recursively repeat
this with all parents and children as query for parent and
child relationships, respectively.
This is an internal method.
Example :
Returns : A reference to an array of L<GO::Model::Term> objects.
Args : - the kind of relationship, either "child" or "parent"
- the accession of the term with which to query
- the type to which to constrain relationships (optional,
all types if left undef)
- TRUE if reflexive and FALSE otherwise (default FALSE)
See also GO::Model::Term
Usage - my $term_lref = $graph->_get_related_terms_by_type("child",$acc);
Returns - ref to array of GO::Model::Term objs
Args - the kind of relationship, either "child" or "parent"
- the accession of the term for which to obtain rel.ships
- the type by which to constrain relationships (optional,
defaults to all terms if left undef)
This is an internal method.
get_parent_accs_by_type¶
Usage -
Returns -
Args - acc, type
get_reflexive_parent_accs_by_type¶
Title : get_reflexive_parent_accs_by_type
Usage :
Function:
Example :
Returns : listref of terms
Args : acc, type
closure of relationship including the term itself
See also GO::Model::Term
get_relationships_between_terms¶
Title : get_relationships_between_terms
Usage :
Function:
Example :
Returns : [] of relationships
Args : parent id, child id
See also GO::Model::Relationship
get_parent_closure_hash_by_type¶
Title : get_parent_closure_hash_by_type
Usage :
Function: given a term-acc and relationship type, will give a hash that
can be used to check if a term X is a parent of term Y
Example :
Returns :
Args :
keys will be lower-cased
add_child_relationship¶
See also GO::Model::Relationship
add_parent_relationship¶
parent relationships are as valued as child relationships
See also GO::Model::Relationship
close_below¶
Usage - $graph->close_below(3677);
Returns -
Args - term (as acc or GO::Model::Term object)
gets rid of everything below a node
used by AmiGO for when a user closes a term in the graph
find_roots¶
Usage - my $terms = $graph->find_roots;
Returns - arrayref of GO::Model::Term objects
Args -
All terms withOUT a parent
See also GO::Model::Term
get_all_products¶
Usage -
Returns -
Args -
See also GO::Model::GeneProduct
merge¶
Usage - $g->merge($g2);
Returns -
Args - GO::Model::Graph
merges two graphs
export¶
Usage - $graph->export({format=>$format});
Returns -
Args - opt hash
writes out the graph in any export format, including obo, go_ont, owl, png
(graphviz) etc
to_xml¶
Usage -
Returns -
Args -
add_term¶
Usage - $g->add_term($term)
Returns -
Args - GO::Model::Term
add_node¶
Usage -
Returns -
Args -
synonym for add_term
add_relationship¶
Usage - $graph->add_relationship({acc1=>from_id, acc2=>to_id});
Usage - $graph->add_relationship($from_id, $to_id, $type});
Usage - $graph->add_relationship($obj, $subj, $type});
Returns -
Args -
only one relationship between id1 and id2 is allowed
See also GO::Model::Relationship
add_buckets¶
Usage -
Returns -
Args -
adds bucket terms to non-leaf nodes
this is useful for making GO slims
to_text_output¶
Usage -
Returns -
Args - fmt, assocs [bool]
hacky text output
this method should probably move out of the model code into output
adapters