Bio::Seq PrimedSeq
SummaryIncluded librariesPackage variablesSynopsisDescriptionGeneral documentationMethods
Summary
Bio::Seq::PrimedSeq - A representation of a sequence and two primers flanking a
target region for amplification
Package variables
No package variables defined.
Included modules
Bio::RangeI
Bio::SeqFeature::Generic
Bio::SeqFeature::Primer
Inherit
Bio::Root::Root Bio::SeqFeature::Generic
Synopsis
  # The easiest way to use this is probably as one of the following:
  # (i) to get the output from Bio::Tools::Run::Primer3, Bio::Tools::Primer3,
  # or Bio::Tools::PCRSimulation

  #    For example, start with a fasta file

      use Bio::SeqIO;
      use Bio::Tools::Run::Primer3;

      my $file = shift || die "need a file to read";
      my $seqin = Bio::SeqIO->new(-file=>$file);
      my $seq = $seqin->next_seq;
      # use primer3 to design some primers
      my $primer3run = Bio::Tools::Run::Primer3->new(-seq=>$seq);
      $primer3run -> run; # we'll just run it with the default parameters

      # create a file to write the results to
      my $seqout=Bio::SeqIO->new(-file=>">primed_sequence.gbk", -format=>'genbank');

      # now just get all the results and write them out.
      while (my $results=$primer3run->next_primer) {
       $seqout->write_seq($results->annotated_seq);
      }

   #(ii) to create a genbank file for a sequence and its cognate primers

     #For example:

     use Bio::SeqIO;
     use Bio::Seq::PrimedSeq;

     # have a sequence file ($file) with the template, and two primers
     # that match it, in fasta format

     my $file=shift || die "$0 ";
     my $seqin=new Bio::SeqIO(-file=>$file);

     # read three sequences
     my ($template, $leftprimer, $rightprimer) =
           ($seqin->next_seq, $seqin->next_seq, , $seqin->next_seq);
     # set up the primed sequence object
     my $primedseq = Bio::Seq::PrimedSeq->new(-seq=>$template, 
                                              -left_primer=>$leftprimer,
                                              -right_primer=>$rightprimer);
     # open a file for output
     my $seqout=Bio::SeqIO->new(-file=>">primed_sequence.gbk",
                                -format=>'genbank');
     # print the sequence out
     $seqout->write_seq($primedseq->annotated_sequence);

  # This should output a genbank file with the two primers labeled.
Description
This module is a slightly glorified capsule containg a primed sequence. It was
created to address the fact that a primer is more the a seqfeature and there
need to be ways to represent the primer-sequence complex and the behaviors and
attributes that are associated with the complex.
The primers are represented as Bio::SeqFeature::Primer objects, and should
be instatiated first.
The simplest way to initiate a PrimedSeq object is as follows:
  my $primedseq=Bio::Seq::PrimedSeq->new(
  -seq=>Bio::Seq object,
  -left_primer=>Bio::SeqFeature::Primer object,
  -right_primer=>Bio::SeqFeature::Primer object,
  );
From the PrimedSeq object you should be able to retrieve
information about Tm's and what not of each of the primers
and the amplicon.
This is based on the PrimedSeq.pm module started by Chad Matsalla, with
additions/improvements by Rob Edwards.
Methods
BEGIN Code
AUTOLOAD
No description
Code
newDescriptionCode
get_primer()
No description
Code
annotated_sequenceDescriptionCode
ampliconDescriptionCode
seqDescriptionCode
_place_seqsDescriptionCode
_set_seqfeatureDescriptionCode
Methods description
newcode    nextTop
 Title   : new()
 Usage   : $primed_sequence = new Bio::SeqFeature::Primer( -seq => $sequence,
                                                            -left_primer => $left_primer,
                                                            -right_primer => $right_primer);
 Function: A constructor for an object representing a primed sequence 
 Returns : A Bio::Seq::PrimedSeq object
 Args    : 
     -target_sequence => a Bio::Seq object (required)
     -left_primer => a Bio::SeqFeature::Primer object (required)
     -right_primer => a Bio::SeqFeature::Primer object (required)

     Many other parameters can be included including all of the output
     parameters from the primer3 program. At the moment some of these
     parameters (most...) will not do anything.
