/ 
Bio-EnsEMBL-112.0.0_58
River stage zero No dependents
/ Bio::EnsEMBL::IdMapping::ScoredMappingMatrix

LICENSE

Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute Copyright [2016-2024] EMBL-European Bioinformatics Institute

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CONTACT

Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.

Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.

NAME

Bio::EnsEMBL::IdMapping::ScoredMappingMatrix - object holding a list of scored Entries

SYNOPSIS

# create a new ScoredMappingMatrix
my $gene_scores = Bio::EnsEMBL::IdMapping::ScoredMappingMatrix->new(
  -DUMP_PATH  => $dump_path,
  -CACHE_FILE => 'gene_scores.ser',
);

# add entries
my $gene_scores->add_Entry($entry1);

# serialise to file
$gene_scores->write_to_file;

# later, read these gene_scores from file
my $gene_scores1 = Bio::EnsEMBL::IdMapping::ScoredMappingMatrix->new(
  -DUMP_PATH  => $dump_path,
  -CACHE_FILE => 'gene_gene_scores.ser',
);
$gene_scores1->read_from_file;

DESCRIPTION

This object represents a collection of scores between source and target objects. It holds a list of Bio::EnsEMBL::IdMapping::Entry objects and has methods to retrieve indiviual or all Entries, as well as derived data like number of unique sources or targets, or various counts and averages.

It is the main collection for dealing with scored relationships in the stable Id mapping application.

METHODS

new
flush
sub_matrix
add_Entry
update_Entry
remove_Entry
add_score
set_score
get_Entry
get_score
get_targets_for_source
get_Entries_for_source
get_sources_for_target
get_Entries_for_target
get_all_Entries
get_all_sources
get_all_targets
get_entry_count
size
get_source_count
get_target_count
get_min_max_scores
get_average_score
merge
log
to_string

new

Arg[1-N]    : see superclass
Example     : my $gene_scores = Bio::EnsEMBL::IdMapping::ScoredMappingMatrix->new(
                -DUMP_PATH   => $dump_path,
                -CACHE_FILE  => 'gene_scores.ser',
              );
Description : Constructor.
Return type : Bio::EnsEMBL::IdMapping::ScoredMappingMatrix
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

flush

Example     : $gene_scores->flush;
Description : Flushes (empties) the scoring matrix.
Return type : none
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

sub_matrix

Arg[1]      : Int $start - start index (inclusive)
Arg[2]      : Int $end - end index (inclusive)
Example     : # get the first 1000 elements in the matrix
              my $sub_matrix = $gene_scores->sub_matrix(1, 1000);
Description : Returns a sub-matrix of the ScoredMappingMatrix. The arguments
              ($start and $end) specify the position of the first and last
              element to return (inclusive, counting starts with element 1,
              not 0)
Return type : Bio::EnsEMBL::IdMapping::ScoredMappingMatrix
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

add_Entry

Arg[1]      : Bio::EnsEMBL::IdMapping::Entry $entry - Entry to add
Example     : $gene_scores->add_Entry($entry);
Description : Adds an Entry to the scoring matrix.
Return type : Float - the Entry's score
Exceptions  : thrown on wrong or missing argument
Caller      : general
Status      : At Risk
            : under development

update_Entry

Arg[1]      : Bio::EnsEMBL::IdMapping::Entry $entry - Entry to update
Example     : $gene_scores->update_Entry($entry);
Description : Updates an Entry (or rather its score) in the scoring matrix.
              Actually delegates to add_Entry(), only there as an intuitively
              named wrapper.
Return type : Float - the Entry's score
Exceptions  : thrown on wrong or missing argument
Caller      : general
Status      : At Risk
            : under development

add_score

Arg[1]      : Int $source - source object's internal Id ("dbID")
Arg[2]      : Int $target - target object's internal Id ("dbID")
Arg[3]      : Float $score - score for source/target pair
Example     : $gene_scores->add_score(1234, 5678, 0.997);
Description : Adds a score for a source/target pair to the scoring matrix.
              This is a low-level version of add_Entry().
Return type : Float - the score
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

set_score

Arg[1]      : Int $source - source object's internal Id ("dbID")
Arg[2]      : Int $target - target object's internal Id ("dbID")
Arg[3]      : Float $score - score for source/target pair
Example     : $gene_scores->set_score(1234, 5678, 0.997);
Description : Sets the score for a source/target pair in the scoring matrix.
              This method is similar to add_score, but assumes that the Entry
              has been added before, so won't update the sources and target
              lists.
Return type : Float - the score
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_Entry

Arg[1]      : Int $source - source object's internal Id ("dbID")
Arg[2]      : Int $target - target object's internal Id ("dbID")
Example     : my $entry = $gene_scores->get_Entry($source_gene->id,
                $target_gene->id);
