view release on metacpan or  search on metacpan

lib/Bio/Tools/Run/Infernal.pm  view on Meta::CPAN

#
# You may distribute this module under the same terms as perl itself
#
# POD documentation - main docs before the code
#
# _history
#
# March 2007 - first full implementation; needs some file IO tweaking between
#              runs but works for now
# April 2008 - add 0.81 parameters (may be removed in the 1.0 release)
#
# July  2009 - updated for v1.0. No longer supporting pre-1.0 Infernal

=head1 NAME

Bio::Tools::Run::Infernal - Wrapper for local execution of cmalign, cmbuild,
cmsearch, cmscore

=head1 SYNOPSIS

  # parameters which are switches are set with any value that evals TRUE,
  # others are set to a specific value

  my $factory = Bio::Tools::Run::Infernal->new(@params);

  # run cmalign|cmbuild|cmsearch|cmscore|cmemit directly as a wrapper method
  # this resets the program flag if previously set

  $factory->cmsearch(@seqs); # searches Bio::PrimarySeqI's based on set cov. model
                             # saves output to optional outfile_name, returns
                             # Bio::SearchIO

  # only values which are allowed for a program are set, so one can use the same
  # wrapper for the following...

  $factory->cmalign(@seqs); # aligns Bio::PrimarySeqI's to a set cov. model,
                            # --merge option allows two alignments generated
                            #     from the same CM to be merged.
                            # output to outfile_name, returns Bio::AlignIO
  $factory->cmscore();      # scores set cov. model against Bio::PrimarySeqI,
                            # output to outfile_name/STDOUT.
  $factory->cmbuild($aln); # builds covariance model based on alignment
                           # CM to outfile_name or model_file (one is required
                           # here), output to STDOUT.
  $factory->cmemit();      # emits sequence from specified cov. model;
                           # set one if no file specified. output to
                           # outfile_name, returns Bio::SeqIO or (if -a is set)
                           # Bio::AlignIO
  $factory->cmcalibrate($file); # calibrates specified cov. model; output to
                                # STDOUT
  $factory->cmstat($file); # summary stats for cov. model; set one if no file
                           # specified; output to STDOUT

  # run based on the setting of the program parameter

  my $factory = Bio::Tools::Run::Infernal->new(-program => 'cmsearch',
                                                @params);
  my $search = $factory->run($seq);

  # using cmsearch returns a Bio::SearchIO object

  while (my $result = $searchio->next_result){
   while(my $hit = $result->next_hit){
    while (my $hsp = $hit->next_hsp){
            print join("\t", ( $r->query_name,
                               $hit->name,
                               $hsp->hit->start,
                               $hsp->hit->end,
                               $hsp->meta,
                               $hsp->score,
                               )), "\n";
    }
   }
  }

=head1 DESCRIPTION

Wrapper module for Sean Eddy's Infernal suite of programs. The current
implementation runs cmsearch, cmcalibrate, cmalign, cmemit, cmbuild, cmscore,
and cmstat. cmsearch will return a Bio::SearchIO, cmemit a Bio::SeqIO/AlignIO,
and cmalign a Bio::AlignIO.  All others send output to STDOUT.  Optionally,
any program's output can be redirected to outfile_name.

We HIGHLY suggest upgrading to Infernal 1.0.  In that spirit, this wrapper now
supports parameters for Infernal 1.0 only; for wrapping older versions of
Infernal we suggest using the version of Bio::Tools::Run::Infernal that came
with previous versions of BioPerl-run.

NOTE: Due to conflicts in the way Infernal parameters are now formatted vs.
subroutine naming in Perl (specifically the inclusion of hyphens) and due to the
very large number of parameters available, setting and resetting parameters via
set_parameters() and reset_parameters() is required. All valid parameters can
be set, but only ones valid for the executable set via program()/program_name()
are used for calling the executables, the others are silently ignored.

=head1 FEEDBACK

