Bio/Coordinate/Chain.pm

   1 #
   2 # bioperl module for Bio::Coordinate::Chain
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Heikki Lehvaslaiho <heikki-at-bioperl-dot-org>
   7 #
   8 # Copyright Heikki Lehvaslaiho
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Coordinate::Chain - Mapping locations through a chain of  coordinate mappers
  17
  18 =head1 SYNOPSIS
  19
  20   # create Bio::Coordinate::Pairs, or any MapperIs, somehow
  21   $pair1; $pair2;
  22
  23   # add them into a Chain
  24   $collection = Bio::Coordinate::Chain->new;
  25   $collection->add_mapper($pair1);
  26   $collection->add_mapper($pair2);
  27
  28   # create a position and map it
  29   $pos = Bio::Location::Simple->new (-start => 5, -end => 9 );
  30   $match = $collection->map($pos);
  31   if ($match) {
  32       sprintf "Matches at %d-%d\n", $match->start, $match->end,
  33   } else {
  34       print "No match\n";
  35   }
  36
  37 =head1 DESCRIPTION
  38
  39 This class assumes that you have built several mappers and want to
  40 link them together so that output from the previous mapper is the next
  41 mappers input. This way you can build arbitrarily complex mappers from
  42 simpler components.
  43
  44 Note that Chain does not do any sanity checking on its mappers. You
  45 are solely responsible that input and output coordinate systems,
  46 direction of mapping and parameters internal to mappers make sense
  47 when chained together.
  48
  49 To put it bluntly, the present class is just a glorified foreach loop
  50 over an array of mappers calling the map method.
  51
  52 It would be neat to an internal function that would generate a new
  53 single step mapper from those included in the chain. It should speed
  54 things up considerably. Any volunteers?
  55
  56 =head1 FEEDBACK
  57
  58 =head2 Mailing Lists
  59
  60 User feedback is an integral part of the evolution of this and other
  61 Bioperl modules. Send your comments and suggestions preferably to the
  62 Bioperl mailing lists  Your participation is much appreciated.
  63
  64   bioperl-l@bioperl.org                  - General discussion
  65   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  66
  67 =head2 Support
  68
  69 Please direct usage questions or support issues to the mailing list:
  70
  71 I<bioperl-l@bioperl.org>
  72
  73 rather than to the module maintainer directly. Many experienced and
  74 reponsive experts will be able look at the problem and quickly
  75 address it. Please include a thorough description of the problem
  76 with code and data examples if at all possible.
  77
  78 =head2 Reporting Bugs
  79
  80 Report bugs to the Bioperl bug tracking system to help us keep track
  81 the bugs and their resolution.  Bug reports can be submitted via the
  82 web:
  83
  84   http://bugzilla.open-bio.org/
  85
  86 =head1 AUTHOR - Heikki Lehvaslaiho
  87
  88 Email:  heikki-at-bioperl-dot-org
  89
  90 =head1 CONTRIBUTORS
  91
  92 Ewan Birney, birney@ebi.ac.uk
  93
  94 =head1 APPENDIX
  95
  96 The rest of the documentation details each of the object
  97 methods. Internal methods are usually preceded with a _
  98
  99 =cut
 100
 101
 102 # Let the code begin...
 103
 104 package Bio::Coordinate::Chain;
 105 use strict;
 106
 107 # Object preamble - inherits from Bio::Root::Root
 108 use Bio::Root::Root;
 109 use Bio::Coordinate::Result;
 110
 111 use base qw(Bio::Coordinate::Collection Bio::Coordinate::MapperI);
 112
 113
 114 =head2 map
 115
 116  Title   : map
 117  Usage   : $newpos = $obj->map($pos);
 118  Function: Map the location through all the mappers in the chain.
 119  Example :
 120  Returns : new Location in the output coordiante system
 121  Args    : a Bio::Location::Simple object
 122
 123 =cut
 124
 125 sub map {
 126     my ($self,$value) = @_;
 127
 128     $self->throw("Need to pass me a value.")
 129         unless defined $value;
 130     $self->throw("I need a Bio::Location, not [$value]")
 131         unless $value->isa('Bio::LocationI');
 132     $self->throw("No coordinate mappers!")
 133         unless $self->each_mapper;
 134
 135     my $res = Bio::Coordinate::Result->new();
 136
 137     foreach my $mapper ($self->each_mapper) {
 138
 139         my $res = $mapper->map($value);
 140         return unless $res->each_match;
 141         $value = $res->match;
 142     }
 143
 144    return $value;
 145 }
 146
 147
 148 =head2 Inherited methods
 149
 150 =cut
 151
 152 =head2 add_mapper
 153
 154  Title   : add_mapper
 155  Usage   : $obj->add_mapper($mapper)
 156  Function: Pushes one Bio::Coodinate::MapperI into the list of mappers.
 157            Sets _is_sorted() to false.
 158  Example :
 159  Returns : 1 when succeeds, 0 for failure.
 160  Args    : mapper object
 161
 162 =cut
 163
 164 =head2 mappers
 165
 166  Title   : mappers
 167  Usage   : $obj->mappers();
 168  Function: Returns or sets a list of mappers.
 169  Example :
 170  Returns : array of mappers
 171  Args    : array of mappers
 172
 173 =cut
 174
 175 =head2 each_mapper
 176
 177  Title   : each_mapper
 178  Usage   : $obj->each_mapper();
 179  Function: Returns a list of mappers.
 180  Example :
 181  Returns : array of mappers
 182  Args    : none
 183
 184 =cut
 185
 186 =head2 swap
 187
 188  Title   : swap
 189  Usage   : $obj->swap;
 190  Function: Swap the direction of mapping;input <-> output
 191  Example :
 192  Returns : 1
 193  Args    :
 194
 195 =cut
 196
 197 =head2 test
 198
 199  Title   : test
 200  Usage   : $obj->test;
 201  Function: test that both components of all pairs are of the same length.
 202            Ran automatically.
 203  Example :
 204  Returns : boolean
 205  Args    :
 206
 207 =cut
 208
 209
 210
 211 sub sort{
 212    my ($self) = @_;
 213    $self->warn("You do not really want to sort your chain, do you!\nDoing nothing.");
 214 }
 215
 216 1;
 217