Bio::Tools::Run::Alignment::Clustalw(3)

NAME
Bio::Tools::Run::Alignment::Clustalw - Object for the calculation of a multiple sequence alignment from a set of unaligned sequences or alignments using the Clustalw program

SYNOPSIS
  #  Build a clustalw alignment factory
  @params = ('ktuple' => 2, 'matrix' => 'BLOSUM');
  $factory = Bio::Tools::Run::Alignment::Clustalw->new(@params);

  #  Pass the factory a list of sequences to be aligned.
  $inputfilename = 't/data/cysprot.fa';
  $aln = $factory->align($inputfilename); # $aln is a SimpleAlign object.
  # or
  $seq_array_ref = \@seq_array;
  # where @seq_array is an array of Bio::Seq objects
  $aln = $factory->align($seq_array_ref);

  # Or one can pass the factory a pair of (sub)alignments
  #to be aligned against each other, e.g.:
  $aln = $factory->profile_align($aln1,$aln2);
  # where $aln1 and $aln2 are Bio::SimpleAlign objects.

  # Or one can pass the factory an alignment and one or more unaligned
  # sequences to be added to the alignment. For example:
  $aln = $factory->profile_align($aln1,$seq); # $seq is a Bio::Seq object.

  # There are various additional options and input formats available.
  # See the DESCRIPTION section that follows for additional details.

DESCRIPTION
Note: this DESCRIPTION only documents the (Bio)perl interface to Clustalw. Clustalw, itself, is a large & complex program - for more information regarding clustalw, please see the clustalw documentation which accompanies the clustalw distribution. Clustalw is available from (among others) ftp://ftp.ebi.ac.uk/pub/software/. Clustalw.pm has been tested so far only under Linux. I expect that it should also work under other Unix systems. However, since the module is currently implemented using (unix) system calls, extensive modification may be necessary before Clustalw.pm would work under non-Unix operating systems (eg Windows, MacOS). Clustalw.pm has only been tested using version 1.8 of clustalw. Compatibility with earlier versions of the clustalw program is currently unknown. Before running Clustalw.pm successfully it will be necessary: to install clustalw on your system, to edit the variable $clustdir in Clustalw.pm to point to the clustalw program, and to ensure that users have execute privilieges for the clustalw program.

Bio::Tools::Run::Alignment::Clustalw.pm: is an object for performing a multiple sequence alignment from a set of unaligned sequences and/or sub-alignments by means of the clustalw program.

Initially, a clustalw "factory object" is created. Optionally, the factory may be passed most of the parameters or switches of the clustalw program, e.g.:

        @params = ('ktuple' => 2, 'matrix' => 'BLOSUM');
        $factory = Bio::Tools::Run::Alignment::Clustalw->new(@params);

Any parameters not explicitly set will remain as the defaults of the clustalw program. Additional parameters and switches (not available in clustalw) may also be set. Currently, the only such parameter is "quiet", which when set to a non-zero value, suppresses clustalw terminal output. Not all clustalw parameters are supported at this stage.

By default, Clustalw.pm output is returned solely in a the form of a BioPerl Bio::SimpleAlign object which can then be printed and/or saved in multiple formats using the AlignIO.pm module. Optionally the raw clustalw output file can be saved if the calling script specifies an output file (with the clustalw parameter OUTFILE). Currently only the GCG-MSF output file formats is supported.

Other parameters and features (such as those corresponding to tree production) have not been implemented yet in Perl format.

Alignment parameters can be changed and/or examined at any time after the factory has been created. The program checks that any parameter/switch being set/read is valid. However, currently no additional checks are included to check that parameters are of the proper type (eg string or numeric) or that their values are within the proper range. As an example, to change the value of the clustalw parameter ktuple to 3 and subsequently to check its value one would write:

        $ktuple = 3;
        $factory->ktuple($ktuple);
        $get_ktuple = $factory->ktuple();

Once the factory has been created and the appropriate parameters set, one can call the method align() to align a set of unaligned sequences, or call profile_align() to add one or more sequences or a second alignment to an initial alignment.

Input to align() may consist of a set of unaligned sequences in the form of the name of file containing the sequences. For example, $inputfilename = 't/data/cysprot.fa'; $aln = $factory->align($inputfilename);

