Provided by: gbrowse_2.56+dfsg-11_all bug

NAME

       Bio::Graphics::Browser2::PadAlignment - Insert pads into a multiple alignment

VERSION (CVS-info)

        $RCSfile: PadAlignment.pm,v $
        $Revision$
        $Author: lstein $
        $Date: 2008-09-09 20:53:36 $

SYNOPSIS

        use Bio::Graphics::Browser2::PadAlignment;

        my @dnas = (
                    dna1 =>'FFFFgatcGATCgatcGATCgatcGATCgatcGBATCgatcGATCatcGATCgatcGATCgatcGATCgatcGATgatcGATCgatcNNNNGATC',
                    dna2 =>'FFgatcGATCGATCgatcNNGATCgatcGATCgatcGATCgatcGATCgatcGATCtcGATBCgatcGATCatcGATCgatcNNNNGATCFFFF',
                    dna3 =>'FFFFgatcGATCgatcGATCgatcGATCgatcBBBGATCgatcGATCatcGATCBgatcGATCgatcGATCgatcGATgatcGATCgatcNNNNGATCFF',
                    dna4 =>'ZZFFFFgatcGATCgatcGATCgatcGATCgatc',
                    dna5 =>'ATBGGATtcttttttt',
                  );

        #                   target  st  en  tst ten
        my @alignments = ([ 'dna2', 4,  11,  2, 9      ],
                          [ 'dna2', 16, 23,  10, 17    ],
                          [ 'dna2', 24, 32,  20, 28    ],
                          [ 'dna2', 34, 44,  29, 39    ],
                          [ 'dna2', 45, 59,  41, 55    ],
                          [ 'dna2', 62, 66,  56, 60    ],
                          [ 'dna2', 67, 74,  62, 69    ],
                          [ 'dna2', 76, 86,  71, 81    ],
                          [ 'dna2', 91, 94,  86, 89    ],

                          [ 'dna3',  4,  31, 4, 31    ],
                          [ 'dna3',  33, 33, 34, 34    ],
                          [ 'dna3',  34, 51, 36, 53    ],
                          [ 'dna3',  52, 86, 55, 89    ],
                          [ 'dna3',  91, 94, 94, 97    ],

                          [ 'dna4',  0,  31, 2,  33    ],

                          [ 'dna5',  17, 18, 0, 1    ],
                          [ 'dna5',  41, 43, 4,   6    ],
                          [ 'dna5',  85, 86, 7,   8    ],
                         );

        my $align = Bio::Graphics::Browser2::PadAlignment->new(\@dnas,\@alignments);

        my @padded = $align->padded_sequences;
        print join "\n",@padded,"\n";
        # ..FFFFgatcGATCgatcGATCgatc--GATCgatcG-B-ATCgatcGATC-atcGATC-gatcGATCgatcGAT-CgatcGATgatcGATCgatcNNNNGATC....
        # ....FFgatcGATC----GATCgatcNNGATCgatcG---ATCgatcGATCgatcGATC-gatcGATC--tcGATBCgatcGATCatcGATCgatcNNNNGATCFFFF
        # ..FFFFgatcGATCgatcGATCgatc--GATCgatcBBBGATCgatcGATC-atcGATCBgatcGATCgatcGAT-CgatcGATgatcGATCgatcNNNNGATCFF..
        # ZZFFFFgatcGATCgatcGATCgatc--GATCgatc........................................................................
        # ...................AT-----------------BG-------GAT--------------------------------------------tcttttttt.....

        my $pretty = $align->alignment;
        print $pretty,"\n";
        # dna1   1 ..FFFFgatc GATCgatcGA TCgatc--GA TCgatcG-B- ATCgatcGAT C-atcGATC- gatcGATCga tcGAT-Cgat
        # dna2   1 ....FFgatc GATC----GA TCgatcNNGA TCgatcG--- ATCgatcGAT CgatcGATC- gatcGATC-- tcGATBCgat
        # dna3   1 ..FFFFgatc GATCgatcGA TCgatc--GA TCgatcBBBG ATCgatcGAT C-atcGATCB gatcGATCga tcGAT-Cgat
        # dna4   1 ZZFFFFgatc GATCgatcGA TCgatc--GA TCgatc.... .......... .......... .......... ..........
        # dna5   1 .......... .........A T--------- ---------- -----BGGAT ---------- ---------- ----------

        # dna1  72 cGATgatcGA TCgatcNNNN GATC....
        # dna2  67 cGATCatcGA TCgatcNNNN GATCFFFF
        # dna3  75 cGATgatcGA TCgatcNNNN GATCFF..
        # dna4  35 .......... .......... ........
        # dna5   8 ---------- ----tctttt ttt.....

