Archive Ensembl HomeArchive Ensembl Home
Bio::EnsEMBL::StableIdHistoryTree Class Reference

List of all members.


Class Summary

Synopsis

  my $reg = "Bio::EnsEMBL::Registry";
  my $archiveStableIdAdaptor =
    $reg-\>get_adaptor( 'human', 'core', 'ArchiveStableId' );

  my $stable_id = 'ENSG00000068990';
  my $history =
    $archiveStableIdAdaptor-\>fetch_history_tree_by_stable_id('ENSG01');

  print "Unique stable IDs in this tree:\n";
  print join( ", ", @{ $history-\>get_unique_stable_ids } ), "\n";

  print "\nReleases in this tree:\n";
  print join( ", ", @{ $history-\>get_release_display_names } ), "\n";

  print "\nCoordinates of nodes in the tree:\n\n";
  foreach my $a ( @{ $history-\>get_all_ArchiveStableIds } ) {
    print "  Stable ID: " . $a-\>stable_id . "." . $a-\>version . "\n";
    print "  Release: "
      . $a-\>release . " ("
      . $a-\>assembly . ", "
      . $a-\>db_name . ")\n";
    print "  coords: "
      . join( ', ', @{ $history-\>coords_by_ArchiveStableId($a) } )
      . "\n\n";
  }

Description

This object represents a stable ID history tree graph.
The graph is implemented as a collection of nodes (ArchiveStableId
objects) and links (StableIdEvent objects) which have positions
on an (x,y) grid. The x axis is used for releases, the y axis for
stable_ids. The idea is to create a plot similar to this (the numbers
shown on the nodes are the stable ID versions):
  ENSG001   1-------------- 2--
                                \
  ENSG003                         1-----1
                                /
  ENSG002   1-------2----------
           38      39      40    41    42
The grid coordinates of the ArchiveStableId objects in this example
would be (note that coordinates are zero-based):
  ENSG001.1               (0, 0)
  ENSG001.2               (2, 0)
  ENSG003.1 (release 41)  (3, 1) 
  ENSG003.1 (release 42)  (4, 1) 
  ENSG002.1               (0, 2)
  ENSG002.2               (1, 2)
The tree will only contain those nodes which had a change in the stable
ID version. Therefore, in the above example, in release 39 ENSG001 was
present and had version 1 (but will not be drawn there, to unclutter the
output).
The grid positions will be calculated by the API and will try to
untangle the tree (i.e. try to avoid overlapping lines).
 

Definition at line 72 of file StableIdHistoryTree.pm.

Available Methods

protected _factorial ()
protected _index_of ()
protected _link_id ()
protected _move_nodes ()
protected _node_id ()
protected _sort_links ()
protected _sort_releases ()
protected _sort_stable_ids ()
protected _total_link_length ()
public void add_ArchiveStableIds ()
public void add_ArchiveStableIds_for_events ()
public void add_StableIdEvents ()
public void calculate_coords ()
public void consolidate_tree ()
public Arrayref coords_by_ArchiveStableId ()
public String current_assembly ()
public String current_dbname ()
public Int current_release ()
public void flush_ArchiveStableIds ()
public void flush_StableIdEvents ()
public Arrayref get_all_ArchiveStableIds ()
public Arrayref get_all_current_ArchiveStableIds ()
public Arrayref get_all_StableIdEvents ()
public Bio::EnsEMBL::StableIdEvent get_latest_StableIdEvent ()
public Arrayref get_release_db_names ()
public Arrayref get_release_display_names ()
public Arrayref get_unique_stable_ids ()
public Boolean is_incomplete ()
public
Bio::EnsEMBL::StableIdHistoryTree 
new ()
public void optimise_tree ()
public void remove_ArchiveStableId ()
public void remove_StableIdEvent ()
public void reset_tree ()

Method Documentation

protected Bio::EnsEMBL::StableIdHistoryTree::_factorial ( )

Undocumented method

Code:
click to view
protected Bio::EnsEMBL::StableIdHistoryTree::_index_of ( )

Undocumented method

Code:
click to view
protected Bio::EnsEMBL::StableIdHistoryTree::_link_id ( )

Undocumented method

