Archive Ensembl HomeArchive Ensembl Home
MappingList.pm
Go to the documentation of this file.
00001 =head1 LICENSE
00002 
00003   Copyright (c) 1999-2012 The European Bioinformatics Institute and
00004   Genome Research Limited.  All rights reserved.
00005 
00006   This software is distributed under a modified Apache license.
00007   For license details, please see
00008 
00009     http://www.ensembl.org/info/about/code_licence.html
00010 
00011 =head1 CONTACT
00012 
00013   Please email comments or questions to the public Ensembl
00014   developers list at <dev@ensembl.org>.
00015 
00016   Questions may also be sent to the Ensembl help desk at
00017   <helpdesk@ensembl.org>.
00018 
00019 =cut
00020 
00021 =head1 NAME
00022 
00023 Bio::EnsEMBL::IdMapping::MappingList - object holding a list of Entries
00024 
00025 =head1 SYNOPSIS
00026 
00027   # create a new MappingList
00028   my $mappings = Bio::EnsEMBL::IdMapping::MappingList->new(
00029     -DUMP_PATH  => $dump_path,
00030     -CACHE_FILE => 'gene_mappings.ser',
00031   );
00032 
00033   # add entries
00034   my $mappings->add_Entry($entry1);
00035   my $mappings->add_all( $entry2, $entry3 );
00036 
00037   # serialise to file
00038   $mappings->write_to_file;
00039 
00040   # later, read these mappings from file
00041   my $mappings1 = Bio::EnsEMBL::IdMapping::MappingList->new(
00042     -DUMP_PATH  => $dump_path,
00043     -CACHE_FILE => 'gene_mappings.ser',
00044   );
00045   $mappings1->read_from_file;
00046 
00047 =head1 DESCRIPTION
00048 
00049 This object represents a list of Bio::EnsEMBL::IdMapping::Entry
00050 objects. It's essentially an OO wrapper for an array with some type
00051 checking and convenience methods.
00052 
00053 =head1 METHODS
00054 
00055   new
00056   add_Entry
00057   get_all_Entries
00058   add_all
00059   get_entry_count
00060   log
00061   to_string
00062 
00063 =cut
00064 
00065 package Bio::EnsEMBL::IdMapping::MappingList;
00066 
00067 use strict;
00068 use warnings;
00069 no warnings 'uninitialized';
00070 
00071 use Bio::EnsEMBL::IdMapping::Serialisable;
00072 our @ISA = qw(Bio::EnsEMBL::IdMapping::Serialisable);
00073 
00074 use Bio::EnsEMBL::Utils::Exception qw(throw warning);
00075 use Bio::EnsEMBL::Utils::ScriptUtils qw(path_append);
00076 
00077 
00078 =head2 new
00079 
00080   Arg[1-N]    : see superclass
00081   Example     : my $gene_mappings = Bio::EnsEMBL::IdMapping::MappingList->new(
00082                   -DUMP_PATH   => $dump_path,
00083                   -CACHE_FILE  => 'gene_mappings.ser',
00084                 );
00085   Description : Constructor.
00086   Return type : Bio::EnsEMBL::IdMapping::MappingList
00087   Exceptions  : none
00088   Caller      : general
00089   Status      : At Risk
00090               : under development
00091 
00092 =cut
00093 
00094 sub new {
00095   my $caller = shift;
00096   my $class = ref($caller) || $caller;
00097   my $self = $class->SUPER::new(@_);
00098 
00099   # initialise internal datastructure unless we loaded a serialised object
00100   unless ($self->loaded) {
00101     $self->{'cache'}->{'entries'} = [];
00102   }
00103 
00104   return $self;
00105 }
00106 
00107 
00108 =head2 add_Entry
00109 
00110   Arg[1]      : Bio::EnsEMBL::IdMapping::Entry - Entry to add
00111   Example     : $mappings->add_Entry($entry);
00112   Description : Adds an Entry to the MappingList.
00113   Return type : none
00114   Exceptions  : thrown on wrong or missing argument
00115   Caller      : general
00116   Status      : At Risk
00117               : under development
00118 
00119 =cut
00120 
00121 sub add_Entry {
00122   my $self = shift;
00123   my $entry = shift;
00124 
00125   unless ($entry and $entry->isa('Bio::EnsEMBL::IdMapping::Entry')) {
00126     throw("Need a Bio::EnsEMBL::IdMapping::Entry");
00127   }
00128 
00129   push @{ $self->{'cache'}->{'entries'} }, $entry;
00130 }
00131 
00132 
00133 =head2 get_all_Entries
00134 
00135   Example     : foreach my $entry (@{ $mappings->get_all_Entries }) {
00136                   # do something with the entry
00137                 }
00138   Description : Gets all Entries in the MappingList.
00139   Return type : Arrayref of Bio::EnsEMBL::IdMapping::Entry
00140   Exceptions  : none
00141   Caller      : general
00142   Status      : At Risk
00143               : under development
00144 
00145 =cut
00146 
00147 sub get_all_Entries {
00148   my $self = shift;
00149   return $self->{'cache'}->{'entries'};
00150 }
00151 
00152 
00153 =head2 add_all
00154 
00155   Arg[1]      : List of Bio::EnsEMBL::IdMapping::Entry objects
00156   Example     : my @entries = ($entry1, $entry2);
00157                 $mappings->add_all(@entries);
00158   Description : Adds a list of Entries to the MappingList.
00159   Return type : none
00160   Exceptions  : thrown on wrong argument
00161   Caller      : general
00162   Status      : At Risk
00163               : under development
00164 
00165 =cut
00166 
00167 sub add_all {
00168   my $self = shift;
00169   my @mappings = @_;
00170 
00171   foreach my $mapping (@mappings) {
00172     
00173     unless ($mapping->isa('Bio::EnsEMBL::IdMapping::MappingList')) {
00174       throw("Need a Bio::EnsEMBL::IdMapping::MappingList");
00175     }
00176 
00177     push @{ $self->{'cache'}->{'entries'} }, @{ $mapping->get_all_Entries };
00178   }
00179 }
00180 
00181 
00182 =head2 get_entry_count
00183 
00184   Example     : my $num_entries = $mappings->get_entry_count;
00185   Description : Returns the number of Entries in the MappingList.
00186   Return type : Int
00187   Exceptions  : none
00188   Caller      : general
00189   Status      : At Risk
00190               : under development
00191 
00192 =cut
00193 
00194 sub get_entry_count {
00195   my $self = shift;
00196   return scalar(@{ $self->{'cache'}->{'entries'} });
00197 }
00198 
00199 
00200 =head2 log
00201 
00202   Arg[1]      : String $type - object type (e.g. 'gene')
00203   Arg[2]      : String $dump_path - path for writing output
00204   Example     : $mappings->log('gene', $conf->param('basedir'));
00205   Description : Logs all Entries in the MappingList to a file. Used for
00206                 debugging.
00207   Return type : none
00208   Exceptions  : thrown on I/0 error
00209   Caller      : general
00210   Status      : At Risk
00211               : under development
00212 
00213 =cut
00214 
00215 sub log {
00216   my $self = shift;
00217   my $type = shift;
00218   my $dump_path = shift;
00219   
00220   my $debug_path = path_append($dump_path, 'debug');
00221   my $logfile = "$debug_path/${type}_final_scores.txt";
00222   
00223   open(my $fh, '>', $logfile) or
00224     throw("Unable to open $logfile for writing: $!");
00225 
00226   foreach my $entry (@{ $self->get_all_Entries }) {
00227     print $fh ($entry->to_string."\n");
00228   }
00229 
00230   close($fh);
00231 }
00232 
00233 
00234 =head2 to_string
00235 
00236   Example     : print LOG $mappings->to_string, "\n";
00237   Description : Returns a string representation of the MappingList. This is
00238                 simply a multi-line string, where each line is a stringified
00239                 Entry.
00240                 Useful for debugging and logging.
00241   Return type : String
00242   Exceptions  : none
00243   Caller      : general
00244   Status      : At Risk
00245               : under development
00246 
00247 =cut
00248 
00249 sub to_string {
00250   my $self = shift;
00251   
00252   my $string = '';
00253   
00254   foreach my $entry (@{ $self->get_all_Entries }) {
00255     $string .= $entry->to_string."\n";
00256   }
00257 
00258   return $string;
00259 }
00260 
00261 
00262 1;
00263