Description : Gets an Entry from the scoring matrix for a given source and
              target object.
Return type : Bio::EnsEMBL::IdMapping::Entry or undef
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_score

Arg[1]      : Int $source - source object's internal Id ("dbID")
Arg[2]      : Int $target - target object's internal Id ("dbID")
Example     : my $score = $gene_scores->get_score($source_gene->id,
                $target_gene->id);
Description : Gets the score from the scoring matrix for a given source and
              target object.
Return type : Float or undef
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_targets_for_source

Arg[1]      : Int $source - source object's internal Id ("dbID")
Example     : my @targets = @{ $gene_scores->get_targets_for_source(1234) };
Description : Returns a list of all targets which have a score against a given
              source object.
Return type : Arrayref of Int (target objects' internal Ids)
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_Entries_for_source

Arg[1]      : Int $source - source object's internal Id ("dbID")
Example     : my @entries = @{ $gene_scores->get_Entries_for_source(1234) };
Description : Returns a list of all Entries in the scoring matrix for a given
              source object.
Return type : Arrayref of Bio::EnsEMBL::IdMapping::Entry objects
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_sources_for_target

Arg[1]      : Int $target - target object's internal Id ("dbID")
Example     : my @sources = @{ $gene_scores->get_sources_for_target(5678) };
Description : Returns a list of all sources which have a score against a given
              target object.
Return type : Arrayref of Int (source objects' internal Ids)
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_Entries_for_target

Arg[1]      : Int $target - target object's internal Id ("dbID")
Example     : my @entries = @{ $gene_scores->get_Entries_for_target(5678) };
Description : Returns a list of all Entries in the scoring matrix for a given
              target object.
Return type : Arrayref of Bio::EnsEMBL::IdMapping::Entry objects
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_all_Entries

Example     : foreach my $entry (@{ $gene_scores->get_all_Entries }) {
                # do something with the entry
              }
Description : Returns a list of all Entries in the scoring matrix.
Return type : Arrayref of Bio::EnsEMBL::IdMapping::Entry objects
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_all_sources

Example     : my @sources = @{ $gene_scores->get_all_sources };
Description : Returns a list of all sources in the scoring matrix.
Return type : Arrayref of Int (source objects' internal Ids)
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_all_targets

Example     : my @targets = @{ $gene_scores->get_all_targets };
Description : Returns a list of all targets in the scoring matrix.
Return type : Arrayref of Int (target objects' internal Ids)
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_entry_count

Example     : my $num_entries = $gene_scores->get_entry_count;
Description : Returns the number of Entries in the scoring matrix.
Return type : Int
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

size

Example     : my $size = $gene_scores->size;
Description : Returns the size of the scoring matrix. Same value as returned
              by get_entry_count().
Return type : Int
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_source_count

Example     : my $num_sources = $gene_scores->get_source_count;
Description : Returns the number of distinct sources in the scoring matrix.
Return type : Int
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_target_count

Example     : my $num_targets = $gene_scores->get_target_count;
Description : Returns the number of distinct targets in the scoring matrix.
Return type : Int
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_min_max_scores

Example     : my ($min_score, $max_score) = 
               @{ $gene_scores->get_min_max_scores };
Description : Returns the mininum and maximum score in the scoring matrix.
Return type : Arrayref of Float [min_score, max_score]
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

get_average_score

Example     : my $avg_score = $gene_scores->get_average_score;
Description : Returns the average (mean) score in the matrix.
Return type : Float
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

merge

Arg[1]      : Bio::EnsEMBL::IdMapping::ScoredMappingMatrix $matrix - another
              matrix to merge with
Example     : my $update_count = $gene_scores->merge($more_gene_scores);
Description : Merges two scoring matrices. If there's an Entry for a
              source/target pair in both matrices, the higher score will be
              retained.
Return type : Int - number of Entries added or updated
Exceptions  : thrown on wrong or missing argument
Caller      : general
Status      : At Risk
            : under development

log

Arg[1]      : String $type - object type (e.g. 'gene')
Arg[2]      : String $dump_path - path for writing output
Example     : $gene_scores->log('gene', $conf->param('basedir'));
Description : Logs all Entries in the scoring matrix to a file. Used for
              debugging.
Return type : none
Exceptions  : thrown on I/0 error
Caller      : general
Status      : At Risk
            : under development

to_string

Example     : print LOG $gene_scores->to_string, "\n";
Description : Returns a string representation of the scoring matrix. This is
              simply a multi-line string, where each line is a stringified
              Entry.
              Useful for debugging and logging.
Return type : String
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development