protected Bio::EnsEMBL::StableIdHistoryTree::_move_nodes ( )

Undocumented method

Code:
click to view
protected Bio::EnsEMBL::StableIdHistoryTree::_node_id ( )

Undocumented method

Code:
click to view
protected Bio::EnsEMBL::StableIdHistoryTree::_sort_links ( )

Undocumented method

protected Bio::EnsEMBL::StableIdHistoryTree::_sort_releases ( )

Undocumented method

Code:
click to view
protected Bio::EnsEMBL::StableIdHistoryTree::_sort_stable_ids ( )

Undocumented method

Code:
click to view
protected Bio::EnsEMBL::StableIdHistoryTree::_total_link_length ( )

Undocumented method

public void Bio::EnsEMBL::StableIdHistoryTree::add_ArchiveStableIds ( )
  Arg[1..n]   : Bio::EnsEMBL::ArchiveStableId's @archive_ids
                The ArchiveStableIds to add to the the history tree
  Example     : my $archive_id = $archiveStableIdAdaptor->fetch_by_stable_id(
                  'ENSG00024808');
                $history->add_ArchiveStableId($archive_id);
  Description : Adds ArchiveStableIds (nodes) to the history tree. No
                calculation of grid coordinates is done at this point, you need
                to initiate this manually with calculate_coords().
                ArchiveStableIds are only added once for each release (to avoid
                duplicates).
  Return type : none
  Exceptions  : thrown on invalid or missing argument
  Caller      : Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor::fetch_history_by_stable_id, general
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::add_ArchiveStableIds_for_events ( )
  Example     : my $history = Bio::EnsEMBL::StableIdHistoryTree->new;
                $history->add_StableIdEvents($event1, $event2);
                $history->add_ArchiveStableIds_for_events;
  Description : Convenience method that adds all ArchiveStableIds for all
                StableIdEvents attached to this object to the tree.
  Return type : none
  Exceptions  : none
  Caller      : Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor::fetch_history_by_stable_id, general
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::add_StableIdEvents ( )
  Arg[1..n]   : Bio::EnsEMBL::StableIdEvent's @events
                The StableIdEvents to add to the the history tree
  Example     : $history->add_StableIdEvents($event);
  Description : Adds StableIdEvents (links) to the history tree. Note that 
                ArchiveStableIds attached to the StableIdEvent aren't added to
                the tree automatically, you'll need to call
                add_ArchiveStableIds_for_events later.
  Return type : none
  Exceptions  : thrown on invalid or missing argument
  Caller      : Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor::fetch_history_by_stable_id, general
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::calculate_coords ( )
  Example     : $history->calculate_coords;
  Description : Pre-calculates the grid coordinates of all nodes in the tree.
  Return type : none
  Exceptions  : none
  Caller      : ArchiveStableIdAdaptor::fetch_history_by_stable_id
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::consolidate_tree ( )
  Example     : $history->consolidate_tree;
  Description : Consolidate the history tree. This means removing nodes where
                there wasn't a change and bridging gaps in the history. The end
                result will be a sparse tree which only contains the necessary
                information.
  Return type : none
  Exceptions  : none
  Caller      : ArchiveStableIdAdaptor->fetch_history_tree_by_stable_id
  Status      : At Risk
              : under development
 
