GO::Model::Graph(3pm)					User Contributed Perl Documentation				     GO::Model::Graph(3pm)

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
", $term->acc, $term->name;
	   print "  Associations (direct and via transitive closure_
";
	   foreach my $assoc (@$assocs) {
	     next if $assoc->is_not;
	     printf "  Assoc evidence: %s to: %s %s
",
	       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
",
		 "----" 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
", $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
", $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

   _get_recursive_related_terms_by_type
	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

   _get_related_terms_by_type
	 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

perl v5.14.2							    2010-05-12						     GO::Model::Graph(3pm)