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->no_residues, "\n";
  25   print $aln->is_flush, "\n";
  26   print $aln->no_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 L<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              no_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 no_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 no_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 no_residues
 630
 631  Title     : no_residues
 632  Usage     : $no = $ali->no_residues
 633  Function  : number of residues in total in the alignment
 634  Returns   : integer
 635  Argument  :
 636
 637 =cut
 638
 639 sub no_residues {
 640     my ($self) = @_;
 641     $self->throw_not_implemented();
 642 }
 643
 644 =head2 no_sequences
 645
 646  Title     : no_sequences
 647  Usage     : $depth = $ali->no_sequences
 648  Function  : number of sequence in the sequence alignment
 649  Returns   : integer
 650  Argument  : None
 651
 652 =cut
 653
 654 sub no_sequences {
 655     my ($self) = @_;
 656     $self->throw_not_implemented();
 657 }
 658
 659 =head2 percentage_identity
 660
 661  Title   : percentage_identity
 662  Usage   : $id = $align->percentage_identity
 663  Function: The function calculates the percentage identity of the alignment
 664  Returns : The percentage identity of the alignment (as defined by the
 665            implementation)
 666  Argument: None
 667
 668 =cut
 669
 670 sub percentage_identity{
 671     my ($self) = @_;
 672     $self->throw_not_implemented();
 673 }
 674
 675 =head2 overall_percentage_identity
 676
 677  Title   : overall_percentage_identity
 678  Usage   : $id = $align->overall_percentage_identity
 679  Function: The function calculates the percentage identity of
 680            the conserved columns
 681  Returns : The percentage identity of the conserved columns
 682  Args    : None
 683
 684 =cut
 685
 686 sub overall_percentage_identity{
 687     my ($self) = @_;
 688     $self->throw_not_implemented();
 689 }
 690
 691
 692 =head2 average_percentage_identity
 693
 694  Title   : average_percentage_identity
 695  Usage   : $id = $align->average_percentage_identity
 696  Function: The function uses a fast method to calculate the average
 697            percentage identity of the alignment
 698  Returns : The average percentage identity of the alignment
 699  Args    : None
 700
 701 =cut
 702
 703 sub average_percentage_identity{
 704     my ($self) = @_;
 705     $self->throw_not_implemented();
 706 }
 707
 708 =head1 Alignment positions
 709
 710 Methods to map a sequence position into an alignment column and back.
 711 column_from_residue_number() does the former. The latter is really a
 712 property of the sequence object and can done using
 713 L<Bio::LocatableSeq::location_from_column>:
 714
 715     # select somehow a sequence from the alignment, e.g.
 716     my $seq = $aln->get_seq_by_pos(1);
 717     #$loc is undef or Bio::LocationI object
 718     my $loc = $seq->location_from_column(5);
 719
 720
 721 =head2 column_from_residue_number
 722
 723  Title   : column_from_residue_number
 724  Usage   : $col = $ali->column_from_residue_number( $seqname, $resnumber)
 725  Function:
 726
 727            This function gives the position in the alignment
 728            (i.e. column number) of the given residue number in the
 729            sequence with the given name. For example, for the
 730            alignment
 731
 732              Seq1/91-97 AC..DEF.GH
 733              Seq2/24-30 ACGG.RTY..
 734              Seq3/43-51 AC.DDEFGHI
 735
 736            column_from_residue_number( "Seq1", 94 ) returns 5.
 737            column_from_residue_number( "Seq2", 25 ) returns 2.
 738            column_from_residue_number( "Seq3", 50 ) returns 9.
 739
 740            An exception is thrown if the residue number would lie
 741            outside the length of the alignment
 742            (e.g. column_from_residue_number( "Seq2", 22 )
 743
 744           Note: If the parent sequence is represented by more than one
 745           alignment sequence and the residue number is present in
 746           them, this method finds only the first one.
 747
 748  Returns : A column number for the position in the alignment of the
 749            given residue in the given sequence (1 = first column)
 750  Args    : A sequence id/name (not a name/start-end)
 751            A residue number in the whole sequence (not just that
 752            segment of it in the alignment)
 753
 754 =cut
 755
 756 sub column_from_residue_number {
 757     my ($self) = @_;
 758     $self->throw_not_implemented();
 759 }
 760
 761 =head1 Sequence names
 762
 763 Methods to manipulate the display name. The default name based on the
 764 sequence id and subsequence positions can be overridden in various
 765 ways.
 766
 767 =head2 displayname
 768
 769  Title     : displayname
 770  Usage     : $myalign->displayname("Ig", "IgA")
 771  Function  : Gets/sets the display name of a sequence in the alignment
 772            :
 773  Returns   : A display name string
 774  Argument  : name of the sequence
 775              displayname of the sequence (optional)
 776
 777 =cut
 778
 779 sub displayname {
 780     my ($self) = @_;
 781     $self->throw_not_implemented();
 782 }
 783
 784 =head2 set_displayname_count
 785
 786  Title     : set_displayname_count
 787  Usage     : $ali->set_displayname_count
 788  Function  :
 789
 790              Sets the names to be name_# where # is the number of
 791              times this name has been used.
 792
 793  Returns   : None
 794  Argument  : None
 795
 796 =cut
 797
 798 sub set_displayname_count {
 799     my ($self) = @_;
 800     $self->throw_not_implemented();
 801 }
 802
 803 =head2 set_displayname_flat
 804
 805  Title     : set_displayname_flat
 806  Usage     : $ali->set_displayname_flat()
 807  Function  : Makes all the sequences be displayed as just their name,
 808              not name/start-end
 809  Returns   : 1
 810  Argument  : None
 811
 812 =cut
 813
 814 sub set_displayname_flat {
 815     my ($self) = @_;
 816     $self->throw_not_implemented();
 817 }
 818
 819 =head2 set_displayname_normal
 820
 821  Title     : set_displayname_normal
 822  Usage     : $ali->set_displayname_normal()
 823  Function  : Makes all the sequences be displayed as name/start-end
 824  Returns   : None
 825  Argument  : None
 826
 827 =cut
 828
 829 sub set_displayname_normal {
 830     my ($self) = @_;
 831     $self->throw_not_implemented();
 832 }
 833
 834 1;