Code:
click to view
public Arrayref Bio::EnsEMBL::StableIdHistoryTree::coords_by_ArchiveStableId ( )
  Arg[1]      : Bio::EnsEMBL::ArchiveStableId $archive_id
                The ArchiveStableId to get tree grid coordinates for
  Example     : my ($x, $y) =
                  @{ $history->coords_by_ArchiveStableId($archive_id) };
                print $archive_id->stable_id, " coords: $x, $y\\n";
  Description : Returns the coordinates of an ArchiveStableId in the history
                tree grid. If the ArchiveStableId isn't found in this tree, an
                empty list is returned.
                Coordinates are zero-based (i.e. the top leftmost element in
                the grid has coordinates [0, 0], not [1, 1]). This is to
                facilitate using them to create a matrix as a two-dimensional
                array of arrays.
  Return type : Arrayref (x coordinate, y coordinate)
  Exceptions  : thrown on wrong argument type
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public String Bio::EnsEMBL::StableIdHistoryTree::current_assembly ( )
  Arg[1]      : (optional) String $assembly - the assembly to set
  Example     : my $assembly = $history->current_assembly;
  Description : Getter/setter for current assembly.
  Return type : String
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public String Bio::EnsEMBL::StableIdHistoryTree::current_dbname ( )
  Arg[1]      : (optional) String $dbname - the dbname to set
  Example     : my $dbname = $history->current_dbname;
  Description : Getter/setter for current dbname.
  Return type : String
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Int Bio::EnsEMBL::StableIdHistoryTree::current_release ( )
  Arg[1]      : (optional) Int $release - the release to set
  Example     : my $release = $history->current_release;
  Description : Getter/setter for current release.
  Return type : Int
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::flush_ArchiveStableIds ( )
  Example     : $history->flush_ArchiveStableIds;
  Description : Remove all ArchiveStableIds from the tree.
  Return type : none
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::flush_StableIdEvents ( )
  Example     : $history->flush_StableIdEvents; 
  Description : Removes all StableIdEvents from the tree.
  Return type : none
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Arrayref Bio::EnsEMBL::StableIdHistoryTree::get_all_ArchiveStableIds ( )
  Example     : foreach my $arch_id (@{ $history->get_all_ArchiveStableIds }) {
                  print $arch_id->stable_id, '.', $arch_id->version, "\\n";
                }
  Description : Gets all ArchiveStableIds (nodes) in this tree.
  Return type : Arrayref of Bio::EnsEMBL::ArchiveStableId objects
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Arrayref Bio::EnsEMBL::StableIdHistoryTree::get_all_current_ArchiveStableIds ( )
  Example     : foreach my $arch_id (@{ $history->get_all_current_ArchiveStableIds }) {
                  print $arch_id->stable_id, '.', $arch_id->version, "\\n";
                }
  Description : Convenience method to get all current ArchiveStableIds in this
                tree.
                Note that no lazy loading of "current" status is done at that
                stage; as long as you retrieve your StableIdHistoryTree object
                from ArchiveStableIdAdaptor, you'll get the right answer. In
                other use cases, if you want to make sure you really get all
                current stable IDs, loop over the result of
                get_all_ArchiveStableIds() and call
                ArchiveStableId->current_version() on all of them.
  Return type : Arrayref of Bio::EnsEMBL::ArchiveStableId objects
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Arrayref Bio::EnsEMBL::StableIdHistoryTree::get_all_StableIdEvents ( )
  Example     : foreach my $event (@{ $history->get_all_StableIdsEvents }) {
                  print "Old stable ID: ", 
                    ($event->get_attribute('old', 'stable_id') or 'none'), "\\n";
                  print "New stable ID: ", 
                    ($event->get_attribute('new', 'stable_id') or 'none'), "\\n";
                  print "Mapping score: ", $event->score, "\\n";
                }
  Description : Gets all StableIdsEvents (links) in this tree.
  Return type : Arrayref of Bio::EnsEMBL::StableIdEvent objects
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Bio::EnsEMBL::StableIdEvent Bio::EnsEMBL::StableIdHistoryTree::get_latest_StableIdEvent ( )
  Arg[1]      : Bio::EnsEMBL::ArchiveStableId $arch_id - the stable ID to get
                the latest Event for
  Example     : my $arch_id = Bio::EnsEMBL::ArchiveStableId->new(
                  -stable_id => 'ENSG00001'
                );
                my $event = $history->get_latest_Event($arch_id);
  Description : Returns the latest StableIdEvent found in the tree where a given
                stable ID is the new stable ID. If more than one is found (e.g.
                in a merge scenario in the latest mapping), preference is given
                to self-events.
  Return type : Bio::EnsEMBL::StableIdEvent
  Exceptions  : thrown on missing or wrong argument
  Caller      : Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor::add_all_current_to_history, general
  Status      : At Risk
              : under development
 