annotated_sequencecodeprevnextTop
 Title   : annotated_sequence
 Usage   : $annotated_sequence_object = $primedseq->annotated_sequence()
 Function: Get an annotated sequence object containg the left and right primers
 Returns : An annotated sequence object or 0 if not defined.
 Args    : 
 Note    : Use this method to return a sequence object that you can write out (e.g. in GenBank format)
           See the example above.
ampliconcodeprevnextTop
 Title   : amplicon
 Usage   : my $amplicon = $primedseq->amplicon()
 Function: Retrieve the amplicon as a sequence object
 Returns : A seq object. To get the sequence use $amplicon->seq
 Args    : None
 Note    :
seqcodeprevnextTop
 Title   : seq
 Usage   : my $seqobj = $primedseq->seq()
 Function: Retrieve the target sequence as a sequence object
 Returns : A seq object. To get the sequence use $seqobj->seq
 Args    : None
 Note    :
_place_seqscodeprevnextTop
 Title   : _place_seqs
 Usage   : $self->_place_seqs()
 Function: An internal method to place the primers on the sequence, and set up the ranges of the sequences
 Returns : Nothing
 Args    : None
 Note    : Internal use only
_set_seqfeaturecodeprevnextTop
 Title   : _set_seqfeature
 Usage   : $self->_set_seqfeature()
 Function: An internal method to create Bio::SeqFeature::Generic objects for the primed seq
 Returns : Nothing
 Args    : None
 Note    : Internal use only. Should only call this once left and right primers have been placed on the sequence
           This will then set them as sequence features so hopefully we can get a nice output with write_seq
