view release on metacpan or  search on metacpan

Das/Map.pm  view on Meta::CPAN

 for my $location (@abs_locations) {
    my @rel_locations = $m->project($location,'c1.1.1');
    print_location(@rel_locations);

    my @all_rel_locations = $m->sub_segments($location);
    print_location(@all_rel_locations);
 }


=head1 DESCRIPTION

This module provides the infrastructure for handling relative
coordinates in sequence annotations.  You use it by creating a "map"
that relates a set of sequence segment pairs.  The segments are
related in a parent/child relationship so that you can move "up" or
"down" in the hierarchy.  However the exact meaning of the paired
relationships is up to you; it can be chromosome->contig->clone,
scaffold->supercontig->contig->read, or whatever you wish.

Once the map is created you can perform the following operations:

=over 4

=item resolution to absolute coordinates

Given a sequence segment somewhere in the map, the resolve() call will
move up to the topmost level, translating the coordinates into
absolute coordinates.

=item directed projection to relative coordinates

Given a sequence segment somewhere in the map, the project() call will
attempt to project the coordinate downward into the specified
coordinate system, changing it into the corresponding relative
coordinates.

=item undirected projection

Given a sequence segment somewhere in the map, the sub_segments() call
will return all possible coordinates relative to the children of this
segment.  The super_segments() performs the opposite operation, moving
upwards in the hierarchy.

=back

Here is an example using ASCII art:

        100          1000           2000             4000
   chr1 |---------------|--------------|----------------|
        .               ..             .                .
        1             901.           3000    4000    4999
   c1.1 |---------------|.             .|-------|-------|
                         .             .        .       .
                       501           1500       .       .
   c1.2                  |-------------|        .       .
                                                .       .
                                                1    1000
   c1.1.1                                       |-------|


These relationships can be described with the following code fragment:

 my $m = Bio::Das::Map->new('my_map');
 $m->add_segment(['chr1',100,1000]  => ['c1.1',1,901]);
 $m->add_segment(['chr1',1001,2000] => ['c1.2',501,1500]);
 $m->add_segment(['chr1',2001,4000] => ['c1.1',3000,4999]);
 $m->add_segment(['c1.1',4000,4999] => ['c1.1.1',1,1000]);

A call to resolve() can now be used to transform a segment relative to
"c1.1.1" into "chr1" coordinates:

 my @chr1_coordinates = $m->resolve('c1.1.1',500=>600);

This will return the segment chr1:3500..3600.

Conversely a call to project() can be used to transform a segment
relative to "chr1" into "c1.1.1" coordinates:

 my @c1_1_1_coordinates = $m->project('chr1',3500=>3600,'c1.1.1');

As expected, this returns the segment c1.1.1:500..600.

=head1 METHODS

=over 4

=item $map = Bio::Das::Map->new('map_name')

Create a new Bio::Das::Map, optionally giving it name "map_name."

=item $name = $map->name(['new_name'])

Get or set the map name.

=item $clip_flag = $map->clip([$new_clip_flag])

Get or set the "clip" flag.  If the clip flag is set to a true value,
then requests for operations on coordinate ranges that are outside the
list of segments contained within the map will be clipped to that
portion of the coordinate range within known segments.  If the flag is
false, then the coordinate mapping routines will perform linear
extrapolation on those portions of the segments that are outside the
map.

The default is false.

=item $map->add_segment($segment1 => $segment2)

Establish a parent/child relationship between $segment1 and
$segment2. The two segments can be array references or Bio::LocationI
objects.  In the former case, the format of the array reference is:

  [$coordinate_system_name,$start,$end [,$strand]

$coordinate_system_name is any sequence ID.  $start and $end are the
usual BioPerl 1-based coordinates with $start <= $end.  The $strand is
one of +1, 0 or -1.  If not provided the strand is assumed to be +1.
A strand of zero is equivalent to a strand of +1 for the coordinate
calculations.

Bio::LocationI objects can be used for either or both of the