Code:
click to view
public Arrayref Bio::EnsEMBL::StableIdHistoryTree::get_release_db_names ( )
  Example     : print "Unique release db_names in this tree:\\n"
                foreach my $name (@{ $history->get_release_db_names }) {
                  print "  $name\\n";
                }
  Description : Returns a chronologically sorted list of unique release
                db_names in this tree.
  Return type : Arrayref of strings.
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Arrayref Bio::EnsEMBL::StableIdHistoryTree::get_release_display_names ( )
  Example     : print "Unique release display_names in this tree:\\n"
                foreach my $name (@{ $history->get_release_display_names }) {
                  print "  $name\\n";
                }
  Description : Returns a chronologically sorted list of unique release
                display_names in this tree.
                This method can be used to determine the number of columns when
                plotting the history tree.
  Return type : Arrayref of strings.
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Arrayref Bio::EnsEMBL::StableIdHistoryTree::get_unique_stable_ids ( )
  Example     : print "Unique stable IDs in this tree:\\n"
                foreach my $id (@{ $history->get_unique_stable_ids }) {
                  print "  $id\\n";
                }
  Description : Returns a list of unique stable IDs in this tree. Version is not
                taken into account here. This method can be used to determine
                the number of rows when plotting the history with each stable ID
                occupying one line.
                Sort algorithm will depend on what was chosen when the sorted
                tree was generated. This ranges from a simple alphanumeric sort
                to algorithms trying to untangle the history tree. If no
                pre-sorted data is found, an alphanumerically sorted list will
                be returned by default.
  Return type : Arrayref of strings.
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Boolean Bio::EnsEMBL::StableIdHistoryTree::is_incomplete ( )
  Arg[1]      : (optional) Boolean $incomplete 
  Example     : if ($history->is_incomplete) {
                  print "Returned tree is incomplete due to too many mappings
                    in the database.\\n";
                }
  Description : Getter/setter for incomplete flag. This is used by
                ArchiveStableIdAdaptor to indicate that it finished building
                the tree prematurely due to too many mappins in the db and can
                be used by applications to print warning messages.
  Return type : Boolean
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public Bio::EnsEMBL::StableIdHistoryTree Bio::EnsEMBL::StableIdHistoryTree::new ( )
  Arg [CURRENT_DBNAME]   : (optional) name of current db
  Arg [CURRENT_RELEASE]  : (optional) current release number
  Arg [CURRENT_ASSEMBLY] : (optional) current assembly name
  Example     : my $history = Bio::EnsEMBL::StableIdHistoryTree->new;
  Description : object constructor
  Return type : Bio::EnsEMBL::StableIdHistoryTree
  Exceptions  : none
  Caller      : general
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::optimise_tree ( )
  Example     : $history->optimise_tree;
  Description : This method sorts the history tree so that the number of
                overlapping branches is minimised (thus "untangling" the tree).
                It uses a clustering algorithm for this which iteratively moves
                the nodes with the largest vertical distance next to each other
                and looking for a mininum in total branch length. This might not
                produce the overall optimum but usually converges on a local
                optimum very quickly.
  Return type : none
  Exceptions  : none
  Caller      : calculate_coords
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::remove_ArchiveStableId ( )
  Arg[1]      : Bio::EnsEMBL::ArchiveStableId $archive_id
                the ArchiveStableId to remove from the tree
  Example     : $history->remove_ArchiveStableId($archive_id);
  Description : Removes an ArchiveStableId from the tree.
  Return type : none
  Exceptions  : thrown on missing or invalid argument
  Caller      : Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor::fetch_history_by_stable_id, general
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::remove_StableIdEvent ( )
  Arg[1]      : Bio::EnsEMBL::StableIdEvent $event
                the StableIdEvent to remove from the tree
  Example     : $history->remove_StableIdEvent($event);
  Description : Removes a StableIdEvent from the tree.
  Return type : none
  Exceptions  : thrown on missing or invalid arguments
  Caller      : Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor::fetch_history_by_stable_id, general
  Status      : At Risk
              : under development
 
Code:
click to view
public void Bio::EnsEMBL::StableIdHistoryTree::reset_tree ( )
  Example     : $history->reset_tree;
  Description : Resets all pre-calculated tree grid data. Mostly used internally
                by methods that modify the tree.
  Return type : none
  Exceptions  : none
  Caller      : internal
  Status      : At Risk
              : under development
 
Code:
click to view

The documentation for this class was generated from the following file: