BioPerlTutorial - a tutorial for bioperl

AUTHOR
Written by Peter Schattner <[email protected]>

DESCRIPTION
This tutorial includes "snippets" of code and text from various
Bioperl documents including module documentation, example scripts
and "t" test scripts. You may distribute this tutorial under the
same terms as perl itself.
This document is written in Perl POD (plain old documentation)
format. You can run this file through your favorite pod translator
(pod2html, pod2man, pod2text, etc.) if you would like a more
convenient formatting.

[email protected] May 17, 2003

I. Introduction ..........................................................................................................................................4
I. Introduction ..........................................................................................................................................4
I.4 Installation ...................................................................................................................................4
I.5 Additional comments for non-unix users ..........................................................................................4
I.6 Places to look for additional documentation......................................................................................5
II. Brief introduction to bioperl's objects......................................................................................................5
II.1 Sequence objects .........................................................................................................................5
II.2 Location objects ..........................................................................................................................6
II.4 Interface objects and implementation objects...................................................................................7
III. Using bioperl......................................................................................................................................7
III.1 Accessing sequence data from local and remote databases................................................................7
III.1.1 Accessing remote databases (Bio::DB::GenBank, etc)............................................................8
III.1.2 Indexing and accessing local databases (Bio::Index::*, bpindex.pl, ..........................................8
III.2 Transforming formats of database/ file records ...............................................................................9
III.2.1 Transforming sequence files (SeqIO)...................................................................................9
III.2.2 Transforming alignment files (AlignIO) ............................................................................. 10
III.3 Manipulating sequences ............................................................................................................ 11
III.3.1 Manipulating sequence data with Seq methods ................................................................... 11
III.3.2 Obtaining basic sequence statistics- molecular weights, residue &......................................... 13
III.3.3 Identifying restriction enzyme sites (RestrictionEnzyme) ..................................................... 13
III.3.4 Identifying amino acid cleavage sites (Sigcleave) ................................................................ 13
III.3.5 Miscellaneous sequence utilities: OddCodes, SeqPattern...................................................... 14
III.3.6 Sequence manipulation without creating Bioperl ``objects'' .................................................. 15
III.4 Searching for ``similar'' sequences .............................................................................................. 15
III.4.1 Running BLAST (using RemoteBlast.pm).......................................................................... 15
III.4.2 Parsing BLAST and FASTA reports with Search and SearchIO.................................................... 16
III.4.3 Parsing BLAST reports with BPlite, BPpsilite, and BPbl2seq ............................................... 17
III.4.4 Parsing HMM reports (HMMER::Results, SearchIO) ................................................................. 18
III.4.5 Running BLAST locally (StandAloneBlast)............................................................................... 18
III.6 Searching for genes and other structures on genomic DNA (Genscan,.............................................. 20
III.7 Developing machine readable sequence annotations ...................................................................... 21
III.7.1 Representing sequence annotations.................................................................................... 21
III.7.2 Representing and large and/or changing sequences.............................................................. 22
III.7.3 Representing related sequences - mutations, polymorphisms etc............................................ 23
III.7.4 Incorporating quality data in sequence annotation (SeqWithQuality)...................................... 24
III.7.5 Sequence XML representations - generation and parsing...................................................... 25
III.7.6 Representing Sequences using GFF (Bio:DB:GFF ) ............................................................ 25
III.8 Manipulating clusters of sequences (Cluster, ClusterIO) ................................................................ 26
III.9 Representing non-sequence data in Bioperl: structures, trees and maps ............................................ 26
III.9.3 Map objects for manipulating genetic maps (Map::MapI, MapIO)......................................... 27
III.9.5 Graphics objects for representing sequence objects as images ............................................... 27
III.10 Bioperl alphabets .................................................................................................................... 28
2
 III.10.1 Extended DNA / RNA alphabet ....................................................................................... 28
III.10.2 Amino Acid alphabet ..................................................................................................... 28
IV. Auxilliary Bioperl Libraries (Bioperl-run, Bioperl-db, etc.)..................................................................... 29
IV.1 Using the Bioperl Auxilliary Libraries ......................................................................................... 29
IV.2 Running programs (Bioperl-run, Bioperl-ext) ............................................................................... 30
IV.2.2 Aligning 2 sequences with Blast using bl2seq and AlignIO ................................................... 31
IV.2.3 Aligning multiple sequences (Clustalw.pm, TCoffee.pm)...................................................... 31
IV.3 bioperl-db ................................................................................................................................ 32
IV.4 Other Bioperl auxilliary libraries................................................................................................. 32
V Appendix ........................................................................................................................................... 33
V.1 Appendix: Finding out which methods are used by which Bioperl Objects......................................... 33
V.2 Appendix: Tutorial demo scripts................................................................................................... 33

3
I. Introduction

I.4 Installation

The actual installation of the various system components is accomplished in the standard manner:
Locate the package on the network
Download
Decompress (with gunzip or a similiar utility)
Remove the file archive (eg with tar -xvf)
Create a ``makefile'' (with ``perl Makefile.PL'' for perl modules or a supplied ``install'' or ``configure'' program for
non-perl program Run ``make'', ``make test'' and ``make install'' This procedure must be repeated for every CPAN
module, bioperl-extension and external module to be installed. A helper module CPAN.pm is available from
CPAN which automates the process for installing the perl modules. The CPAN module can also be used to install
all of the modules listed above in a single step as a ``bundle'' of modules, Bundle::BioPerl, eg
$>perl -MCPAN -e shell
cpan>install Bundle::BioPerl
<installation details....>
cpan>install B/BI/BIRNEY/bioperl-1.0.1.tar.gz
<installation details....>
cpan>quit
Be advised that version numbers change regularly, so the number used above may not apply. A disadvantage of the
``bundle'' approach is that if there's a problem installing any individual module it may be a bit more difficult to
isolate. See the package's INSTALL file for more details. For the external programs (clustal, Tcoffee, ncbi-blast),
there is an extra step:
Set the relevant environmental variable (CLUSTALDIR, TCOFFEEDIR or BLASTDIR) to the directory holding
the executable in your startup file - eg in .bashrc. (For running local blasts, it is also necessary that the name of
local-blast database directory is known to bioperl. This will typically happen automatically, but in case of
difficulty, refer to the documentation in the Bio::Tools::Run::StandAloneBlast manpage) The only likely
complication (at least on unix systems) that may occur is if you are unable to obtain system level writing
privileges. For instructions on modifying the installation in this case and for more details on the overall
installation procedure, see the INSTALL file in the bioperl distribution as well as the README files in the
external programs you want to use (eg bioperl-ext, clustalw, TCoffee, NCBI -blast).

I.5 Additional comments for non-unix users

Bioperl has mainly been developed and tested under various unix environments (including Linux and MacOSX).
In addition, this tutorial has been written largely from a Unix perspective. Mac users may find Steve Cannon's
installation notes and suggestions for Bioperl on OS X at
http://www.tc.umn.edu/~cann0010/Bioperl_OSX_install.html helpful. Also Todd Richmond has written of his
experiences with BioPerl on MacOS 9 at http://bioperl.org/Core/mac-bioperl.html The bioperl core has also
been tested and should work under most versions of Microsoft Windows. For many windows users the perl and
bioperl distributions from Active State, at http://www.activestate.com/ has been quite helpful. Other windows
users have had success running bioperl under Cygwin (http://www.cygwin.com). See the package's
4
INSTALL.WIN file for more details.
Many bioperl features require the use of CPAN modules, compiled extensions or external programs. These
features probably will not work under some or all of these other operating systems. If a script attempts to access
these features from a non-unix OS, bioperl is designed to simply report that the desired capability is not available.
However, since the testing of bioperl in these environments has been limited, the script may well crash in a less
``graceful'' manner.

I.6 Places to look for additional documentation

This tutorial does not intend to be a comprehensive description of all the objects and methods available in bioperl.
For that the reader is directed to the documentation included with each of the modules. A very useful
interface for finding one's way within all the module documentation can be found at
http://doc.bioperl.org/bioperl-live/ This interface lists all bioperl modules and descriptions of all of their methods.
In addition, beginner questions can often be answered by looking at the FAQ, INSTALL and README files in
the top-level directory of the bioperl distribution. One potential problem in locating the correct documentation is
that multiple methods in different modules may all share the same name. Moreover, because of perl's complex
method of ``inheritance'', it is not often clear which of the identically named methods is being called by a given
object. One way to resolve this question is by using the software described in Appendix V.1.
For those who prefer more visual descriptions, http://bioperl.org/Core/Latest/modules.html also offers links to
PDF files which contain schematics that describe how many of the bioperl objects related to one another. In
addition, a bioperl online course is available on the web at
http://www.pasteur.fr/recherche/unites/sis/formation/bioperl/ The user is also referred to numerous bioperl
scripts in the scripts/ and examples/ directories (see bioscripts.pod for a description of these scripts).

II. Brief introduction to bioperl's objects

The purpose of this tutorial is to get you using bioperl to solve real-life bioinformatics problems as quickly as
possible. The aim is not to explain the structure of bioperl objects or perl object-oriented programming in general.
Indeed, the relationships among the bioperl objects is not simple; however, understanding them in detail is
fortunately not necessary for successfully using the package. Nevertheless, a little familiarity with the bioperl
object ``bestiary'' can be very helpful even to the casual user of bioperl. For example there are (at least) eight
different ``sequence objects'' - Seq, PrimarySeq, LocatableSeq, RelSegment, LiveSeq, LargeSeq, SeqI, and
SeqWithQuality. Understanding the relationships among these objects - and why there are so many of them - will
help you select the appropriate one to use in your script.

II.1 Sequence objects

Seq is the central sequence object in bioperl. When in doubt this is probably the object that you want to use to
describe a DNA, RNA or protein sequence in bioperl. Most common sequence manipulations can be performed
with Seq. These capabilities are described in sections III.3.1 and III.7.1, or in the Bio::Seq manpage. Seq objects
can be created explicitly (see section III.2.1 for an example). However usually Seq objects will be created for you
automatically when you read ni a file containing sequence data using the SeqIO object. This procedure is
described in section III.2.1. In addition to storing its identification labels and the sequence itself, a Seq object can

5
store multiple annotations and associated ``sequence features''. This capability can be very useful - especially in
development of automated genome annotation systems, see section III.7.1. RichSeq objects store additional
annotations beyond those used by standard Seq objects. If you are using sources with very ric h sequence
annotation, you may want to consider using these objects which are described in section III.7.1. SeqWithQuality
objects are used to manipulate sequences with quality data, like those produced by phred. These objects are
described in section III.7.4, the Bio::Seq::RichSeqI manpage, and in the Bio::Seq::SeqWithQuality manpage. On
the other hand, if you need a script capable of simultaneously handling many (hundreds or thousands) sequences
at a time, then the overhead of adding annotations to each sequence can be significant. For such applications, you
will want to use the PrimarySeq object. PrimarySeq is basically a ``stripped down'' version of Seq. It contains just
the sequence data itself and a few identifying labels (id, accession number, molecule type = dna, rna, or protein).
For applications with hundreds or thousands or sequences, using PrimarySeq objects can significantly speed up
program execution and decrease the amount of RAM the program requires. See the Bio::PrimarySeq manpage for
more details. What is (for historical reasons) called a LocatableSeq object might be more appropriately called an
``AlignedSeq'' object. It is a Seq object which is part of a multiple sequence alignment. It has ``start'' and ``end''
positions indicating from where in a larger sequence it may have been extracted. It also may have ``gap'' symbols
corresponding to the alignment to which it belongs. It is used by the alignment object SimpleAlign and other
modules that use SimpleAlign objects (eg AlignIO.pm, pSW.pm). In general you don't have to worry about
creating LocatableSeq objects because they will be made for you automatically when you create an alignment
(using pSW, Clustalw, Tcoffee or bl2seq) or when you input an alignment data file using AlignIO. However if you
need to input a sequence alignment by hand (eg to build a SimpleAlign object), you will need to input the
sequences as LocatableSeqs. Other sources of information include the Bio::LocatableSeq manpage, the
Bio::SimpleAlign manpage, the Bio::AlignIO manpage, and the Bio::Tools::pSW manpage. The RelSegment
object is also a type of bioperl Seq object. RelSegment objects are useful when you want to be able to manipulate
the origin of the genomic coordinate system. This situation may occur when looking at a sub-sequence (e.g. an
exon) which is located on a longer underlying underlying sequence such as a chromosome or a contig. Such
manipulations may be important, for example when designing a graphical genome ``browaer''. If your code may
need such a capability, look at the documentation the Bio::DB::GFF::RelSegment manpage which describes this
feature in detail.
A LargeSeq object is a special type of Seq object used for handling very long ( eg > 100 MB) sequences. If you
need to manipulate such long sequences see section III.7.2 which describes LargeSeq objects, or the
Bio::Seq::LargeSeq manpage. A LiveSeq object is another specialized object for storing sequence data. LiveSeq
addresses the problem of features whose location on a sequence changes over time. This can happen, for example,
when sequence feature objects are used to store gene locations on newly sequenced genomes -
locations which can change as higher quality sequencing data becomes available. Although a LiveSeq object is not
implemented in the same way as a Seq object, LiveSeq does implement the SeqI interface (see below).
Consequently, most methods available for Seq objects will work fine with LiveSeq objects. Section III.7.2 and the
Bio::LiveSeq manpage contain further discussion of LiveSeq objects. SeqI objects are Seq ``interface objects'' (see
section II.4 and the Bio::SeqI manpage). They are used to ensure bioperl's compatibility with other software
packages. SeqI and other interface objects are not likely to be relevant to the casual bioperl user. *** Having
described these other types of sequence objects, the ``bottom line'' still is that if you store your sequence data in
Seq objects (which is where they'll be if you read them in with SeqIO), you will usually do just fine. ***

II.2 Location objects

A Location object is designed to be associated with a Sequence Feature object to indicate where on a larger

6
structure (eg a chromosome or contig) the feature can be found. The reason why this simple concept has evolved
into a collection of rather complicated objects is that: 1) Some objects have multiple locations or sub-locations
(e.g. a gene's exons may have multiple start and stop locations) 2) In unfinished genomes, the precise locations of
features is not known with certainty. Bioperl's various Location objects address these complications. In addition
there are ``CoordinatePolicy'' objects that allow the user to specify how to measure the ``length'' of a feature if its
precise start and end coordinates are not know. In most cases, you will not need to worry about these
complications if you are using bioperl to handle simple features with well-defined start and stop locations.
However, if you are using bioperl to annotate partially or unfinished genomes or to read annotations of such
genomes with bioperl, understanding the various Location objects will be important. See the documentation of the
various modules in the Bio::Locations directory or the Bio::Location::CoordinatePolicyI manpage for more
information.

II.4 Interface objects and implementation objects

One goal of the design of Bioperl is to separate interface and implementation objects. An interface is solely the
definition of what methods one can call on an object, without any knowledge of how it is implemented. An
implementation is an actual, working implementation of an object. In languages like Java, interface definition is
part of the language. In Perl, you have to roll your own. In bioperl, the interface objects usually have names like
Bio::MyObjectI, with the trailing I indicating it is an interface object. The interface objects mainly provide
documentation on what the interface is, and how to use it, without any implementations (though there are some
exceptions). Although interface objects are not of much direct utility to the casual bioperl user, being aware of
their existence is useful since they are the basis to understanding how bioperl programs can communicate with
other bioinformatics projects and computer languages such as Ensembl and biopython and biojava. For more
discussion of design and development issues please see the biodesign.pod file.

III. Using bioperl

Bioperl provides software modules for many of the typical tasks of bioinformatics programming. These include:
Accessing sequence data from local and remote databases
Transforming formats of database/ file records
Manipulating individual sequences
Searching for ``similar'' sequences
Creating and manipulating sequence alignments
Searching for genes and other structures on genomic DNA
Developing machine readable sequence annotations
The following sections describe how bioperl can help perform all of these
tasks.

III.1 Accessing sequence data from local and remote databases

Much of bioperl is focused on sequence manipulation. However, before bioperl can manipulate sequences, it
needs to have access to sequence data. Now one can directly enter data sequence data into a bioperl Seq object,
eg:

7
 $seq = Bio::Seq->new('-seq'=>'actgtggcgtcaact','-desc'=>'Sample Bio::Seq object',
'-display_id' => 'something', '-accession_number' => 'accnum',
'-alphabet' => 'dna' );
However, in most cases, it is preferable to access sequence data from some online data file or database (Note that
in common with conventional bioinformatics usage we will sometimes call a ``database'' what might be more
appropriately referred to as an ``indexed flat file''.) Bioperl supports accessing remote databases as well as
developing indices for setting up local databases.

III.1.1 Accessing remote databases (Bio::DB::GenBank, etc)

Accessing sequence data from the principal molecular biology databases is straightforward in bioperl. Data can be
accessed by means of the sequence's accession number or id. Batch mode access is also supported to facilitate the
efficient retrieval of multiple sequences. For retrieving data from genbank, for example, the code could be as
follows:
$gb = new Bio::DB::GenBank();
# this returns a Seq object :
$seq1 = $gb->get_Seq_by_id('MUSIGHBA1');
# this returns a Seq object :
$seq2 = $gb->get_Seq_by_acc('AF303112'))
# this returns a SeqIO object :
$seqio = $gb->get_Stream_by_id("J00522","AF303112","2981014");
Bioperl currently supports sequence data retrieval from the genbank, genpept, RefSeq, swissprot, and EMBL
databases. See the Bio::DB::GenBank manpage, the Bio::DB::GenPept manpage, the Bio::DB::SwissProt
manpage, the Bio::DB::RefSeq manpage and the Bio::DB::EMBL manpage for more information. A user can also
specify a different database mirror for a database - this is especially relevent for the SwissProt resource where
there are many ExPaSy mirrors. There are also configuration options for specifying local proxy servers for those
behind firewalls. The retrieval of NCBI RefSeqs sequences is supported through a special module called
Bio::DB::RefSeq which actually queries an EBI server. Please see the Bio::DB::RefSeq manpage before using it
as there are some caveats with RefSeq retrieval. RefSeq ids in Genbank begin with ``NT_'', ``NC_'',
``NG_'', ``NM_'', ``NP_'', ``XM_'' ``XR_'', or ``XP_'' (for more information see
http://www.ncbi.nlm.nih.gov/LocusLink/refseq.html). Bio::DB::GenBank can be used to retrieve entries
corresponding to these ids but bear in mind that these are not Genbank entries, strictly speaking. See the
Bio::DB::GenBank manpage for special details on retrieving entries beginning with ``NT_'', these are specially
formatted ``CONTIG'' entries. Bioperl also supports retrieval from a remote Ace database. This capability requires
the presence of the external AcePerl module. You need to download and install the aceperl module from
http://stein.cshl.org/AcePerl/ An additional module is available for accessing remote databases, BioFetch, which
queries the dbfetch script at EBI. The available databases are EMBL, GenBank, or SWALL, and the entries can be
retrieved in different formats as objects or streams (SeqIO objects), or as ``tempfiles''. See the Bio::DB::BioFetch
manpage for the details.

III.1.2 Indexing and accessing local databases (Bio::Index::*,

bpindex.pl,

bpfetch.pl, Bio::DB::*)
8
Alternately, bioperl permits indexing local sequence data files by means of the Bio::Index or Bio::DB::Fasta
objects. The following sequence data formats are supported by Bio::Index: genbank, swissprot, pfam, embl and
fasta. Once the set of sequences have been indexed using Bio::Index, individual sequences can be accessed using
syntax very similar to that described above for accessing remote databases. For example, if one wants to set up an
indexed flat-file database of fasta files, and later wants then to retrieve one file, one could write scripts like:
# script 1: create the index
use Bio::Index::Fasta; # using fasta file format
use strict; # some users have reported that this is necessary
my $Index_File_Name = shift;
my $inx = Bio::Index::Fasta->new(-filename => $Index_File_Name,-write_flag => 1);
$inx->make_index(@ARGV);
# script 2: retrieve some files
use Bio::Index::Fasta;
use strict; # some users have reported that this is necessary
my $Index_File_Name = shift;
my $inx = Bio::Index::Fasta->new($Index_File_Name);
foreach my $id (@ARGV) {
my $seq = $inx->fetch($id); # Returns Bio::Seq object
# do something with the sequence
}
To facilitate the creation and use of more complex or flexible indexing systems, the bioperl distribution includes
two sample scripts in the scripts/ directory, bpindex.pl and bpfetch.pl. These scripts can be used as templates to
develop customized local data-file indexing systems. Bioperl also supplies Bio::DB::Fasta as a means to index and
query Fasta format files. It's similar in spirit to Bio::Index::Fasta but offers more methods, eg
use Bio::DB::Fasta;
use strict;
my $db = Bio::DB::Fasta->new($file); # one file or many files
my $seqstring = $db->seq($id); # get a sequence as string
my $seqobj = $db->get_Seq_by_id($id); # get a PrimarySeq obj
my $desc = $db->header($id); # get the header, or description, line
This module also offers the user the ability to designate a specific string within the fasta header as the desired id,
such as the gi number within the string ``gi|4556644|gb|X45555'' (use the -makeid option for this capability). See
the Bio::DB::Fasta manpage for more information on this fully-featured module. The core bioperl installation does
not support accessing sequences stored in relational databases. However, such capabilility is available with the
auxilliary bioperl-db library. See section IV.3 for more information.

III.2 Transforming formats of database/ file records

III.2.1 Transforming sequence files (SeqIO)

A common - and tedious - bioinformatics task is that of converting sequence data among the many widely used
data formats. Bioperl's SeqIO object, however, makes this chore a breeze. SeqIO can read a stream of sequences -
located in a single or in multiple files - in a number of formats: Fasta, EMBL, GenBank, Swissprot, PIR, GCG,
SCF, phd/phred, Ace, fastq, or raw (plain sequence). Once the sequence data has been read in with SeqIO, it is
available to bioperl in the form of Seq objects. Moreover, the Seq objects can then be written to another file (again
9
using SeqIO) in any of the supported data formats making data converters simple to implement, for example:
use Bio::SeqIO;
$in = Bio::SeqIO->new('-file' => "inputfilename",'-format' => 'Fasta');
$out = Bio::SeqIO->new('-file' => ">outputfilename",'-format' => 'EMBL');
while ( my $seq = $in->next_seq() ) {$out->write_seq($seq); }
In addition, perl ``tied filehandle'' syntax is available to SeqIO, allowing you to use the standard <> and print
operations to read and write sequence objects, eg:
$in = Bio::SeqIO->newFh('-file' => "inputfilename" ,'-format' => 'Fasta');
$out = Bio::SeqIO->newFh('-format' => 'EMBL');
print $out $_ while <$in>;
If the ``-format'' argument isn't used then Bioperl will guess the format based on the file's suffix in a
case-insensitive manner. Here are the current interpretations:
Format Suffixes
fasta fasta|fast|seq|fa|fsa|nt|aa
genbank gb|gbank|genbank
scf scf
pir pir
embl embl|ebl|emb|dat
raw txt
gcg gcg
ace ace
bsml bsm|bsml
swiss swiss|sp
phd phd|phred
fastq fastq
For more information see the Bio::SeqIO manpage.

III.2.2 Transforming alignment files (AlignIO)

Data files storing multiple sequence alignments also appear in varied formats. AlignIO is the bioperl object for
data conversion of alignment files. AlignIO is patterned on the SeqIO object and shares most of SeqIO's features.
AlignIO currently supports input in the following formats:
fasta
mase (Seaview)
stockholm
prodom
selex (HMMER))
bl2seq
clustalw (.aln)
msf (GCG)
water*
phylip (interleaved)
stockholm
nexus
mega

10
 meme
psi (PSI-BLAST)
*used by EMBOSS, see IV.2.1
AlignIO supports output in these formats: fasta, mase, selex, clustalw, msf/gcg, and phylip (interleaved). One
significant difference between AlignIO and SeqIO is that AlignIO handles IO for only a single alignment at a time
but SeqIO.pm handles IO for multiple sequences in a single stream. Syntax for AlignIO is almost identical to that
of SeqIO:
use Bio::AlignIO;
$in = Bio::AlignIO->new('-file' => "inputfilename" ,'-format' => 'fasta');
$out = Bio::AlignIO->new('-file' => ">outputfilename",'-format' => 'pfam');
while ( my $aln = $in->next_aln() ) { $out->write_aln($aln); }
The only difference is that here, the returned object reference, $aln, is to a SimpleAlign object rather than a Seq
object. AlignIO also supports the tied filehandle syntax described above for SeqIO. See the Bio::AlignIO manpage
and section III.5 for more information.

III.3 Manipulating sequences

Bioperl contains many modules with functions for sequence analysis. And if you cannot find the function you
want in bioperl you may be able to find it in EMBOSS or PISE , which are accessible through the bioperl-run
auxilliary library (see IV.2.1).

III.3.1 Manipulating sequence data with Seq methods

OK, so we know how to retrieve sequences and access them as Seq objects. Let's see how we can use the Seq
objects to manipulate our sequence data and retrieve information. Seq provides multiple methods for performing
many common (and some not-so-common) tasks of sequence manipulation and data retrieval. Here are some of
the most useful: The following methods return strings
$seqobj->display_id(); # the human read-able id of the sequence
$seqobj->seq(); # string of sequence
$seqobj->subseq(5,10); # part of the sequence as a string
$seqobj->accession_number(); # when there, the accession number
$seqobj->alphabet(); # one of 'dna','rna','protein'
$seqobj->primary_id(); # a unique id for this sequence irregardless
# of its display_id or accession number
$seqobj->desc(); # a description of the sequence
It is worth mentioning that some of these values correspond to specific fields of given formats. For example, the
display_id method returns the LOCUS name of a Genbank entry, the (\S+) following the > character in a Fasta file,
the ID from a SwissProt file, and so on. The desc() method will return the DEFINITION line of a Genbank file,
the line following the display_id in a Fasta file, and the DE field in a SwissProt file. The following methods return
an array of Bio::SeqFeature objects
$seqobj->get_SeqFeatures; # The 'top level' sequence features
$seqobj->get_all_SeqFeatures; # All sequence features, including sub
# seq features
For a comment annotation, you can use:
use Bio::Annotation::Comment;
11
 $seq->annotation->add_Annotation('comment',
Bio::Annotation::Comment->new(-text => 'some description');
For a reference annotation, you can use: use Bio::Annotation::Reference;
$seq->annotation->add_Annotation('reference',
Bio::Annotation::Reference->new(-authors => 'author1,author2',
-title => 'title line', -location => 'location line', -medline => 998122);
Sequence features will be discussed further in section III.7 on machine-readable sequence annotation. A general
description of the object can be found in the Bio::SeqFeature::Generic manpage, and a description of related,
top-level ``annotation'' is found in the Bio::Annotation::Collection manpage. Additional sample code for obtaining
sequence features can be found in the script gb2features.pl in the subdirectory scripts/DB/. The following methods
returns new sequence objects, but do not transfer features across:
$seqobj->trunc(5,10); # truncation from 5 to 10 as new object
$seqobj->revcom; # reverse complements sequence
$seqobj->translate; # translation of the sequence
Note that some methods return strings, some return arrays and some return references to objects. See the Bio::Seq
manpage for more information. Many of these methods are self-explanatory. However, bioperl's flexible
translation methods warrant further comment. Translation in bioinformatics can mean two slightly different
things:
Translating a nucleotide sequence from start to end. Taking into account the constraints of real coding regions in
mRNAs. The bioperl implementation of sequence-translation does the first of these tasks easily. Any sequence
object which is not of type 'protein' can be translated by simply calling the method which returns a protein
sequence object:
$translation1 = $my_seq_object->translate;
However, the translate method can also be passed several optional parameters to modify its behavior. For example,
the first two arguments to ``translate'' can be used to modify the characters used to represent stop
(default '*') and unknown amino acid ('X'). (These are normally best left untouched.) The third argument
determines the frame of the translation. The default frame is ``0''. To get translations in the other two forward
frames, we would write:
$translation2 = $my_seq_object->translate(undef,undef,1);
$translation3 = $my_seq_object->translate(undef,undef,2);
The fourth argument to ``translate'' makes it possible to use alternative genetic codes. There are currently 16
codon tables defined, including tables for 'Verterbate Mitochondrial', 'Bacterial', 'Alternative Yeast Nuclear' and
'Ciliate, Dasycladacean and Hexamita Nuclear' translation. These tables are located in the object
Bio::Tools::CodonTable which is used by the translate method. For example, for mitochondrial translation:
$human_mitochondrial_translation =$my_seq_object->translate(undef,undef,undef, 2);
If we want to translate full coding regions (CDS) the way major nucleotide databanks EMBL, GenBank and
DDBJ do it, the translate method has to perform more tricks. Specifically, 'translate' needs to confirm that the
sequence has appropriate start and terminator codons at the beginning and the end of the sequence and that there
are no terminator codons present within the sequence. In addition, if the genetic code being used has an atypical
(non-ATG) start codon, the translate method needs to convert the initial amino acid to methionine. These checks
and conversions are triggered by setting the fifth argument of the translate method to evaluate to ``true''. If
argument 5 is set to true and the criteria for a proper CDS are not met, the method, by default, issues a warning.
By setting the sixth argument to evaluate to ``true'', one can instead instruct the program to die if an improper
CDS is found, e.g. $protein_object =$cds->translate(undef,undef,undef,undef,1,'die_if_errors');
See the Bio::Tools::CodonTable manpage for related details.

12
III.3.2 Obtaining basic sequence statistics- molecular weights, residue

&

codon frequencies(SeqStats, SeqWord)

In addition to the methods directly available in the Seq object, bioperl provides various ``helper'' objects to
determine additional information about a sequence. For example, SeqStats object provides methods for obtaining
the molecular weight of the sequence as well the number of occurrences of each of the component residues (bases
for a nucleic acid or amino acids for a protein.) For nucleic acids, SeqStats also returns counts of the number of
codons used. For example:
use SeqStats;
$seq_stats = Bio::Tools::SeqStats->new($seqobj);
$weight = $seq_stats->get_mol_wt();
$monomer_ref = $seq_stats->count_monomers();
$codon_ref = $seq_stats->count_codons(); # for nucleic acid sequence
Note: sometimes sequences will contain ``ambiguous'' codes. For this reason, get_mol_wt() returns (a reference to)
a two element array containing a greatest lower bound and a least upper bound of the molecular weight. The
SeqWords object is similar to SeqStats and provides methods for calculating frequencies of ``words'' (eg tetramers
or hexamers) within the sequence. See the Bio::Tools::SeqStats manpage and the Bio::Tools::SeqWords manpage
for more information.

III.3.3 Identifying restriction enzyme sites (RestrictionEnzyme)

Another common sequence manipulation task for nucleic acid sequences is locating restriction enzyme cutting
sites. Bioperl provides the RestrictionEnzyme object for this purpose. Bioperl's standard RestrictionEnzyme object
comes with data for more than 150 different restriction enzymes. A list of the available enzymes can be accessed
using the available_list() method. For example to select all available enzymes with cutting patterns that are six
bases long one would write:
$re = new Bio::Tools::RestrictionEnzyme('-name'=>'EcoRI');
@sixcutters = $re->available_list(6);
Once an appropriate enzyme has been selected, the sites for that enzyme on a given nucleic acid sequence can be
obtained using the cut_seq() method. The syntax for performing this task is:
$re1 = new Bio::Tools::RestrictionEnzyme(-name=>'EcoRI');
# $seqobj is the Seq object for the dna to be cut
@fragments = $re1->cut_seq($seqobj);
Adding an enzyme not in the default list is easily accomplished:
$re2 = new Bio::Tools::RestrictionEnzyme('-NAME' =>'EcoRV--GAT^ATC','-MAKE' =>'custom');
Once the custom enzyme object has been created, cut_seq() can be called in
the usual manner. See the Bio::Tools::RestrictionEnzyme manpage for
details.

III.3.4 Identifying amino acid cleavage sites (Sigcleave)

For amino acid sequences we may be interested to know whether the amino acid sequence contains a cleavable
13
signal sequence for directing the transport of the protein within the cell. SigCleave is a program (originally part of
the EGCG molecular biology package) to predict signal sequences, and to identify the cleavage site based on the
von Heijne algorithm. The ``threshold'' setting controls the score reporting. If no value for threshold is passed in
by the user, the code defaults to a reporting value of 3.5. SigCleave will only return score/position pairs which
meet the threshold limit. There are 2 accessor methods for this object. ``signals'' will return a perl hash containing
the sigcleave scores keyed by amino acid position. ``pretty_print'' returns a formatted string similar to the output
of the original sigcleave utility. The syntax for using Sigcleave is as follows:
# create a Seq object, for example:
$seqobj = Bio::Seq->new(-seq => "AALLHHHHHHGGGGPPRTTTTTVVVVVVVVVVVVVVV");
use Bio::Tools::Sigcleave;
$sigcleave_object = new Bio::Tools::Sigcleave( -seq => $seqobj,-threshold => 3.5,
-desc => 'test sigcleave protein seq',
-type=> 'AMINO'
);
%raw_results = $sigcleave_object->signals;
$formatted_output = $sigcleave_object->pretty_print;
Note that the ``type'' in the Sigcleave object is ``amino'' whereas in a Seq object it would be called ``protein''.
Please see the Bio::Tools::Sigcleave manpage for details.

III.3.5 Miscellaneous sequence utilities: OddCodes, SeqPattern

OddCodes:
For some purposes it's useful to have a listing of an amino acid sequence showing where the hydrophobic amino
acids are located or where the positively charged ones are. Bioperl provides this capability via the module
Bio::Tools::OddCodes. For example, to quickly see where the charged amino acids are located along the sequence
we perform:
use Bio::Tools::OddCodes;
$oddcode_obj = Bio::Tools::OddCodes->new($amino_obj);
$output = $oddcode_obj->charge();
The sequence will be transformed into a three-letter sequence (A,C,N) for negative (acidic), positive (basic), and
neutral amino acids. For example the ACDEFGH would become NNAANNC. For a more complete chemical
description of the sequence one can call the chemical() method which turns sequence into one with an 8-letter
chemical alphabet { A (acidic), L (aliphatic), M (amide), R (aromatic), C (basic), H (hydroxyl), I (imino), S
(sulfur) }: $output = $oddcode_obj->chemical();
In this case the sample sequence ACDEFGH would become LSAARAC. OddCodes also offers translation into
alphabets showing alternate characteristics of the amino acid sequence such as hydrophobicity, ``functionality'' or
grouping using Dayhoff's definitions. See the documentation in the Bio::Tools::OddCodes manpage for further
details. SeqPattern: The SeqPattern object is used to manipulate sequences that include perl ``regular expressions''.
A key motivation for SeqPattern is to have a way of generating a reverse complement of a nucleic acid sequence
pattern that includes ambiguous bases and/or regular expressions. This capability leads to significant performance
gains when pattern matching on both the sense and anti-sense strands of a query sequence are required. Typical
syntax for using SeqPattern is shown below. For more information, there are several interesting examples in the
script seq_pattern.pl in the scripts/tools directory.
Use Bio::Tools::SeqPattern;
$pattern = '(CCCCT)N{1,200}(agggg)N{1,200}(agggg)';

14
 $pattern_obj = new Bio::Tools::SeqPattern('-SEQ' => $pattern,'-TYPE' => 'dna');
$pattern_obj2 = $pattern_obj->revcom();
$pattern_obj->revcom(1); # returns expanded rev complement pattern.
More detail can be found in the Bio::Tools::SeqPattern manpage.

III.3.6 Sequence manipulation without creating Bioperl ``objects''

(Perl.pm)
Using the Bio::Perl.pm module, it is possible to manipulate sequence data in Bioperl without explicitly creating
Seq or SeqIO objects. This feature may ease the Bioperl learning curve for new users unfamiliar or uncomfortable
with using Perl objects. However, only limited data manipulation are supported in this mode. In addition, each
method (i.e. function) that will be used by the script must be explicitly declared in the initial ``use directive''. For
example a simple data format conversion and sequence manipulation could be performed as follows - note that no
``new'' methods are called and that no Seq or SeqIO objects are created:
use Bio::Perl qw( get_sequence );
# get a sequence from a database (assummes internet connection)
$seq_object = get_sequence('swissprot',"ROA1_HUMAN");
# $seq_object is Bio::Seq object, so the following methods work
$seq_id = $seq_object->display_id;
$seq_as_string = $seq_object->seq();
For more details see the Bio::Perl manpage and scripts/bioperl.pl.

III.4 Searching for ``similar'' sequences

One of the basic tasks in molecular biology is identifying sequences that are, in some way, similar to a sequence
of interest. The Blast programs, originally developed at the NCBI, are widely used for identifying such sequences.
The bioperl and bioperl-run packages offer a number of modules to facilitate running Blast as well as to parse the
often voluminous reports produced by Blast.

III.4.1 Running BLAST (using RemoteBlast.pm)

Bioperl supports remote execution of blasts at NCBI by means of the RemoteBlast object. A skeleton script to run
a remote blast might look as follows:
$remote_blast = Bio::Tools::Run::RemoteBlast->new(
'-prog' => 'blastp','-data' => 'ecoli','-expect' => '1e-10' );
$r = $remote_blast->submit_blast("t/data/ecolitst.fa");
while (@rids = $remote_blast->each_rid ) {
foreach $rid ( @rids ) {$rc = $remote_blast->retrieve_blast($rid);}}
You may want to change some parameter of the remote job and this example shows how to change the matrix:
$Bio::Tools::Run::RemoteBlast::HEADER{'MATRIX_NAME'} = 'BLOSUM25';
For a description of the many CGI parameters see: http://www.ncbi.nlm.nih.gov/BLAST/Doc/urlapi.html
Note that the script has to be broken into two parts. The actual Blast submission and the subsequent retrieval of
the results. At times when the NCBI Blast is being heavily used, the interval between when a Blast submission is
made and when the results are available can be substantial. The object $rc would contain the blast report that
15
could then be parsed with Bio::Tools::BPlite or Bio::SearchIO. The default object is BPlite in version 1.0 or
earlier and it's SearchIO after version 1.0. The object type can be changed using the -readmethod parameter but
bear in mind that the favored Blast parser is Bio::SearchIO, others won't be supported in later versions. Note that
to make this script actually useful, one should add details such as checking return codes from the Blast to see if it
succeeded and a ``sleep'' loop to wait between consecutive requests to the NCBI server. See example 25 in the
demonstration script in the appendix to see some working code you could use, or the
Bio::Tools::Run::RemoteBlast manpage for details. It should also be noted that the syntax for creating a remote
blast factory is slightly different from that used in creating StandAloneBlast, Clustalw, and T-Coffee factories.
Specifically RemoteBlast requires parameters to be passed with a leading hyphen, as in '-prog' => 'blastp', while
the other programs do not pass parameters with a leading hyphen.

III.4.2 Parsing BLAST and FASTA reports with Search and

SearchIO

No matter how Blast searches are run (locally or remotely, with or without a perl interface), they return large
quantities of data that are tedious to sift through. Bioperl offers several different objects - Search.pm/SearchIO.pm,
and BPlite.pm (along with its minor modifications, BPpsilite and BPbl2seq) for parsing Blast reports. Search and
SearchIO which are the principal Bioperl interfaces for Blast and FAST report parsing are described in this section.
The older BPlite is described in section III.4.3. We recommend you use SearchIO, it's certain to be supported in
future releases. The Search and SearchIO modules provide a uniform interface for parsing
sequence-similarity-search reports generated by BLAST (in standard and BLAST XML formats), PSI-BLAST,
RPS-BLAST and FASTA. The SearchIO modules also provide a parser for HMMER reports and in the future, it is
envisioned that the Search/SearchIO syntax will be extended to provide a uniform interface to an even wider
range of report parsers including parsers for Genscan. Parsing sequence-similarity reports with Search and
SearchIO is straightforward. Initially a SearchIO object specifies a file containing the report(s). The method
next_result reads the next report into a Search object in just the same way that the next_seq method of SeqIO
reads in the next sequence in a file into a Seq object. Once a report (i.e. a Search object) has been read in and is
available to the script, the report's overall attributes (e.g. the query) can be determined and its individual ``hits''
can be accessed with the next_hit method. Individual high-scoring-pairs for each hit can then be accessed with the
next_hsp method. Except for the additional syntax required to enable the reading of multiple reports in a single
file, the remainder of the Search/SearchIO parsing syntax is very similar to that of the BPlite object it is intended
to replace. Sample code to read a BLAST report might look like this:
# Get the report
$searchio = new Bio::SearchIO (-format => 'blast',
-file => $blast_report);
$result = $searchio->next_result;
# Get info about the entire report
$result->database_name;
$algorithm_type = $result->algorithm;
# get info about the first hit
$hit = $result->next_hit;
$hit_name = $hit->name ;
# get info about the first hsp of the first hit
$hsp = $hit->next_hsp;

16
 $hsp_start = $hsp->query->start;
For more details there is an excellent description of how to use SearchIO in the bioperl ``HOWTOs'' directory at
www.bioperl.org/HOWTOs/ or in the docs/ subdirectory of the distribution. Additional documentation can be
found in: the Bio::SearchIO::blast manpage, the Bio::SearchIO::psiblast manpage, the Bio::SearchIO::blastxml
manpage, the Bio::SearchIO::fasta manpage, and the Bio::SearchIO manpage. There is also sample code in the
Bio/scripts/searchio directory which illustrates how to use SearchIO.

III.4.3 Parsing BLAST reports with BPlite, BPpsilite, and BPbl2seq

Bioperl's older BLAST report parsers - BPlite, BPpsilite, BPbl2seq and Blast.pm - are expected to be phased out
over a period of time. Since a considerable amount of legacy Bioperl scripts has been written which heavily use
these objects, they are likely to remain within Bioperl for some time. Much of the user interface of BPlite is very
similar to that of Search. However accessing the next hit or HSP uses methods called next_Sbjct and next_HSP,
respectively - in contrast to Search's next_hit and next_hsp. BPlite The syntax for using BPlite is as follows where
the method for retrieving hits is now called ``nextSbjct'' (for ``subject''), while the method for retrieving
high-scoring-pairs is called ``nextHSP'':
use Bio::Tools::BPlite;
$report = new Bio::Tools::BPlite(-fh=>\*STDIN);
$report->query;
while(my $sbjct = $report->nextSbjct) {
$sbjct->name;
while (my $hsp = $sbjct->nextHSP) { $hsp->score; }
}
A complete description of the module can be found in the Bio::Tools::BPlite manpage.
BPpsilite
BPpsilite and BPbl2seq are objects for parsing (multiple iteration) PSIBLAST reports and Blast bl2seq reports,
respectively. They are both minor variations on the BPlite object. See the Bio::Tools::BPbl2seq manpage and the
Bio::Tools::BPpsilite manpage for details. The syntax for parsing a multiple iteration PSIBLAST report is as
shown below. The only significant additions to BPlite are methods to determine the number of iterated blasts and
to access the results from each iteration. The results from each iteration are parsed in the same manner as a
(complete) BPlite object.
use Bio::Tools::BPpsilite;
$report = new Bio::Tools::BPpsilite(-fh=>\*STDIN);
$total_iterations = $report->number_of_iterations;
$last_iteration = $report->round($total_iterations)
while(my $sbjct = $last_iteration ->nextSbjct) {
$sbjct->name;
while (my $hsp = $sbjct->nextHSP) {$hsp->score; }
}
See the Bio::Tools::BPpsilite manpage for details.
BPbl2seq
BLAST bl2seq is a program for comparing and aligning two sequences using BLAST. Although the report format
is similar to that of a conventional BLAST, there are a few differences. Consequently, the standard bioperl parser
BPlite ia unable to read bl2seq reports directly. From the user's perspective, one difference between bl2seq and
other blast reports is that the bl2seq report does not print out the name of the first of the two aligned sequences.

17
Consequently, BPbl2seq has no way of identifying the name of one of the initial sequence unless it is explicitly
passed to constructor as a second argument as in:
use Bio::Tools::BPbl2seq;
$report = Bio::Tools::BPbl2seq->new(-file => "t/data/dblseq.out",
-queryname => "ALEU_HORVU");
$hsp = $report->next_feature;
$answer=$hsp->score;
In addition, since there will only be (at most) one ``subject'' (hit) in a bl2seq report one should use the method
$report->next_feature, rather than $report->nextSbjct->nextHSP to obtain the next high scoring pair. See the
Bio::Tools::BPbl2seq manpage for more details. Blast.pm The Bio::Tools::Blast parser has been removed from
Bioperl as of version 1.1. Consequently, the BPlite parser (described in the section III.4.3) or the Search/SearchIO
parsers (section III.4.2) should be used for BLAST parsing within bioperl (SearchIO is the preferred approach and
will be formally supported in subsequent releases).

III.4.4 Parsing HMM reports (HMMER::Results, SearchIO)

Blast is not the only sequence-similarity-searching program supported by bioperl. HMMER is a Hidden Markov
Model (HMM) program that (among other capabilities) enables sequence similarity searching, from
http://hmmer.wustl.edu./ Bioperl does not currently provide a perl interface for running HMMER. However,
bioperl does provide 2 HMMER report parsers, the recommended SearchIO HMMER parser and an older parser
called HMMER::Results. SearchIO can parse reports generated both by the HMMER program hmmsearch -
which searches a sequence database for sequences similar to those generated by a given HMM - and the program
hmmpfam - which searches a HMM database for HMMs which match domains of a given sequence. Sample
usage for parsing a hmmsearch report might be:
use Bio::SearchIO;
$in = new Bio::SearchIO(-format => 'hmmer',-file => '123.hmmsearch');
while ( $res = $in->next_result ){
# get a Bio::Search::Result::HMMERResult object
print $res->query_name, " for HMM ", $res->hmm_name, "\n";
while ( $hit = $res->next_hit ){
print $hit->name, "\n";
while ( $hsp = $hit->next_hsp ){
print "length is ", $hsp->length, "\n";
}
}
}
Purists may insist that the term ``hsp'' is not applicable to hmmsearch or hmmpfam results and they may be correct
- this is an unintended consequence of using the flexible and extensible SearchIO approach. See the
Bio::Search::Result::HMMERResult manpage for more information. For documentation on the older HMMER
parser, look at the Bio::Tools::HMMER::Results manpage.

III.4.5 Running BLAST locally (StandAloneBlast)

There are several reasons why one might want to run the Blast programs locally - speed, data security, immunity
to network problems, being able to run large batch runs, wanting to use custom or proprietary databases, etc. The
18
NCBI provides a downloadable version of blast in a stand-alone format, and running blast locally without any use
of perl or bioperl is completely straightforward. However, there are situations where having a perl interface for
running the blast programs locally is convenient. The module Bio::Tools::Run::StandAloneBlast offers the ability
to wrap local calls to blast from within perl. All of the currently available options of NCBI Blast (eg PSIBLAST,
PHIBLAST, bl2seq) are available from within the bioperl StandAloneBlast interface. Of course, to use
StandAloneBlast, one needs to have installed locally ncbi-blast as well as one or more blast-readable databases.
Basic usage of the StandAloneBlast.pm module is simple. Initially, a local blast ``factory object'' is created.
@params = ('program' => 'blastn',
'database' => 'ecoli.nt');
$factory = Bio::Tools::Run::StandAloneBlast->new(@params);
Any parameters not explicitly set will remain as the BLAST defaults. Once the factory has been created and the
appropriate parameters set, one can call one of the supported blast executables. The input sequence(s) to these
executables may be fasta file(s), a Seq object or an array of Seq objects, eg
$input = Bio::Seq->new(-id =>"test query",-seq =>"ACTAAGTGGGGG");
$blast_report = $factory->blastall($input);
The returned blast report will be in the form of a bioperl parsed-blast object. The report object may be either a
BPlite, BPpsilite, BPbl2seq or Blast object depending on the type of blast search. The ``raw'' blast report is also
available. The syntax for running PHIBLAST, PSIBLAST and bl2seq searches via StandAloneBlast is also
straightforward. See the Bio::Tools::Run::StandAloneBlast manpage documentation for details. In addition, the
script standaloneblast.pl in the scripts/tools directory contains descriptions of various possible applications of the
StandAloneBlast object. This script shows how the blast report object can access a blast parser directly, eg
while (my $sbjct = $blast_report->next_hit){
while (my $hsp = $sbjct->next_hsp){
print $hsp->score . " " . $hsp->subject->seqname . "\n";
}
}
See the sections III.4.2 and III.4.3 on for more details on parsing BLAST reports. Also see the script
standaloneblast.pl in the scripts/tools/ subdirectory for more detailed working examples of code using this module.
III.5 Manipulating sequence alignments Once one has identified a set of similar sequences, one often needs to
create an alignment of those sequences. Bioperl offers several perl objects to facilitate sequence alignment: pSW,
Clustalw.pm, TCoffee.pm and the bl2seq option of StandAloneBlast. As of release 1.2 of bioperl, using these
modules (except bl2seq) requires a bioperl auxilliary library (bioperl-ext for pSW, bioperl-run for the others) and
are therefore described in section IV. Here we describe only the module within the bioperl core package for
manipulating previously created alignments, namely the SimpleAlign module. The script aligntutorial.pl in the
scripts/align/ subdirectory is another good source of information of ways to create and manipulate sequence
alignments within bioperl. SimpleAlign objects are produced by bioperl-run alignment creation objects (eg
Clustalw.pm, BLAST's bl2seq, and pSW) or they can be read in from files of multiple-sequence alignments in
various formats using AlignIO. Some of the manipulations possible with SimpleAlign include:
slice(): Obtaining an alignment ``slice'', that is, a subalignment inclusive of specified start and end columns.
Sequences with no residues in the slice are excluded from the new alignment and a warning is printed.
column_from_residue_number(): Finding column in an alignment where a specified residue of a specified
sequence is located.
consensus_string(): Making a consensus string. This method includes an optional threshold parameter, so that
positions in the alignment with lower percent-identity than the threshold are marked by ``?'''s in the consensus
percentage_identity(): A fast method for calculating the average percentage identity of the alignment
consensus_iupac(): Making a consensus using IUPAC ambiguity codes from DNA and RNA.
19
Skeleton code for using some of these features is shown below. More detailed, working code is in bptutorial.pl
example 13 and in align_on_codons.pl in the scripts directory. Additional documentation on methods can be found
in the Bio::SimpleAlign manpage and the Bio::LocatableSeq manpage.
use Bio::SimpleAlign;
$aln = Bio::SimpleAlign->new('t/data/testaln.dna');
$threshold_percent = 60;
$consensus_with_threshold = $aln->consensus_string($threshold_percent);
$iupac_consensus = $aln->consensus_iupac(); # dna/rna alignments only
$percent_ident = $aln->percentage_identity;
$seqname = '1433_LYCES';
$pos = $aln->column_from_residue_number($seqname, 14);

III.6 Searching for genes and other structures on genomic DNA

(Genscan,

Sim4, Grail, Genemark, ESTScan, MZEF, EPCR)

Automated searching for putative genes, coding sequences, sequence-tagged-sites (STS's) and other functional
units in genomic and expressed sequence tag (EST) data has become very important as the available quantity of
sequence data has rapidly increased. Many feature searching programs currently exist. Each produces reports
containing predictions that must be read manually or parsed by automated report readers. Parsers for six widely
used gene prediction programs - Genscan, Sim4, Genemark, Grail, ESTScan and MZEF - are available in bioperl.
The interfaces for these parsers are all similar. We illustrate the usage for Genscan and Sim4 here. The syntax is
relatively self-explanatory; see the Bio::Tools::Genscan manpage, the Bio::Tools::Genemark manpage, the
Bio::Tools::Grail manpage, the Bio::Tools::ESTScan manpage, the Bio::Tools::MZEF manpage, and the
Bio::Tools::Sim4::Results manpage for further details.
use Bio::Tools::Genscan;
$genscan = Bio::Tools::Genscan->new(-file => 'result.genscan');
# $gene is an instance of Bio::Tools::Prediction::Gene
# $gene->exons() returns an array of Bio::Tools::Prediction::Exon objects
while($gene = $genscan->next_prediction())
{ @exon_arr = $gene->exons(); }
$genscan->close();
See the Bio::Tools::Prediction::Gene manpage and the Bio::Tools::Prediction::Exon manpage for more details.
use Bio::Tools::Sim4::Results;
$sim4 = new Bio::Tools::Sim4::Results(-file => 't/data/sim4.rev',
-estisfirst => 0);
# $exonset is-a Bio::SeqFeature::Generic with Bio::Tools::Sim4::Exons
# as sub features
$exonset = $sim4->next_exonset;
@exons = $exonset->sub_SeqFeature();
# $exon is-a Bio::SeqFeature::FeaturePair
$exon = 1;
$exonstart = $exons[$exon]->start();
$estname = $exons[$exon]->est_hit()->seqname();

20
 $sim4->close();
See the Bio::SeqFeature::Generic manpage and the Bio::Tools::Sim4::Exons manpage for more information. A
parser for the ePCR program is also available. The ePCR program identifies potential PCR-based sequence tagged
sites (STSs) For more details see the documentation in the Bio::Tools::EPCR manpage. A sample skeleton script
for parsing an ePCR report and using the data to annotate a genomic sequence might look like this:
use Bio::Tools::EPCR;
use Bio::SeqIO;
$parser = new Bio::Tools::EPCR(-file => 'seq1.epcr');
$seqio = new Bio::SeqIO(-format => 'fasta', -file => 'seq1.fa');
$seq = $seqio->next_seq;
while( $feat = $parser->next_feature ) {
# add EPCR annotation to a sequence
$seq->add_SeqFeature($feat);}

III.7 Developing machine readable sequence annotations

Historically, annotations for sequence data have been entered and read manually in flat-file or relational databases
with relatively little concern for machine readability. More recent projects - such as EBI's Ensembl project and the
efforts to develop an XML molecular biology data specification - have begun to address this limitation. Because
of its strengths in text processing and regular-expression handling, perl is a natural choice for the computer
language to be used for this task. And bioperl offers numerous tools to facilitate this process - several of which are
described in the following sub-sections.

III.7.1 Representing sequence annotations

(Annotation::Collection,SeqFeature)
In Bioperl, most sequence annotations are stored in sequence-feature (SeqFeature) objects. A SeqFeature onject
generally has (at least) a description (e.g. exon, promoter) and a location specified in as its start postion and length
an a reference to the ``parent'' sequence of which it is a feature. In addition, A Seq object can also have an
Annotation object (used to store database links, literature references and comments) associated with it. Creating a
new SeqFeature and Annotation and associating it with a Seq is accomplished with syntax like:
$feat = new Bio::SeqFeature::Generic('-start' => 40,
'-end' => 80,
'-strand' => 1,
'-primary' => 'exon',
'-source' => 'internal' );
$seqobj->add_SeqFeature($feat); # Add the SeqFeature to the parent
$annotations = $seqobj->annotation(new Bio::Annotation::Collection);
$annotations->add_Annotation('disease', $object);
Once the features and annotations have been associated with the Seq, they can be with retrieved, eg:
@topfeatures = $seqobj->top_SeqFeatures(); # just top level, or
@allfeatures = $seqobj->all_SeqFeatures(); # descend into sub features
$disease_annotation = $annotations->get_Annotations('disease');
The individual components of a SeqFeature can also be set or retrieved with methods including:
# attributes which return numbers
21
 $feat->start # start position
$feat->end # end position
$feat->strand # 1 means forward, -1 reverse, 0 not relevant
# attributes which return strings
$feat->primary_tag # the main 'name' of the sequence feature,
# eg, 'exon'
$feat->source_tag # where the feature comes from, eg'BLAST'
# attributes which return Bio::PrimarySeq objects
$feat->seq # the sequence between start,end
$feat->entire_seq # the entire sequence
# other useful methods include
$feat->overlap($other) # do SeqFeature $feat and SeqFeature $other overlap?
$feat->contains($other) # is $other completely within $feat?
$feat->equals($other) # do $feat and $other completely agree?
$feat->sub_SeqFeatures # create/access an array of subsequence features
See the Bio::Annotation::Collection manpage and the Bio::SeqFeature::Generic manpage as starting points for
further exploration, and see the scripts/tools/gff2ps.pl and scripts/tools/gb_to_gff.pl scripts. It is worth mentioning
that one can also retrieve the start and end positions of a feature using a Bio::LocationI object:
$location = $feat->location # $location is a Bio::LocationI object
$location->start; # start position
$location->end; # end position
This is useful because one needs a Bio::Location::SplitLocationI object in order to retrieve the split coordinates
inside the Genbank or EMBL join() statements (e.g. ``CDS join(51..142,273..495,1346..1474)''):
if ( $feat->location->isa('Bio::Location::SplitLocationI') &&
$feat->primary_tag eq 'CDS' ) {
foreach $loc ( $feat->location->sub_Location ) {
print $loc->start . ".." . $loc->end . "\n";
}
}
See the Bio::LocationI manpage and the Bio::Location::SplitLocationI manpage for more information. If more
detailed annotation is required than is currently available in Seq objects the RichSeq object may be used. It is
applicable in particular to database sequences (EMBL, GenBank and Swissprot) with detailed annotations.
Sample usage might be:
@secondary = $richseq->get_secondary_accessions;
$division = $richseq->division;
@dates = $richseq->get_dates;
$seq_version = $richseq->seq_version;
See the Bio::Seq::RichSeqI manpage for more details.

III.7.2 Representing and large and/or changing sequences

(LiveSeq,LargeSeq)
Very large sequences and/or data files with sequences that are frequently being updated present special problems
to automated sequence-annotation storage and retrieval projects. Bioperl's LargeSeq and LiveSeq objects are
designed to address these two situations.

22
LargeSeq A LargeSeq object is a SeqI compliant object that stores a sequence as a series of files in a temporary
directory (see sect II.1 or the Bio::SeqI manpage for a definition of SeqI objects). The aim is to enable storing
very large sequences (eg, > 100MBases) without running out of memory and, at the same time, preserving the
familiar bioperl Seq object interface. As a result, from the users perspective, using a LargeSeq object is almost
identical to using a Seq object. The principal difference is in the format used in the SeqIO calls. Another
difference is that the user must remember to only read in small chunks of the sequence at one time. These
differences are illustrated in the following code:
$seqio = new Bio::SeqIO('-format'=>'largefasta',
'-file' =>'t/data/genomic-seq.fasta');
$pseq = $seqio->next_seq();
$plength = $pseq->length();
$last_4 = $pseq->subseq($plength-3,$plength); # this is OK
# On the other hand, the next statement would
# probably cause the machine to run out of memory
# $lots_of_data = $pseq->seq(); # NOT OK for a large LargeSeq object
LiveSeq The LiveSeq object addresses the need for a sequence object capable of handling sequence data that may
be changing over time. In such a sequence, the precise locations of features along the sequence may change.
LiveSeq deals with this issue by re-implementing the sequence object internally as a ``double linked chain.'' Each
element of the chain is connected to other two elements (the PREVious and the NEXT one). There is no absolute
position (like in an array), hence if positions are important, they need to be computed (methods are provided).
Otherwise it's easy to keep track of the elements with their ``LABELs''. There is one LABEL (think of it as a
pointer) to each ELEMENT. The labels won't change after insertions or deletions of the chain. So it's always
possible to retrieve an element even if the chain has been modified by successive insertions or deletions. Although
the implementation of the LiveSeq object is novel, its bioper l user interface is unchanged since LiveSeq
implements a PrimarySeqI interface (recall PrimarySeq is the subset of Seq without annotations or SeqFeatures -
see section II.1 or the Bio::PrimarySeq manpage). Consequently syntax for using LiveSeq objects is familiar
although a modified version of SeqIO called Bio::LiveSeq::IO::Bioperl needs to be used to actually load the data,
eg:
$loader=Bio::LiveSeq::IO::BioPerl->load('-db'=>"EMBL",
'-file'=>"t/data/factor7.embl");
$gene=$loader->gene2liveseq('-gene_name' => "factor7");
$id = $gene->get_DNA->display_id ;
$maxstart = $gene->maxtranscript->start;
See the Bio::LiveSeq::IO::BioPerl manpage for more details.

III.7.3 Representing related sequences - mutations, polymorphisms etc

(Allele, SeqDiff)
A Mutation object allows for a basic description of a sequence change in the DNA sequence of a gene. The
Mutator object takes in mutations, applies them to a LiveSeq gene and returns a set of Bio::Variation objects
describing the net effect of the mutation on the gene at the DNA, RNA and protein level. The objects in
Bio::Variation and Bio::LiveSeq directory were originally designed for the ``Computational Mutation Expression
Toolkit'' project at European Bioinformatics Institute (EBI). The result of using them to mutate a gene is a holder
object, 'SeqDiff', that can be printed out or queried for specific information. For example, to find out if restriction
enzyme changes caused by a mutation are exactly the same in DNA and RNA sequences, we can write:

23
 use Bio::LiveSeq::IO::BioPerl;
use Bio::LiveSeq::Mutator;
use Bio::LiveSeq::Mutation;
$loader = Bio::LiveSeq::IO::BioPerl->load('-file' => "$filename");
$gene = $loader->gene2liveseq('-gene_name' => $gene_name);
$mutation = new Bio::LiveSeq::Mutation ('-seq' =>'G',
'-pos' => 100 );
$mutate = Bio::LiveSeq::Mutator->new('-gene' => $gene,
'-numbering' => "coding" );
$mutate->add_Mutation($mutation);
$seqdiff = $mutate->change_gene();
$DNA_re_changes = $seqdiff->DNAMutation->restriction_changes;
$RNA_re_changes = $seqdiff->RNAChange->restriction_changes;
$DNA_re_changes eq $RNA_re_changes or print "Different!\n";
For a complete working script, see the change_gene.pl script in the scripts/liveseq directory. For more details on
the use of these objects see the Bio::LiveSeq::Mutator manpage and the Bio::LiveSeq::Mutation manpage as well
as the original documentation for the ``Computational Mutation Expression Toolkit'' project at
http://www.ebi.ac.uk/mutations/toolkit/

III.7.4 Incorporating quality data in sequence annotation

(SeqWithQuality)

SeqWithQuality objects are used to describe sequences with very specific annotations - that is, data quality
annotations. Data quality information is important for documenting the reliability of base ``calls'' in newly
sequenced or otherwise questionable sequence data. The quality data is contained within a Bio::Seq::PrimaryQual
object. Syntax for using SeqWithQuality objects is as follows:
# first, make a PrimarySeq object
$seqobj = Bio::PrimarySeq->new
( -seq => 'atcgatcg', -id => 'GeneFragment-12',
-accession_number => 'X78121', -alphabet => 'dna');
# now make a PrimaryQual object
$qualobj = Bio::Seq::PrimaryQual->new
( -qual => '10 20 30 40 50 50 20 10', -id => 'GeneFragment-12',
-accession_number => 'X78121', -alphabet => 'dna');
# now make the SeqWithQuality object
$swqobj = Bio::Seq::SeqQithQuality->new
( -seq => $seqobj, -qual => $qualobj);
# Now we access the sequence with quality object
$swqobj->id(); # the id of the SeqWithQuality object may not match the
# id of the sequence or of the quality
$swqobj->seq(); # the sequence of the SeqWithQuality object
$swqobj->qual(); # the quality of the SeqWithQuality object
A SeqWithQuality object is created automatic ally when phred output, a *phd file, is read by SeqIO, eg
$seqio = Bio::SeqIO->new(-file=>"my.phd",-format=>"phd");

24
 # or just 'Bio::SeqIO->new(-file=>"my.phd")'
$seqWithQualObj = $seqio->next_seq;
See the Bio::Seq::SeqWithQuality manpage for a detailed description of the methods, the Bio::Seq::PrimaryQual
manpage, and the Bio::SeqIO::phd manpage.

III.7.5 Sequence XML representations - generation and parsing

(SeqIO::game, SeqIO::bsml)
The previous subsections have described tools for automated sequence annotation by the creation of an ``object
layer'' on top of a traditional database structure. XML takes a somewhat different approach. In XML, the data
structure is unmodified, but machine readability is facilitated by using a data-record syntax with special flags and
controlled vocabulary. In order to transfer data with XML in biology, one needs an agreed upon ``vocabulary'' of
biological terms. Several of these have been proposed and bioperl has at least some support for three: ``game'',
BSML and AGAVE. Once a vocabulary is agreed upon, it becomes possible to convert sequence XML sequence
features can be turned into bioperl Seq annotations and SeqFeature objects. Conversely Seq object features and
annotations can be converted to XML so that they become available to any other systems. Typical usage with
``game'' or ``BSML'' are shown below. No special syntax is required by the user. Note that some Seq annotation
will be lost when using XML in this manner since generally XML does not support all the annotation information
available in Seq objects.
$str = Bio::SeqIO->new('-file'=> 't/data/test.game','-format' => 'game');
$seq = $str->next_primary_seq();
$id = $seq->id;
@feats = $seq->all_SeqFeatures();
$first_primary_tag = $feats[0]->primary_tag;
$str = Bio::SeqIO->new('-file'=> 'bsmlfile.xml',
'-format' => 'bsml');
$seq = $str->next_primary_seq();
$id = $seq->id;
@feats = $seq->all_SeqFeatures();
$first_primary_tag = $feats[0]->primary_tag;

III.7.6 Representing Sequences using GFF (Bio:DB:GFF )

Another format for transmitting machine-readable sequence-feature data is the Genome Feature Format (GFF).
This file type is well suited to sequence annotation because it allows the ability to describe entries in terms of
parent-child relationships (see http://www.sanger.ac.uk/software/GFF for details). Bioperl includes a parser for
converting between GFF files and SeqFeature objects. Typical syntax looks like:
$gffio = Bio::Tools::GFF->new(-fh => \*STDIN, -gff_version => 2);
$feature;# loop over the input stream
while($feature = $gffio->next_feature()) {
# do something with feature
}
$gffio->close();
Further information can be found at the Bio::Tools::GFF manpage. Also see the scripts/tools/gff2ps.pl and
scripts/tools/gb_to_gff.pl scripts. (Note: this module shouldn\'t be confused with the module Bio::DB::GFF which
25
is for implementing relational databases when using bioperl-db.)

III.8 Manipulating clusters of sequences (Cluster, ClusterIO)

Sequence alignments are not the only examples in which one might want to manipulate a group of sequences
together. Such groups of related sequences are generally referred to as clusters. Examples include Unigene
clusters and gene clusters resulting from clustering algorithms being applied to microarray data. The bioperl
Cluster and ClusterIO modules are available for handling sequence clusters. Currently, cluster input/output
modules are available only for Unigene clusters. To read in a Unigene cluster (in the NCBI XML format) and then
extract individual sequences for the cluster for manipulation might look like this:
$stream = Bio::ClusterIO->new('-file' => "Hs.data", -' format' => "unigene");
# note: we quote -format to keep older perl's from complaining.
while ( my $in = $stream->next_cluster() ) {
print $in->unigene_id() . "\n";
while ( my $sequence = $in->next_seq() ) {
print $sequence->accession_number() . "\n";
}
}
See the Bio::Cluster::UniGene manpage for more details.

III.9 Representing non-sequence data in Bioperl: structures,

trees and maps

Though bioperl has its roots in describing and searching nucleotide and protein sequences it has also branched out
into related fields of study, such as protein structure, phylogenetic trees and genetic maps. III.9.1 Using 3D
structure objects and reading PDB files (StructureI, Structure::IO) A StructureIO object can be created from one or
more 3D structures represented in Protein Data Bank, or pdb, format (see http://www.rcsb.org/pdb for details).
StructureIO objects allow access to a variety of related Bio:Structure objects. An Entry object consist of one or
more Model objects, which in turn consist of one or more Chain objects. A Chain is composed of Residue objects,
which in turn consist of Atom objects. There's a wealth of methods, here are just a few:
$structio = Bio::Structure::IO->new( -file => "1XYZ.pdb");
$struc = $structio->next_structure; # returns an Entry object
$pseq = $struc->seqres; # returns a PrimarySeq object, thus
$pseq->subseq(1,20); # returns a sequence string
@atoms = $struc->get_atoms($res); # Atom objects, given a Residue
@xyz = $atom->xyz; # the 3D coordinates of the atom
These lines show how one has access to a number of related objects and methods. For examples of typical usage
of these modules, see the scripts in the scripts/structure subdirectory. Also see the Bio::Structure::IO manpage, the
Bio::Structure::Entry manpage, the Bio::Structure::Model manpage, the Bio::Structure::Chain manpage, the
Bio::Structure::Residue manpage, and the Bio::Structure::Atom manpage for more information. III.9.2 Tree
objects and phylogenetic trees (Tree::Tree, TreeIO, PAML) Bioperl Tree objects can store data for all kinds of
computer trees and are intended especially for phylogenetic trees. Nodes and branches of trees can be individually
manipulated. The TreeIO object is used for stream I/O of tree objects. Currently only phylip/newick tree format is
supported. Sample code might be:
26
 $treeio = new Bio::TreeIO( -format => 'newick', -file => $treefile);
$tree = $treeio->next_tree; # get the tree
@nodes = $tree->get_nodes; # get all the nodes
$tree->get_root_node()->each_Descendent(); # get descendents of root node
See the Bio::TreeIO manpage and the Bio ::Tree::Tree manpage for details. Using the Bio::Tools::Phylo::PAML
module one can also parse the results of the PAML tree-building programs codeml, baseml, basemlg, codemlsites
and yn00. See the Bio::Tools::Phylo::PAML manpage for details.

III.9.3 Map objects for manipulating genetic maps (Map::MapI,

MapIO)

Bioperl map objects can be used to describe any type of biological map data including genetic maps, STS maps
etc. Map I/O is performed with the MapIO object which works in a similar manner to the SeqIO, SearchIO and
similar I/O objects described previously. In principle, Map I/O with various map data formats can be performed.
However currently only ``mapmaker'' format is supported. Manipulation of genetic map data with Bioperl Map
objects might look like this:
$mapio = new Bio::MapIO( '-format' => 'mapmaker', '-file' => $mapfile);
$map = $mapio->next_map; # get a map
$maptype = $map->type ;
foreach $marker ( $map->each_element ) {
$marker_name = $marker->name ; # get the name of each map marker
}
See the Bio::MapIO manpage and the Bio::Map::SimpleMap manpage for more information.
III.9.4 Bibliographic objects for querying bibliographic databases
(Biblio)
Bio::Biblio objects are used to query bibliographic databases, such as MEDLINE. The associated modules are
built to work with OpenBQS-compatible databases (see http://industry.ebi.ac.uk/openBQS). A Bio::Biblio object
can execute a query like:
my $collection = $biblio->find ('brazma', 'authors');
while ( $collection->has_next ) {
print $collection->get_next;
}
See the Bio::Biblio manpage or the scripts/biblio/biblio.pl script for details.

III.9.5 Graphics objects for representing sequence objects as images

(Graphics)
A user may want to represent Seq objects and their SeqFeatures graphically. The Bio::Graphics::* modules use
Perl's GD.pm module to create a PNG or GIF image given the SeqFeatures (Section III.7.1) contained within a
Seq object. These modules contain numerous methods to dictate the sizes, colors, labels, and line formats within
the image. For information see the excellent Graphics-HOWTO at www.bioperl.org/HOWTOs/ or in the
docs/howto subdirectory. Additional documentation can be found at the Bio::Graphics manpage, the
Bio::Graphics::Panel manpage, and in the scripts/graphics/render_sequence.pl script.

27
III.10 Bioperl alphabets

Bioperl modules use the standard extended single-letter genetic alphabets to represent nucleotide and amino acid
sequences. In addition to the standard alphabet, the following symbols are also acceptable in a biosequence:
? (a missing nucleotide or amino acid)
- (gap in sequence)

III.10.1 Extended DNA / RNA alphabet

(includes symbols for nucleotide ambiguity)

------------------------------------------
Symbol Meaning Nucleic Acid
------------------------------------------
A A Adenine
C C Cytosine
G G Guanine
T T Thymine
U U Uracil
M A or C
R A or G
W A or T
S C or G
Y C or T
K G or T
V A or C or G
H A or C or T
D A or G or T
B C or G or T
X G or A or T or C
N G or A or T or C
IUPAC-IUB SYMBOLS FOR NUCLEOTIDE NOMENCLATURE:Cornish-Bowden (1985) Nucl. Acids Res. 13:
3021-3030.

III.10.2 Amino Acid alphabet

------------------------------------------
Symbol Meaning
------------------------------------------
A Alanine
B Aspartic Acid, Asparagine
C Cystine
D Aspartic Acid
E Glutamic Acid
F Phenylalanine
28
G Glycine
H Histidine
I Isoleucine
K Lysine
L Leucine
M Methionine
N Asparagine
P Proline
Q Glutamine
R Arginine
S Serine
T Threonine
V Valine
W Tryptophan
X Unknown
Y Tyrosine
Z Glutamic Acid, Glutamine
* Terminator
IUPAC-IUP AMINO ACID SYMBOLS:Biochem J. 1984 Apr 15; 219(2): 345-373Eur J Biochem. 1993 Apr 1;
213(1): 2

IV. Auxilliary Bioperl Libraries (Bioperl-run,

Bioperl-db, etc.)

IV.1 Using the Bioperl Auxilliary Libraries

Beyond the bioperl ``core'' distribution which you get with the ``minimal'' installation, bioperl contains numerous
other modules in so-called auxilliary libraries. These auxilliary libraries include bioperl-run, bioperl-db,
bioperl-pipeline, bioperl-microarray and bioperl-ext among others. Generally, modules are placed in an auxilliary
library if either: the module requires the installation of additional non-standard external programs or modules, or
the module is perceived to be of interest to only a small percentage of the bioinformatics community However
there are exceptions and it is not always obvious whether a given module will be found in the ``core'' or in an
auxiliary library. At present, modules in the auxilliary packages can be obtained only by means of the CVS system.
To browse through the auxilliary libraries and to obtain the download files, go to:
http://cvs.bioperl.org/cgi-bin/viewcvs/viewcvs.cgi/?cvsroot=bioperl Generally CVS packages are not as well
tested as the released core library. Consequently after downloading and running:
$ perl Makefile.PL
and
$ make
one should always run:
$make test

29
before using the packages. Even if "make test" runs successfully. It may be safer to _not_ run "make install" and
instead to include the library with the auxilliary modules (say in /home/peter/auxmodules) by adding this line to
each of your scripts:
use lib '/home/peter/auxmodules';
or by adding a ``switch'' to your invocation of perl on the command line, e,g,:
$perl -I/home/peter/auxmodules myscript.pl
Once the auxiliary library has been installed in this manner, the modules can be used in exactly the same manner
as if they were in the bioperl core.

IV.2 Running programs (Bioperl-run, Bioperl-ext)

It possible to run various external (to Bioperl) sequence alignment and sequence manipulation programs via a perl
interface using bioperl. However in most cases this requires having the bioperl-run auxilliary library (some cases
may require bioperl-ext). Prior to bioperl release 1.2, many of these features were available within the bioperl
``core'' release. However currently some of the required modules have been transferred out of the core library.
Some of the more commonly used of these modules are described in this section. IV.2.1 Sequence manipulation
using the Bioperl EMBOSS and PISE interfaces EMBOSS (European Molecular Biology Open Source Software)
is an extensive collection of sequence analysis programs written in the C programming language, from
http://www.uk.embnet.org/Software/EMBOSS. There are a number of algorithms in EMBOSS that are not found
in ``Bioperl proper'' (eg. calculating DNA melting temperature, finding repeats, identifying prospective antigenic
sites) so if you cannot find the function you want in bioperl you might be able to find it in EMBOSS. EMBOSS
programs are usually called from the command line but the bioperl-run auxilliary library provides a Perl
``wrapper'' for EMBOSS function calls so that they can be executed from within a Perl script. Of course, the
EMBOSS package as well as the bioperl-run must be installed for the Bioperl wrapper to function. In the future, it
is planned that Bioperl EMBOSS objects will return appropriate Bioperl objects to the calling script in addition to
generating standard EMBOSS reports. This functionality is being initially implemented with the EMBOSS
sequence alignment programs, so that they will return SimpleAlign objects in a manner similar to the way the
Bioperl-run modules TCoffee.pm and Clustalw.pm work (see section III.5 for a discussion of SimpleAlign). An
example of the Bioperl EMBOSS wrapper where a file is returned would be:
$factory = new Bio::Factory::EMBOSS;
$compseqapp = $factory->program('compseq');
%input = ( -word => 4,
-sequence => $seqObj,
-outfile => $compseqoutfile );
$compseqapp->run(\%input);
$seqio = Bio::SeqIO->new( -file => $compseqoutfile ); # etc...
Note that a Seq object was used as input. The EMBOSS object can also accept a file name as input, eg
-sequence => "inputfasta.fa"
Some EMBOSS programs will return strings, others will create files that can be read directly using Bio::SeqIO
(section III.2.1), as in the example above. It's worth mentioning that as another way to align sequences with
bioperl one can run the Smith-Waterman algorithm in the EMBOSS program 'water'. This can produce an output
file that bioperl can read in with the AlignIO system
use Bio::AlignIO;
my $in = new Bio::AlignIO(-format => 'emboss', -file => 'filename');
my $aln = $in->next_aln();

30
The Pise interface is another approach to extending Bioperl's sequence manipulation capabilities by using standard
bioinformatics programs. To use EMBOSS programs within Bioperl you need to have EMBOSS locally installed
(in addition to having the auxiliary bioperl-run library installed). In contrast, with Pise you only need install
bioperl-run, since you run the actual analysis programs over the internet at the Pise site. Advantages of Pise
include not having to load additional programs locally and having access to a wider library of programs (Pise
includes EMBOSS and many other programs as well.) Howerver Pise has the disadvantages of needing an internet
connection, lower performance, decreased security, etc. stemming form running programs over the net. For more
information on the Bioperl Pise interface see: http://www-alt.pasteur.fr/~letondal/Pise/

IV.2.2 Aligning 2 sequences with Blast using bl2seq and AlignIO

As an alternative to Smith-Waterman, two sequences can also be aligned in Bioperl using the bl2seq option of
Blast within the StandAloneBlast object. To get an alignment - in the form of a SimpleAlign object - using bl2seq,
you need to parse the bl2seq report with the Bio::AlignIO file format reader as follows:
$factory = Bio::Tools::Run::StandAloneBlast->new('outfile' => 'bl2seq.out');
$bl2seq_report = $factory->bl2seq($seq1, $seq2);
# Use AlignIO.pm to create a SimpleAlign object from the bl2seq report
$str = Bio::AlignIO->new('-file '=>'bl2seq.out','-format' => 'bl2seq');
$aln = $str->next_aln();

IV.2.3 Aligning multiple sequences (Clustalw.pm, TCoffee.pm)

For aligning multiple sequences (ie two or more), bioperl offers a perl interface to the bioinformatics-standard
clustalw and tcoffee programs. Clustalw has been a leading program in global multiple sequence alignment (MSA)
for several years. TCoffee is a relatively recent program - derived from clustalw - which has been shown to
produce better results for local MSA. To use these capabilities, the clustalw and/or tcoffee programs themselves
need to be installed on the host system. In addition, the environmental variables CLUSTALDIR and
TCOFFEEDIR need to be set to the directories containg the executables. See section I.4 and the the
Bio::Tools::Run::Alignment::Clustalw manpage and the Bio::Tools::Run::Alignment::TCoffee manpage for
information on downloading and installing these programs. From the user's perspective, the bioperl syntax for
calling Clustalw.pm or TCoffee.pm is almost identical. The only differences are the names of the modules
themselves appearing in the initial ``use'' and constructor statements and the names of the some of the individual
program options and parameters. In either case, initially, a ``factory object'' must be created. The factory may be
passed most of the parameters or switches of the relevant program. In addition, alignment parameters can be
changed and/or examined after the factory has been created. Any parameters not explicitly set will remain as the
underlying program's defaults. Clustalw.pm/TCoffee.pm output is returned in the form of a SimpleAlign object. It
should be noted that some Clustalw and TCoffee parameters and features (such as those corresponding to tree
production) have not been implemented yet in the Perl interface. 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 profile_align()
to add one or more sequences or a second alignment to an initial alignment. Input to align() consists of a set of
unaligned sequences in the form of the name of file containing the sequences or a reference to an array of Seq
objects. Typical syntax is shown below. (We illustrate with Clustalw.pm, but the same syntax - except for the
module name - would work for TCoffee.pm)
use Bio::Tools::Run::Alignment::Clustalw;
@params = ('ktuple' => 2, 'matrix' => 'BLOSUM');
31
 $factory = Bio::Tools::Run::Alignment::Clustalw->new(@params);
$ktuple = 3;
$factory->ktuple($ktuple); # change the parameter before executing
$seq_array_ref = \@seq_array;
# where @seq_array is an array of Bio::Seq objects
$aln = $factory->align($seq_array_ref);
Clustalw.pm/TCoffee.pm can also align two (sub)alignments to each other or add a sequence to a previously
created alignment by using the profile_align method. For further details on the required syntax and options for the
profile_align method, the user is referred to the Bio::Tools::Run::Alignment::Clustalw manpage and the
Bio::Tools::Run::Alignment::TCoffee manpage. The user is also encouraged to examine the script clustalw.pl in
the scripts/align directory. IV.2.4 Aligning 2 sequences with Smith-Waterman (pSW) The Smith-Waterman (SW)
algorithm is the standard method for producing an optimal local alignment of two sequences. Bioperl supports the
computation of SW alignments via the pSW object with the auxilliary bioperl-ext library. Note that pSW only
supports the alignment of protein sequences, not nucleotide. The SW algorithm itself is implemented in C and
incorporated into bioperl using an XS extension. This has significant efficiency advantages but means that pSW
will not work unless you have compiled the bioperl-ext auxilliary library. If you have compiled the bioperl-ext
package, usage is simple, where the method align_and_show displays the alignment while pairwise_alignment
produces a (reference to) a SimpleAlign object.
use Bio::Tools::pSW;
$factory = new Bio::Tools::pSW( '-matrix' => 'blosum62.bla','-gap' => 12,'-ext' => 2, );
$factory->align_and_show($seq1, $seq2, STDOUT);
$aln = $factory->pairwise_alignment($seq1, $seq2);
SW matrix, gap and extension parameters can be adjusted as shown. Bioperl comes standard with blosum62 and
gonnet250 matrices. Others can be added by the user. For additional information on accessing the SW algorithm
via pSW see the script psw.pl in the scripts/tools directory and the documentation in the Bio::Tools::pSW
manpage.

IV.3 bioperl-db

The Bioperl-db package is intended to enable the easy access and manipulation of biology relational databases via
a perl interface. Obviously it requires having adminsitrative access to a relational database. Currently the
bioperl-db interface is implemented primarily to support databases in the Mysql format (http://www.mysql.com).
More details on bioperl-db can be found in the bioperl-db CVS directory at
http://cvs.bioperl.org/cgi-bin/viewcvs/viewcvs.cgi/bioperl-db/?cvsroot=bioperl . It is worth mentioning that most
of the bioperl objects mentioned above map directly to tables in the bioperl-db schema. Therefore object data such
as sequences, their features, and annotations can be easily loaded into the databases, as in
$loader->store($newid,$seqobj)
Similarly one can query the database in a variety of ways and retrieve arrays of Seq objects. See biodatabases.pod,
the Bio::DB::SQL::SeqAdaptor manpage, the Bio::DB::SQL::QueryConstraint manpage, and the
Bio::DB::SQL::BioQuery manpage for examples. The README file in the bioperl-db package has a helpful
overview of the approach used in bioperl-db.

IV.4 Other Bioperl auxilliary libraries

There a several other auxilliary libraries in the bioperl CVS repository including bioperl-microarray, bioperl-gui,
32
bioperl-pipeline, bioperl-das-client and bioperl-corba-client. They are typically for specialized uses and/or require
multiple external programs to run and/or are still pretty new and undeveloped. But if you have a need for any of
these capabailities, it is easy to take a look at them at:
http://cvs.bioperl.org/cgi-bin/viewcvs/viewcvs.cgi/?cvsroot=bioperl and see if they might be of use to you.

V Appendix

V.1 Appendix: Finding out which methods are used by which

Bioperl Objects

At numerous places in the tutorial, the reader is directed to the ``documentation included with each of the
modules.'' As was mentioned in the introduction, it is sometimes not easy in perl to determine the appropriate
documentation to look for, because objects inherit methods from other objects (and the relevant documentation
will be stored in the object from which the method was inherited.) For example, say you wanted to find
documentation on the ``parse'' method of the object Genscan.pm. You would not find this documentation in the
code for Genscan.pm, but rather in the code for AnalysisResult.pm from which Genscan.pm inherits the parse
method! So how would you know to look in AnalysisResult.pm for this documentation? The easy way is to use
the special function ``option 100'' in the bptutorial script. Specifically if you run:
> perl -w bptutorial.pl 100 Bio::Tools::Genscan
you will receive the following output:
***Methods for Object Bio::Tools::Genscan ********
Methods taken from package Bio::Root::IO
catfile close gensym new qualify qualify_to_ref
rmtree tempdir tempfile ungensym
Methods taken from package Bio::Root::RootI
DESTROY stack_trace stack_trace_dump throw verbose warn
Methods taken from package Bio::SeqAnalysisParserI
carp confess croak next_feature
Methods taken from package Bio::Tools::AnalysisResult
analysis_date analysis_method analysis_method_version analysis_query analysis_subject
parse
Methods taken from package Bio::Tools::Genscan
next_prediction
From this output, it is clear exactly from which object each method of Genscan.pm is taken, and, in particular that
``parse'' is taken from the package Bio::Tools::AnalysisResult. With this approach you can easily determine the
source of any method in any bioperl object.

V.2 Appendix: Tutorial demo scripts

The following scripts demonstrate many of the features of bioperl. To run all the core demos, run:
> perl -w bptutorial.pl 0
To run a subset of the scripts do
33
 > perl -w bptutorial.pl
and use the displayed help screen. It may be best to start by just running one or two demos at a time. For example,
to run the basic sequence manipulation demo, do:
> perl -w bptutorial.pl 1
Some of the later demos require that you have an internet connection and/or that you have an auxilliary bioperl
library and/or external cpan module and/or external program installed. They may also fail if you are not running
under Linux or Unix. In all of these cases, the script should fail ``gracefully'' simply saying the demo is being
skipped. However if the script ``crashes'', simply run the other demos individually (and perhaps send an email to
[email protected] detailing the problem :-).

34