=head2 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://bioperl.org/wiki/Mailing_lists  - About the mailing lists

=head2 Support 

Please direct usage questions or support issues to the mailing list:

I<bioperl-l@bioperl.org>

lib/Bio/Tools/Run/Infernal.pm  view on Meta::CPAN

    return $self->_run(@_);
}

=head2 cmbuild

 Title   :   cmbuild
 Usage   :   $obj->cmbuild($alignment)
 Function:   Runs Infernal cmbuild and saves covariance model
 Returns :   1 on success (no object for covariance models)
 Args    :   Bio::AlignIO with structural information (such as from Stockholm
             format source) or alignment file name

=cut

sub cmbuild {
    my ($self,@seq) = @_;
    $self->program('cmbuild');
    if  (ref $seq[0] && $seq[0]->isa("Bio::Align::AlignI") ){# it is an object
        my $infile1 = $self->_writeAlignFile(@seq);
        return  $self->_run(-align_files => [$infile1]);
    } else {
        return  $self->_run(-align_files => \@seq);
    }
}

=head2 cmscore

 Title   :   cmscore
 Usage   :   $obj->cmscore($seq)
 Function:   Runs Infernal cmscore and saves output
 Returns :   None
 Args    :   None; set model_file() to use a specific model

=cut

sub cmscore {
    my ($self,@seq) = @_;
    $self->program('cmscore');
    return  $self->_run();
}

=head2 cmcalibrate

 Title   :   cmcalibrate
 Usage   :   $obj->cmcalibrate('file')
 Function:   Runs Infernal calibrate on specified CM
 Returns :   None
 Args    :   None; set model_file() to use a specific model

=cut

sub cmcalibrate {
    my ($self,@seq) = @_;
    $self->program('cmcalibrate');
    return  $self->_run();
}

=head2 cmstat

 Title   :   cmstat
 Usage   :   $obj->cmstat($seq)
 Function:   Runs Infernal cmstat and saves output
 Returns :   None
 Args    :   None; set model_file() to use a specific model

=cut

sub cmstat {
    my ($self,@seq) = @_;
    $self->program('cmstat');
    return  $self->_run();
}

=head1 Bio::ParameterBaseI-specific methods

These methods are part of the Bio::ParameterBaseI interface

=cut

=head2 set_parameters

 Title   : set_parameters
 Usage   : $pobj->set_parameters(%params);
 Function: sets the parameters listed in the hash or array
 Returns : None
 Args    : [optional] hash or array of parameter/values.  These can optionally
           be hash or array references
 Note    : This only sets parameters; to set methods use the method name
=cut

sub set_parameters {
    my $self = shift;
    # circumvent any issues arising from passing in refs
    my %args = (ref($_[0]) eq 'HASH')  ? %{$_[0]} :
               (ref($_[0]) eq 'ARRAY') ? @{$_[0]} :
               @_;
    # set the parameters passed in, but only ones supported for the program
    my ($prog, $validate) = ($self->program, $self->validate_parameters);

    # parameter cleanup
    %args = map { my $a = $_;
              $a =~ s{^-}{};
              lc $a => $args{$_}
                 } sort keys %args;
    
    while (my ($key, $val) = each %args) {
        if (exists $INFERNAL_PARAMS{$key}) {
            my ($type, $prefix) = @{$INFERNAL_PARAMS{$key}}[0..1];
            @{$self->{parameters}->{$key}} = ($type, $prefix);
            unshift @{$self->{parameters}->{$key}}, 
                $type eq 'param'          ? $val :
                $type eq 'switch' && $val ? 1 : 0;
            if ($validate) {
                my %in_exe = map {$_ => 1} @{$INFERNAL_PARAMS{$key}}[2..$#{$INFERNAL_PARAMS{$key}}];
                $self->warn("Parameter $key not used for $prog") if !exists $in_exe{$key};
            }
        } else {
            $self->warn("Parameter $key does not exist") if ($validate);
        }
    }
}