DESCRIPTION

       This is a utility module for pretty-printing the type of alignment that comes out of
       gbrowse, namely a multiple alignment in which each target is aligned to a reference genome
       without explicit pads or other spaces.

       For speed and ease of use, the module does not use form Bio::SeqI objects, but raw strings
       and alignment data structures.  This may change.

       This module does not perform multiple alignments!  It merely pretty-prints them!

   METHODS
       This section describes the methods used by this class.

       $aligner = Bio::Graphics::Browser2::PadAlignment->new(\@sequences,\@alignments)
           Create a new aligner.  The two arguments are \@sequences, an array ref to the list of
           sequences to be aligned, and \@alignments, an array ref describing how the sequences
           are to be aligned.

           \@sequences should have the following structure:

             [ name1 => $sequence1,
               name2 => $sequence2,
               name3 => $sequence3 ]

           The sequences will be displayed in top to bottom order in the order provided.  The
           first sequence in the list is special because it is the reference sequence.  All
           alignments are relative to it.

           \@alignments should have the following structure:

            [ [ target1, $start1, $end1, $tstart1, $tend1 ],
              [ target1, $start2, $end2, $tstart2, $tend2 ],
              ...
             ]

           Each element of @alignments is an arrayref with five elements.  The first element is
           the name of the target sequence, which must be one of the named sequences given in
           @sequences.  The second and third elements are the start and stop position of the
           aligned target segment relative to the reference sequence, "name1" in the example
           given above.  The fourth and fifth elements are the start and stop position of the
           aligned target segment in the coordinate space of the target.

           Example:

             @dnas = ('dna1' => 'ccccccaaaaaatttt',
                      'dna2' => 'aaaaaa');
             @alignment = ( ['dna2', 6, 11, 0, 5 ]);

           Positions 0 to 5 of "dna2" align to positions 6-11 of "dna1".

           Note that sequence positions are zero based.  This may change.

       @lines = $aligner->padded_sequences
           This inserts pads into the sequences and returns them as a list of strings in the
           order specified in new().  In a scalar context, this method will return a hashref in
           which the keys are the sequence names and the values are their padded strings.

       $map = $aligner->gap_map
           This returns an arrayref indicating the position of each base in the gapped reference
           sequence.  The indexes are base positions, and the element values are their positions
           in the reference sequence as returned by padded_sequences().

           Note that the gap map only provides coordinate mapping for the reference sequence.
           For an alternative implementation that provides gap maps for each of the targets (at
           the cost of speed and memory efficiency) see the section after __END__ in the source
           file for this module.

       $align_string = $aligner->alignment(\%origins [,\%options])
           This method returns a pretty-printed string of the aligned sequences.  You may provide
           a hashref of sequence origins in order to control the numbers printed next to each
           line of the alignment.  The keys of the %origins hashref are the names of the
           sequences, and the values are the coordinate to be assigned to the first base of the
           sequence.  Use a negative number if you wish to indicate that the sequence has been
           reverse complemented (the negative number should indicate the coordinate of the first
           base in the provided sequence).

           An optional second argument, if present, contains a hash reference to a set of
           option=>value pairs.  Three options are recognized:

              show_mismatches      0|1      if true, highlight mismatches in pink
              show_matches         0|1      if true, hightligt matches in yellow
              color_code_proteins  0|1      if true, highlight amino acids thus:
                                                   Acidic amino acids in red
                                                   Basic amino acids in blue
                                                   Hydrophobic amino acids in grey
                                                   Polar amino acids in yellow
              flip                 0|1      if true, reverse complement the whole alignment

SEE ALSO

       Bio::Graphics::Panel, Bio::Graphics::Glyph, Bio::Graphics::Feature,
       Bio::Graphics::FeatureFile, Bio::Graphics::Browser, Bio::Graphics::Browser2::Plugin

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2002 Cold Spring Harbor Laboratory

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See DISCLAIMER.txt for disclaimers of warranty.