branch-1-6/Bio/Align/AlignI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Align::AlignI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Jason Stajich <jason@bioperl.org>
   8 #
   9 # Copyright Jason Stajich
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::Align::AlignI - An interface for describing sequence alignments.
  18
  19 =head1 SYNOPSIS
  20
  21   # get a Bio::Align::AlignI somehow - typically using Bio::AlignIO system
  22   # some descriptors
  23   print $aln->length, "\n";
  24   print $aln->num_residues, "\n";
  25   print $aln->is_flush, "\n";
  26   print $aln->num_sequences, "\n";
  27   print $aln->percentage_identity, "\n";
  28   print $aln->consensus_string(50), "\n";
  29
  30   # find the position in the alignment for a sequence location
  31   $pos = $aln->column_from_residue_number('1433_LYCES', 14); # = 6;
  32
  33   # extract sequences and check values for the alignment column $pos
  34   foreach $seq ($aln->each_seq) {
  35       $res = $seq->subseq($pos, $pos);
  36       $count{$res}++;
  37   }
  38   foreach $res (keys %count) {
  39       printf "Res: %s  Count: %2d\n", $res, $count{$res};
  40   }
  41
  42 =head1 DESCRIPTION
  43
  44 This interface describes the basis for alignment objects.
  45
  46 =head1 FEEDBACK
  47
  48 =head2 Mailing Lists
  49
  50 User feedback is an integral part of the evolution of this and other
  51 Bioperl modules. Send your comments and suggestions preferably to
  52 the Bioperl mailing list.  Your participation is much appreciated.
  53
  54   bioperl-l@bioperl.org                  - General discussion
  55   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  56
  57 =head2 Support
  58
  59 Please direct usage questions or support issues to the mailing list:
  60
  61 I<bioperl-l@bioperl.org>
  62
  63 rather than to the module maintainer directly. Many experienced and
  64 reponsive experts will be able look at the problem and quickly
  65 address it. Please include a thorough description of the problem
  66 with code and data examples if at all possible.
  67
  68 =head2 Reporting Bugs
  69
  70 Report bugs to the Bioperl bug tracking system to help us keep track
  71 of the bugs and their resolution. Bug reports can be submitted via the
  72 web:
  73
  74   http://bugzilla.open-bio.org/
  75
  76 =head1 AUTHOR - Jason Stajich
  77
  78 Email jason@bioperl.org
  79
  80 =head1 CONTRIBUTORS
  81
  82 Ewan Birney, birney@ebi.ac.uk
  83 Heikki Lehvaslaiho, heikki-at-bioperl-dot-org
  84
  85 =head1 APPENDIX
  86
  87 The rest of the documentation details each of the object methods.
  88 Internal methods are usually preceded with a _
  89
  90 =cut
  91
  92
  93 # Let the code begin...
  94
  95
  96 package Bio::Align::AlignI;
  97 use strict;
  98
  99
 100 use base qw(Bio::Root::RootI);
 101
 102 =head1 Modifier methods
 103
 104 These methods modify the MSE by adding, removing or shuffling complete
 105 sequences.
 106
 107 =head2 add_seq
 108
 109  Title     : add_seq
 110  Usage     : $myalign->add_seq($newseq);
 111  Function  : Adds another sequence to the alignment. *Does not* align
 112              it - just adds it to the hashes.
 113  Returns   : None
 114  Argument  : a Bio::LocatableSeq object
 115              order (optional)
 116
 117 See L<Bio::LocatableSeq> for more information.
 118
 119 =cut
 120
 121 sub add_seq {
 122     my ($self) = @_;
 123     $self->throw_not_implemented();
 124 }
 125
 126 =head2 remove_seq
 127
 128  Title     : remove_seq
 129  Usage     : $aln->remove_seq($seq);
 130  Function  : Removes a single sequence from an alignment
 131  Returns   :
 132  Argument  : a Bio::LocatableSeq object
 133
 134 =cut
 135
 136 sub remove_seq {
 137     my ($self) = @_;
 138     $self->throw_not_implemented();
 139 }
 140
 141 =head2 purge
 142
 143  Title   : purge
 144  Usage   : $aln->purge(0.7);
 145  Function:
 146
 147            Removes sequences above whatever %id.
 148
 149            This function will grind on large alignments. Beware!
 150            (perhaps not ideally implemented)
 151
 152  Example :
 153  Returns : An array of the removed sequences
 154  Argument:
 155
 156
 157 =cut
 158
 159 sub purge {
 160     my ($self) = @_;
 161     $self->throw_not_implemented();
 162 }
 163
 164 =head2 sort_alphabetically
 165
 166  Title     : sort_alphabetically
 167  Usage     : $ali->sort_alphabetically
 168  Function  :
 169
 170              Changes the order of the alignment to alphabetical on name
 171              followed by numerical by number.
 172
 173  Returns   : an array
 174  Argument  :
 175
 176 =cut
 177
 178 sub sort_alphabetically {
 179     my ($self) = @_;
 180     $self->throw_not_implemented();
 181 }
 182
 183 =head1 Sequence selection methods
 184
 185 Methods returning one or more sequences objects.
 186
 187 =head2 each_seq
 188
 189  Title     : each_seq
 190  Usage     : foreach $seq ( $align->each_seq() )
 191  Function  : Gets an array of Seq objects from the alignment
 192  Returns   : an array
 193  Argument  :
 194
 195 =cut
 196
 197 sub each_seq {
 198     my ($self) = @_;
 199     $self->throw_not_implemented();
 200 }
 201
 202 =head2 each_alphabetically
 203
 204  Title     : each_alphabetically
 205  Usage     : foreach $seq ( $ali->each_alphabetically() )
 206  Function  :
 207
 208              Returns an array of sequence object sorted alphabetically
 209              by name and then by start point.
 210              Does not change the order of the alignment
 211
 212  Returns   :
 213  Argument  :
 214
 215 =cut
 216
 217 sub each_alphabetically {
 218     my($self) = @_;
 219     $self->throw_not_implemented();
 220 }
 221
 222 =head2 each_seq_with_id
 223
 224  Title     : each_seq_with_id
 225  Usage     : foreach $seq ( $align->each_seq_with_id() )
 226  Function  :
 227
 228              Gets an array of Seq objects from the
 229              alignment, the contents being those sequences
 230              with the given name (there may be more than one)
 231
 232  Returns   : an array
 233  Argument  : a seq name
 234
 235 =cut
 236
 237 sub each_seq_with_id {
 238     my ($self) = @_;
 239     $self->throw_not_implemented();
 240 }
 241
 242 =head2 get_seq_by_pos
 243
 244  Title     : get_seq_by_pos
 245  Usage     : $seq = $aln->get_seq_by_pos(3) # third sequence from the alignment
 246  Function  :
 247
 248              Gets a sequence based on its position in the alignment.
 249              Numbering starts from 1.  Sequence positions larger than
 250              num_sequences() will throw an error.
 251
 252  Returns   : a Bio::LocatableSeq object
 253  Argument  : positive integer for the sequence position
 254
 255 =cut
 256
 257 sub get_seq_by_pos {
 258     my ($self) = @_;
 259     $self->throw_not_implemented();
 260 }
 261
 262 =head1 Create new alignments
 263
 264 The result of these methods are horizontal or vertical subsets of the
 265 current MSE.
 266
 267 =head2 select
 268
 269  Title     : select
 270  Usage     : $aln2 = $aln->select(1, 3) # three first sequences
 271  Function  :
 272
 273              Creates a new alignment from a continuous subset of
 274              sequences.  Numbering starts from 1.  Sequence positions
 275              larger than num_sequences() will throw an error.
 276
 277  Returns   : a Bio::SimpleAlign object
 278  Argument  : positive integer for the first sequence
 279              positive integer for the last sequence to include (optional)
 280
 281 =cut
 282
 283 sub select {
 284     my ($self) = @_;
 285     $self->throw_not_implemented();
 286 }
 287
 288
 289 =head2 select_noncont
 290
 291  Title     : select_noncont
 292  Usage     : $aln2 = $aln->select_noncont(1, 3) # first and 3rd sequences
 293  Function  :
 294
 295              Creates a new alignment from a subset of
 296              sequences.  Numbering starts from 1.  Sequence positions
 297              larger than num_sequences() will throw an error.
 298
 299  Returns   : a Bio::SimpleAlign object
 300  Args      : array of integers for the sequences
 301
 302 =cut
 303
 304 sub select_noncont {
 305     my ($self) = @_;
 306     $self->throw_not_implemented();
 307 }
 308
 309 =head2 slice
 310
 311  Title     : slice
 312  Usage     : $aln2 = $aln->slice(20, 30)
 313  Function  :
 314
 315              Creates a slice from the alignment inclusive of start and
 316              end columns.  Sequences with no residues in the slice are
 317              excluded from the new alignment and a warning is printed.
 318              Slice beyond the length of the sequence does not do
 319              padding.
 320
 321  Returns   : a Bio::SimpleAlign object
 322  Argument  : positive integer for start column
 323              positive integer for end column
 324
 325 =cut
 326
 327 sub slice {
 328     my ($self) = @_;
 329     $self->throw_not_implemented();
 330 }
 331
 332 =head1 Change sequences within the MSE
 333
 334 These methods affect characters in all sequences without changing the
 335 alignment.
 336
 337
 338 =head2 map_chars
 339
 340  Title     : map_chars
 341  Usage     : $ali->map_chars('\.','-')
 342  Function  :
 343
 344              Does a s/$arg1/$arg2/ on the sequences. Useful for gap
 345              characters
 346
 347              Notice that the from (arg1) is interpreted as a regex,
 348              so be careful about quoting meta characters (eg
 349              $ali->map_chars('.','-') wont do what you want)
 350
 351  Returns   : None
 352  Argument  : 'from' rexexp
 353              'to' string
 354
 355 =cut
 356
 357 sub map_chars {
 358     my ($self) = @_;
 359     $self->throw_not_implemented();
 360 }
 361
 362 =head2 uppercase
 363
 364  Title     : uppercase()
 365  Usage     : $ali->uppercase()
 366  Function  : Sets all the sequences to uppercase
 367  Returns   :
 368  Argument  :
 369
 370 =cut
 371
 372 sub uppercase {
 373     my ($self) = @_;
 374     $self->throw_not_implemented();
 375 }
 376
 377 =head2 match_line
 378
 379  Title    : match_line()
 380  Usage    : $align->match_line()
 381  Function : Generates a match line - much like consensus string
 382             except that a line indicating the '*' for a match.
 383  Argument : (optional) Match line characters ('*' by default)
 384             (optional) Strong match char (':' by default)
 385             (optional) Weak match char ('.' by default)
 386
 387 =cut
 388
 389 sub match_line {
 390     my ($self) = @_;
 391     $self->throw_not_implemented();
 392 }
 393
 394 =head2 match
 395
 396  Title     : match()
 397  Usage     : $ali->match()
 398  Function  :
 399
 400              Goes through all columns and changes residues that are
 401              identical to residue in first sequence to match '.'
 402              character. Sets match_char.
 403
 404              USE WITH CARE: Most MSE formats do not support match
 405              characters in sequences, so this is mostly for output
 406              only. NEXUS format (Bio::AlignIO::nexus) can handle
 407              it.
 408
 409  Returns   : 1
 410  Argument  : a match character, optional, defaults to '.'
 411
 412 =cut
 413
 414 sub match {
 415     my ($self) = @_;
 416     $self->throw_not_implemented();
 417 }
 418
 419 =head2 unmatch
 420
 421  Title     : unmatch()
 422  Usage     : $ali->unmatch()
 423  Function  :
 424
 425              Undoes the effect of method match. Unsets match_char.
 426
 427  Returns   : 1
 428  Argument  : a match character, optional, defaults to '.'
 429
 430 =cut
 431
 432 sub unmatch {
 433     my ($self) = @_;
 434     $self->throw_not_implemented();
 435 }
 436
 437
 438 =head1 MSE attibutes
 439
 440 Methods for setting and reading the MSE attributes.
 441
 442 Note that the methods defining character semantics depend on the user
 443 to set them sensibly.  They are needed only by certain input/output
 444 methods. Unset them by setting to an empty string ('').
 445
 446 =head2 id
 447
 448  Title     : id
 449  Usage     : $myalign->id("Ig")
 450  Function  : Gets/sets the id field of the alignment
 451  Returns   : An id string
 452  Argument  : An id string (optional)
 453
 454 =cut
 455
 456 sub id {
 457     my ($self) = @_;
 458     $self->throw_not_implemented();
 459 }
 460
 461 =head2 missing_char
 462
 463  Title     : missing_char
 464  Usage     : $myalign->missing_char("?")
 465  Function  : Gets/sets the missing_char attribute of the alignment
 466              It is generally recommended to set it to 'n' or 'N'
 467              for nucleotides and to 'X' for protein.
 468  Returns   : An missing_char string,
 469  Argument  : An missing_char string (optional)
 470
 471 =cut
 472
 473 sub missing_char {
 474     my ($self) = @_;
 475     $self->throw_not_implemented();
 476 }
 477
 478 =head2 match_char
 479
 480  Title     : match_char
 481  Usage     : $myalign->match_char('.')
 482  Function  : Gets/sets the match_char attribute of the alignment
 483  Returns   : An match_char string,
 484  Argument  : An match_char string (optional)
 485
 486 =cut
 487
 488 sub match_char {
 489     my ($self) = @_;
 490     $self->throw_not_implemented();
 491 }
 492
 493 =head2 gap_char
 494
 495  Title     : gap_char
 496  Usage     : $myalign->gap_char('-')
 497  Function  : Gets/sets the gap_char attribute of the alignment
 498  Returns   : An gap_char string, defaults to '-'
 499  Argument  : An gap_char string (optional)
 500
 501 =cut
 502
 503 sub gap_char {
 504     my ($self) = @_;
 505     $self->throw_not_implemented();
 506 }
 507
 508 =head2 symbol_chars
 509
 510  Title   : symbol_chars
 511  Usage   : my @symbolchars = $aln->symbol_chars;
 512  Function: Returns all the seen symbols (other than gaps)
 513  Returns : array of characters that are the seen symbols
 514  Argument: boolean to include the gap/missing/match characters
 515
 516 =cut
 517
 518 sub symbol_chars{
 519     my ($self) = @_;
 520     $self->throw_not_implemented();
 521 }
 522
 523 =head1 Alignment descriptors
 524
 525 These read only methods describe the MSE in various ways.
 526
 527
 528 =head2 consensus_string
 529
 530  Title     : consensus_string
 531  Usage     : $str = $ali->consensus_string($threshold_percent)
 532  Function  : Makes a strict consensus
 533  Returns   : consensus string
 534  Argument  : Optional threshold ranging from 0 to 100.
 535              The consensus residue has to appear at least threshold %
 536              of the sequences at a given location, otherwise a '?'
 537              character will be placed at that location.
 538              (Default value = 0%)
 539
 540 =cut
 541
 542 sub consensus_string {
 543     my ($self) = @_;
 544     $self->throw_not_implemented();
 545 }
 546
 547 =head2 consensus_iupac
 548
 549  Title     : consensus_iupac
 550  Usage     : $str = $ali->consensus_iupac()
 551  Function  :
 552
 553              Makes a consensus using IUPAC ambiguity codes from DNA
 554              and RNA. The output is in upper case except when gaps in
 555              a column force output to be in lower case.
 556
 557              Note that if your alignment sequences contain a lot of
 558              IUPAC ambiquity codes you often have to manually set
 559              alphabet.  Bio::PrimarySeq::_guess_type thinks they
 560              indicate a protein sequence.
 561
 562  Returns   : consensus string
 563  Argument  : none
 564  Throws    : on protein sequences
 565
 566
 567 =cut
 568
 569 sub consensus_iupac {
 570     my ($self) = @_;
 571     $self->throw_not_implemented();
 572 }
 573
 574 =head2 is_flush
 575
 576  Title     : is_flush
 577  Usage     : if( $ali->is_flush() )
 578            :
 579            :
 580  Function  : Tells you whether the alignment
 581            : is flush, ie all of the same length
 582            :
 583            :
 584  Returns   : 1 or 0
 585  Argument  :
 586
 587 =cut
 588
 589 sub is_flush {
 590     my ($self) = @_;
 591     $self->throw_not_implemented();
 592 }
 593
 594 =head2 length
 595
 596  Title     : length()
 597  Usage     : $len = $ali->length()
 598  Function  : Returns the maximum length of the alignment.
 599              To be sure the alignment is a block, use is_flush
 600  Returns   : integer
 601  Argument  :
 602
 603 =cut
 604
 605 sub length {
 606     my ($self) = @_;
 607     $self->throw_not_implemented();
 608 }
 609
 610 =head2 maxname_length
 611
 612  Title     : maxname_length
 613  Usage     : $ali->maxname_length()
 614  Function  :
 615
 616              Gets the maximum length of the displayname in the
 617              alignment. Used in writing out various MSE formats.
 618
 619  Returns   : integer
 620  Argument  :
 621
 622 =cut
 623
 624 sub maxname_length {
 625     my ($self) = @_;
 626     $self->throw_not_implemented();
 627 }
 628
 629 =head2 num_residues
 630
 631  Title     : num_residues
 632  Usage     : $no = $ali->num_residues
 633  Function  : number of residues in total in the alignment
 634  Returns   : integer
 635  Argument  :
 636  Note      : replaces no_residues
 637
 638 =cut
 639
 640 sub num_residues {
 641     my ($self) = @_;
 642     $self->throw_not_implemented();
 643 }
 644
 645 =head2 num_sequences
 646
 647  Title     : num_sequences
 648  Usage     : $depth = $ali->num_sequences
 649  Function  : number of sequence in the sequence alignment
 650  Returns   : integer
 651  Argument  : None
 652  Note      : replaces no_sequences
 653
 654 =cut
 655
 656 sub num_sequences {
 657     my ($self) = @_;
 658     $self->throw_not_implemented();
 659 }
 660
 661 =head2 percentage_identity
 662
 663  Title   : percentage_identity
 664  Usage   : $id = $align->percentage_identity
 665  Function: The function calculates the percentage identity of the alignment
 666  Returns : The percentage identity of the alignment (as defined by the
 667            implementation)
 668  Argument: None
 669
 670 =cut
 671
 672 sub percentage_identity{
 673     my ($self) = @_;
 674     $self->throw_not_implemented();
 675 }
 676
 677 =head2 overall_percentage_identity
 678
 679  Title   : overall_percentage_identity
 680  Usage   : $id = $align->overall_percentage_identity
 681  Function: The function calculates the percentage identity of
 682            the conserved columns
 683  Returns : The percentage identity of the conserved columns
 684  Args    : None
 685
 686 =cut
 687
 688 sub overall_percentage_identity{
 689     my ($self) = @_;
 690     $self->throw_not_implemented();
 691 }
 692
 693
 694 =head2 average_percentage_identity
 695
 696  Title   : average_percentage_identity
 697  Usage   : $id = $align->average_percentage_identity
 698  Function: The function uses a fast method to calculate the average
 699            percentage identity of the alignment
 700  Returns : The average percentage identity of the alignment
 701  Args    : None
 702
 703 =cut
 704
 705 sub average_percentage_identity{
 706     my ($self) = @_;
 707     $self->throw_not_implemented();
 708 }
 709
 710 =head1 Alignment positions
 711
 712 Methods to map a sequence position into an alignment column and back.
 713 column_from_residue_number() does the former. The latter is really a
 714 property of the sequence object and can done using
 715 L<Bio::LocatableSeq::location_from_column>:
 716
 717     # select somehow a sequence from the alignment, e.g.
 718     my $seq = $aln->get_seq_by_pos(1);
 719     #$loc is undef or Bio::LocationI object
 720     my $loc = $seq->location_from_column(5);
 721
 722
 723 =head2 column_from_residue_number
 724
 725  Title   : column_from_residue_number
 726  Usage   : $col = $ali->column_from_residue_number( $seqname, $resnumber)
 727  Function:
 728
 729            This function gives the position in the alignment
 730            (i.e. column number) of the given residue number in the
 731            sequence with the given name. For example, for the
 732            alignment
 733
 734              Seq1/91-97 AC..DEF.GH
 735              Seq2/24-30 ACGG.RTY..
 736              Seq3/43-51 AC.DDEFGHI
 737
 738            column_from_residue_number( "Seq1", 94 ) returns 6.
 739            column_from_residue_number( "Seq2", 25 ) returns 2.
 740            column_from_residue_number( "Seq3", 50 ) returns 9.
 741
 742            An exception is thrown if the residue number would lie
 743            outside the length of the alignment
 744            (e.g. column_from_residue_number( "Seq2", 22 )
 745
 746           Note: If the parent sequence is represented by more than one
 747           alignment sequence and the residue number is present in
 748           them, this method finds only the first one.
 749
 750  Returns : A column number for the position in the alignment of the
 751            given residue in the given sequence (1 = first column)
 752  Args    : A sequence id/name (not a name/start-end)
 753            A residue number in the whole sequence (not just that
 754            segment of it in the alignment)
 755
 756 =cut
 757
 758 sub column_from_residue_number {
 759     my ($self) = @_;
 760     $self->throw_not_implemented();
 761 }
 762
 763 =head1 Sequence names
 764
 765 Methods to manipulate the display name. The default name based on the
 766 sequence id and subsequence positions can be overridden in various
 767 ways.
 768
 769 =head2 displayname
 770
 771  Title     : displayname
 772  Usage     : $myalign->displayname("Ig", "IgA")
 773  Function  : Gets/sets the display name of a sequence in the alignment
 774            :
 775  Returns   : A display name string
 776  Argument  : name of the sequence
 777              displayname of the sequence (optional)
 778
 779 =cut
 780
 781 sub displayname {
 782     my ($self) = @_;
 783     $self->throw_not_implemented();
 784 }
 785
 786 =head2 set_displayname_count
 787
 788  Title     : set_displayname_count
 789  Usage     : $ali->set_displayname_count
 790  Function  :
 791
 792              Sets the names to be name_# where # is the number of
 793              times this name has been used.
 794
 795  Returns   : None
 796  Argument  : None
 797
 798 =cut
 799
 800 sub set_displayname_count {
 801     my ($self) = @_;
 802     $self->throw_not_implemented();
 803 }
 804
 805 =head2 set_displayname_flat
 806
 807  Title     : set_displayname_flat
 808  Usage     : $ali->set_displayname_flat()
 809  Function  : Makes all the sequences be displayed as just their name,
 810              not name/start-end
 811  Returns   : 1
 812  Argument  : None
 813
 814 =cut
 815
 816 sub set_displayname_flat {
 817     my ($self) = @_;
 818     $self->throw_not_implemented();
 819 }
 820
 821 =head2 set_displayname_normal
 822
 823  Title     : set_displayname_normal
 824  Usage     : $ali->set_displayname_normal()
 825  Function  : Makes all the sequences be displayed as name/start-end
 826  Returns   : None
 827  Argument  : None
 828
 829 =cut
 830
 831 sub set_displayname_normal {
 832     my ($self) = @_;
 833     $self->throw_not_implemented();
 834 }
 835
 836 =head1 Deprecated methods
 837
 838 =head2 no_residues
 839
 840  Title     : no_residues
 841  Usage     : $no = $ali->no_residues
 842  Function  : number of residues in total in the alignment
 843  Returns   : integer
 844  Argument  :
 845  Note      : deprecated in favor of num_residues()
 846
 847 =cut
 848
 849 sub no_residues {
 850     # immediate deprecation
 851     shift->deprecated();
 852 }
 853
 854 =head2 no_sequences
 855
 856  Title     : no_sequences
 857  Usage     : $depth = $ali->no_sequences
 858  Function  : number of sequence in the sequence alignment
 859  Returns   : integer
 860  Argument  : None
 861  Note      : deprecated in favor of num_sequences()
 862
 863 =cut
 864
 865 sub no_sequences {
 866     # immediate deprecation
 867     shift->deprecated();
 868 }
 869
 870 1;