Alternately one can create an array of Bio::Seq objects somehow

        $str = Bio::SeqIO->new(-file=> 't/data/cysprot.fa', '-format' => 'Fasta');
        @seq_array =();
        while ( my $seq = $str->next_seq() ) {push (@seq_array, $seq) ;}

and pass the factory a reference to that array

        $seq_array_ref = \@seq_array;
        $aln = $factory->align($seq_array_ref);

In either case, align() returns a reference to a SimpleAlign object which can then be displayed, stored, or converted to a UnivAlign object for further manipulation.

Once an initial alignment exists, one can pass the factory additional sequence(s) to be added (ie aligned) to the original alignment. The alignment can be passed as either an alignment file or a Bio:SimpleAlign object. The unaligned sequence(s) can be passed as a filename or as an array of BioPerl sequence objects or as a single BioPerl Seq object. For example (to add a single sequence to an alignment),

        $str = Bio::AlignIO->new(-file=> 't/data/cysprot1a.msf');
        $aln = $str->next_aln();
        $str1 = Bio::SeqIO->new(-file=> 't/data/cysprot1b.fa');
        $seq = $str1->next_seq();
        $aln = $factory->profile_align($aln,$seq);

In either case, profile_align() returns a reference to a SimpleAlign object containing a new SimpleAlign object of the alignment with the additional sequence(s) added in.

Finally one can pass the factory a pair of (sub)alignments to be aligned against each other. The alignments can be passed in the form of either a pair of alignment files or a pair of Bio:SimpleAlign objects. For example,

        $profile1 = 't/data/cysprot1a.msf';
        $profile2 = 't/data/cysprot1b.msf';
        $aln = $factory->profile_align($profile1,$profile2);
or
        $str1 = Bio::AlignIO->new(-file=> 't/data/cysprot1a.msf');
        $aln1 = $str1->next_aln();
        $str2 = Bio::AlignIO->new(-file=> 't/data/cysprot1b.msf');
        $aln2 = $str2->next_aln();
        $aln = $factory->profile_align($aln1,$aln2);

In either case, profile_align() returns a reference to a SimpleAlign object containing an (super)alignment of the two input alignments.

For more examples of syntax and use of Clustalw.pm, the user is encouraged to run the script Clustalw.t is the bioperl/t directory.

Note: Clustalw.pm is still under development. Various features of the clustalw program have not yet been implemented. If you would like that a specific clustalw feature be added to this perl interface, let me know.

These can be specified as paramters when instantiating a new TCoffee object, or through get/set methods of the same name (lowercase).

PARAMETER FOR ALIGNMENT COMPUTATION

  KTUPLE
 Title       : KTUPLE
 Description : (optional) set the word size to be used in the alignment
               This is the size of exactly matching fragment that is used.
               INCREASE for speed (max= 2 for proteins; 4 for DNA),
               DECREASE for sensitivity.
               For longer sequences (e.g. >1000 residues) you may
               need to increase the default

  TOPDIAGS
 Title       : TOPDIAGS
 Description : (optional) number of best diagonals to use
               The number of k-tuple matches on each diagonal
               (in an imaginary dot-matrix plot) is calculated.
               Only the best ones (with most matches) are used in
               the alignment.  This parameter specifies how many.
               Decrease for speed; increase for sensitivity.

  WINDOW
 Title       : WINDOW
 Description : (optional) window size
               This is the number of diagonals around each of the 'best'
               diagonals that will be used.  Decrease for speed;
               increase for sensitivity.

  PAIRGAP
 Title       : PAIRGAP
 Description : (optional) gap penalty for pairwise alignments
               This is a penalty for each gap in the fast alignments.
               It has little affect on the speed or sensitivity except
               for extreme values.

  FIXEDGAP
 Title       : FIXEDGAP
 Description : (optional) fixed length gap penalty

  FLOATGAP
 Title       : FLOATGAP
 Description : (optional) variable length gap penalty

  MATRIX
 Title       : MATRIX
 Default     : PAM100 for DNA - PAM250 for protein alignment
 Description : (optional) substitution matrix used in the multiple
               alignments. Depends on the version of clustalw as to
               what default matrix will be used

               PROTEIN WEIGHT MATRIX leads to a new menu where you are
               offered a choice of weight matrices. The default for
               proteins in version 1.8 is the PAM series derived by
               Gonnet and colleagues. Note, a series is used! The
               actual matrix that is used depends on how similar the
               sequences to be aligned at this alignment step
               are. Different matrices work differently at each
               evolutionary distance.

               DNA WEIGHT MATRIX leads to a new menu where a single
               matrix (not a series) can be selected. The default is
               the matrix used by BESTFIT for comparison of nucleic
               acid sequences.

  TYPE
 Title       : TYPE
 Description : (optional) sequence type: protein or DNA. This allows
               you to explicitly overide the programs attempt at
               guessing the type of the sequence.  It is only useful
               if you are using sequences with a VERY strange
               composition.

  OUTPUT
 Title       : OUTPUT
 Description : (optional) clustalw supports GCG or PHYLIP or PIR or
                Clustal format.  See the Bio::AlignIO modules for
                which formats are supported by bioperl.

  OUTFILE
 Title       : OUTFILE
 Description : (optional) Name of clustalw output file. If not set
               module will erase output file.  In any case alignment will
               be returned in the form of SimpleAlign objects

  TRANSMIT
 Title       : TRANSMIT
 Description : (optional) transitions not weighted.  The default is to
               weight transitions as more favourable than other
               mismatches in DNA alignments.  This switch makes all
               nucleotide mismatches equally weighted.