Methods code
BEGINTop
BEGIN {
 @RES=qw(); # nothing here yet, not sure what we want!

 foreach my $attr (@RES) {$OK_FIELD{$attr}++
}
AUTOLOADdescriptionprevnextTop
sub AUTOLOAD {
 my $self = shift;
 my $attr = $AUTOLOAD;
 $attr =~ s/.*:://;
 $self->throw("Unallowed parameter: $attr !") unless $OK_FIELD{$attr};
 $self->{$attr} = shift if @_;
 return $self->{$attr};
}
newdescriptionprevnextTop
sub new {
 # note, I have cleaned up a lot of the script that Chad had written here,
 # and I have removed the part where he removed the - before the tags.
 # Very confusing.

 my($class,%args) = @_;
 my $self = $class->SUPER::new(%args);
   # these are the absolute minimum components required to make
   # a primedseq

 foreach my $key (keys %args) {
     if ($key eq "-seq" || $key eq "-SEQ") {
	 $self->{target_sequence} = $args{$key};
	 next;
     } else {
	 my $okey;
	 ($okey=$key)=~s/^-//;;
	 if (($okey eq "left_primer" || $okey eq "right_primer") && 
	     ref($args{$key}) && $args{$key}->isa('Bio::SeqI') ) {
	     # we have been parsed a bio seq object. 
	     # Make it a Bio::SeqFeature::Primer object
	     $self->{$okey} = Bio::SeqFeature::Primer->new(-seq=>$args{$key});
	     push @{$self->{'arguments'}},$okey;
	     next;
	 }

	 $self->{$okey} = $args{$key};
	 push @{$self->{'arguments'}},$okey;
     }
 }
 # and now the insurance- make sure that things are ok
 if (!$self->{target_sequence} || !$self->{left_primer} || !$self->{right_primer} ) {
   $self->throw("You must provide a -target_sequence, -left_primer, and -right_primer to create this object.");
 }
  
 if (! ref($self->{target_sequence}) ||
     ! $self->{target_sequence}->isa('Bio::SeqI') ) {
     $self->throw("The target_sequence must be a Bio::Seq to create this object.");
 }
 if (! ref($self->{left_primer}) ||
     ! $self->{left_primer}->isa("Bio::SeqFeature::Primer") || 
     ! ref($self->{right_primer}) ||
     ! $self->{right_primer}->isa("Bio::SeqFeature::Primer")) {
     $self->throw("You must provide a left_primer and right_primer, both as Bio::SeqFeature::Primer to create this object.");
 }
 
 # now we have the sequences, lets find out where they are
 $self->_place_seqs();
 return $self;
}
get_primer()descriptionprevnextTop
sub get_primer() {
 my ($self, $arg) = @_;
 if ($arg =~ /^l/ || $arg =~ /^-l/) { 
  # what a cheat, I couldn't be bothered to write all those or statements!
  # Hah, now you can write leprechaun to get the left primer.
  return $self->{'left_primer'}
 }
 elsif ($arg =~ /^r/ || $arg =~ /^-r/) {return $self->{'right_primer'}}
 elsif ($arg =~ /^b/ || $arg =~ /^-b/) {return ($self->{'left_primer'}, $self->{'right_primer'})}
}
annotated_sequencedescriptionprevnextTop
sub annotated_sequence {
  my $self = shift;
  if (exists $self->{annotated_sequence}) {return $self->{annotated_sequence}}
  else {return 0}
}
amplicondescriptionprevnextTop
sub amplicon {
 my ($self,@args) = @_;
 my $id = $self->{'-seq'}->{'id'};
 unless ($id) {$id=""}# this just prevents a warning when $self->{'-seq'}->{'id'} is not defined
 $id = "Amplicon from ".$id;
 
 my $seqobj=Bio::Seq->new(-id=>$id, seq=>$self->{'amplicon_sequence'});
 return $seqobj;
}
seqdescriptionprevnextTop
sub seq {
 my $self = shift;
 return $self->{target_sequence};
}
_place_seqsdescriptionprevnextTop
sub _place_seqs {
 my $self = shift;
 
 # we are going to pull out the target sequence, and then the primer sequences
 my $target_sequence = $self->{'target_sequence'}->seq();
 
 # left primer
 my $left_seq = $self->{'left_primer'}->seq()->seq();

 my $rprc = $self->{'right_primer'}->seq()->revcom();
 
 my $right_seq=$rprc->seq();
  
  
 # now just change the case, because we keep getting screwed on this
 $target_sequence=uc($target_sequence);
 $left_seq=uc($left_seq);
 $right_seq=uc($right_seq);
 
 unless ($target_sequence =~ /(.*)$left_seq(.*)$right_seq(.*)/) {
  unless ($target_sequence =~ /$left_seq/) {$self->throw("Can't place left sequence on target!")}
  unless ($target_sequence =~ /$right_seq/) {$self->throw("Can't place right sequence on target!")}
 }
 
 my ($before, $middle, $after) = ($1, $2, $3); # note didn't use $`, $', and $& because they are bad. Just use length instead.

 # cool now we can figure out lengths and what not.
 # we'll figure out the position and compare it to known positions (e.g. from primer3)
 
 my $left_location = length($before). ",". length($left_seq);
 my $right_location = (length($target_sequence)-length($after)-1).",".length($right_seq);
 my $amplicon_size = length($left_seq)+length($middle)+length($right_seq);
 
 if (exists $self->{'left_primer'}->{'PRIMER_LEFT'}) {
  # this is the left primer from primer3 input
  # just check to make sure it is right
  unless ($self->{'left_primer'}->{'PRIMER_LEFT'} eq $left_location) {
   $self->warn("Note got |".$self->{'left_primer'}->{'PRIMER_LEFT'}."| from primer3 and |$left_location| for the left primer. You should email redwards\@utmem.edu about this.");
  }
 }
 else {
  $self->{'left_primer'}->{'PRIMER_LEFT'}=$left_location;
 }
 
 if (exists $self->{'right_primer'}->{'PRIMER_RIGHT'}) {
  # this is the right primer from primer3 input
  # just check to make sure it is right
  unless ($self->{'right_primer'}->{'PRIMER_RIGHT'} eq $right_location) {
   $self->warn("Note got |".$self->{'right_primer'}->{'PRIMER_RIGHT'}."| from primer3 and |$right_location| for the right primer. You should email redwards\@utmem.edu about this.");
  }
 }
 else {
  $self->{'right_primer'}->{'PRIMER_RIGHT'}=$right_location;
 }
 
 if (exists $self->{'PRIMER_PRODUCT_SIZE'}) {
  # this is the product size from primer3 input
  # just check to make sure it is right
  unless ($self->{'PRIMER_PRODUCT_SIZE'} eq $amplicon_size) {
   $self->warn("Note got |".$self->{'PRIMER_PRODUCT_SIZE'}."| from primer3 and |$amplicon_size| for the size. You should email redwards\@utmem.edu about this.");
  }
 }
 else {
  $self->{'PRIMER_PRODUCT_SIZE'} = $amplicon_size;
 }
 
 $self->{'amplicon_sequence'}= lc($left_seq).uc($middle).lc($right_seq); # I put this in a different case, but I think the seqobj may revert this
 
 $self->_set_seqfeature;
}
_set_seqfeaturedescriptionprevnextTop
sub _set_seqfeature {
 my $self = shift;
 unless ($self->{'left_primer'}->{'PRIMER_LEFT'} && $self->{'right_primer'}->{'PRIMER_RIGHT'}) {
  $self->warn("hmmm. Haven't placed primers, but trying to make annotated sequence");
  return 0;
 }
 my ($start, $length) = split /,/, $self->{'left_primer'}->{'PRIMER_LEFT'};
 my $tm=$self->{'left_primer'}->{'PRIMER_LEFT_TM'} || $self->{'left_primer'}->Tm || 0;
 
 my $seqfeatureL=new Bio::SeqFeature::Generic(
   -start => $start, -end => $start+$length, -strand => 1,
   -primary_tag => 'left_primer', -source => 'primer3',
   -tag    => {new => 1, author => 'Bio::Seq::PrimedSeq', Tm => $tm}
    );
 
 ($start, $length) = split /,/, $self->{'right_primer'}->{'PRIMER_RIGHT'};
 $tm=$self->{'right_primer'}->{'PRIMER_RIGHT_TM'} || $self->{'right_primer'}->Tm || 0;
 
 my $seqfeatureR=new Bio::SeqFeature::Generic(
   -start => $start-$length, -end => $start, -strand => -1,
   -primary_tag => 'right_primer', -source => 'primer3',
   -tag    => {new => 1, author => 'Bio::Seq::PrimedSeq', Tm => $tm}
    );

 # now add the sequences to a annotated sequence
 $self->{annotated_sequence} = $self->{target_sequence};
 $self->{annotated_sequence}->add_SeqFeature($seqfeatureL);
 $self->{annotated_sequence}->add_SeqFeature($seqfeatureR);
}
General documentation
FEEDBACKTop
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 BugsTop
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://bugzilla.bioperl.org/
AUTHORTop
Rob Edwards, redwards@utmem.edu
Based on a module written by Chad Matsalla, bioinformatics1@dieselwurks.com
APPENDIXTop
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
get_primerTop
 Title   : get_primer();
 Usage   : $primer = $primedseq->get_primer(l, left, left_primer, -left_primer); to return the left primer
           or 
	   $primer = $primedseq->get_primer(r, right, right_primer, -right_primer); to return the right primer
	   or
	   $primer = $primedseq->get_primer(b, both, both_primers, -both_primers); to return the left primer, right primer array
 Function: A getter for the left primer in thie PrimedSeq object.
 Returns : A Bio::SeqFeature::Primer object
 Args    : Either of (l, left, left_primer, -left_primer) to get left primer.
           Either of (r, right, right_primer, -right_primer) to get right primer
	   Either of (b, both, both_primers, -both_primers) to get both primers. Note that this is plural.