FEEDBACK

  Mailing Lists
User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.

  bioperl-l@bioperl.org          - General discussion
  http://bio.perl.org/MailList.html             - About the mailing lists

  Reporting Bugs
Report bugs to the Bioperl bug tracking system to help us keep track
 the bugs and their resolution. Bug reports can be submitted via
 email or the web:

  bioperl-bugs@bio.perl.org
  http://bio.perl.org/bioperl-bugs/

AUTHOR - Peter Schattner
Email schattner@alum.mit.edu

CONTRIBUTORS
Jason Stajich jason@bioperl.org

APPENDIX
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

  program_name
 Title   : program_name
 Usage   : $factory>program_name()
 Function: holds the program name
 Returns:  string
 Args    : None

  program_dir
 Title   : program_dir
 Usage   : $factory->program_dir(@params)
 Function: returns the program directory, obtiained from ENV variable.
 Returns:  string
 Args    :

  version
 Title   : version
 Usage   : exit if $prog->version() < 1.8
 Function: Determine the version number of the program
 Example :
 Returns : float or undef
 Args    : none

  align
 Title   : align
 Usage   :
        $inputfilename = 't/data/cysprot.fa';
        $aln = $factory->align($inputfilename);
or
        $seq_array_ref = \@seq_array; @seq_array is array of Seq objs
        $aln = $factory->align($seq_array_ref);
 Function: Perform a multiple sequence alignment
 Example :
 Returns : Reference to a SimpleAlign object containing the
           sequence alignment.
 Args    : Name of a file containing a set of unaligned fasta sequences
           or else an array of references to Bio::Seq objects.

 Throws an exception if argument is not either a string (eg a
 filename) or a reference to an array of Bio::Seq objects.  If
 argument is string, throws exception if file corresponding to string
 name can not be found. If argument is Bio::Seq array, throws
 exception if less than two sequence objects are in array.

  profile_align
 Title   : profile_align
 Usage   :
 Function: Perform an alignment of 2 (sub)alignments
 Example :
 Returns : Reference to a SimpleAlign object containing the (super)alignment.
 Args    : Names of 2 files containing the subalignments
         or references to 2 Bio::SimpleAlign objects.

Throws an exception if arguments are not either strings (eg filenames) or references to SimpleAlign objects.

  _run
 Title   :  _run
 Usage   :  Internal function, not to be called directly
 Function:   makes actual system call to clustalw program
 Example :
 Returns : nothing; clustalw output is written to a
           temporary file
 Args    : Name of a file containing a set of unaligned fasta sequences
           and hash of parameters to be passed to clustalw

  _setinput()
 Title   :  _setinput
 Usage   :  Internal function, not to be called directly
 Function:   Create input file for clustalw program
 Example :
 Returns : name of file containing clustalw data input
 Args    : Seq or Align object reference or input file name

  _setparams()
 Title   :  _setparams
 Usage   :  Internal function, not to be called directly
 Function:   Create parameter inputs for clustalw program
 Example :
 Returns : parameter string to be passed to clustalw
           during align or profile_align
 Args    : name of calling object