<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Ace::Sequence - Examine ACeDB Sequence Objects</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<!--
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#creating_new_ace__sequence_objects__the_new___method">Creating New Ace::Sequence Objects, the <code>new()</code> Method</a></li>
<ul>
<li><a href="#reference_sequences_and_the_coordinate_system">Reference Sequences and the Coordinate System</a></li>
</ul>
<li><a href="#object_methods">Object Methods</a></li>
<ul>
<li><a href="#asstring__"><code>asString()</code></a></li>
<li><a href="#source_seq__"><code>source_seq()</code></a></li>
<li><a href="#parent_seq__"><code>parent_seq()</code></a></li>
<li><a href="#refseq___seq__"><code>refseq([$seq])</code></a></li>
<li><a href="#start__"><code>start()</code></a></li>
<li><a href="#end__"><code>end()</code></a></li>
<li><a href="#offset__"><code>offset()</code></a></li>
<li><a href="#length__"><code>length()</code></a></li>
<li><a href="#abslength__"><code>abslength()</code></a></li>
<li><a href="#strand__"><code>strand()</code></a></li>
<li><a href="#reversed__"><code>reversed()</code></a></li>
<li><a href="#dna__"><code>dna()</code></a></li>
<li><a href="#name__"><code>name()</code></a></li>
<li><a href="#get_parent__"><code>get_parent()</code></a></li>
<li><a href="#get_children__"><code>get_children()</code></a></li>
<li><a href="#features__"><code>features()</code></a></li>
<li><a href="#feature_list__"><code>feature_list()</code></a></li>
<li><a href="#transcripts__"><code>transcripts()</code></a></li>
<li><a href="#clones__"><code>clones()</code></a></li>
<li><a href="#gff__"><code>gff()</code></a></li>
<li><a href="#gff__"><code>GFF()</code></a></li>
<li><a href="#absolute__"><code>absolute()</code></a></li>
<li><a href="#automerge__"><code>automerge()</code></a></li>
<li><a href="#db__"><code>db()</code></a></li>
</ul>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
-->
</div>
<!-- INDEX END -->
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Ace::Sequence - Examine ACeDB Sequence Objects</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
# open database connection and get an Ace::Object sequence
use Ace::Sequence;</pre>
<pre>
$db = Ace->connect(-host => 'stein.cshl.org',-port => 200005);
$obj = $db->fetch(Predicted_gene => 'ZK154.3');</pre>
<pre>
# Wrap it in an Ace::Sequence object
$seq = Ace::Sequence->new($obj);</pre>
<pre>
# Find all the exons
@exons = $seq->features('exon');</pre>
<pre>
# Find all the exons predicted by various versions of "genefinder"
@exons = $seq->features('exon:genefinder.*');</pre>
<pre>
# Iterate through the exons, printing their start, end and DNA
for my $exon (@exons) {
print join "\t",$exon->start,$exon->end,$exon->dna,"\n";
}</pre>
<pre>
# Find the region 1000 kb upstream of the first exon
$sub = Ace::Sequence->new(-seq=>$exons[0],
-offset=>-1000,-length=>1000);</pre>
<pre>
# Find all features in that area
@features = $sub->features;</pre>
<pre>
# Print its DNA
print $sub->dna;</pre>
<pre>
# Create a new Sequence object from the first 500 kb of chromosome 1
$seq = Ace::Sequence->new(-name=>'CHROMOSOME_I',-db=>$db,
-offset=>0,-length=>500_000);</pre>
<pre>
# Get the GFF dump as a text string
$gff = $seq->gff;</pre>
<pre>
# Limit dump to Predicted_genes
$gff_genes = $seq->gff(-features=>'Predicted_gene');</pre>
<pre>
# Return a GFF object (using optional GFF.pm module from Sanger)
$gff_obj = $seq->GFF;</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p><em>Ace::Sequence</em>, and its allied classes <a href="/AcePerl/docs/./Ace/Sequence/Feature.html">the Ace::Sequence::Feature manpage</a> and
<a href="/AcePerl/docs/./Ace/Sequence/FeatureList.html">the Ace::Sequence::FeatureList manpage</a>, provide a convenient interface to the
ACeDB Sequence classes and the GFF sequence feature file format.</p>
<p>Using this class, you can define a region of the genome by using a
landmark (sequenced clone, link, superlink, predicted gene), an offset
from that landmark, and a distance. Offsets and distances can be
positive or negative. This will return an <em>Ace::Sequence</em> object.
Once a region is defined, you may retrieve its DNA sequence, or query
the database for any features that may be contained within this
region. Features can be returned as objects (using the
<em>Ace::Sequence::Feature</em> class), as GFF text-only dumps, or in the
form of the GFF class defined by the Sanger Centre's GFF.pm module.</p>
<p>This class builds on top of <a href="/AcePerl/docs/./Ace.html">the Ace manpage</a> and <a href="/AcePerl/docs/./Ace/Object.html">the Ace::Object manpage</a>. Please see
their manual pages before consulting this one.</p>
<p>
</p>
<hr />
<h1><a name="creating_new_ace__sequence_objects__the_new___method">Creating New Ace::Sequence Objects, the <code>new()</code> Method</a></h1>
<pre>
$seq = Ace::Sequence->new($object);</pre>
<pre>
$seq = Ace::Sequence->new(-source => $object,
-offset => $offset,
-length => $length,
-refseq => $reference_sequence);</pre>
<pre>
$seq = Ace::Sequence->new(-name => $name,
-db => $db,
-offset => $offset,
-length => $length,
-refseq => $reference_sequence);</pre>
<p>In order to create an <em>Ace::Sequence</em> you will need an active <em>Ace</em>
database accessor. Sequence regions are defined using a "source"
sequence, an offset, and a length. Optionally, you may also provide a
"reference sequence" to establish the coordinate system for all
inquiries. Sequences may be generated from existing <em>Ace::Object</em>
sequence objects, from other <em>Ace::Sequence</em> and
<em>Ace::Sequence::Feature</em> objects, or from a sequence name and a
database handle.</p>
<p>The class method named <code>new()</code> is the interface to these facilities. In
its simplest, one-argument form, you provide <code>new()</code> with a
previously-created <em>Ace::Object</em> that points to Sequence or
sequence-like object (the meaning of "sequence-like" is explained in
more detail below.) The <code>new()</code> method will return an <em>Ace::Sequence</em>
object extending from the beginning of the object through to its
natural end.</p>
<p>In the named-parameter form of <code>new()</code>, the following arguments are
recognized:</p>
<dl>
<dt><strong><a name="source" class="item">-source</a></strong>
<dd>
<p>The sequence source. This must be an <em>Ace::Object</em> of the "Sequence"
class, or be a sequence-like object containing the SMap tag (see
below).</p>
</dd>
</li>
<dt><strong><a name="offset" class="item">-offset</a></strong>
<dd>
<p>An offset from the beginning of the source sequence. The retrieved
<em>Ace::Sequence</em> will begin at this position. The offset can be any
positive or negative integer. Offets are <strong>0-based</strong>.</p>
</dd>
</li>
<dt><strong><a name="length" class="item">-length</a></strong>
<dd>
<p>The length of the sequence to return. Either a positive or negative
integer can be specified. If a negative length is given, the returned
sequence will be complemented relative to the source sequence.</p>
</dd>
</li>
<dt><strong><a name="refseq" class="item">-refseq</a></strong>
<dd>
<p>The sequence to use to establish the coordinate system for the
returned sequence. Normally the source sequence is used to establish
the coordinate system, but this can be used to override that choice.
You can provide either an <em>Ace::Object</em> or just a sequence name for
this argument. The source and reference sequences must share a common
ancestor, but do not have to be directly related. An attempt to use a
disjunct reference sequence, such as one on a different chromosome,
will fail.</p>
</dd>
</li>
<dt><strong><a name="name" class="item">-name</a></strong>
<dd>
<p>As an alternative to using an <em>Ace::Object</em> with the <strong>-source</strong>
argument, you may specify a source sequence using <strong>-name</strong> and <strong>-db</strong>.
The <em>Ace::Sequence</em> module will use the provided database accessor to
fetch a Sequence object with the specified name. <code>new()</code> will return
undef is no Sequence by this name is known.</p>
</dd>
</li>
<dt><strong><a name="db" class="item">-db</a></strong>
<dd>
<p>This argument is required if the source sequence is specified by name
rather than by object reference.</p>
</dd>
</li>
</dl>
<p>If <code>new()</code> is successful, it will create an <em>Ace::Sequence</em> object and
return it. Otherwise it will return undef and return a descriptive
message in Ace-><code>error()</code>. Certain programming errors, such as a
failure to provide required arguments, cause a fatal error.</p>
<p>
</p>
<h2><a name="reference_sequences_and_the_coordinate_system">Reference Sequences and the Coordinate System</a></h2>
<p>When retrieving information from an <em>Ace::Sequence</em>, the coordinate
system is based on the sequence segment selected at object creation
time. That is, the "+1" strand is the natural direction of the
<em>Ace::Sequence</em> object, and base pair 1 is its first base pair. This
behavior can be overridden by providing a reference sequence to the
<code>new()</code> method, in which case the orientation and position of the
reference sequence establishes the coordinate system for the object.</p>
<p>In addition to the reference sequence, there are two other sequences
used by <em>Ace::Sequence</em> for internal bookeeping. The "source"
sequence corresponds to the smallest ACeDB sequence object that
completely encloses the selected sequence segment. The "parent"
sequence is the smallest ACeDB sequence object that contains the
"source". The parent is used to derive the length and orientation of
source sequences that are not directly associated with DNA objects.</p>
<p>In many cases, the source sequence will be identical to the sequence
initially passed to the <code>new()</code> method. However, there are exceptions
to this rule. One common exception occurs when the offset and/or
length cross the boundaries of the passed-in sequence. In this case,
the ACeDB database is searched for the smallest sequence that contains
both endpoints of the <em>Ace::Sequence</em> object.</p>
<p>The other common exception occurs in Ace 4.8, where there is support
for "sequence-like" objects that contain the <code>SMap</code> ("Sequence Map")
tag. The <code>SMap</code> tag provides genomic location information for
arbitrary object -- not just those descended from the Sequence class.
This allows ACeDB to perform genome map operations on objects that are
not directly related to sequences, such as genetic loci that have been
interpolated onto the physical map. When an <code>SMap</code>-containing object
is passed to the <em>Ace::Sequence</em> <code>new()</code> method, the module will again
choose the smallest ACeDB Sequence object that contains both
end-points of the desired region.</p>
<p>If an <em>Ace::Sequence</em> object is used to create a new <em>Ace::Sequence</em>
object, then the original object's source is inherited.</p>
<p>
</p>
<hr />
<h1><a name="object_methods">Object Methods</a></h1>
<p>Once an <em>Ace::Sequence</em> object is created, you can query it using the
following methods:</p>
<p>
</p>
<h2><a name="asstring__"><code>asString()</code></a></h2>
<pre>
$name = $seq->asString;</pre>
<p>Returns a human-readable identifier for the sequence in the form
<em>Source/start-end</em>, where "Source" is the name of the source
sequence, and "start" and "end" are the endpoints of the sequence
relative to the source (using 1-based indexing). This method is
called automatically when the <em>Ace::Sequence</em> is used in a string
context.</p>
<p>
</p>
<h2><a name="source_seq__"><code>source_seq()</code></a></h2>
<pre>
$source = $seq->source_seq;</pre>
<p>Return the source of the <em>Ace::Sequence</em>.</p>
<p>
</p>
<h2><a name="parent_seq__"><code>parent_seq()</code></a></h2>
<pre>
$parent = $seq->parent_seq;</pre>
<p>Return the immediate ancestor of the sequence. The parent of the
top-most sequence (such as the CHROMOSOME link) is itself. This
method is used internally to ascertain the length of source sequences
which are not associated with a DNA object.</p>
<p>NOTE: this procedure is a trifle funky and cannot reliably be used to
traverse upwards to the top-most sequence. The reason for this is
that it will return an <em>Ace::Sequence</em> in some cases, and an
<em>Ace::Object</em> in others. Use <code>get_parent()</code> to traverse upwards
through a uniform series of <em>Ace::Sequence</em> objects upwards.</p>
<p>
</p>
<h2><a name="refseq___seq__"><a href="#refseq"><code>refseq([$seq])</code></a></a></h2>
<pre>
$refseq = $seq->refseq;</pre>
<p>Returns the reference sequence, if one is defined.</p>
<pre>
$seq->refseq($new_ref);</pre>
<p>Set the reference sequence. The reference sequence must share the same
ancestor with $seq.</p>
<p>
</p>
<h2><a name="start__"><code>start()</code></a></h2>
<pre>
$start = $seq->start;</pre>
<p>Start of this sequence, relative to the source sequence, using 1-based
indexing.</p>
<p>
</p>
<h2><a name="end__"><code>end()</code></a></h2>
<pre>
$end = $seq->end;</pre>
<p>End of this sequence, relative to the source sequence, using 1-based
indexing.</p>
<p>
</p>
<h2><a name="offset__"><a href="#offset"><code>offset()</code></a></a></h2>
<pre>
$offset = $seq->offset;</pre>
<p>Offset of the beginning of this sequence relative to the source
sequence, using 0-based indexing. The offset may be negative if the
beginning of the sequence is to the left of the beginning of the
source sequence.</p>
<p>
</p>
<h2><a name="length__"><a href="#length"><code>length()</code></a></a></h2>
<pre>
$length = $seq->length;</pre>
<p>The length of this sequence, in base pairs. The length may be
negative if the sequence's orientation is reversed relative to the
source sequence. Use <code>abslength()</code> to obtain the absolute value of
the sequence length.</p>
<p>
</p>
<h2><a name="abslength__"><code>abslength()</code></a></h2>
<pre>
$length = $seq->abslength;</pre>
<p>Return the absolute value of the length of the sequence.</p>
<p>
</p>
<h2><a name="strand__"><code>strand()</code></a></h2>
<pre>
$strand = $seq->strand;</pre>
<p>Returns +1 for a sequence oriented in the natural direction of the
genomic reference sequence, or -1 otherwise.</p>
<p>
</p>
<h2><a name="reversed__"><code>reversed()</code></a></h2>
<p>Returns true if the segment is reversed relative to the canonical
genomic direction. This is the same as $seq->strand < 0.</p>
<p>
</p>
<h2><a name="dna__"><code>dna()</code></a></h2>
<pre>
$dna = $seq->dna;</pre>
<p>Return the DNA corresponding to this sequence. If the sequence length
is negative, the reverse complement of the appropriate segment will be
returned.</p>
<p>ACeDB allows Sequences to exist without an associated DNA object
(which typically happens during intermediate stages of a sequencing
project. In such a case, the returned sequence will contain the
correct number of "-" characters.</p>
<p>
</p>
<h2><a name="name__"><a href="#name"><code>name()</code></a></a></h2>
<pre>
$name = $seq->name;</pre>
<p>Return the name of the source sequence as a string.</p>
<p>
</p>
<h2><a name="get_parent__"><code>get_parent()</code></a></h2>
<pre>
$parent = $seq->parent;</pre>
<p>Return the immediate ancestor of this <em>Ace::Sequence</em> (i.e., the
sequence that contains this one). The return value is a new
<em>Ace::Sequence</em> or undef, if no parent sequence exists.</p>
<p>
</p>
<h2><a name="get_children__"><code>get_children()</code></a></h2>
<pre>
@children = $seq->get_children();</pre>
<p>Returns all subsequences that exist as independent objects in the
ACeDB database. What exactly is returned is dependent on the data
model. In older ACeDB databases, the only subsequences are those
under the catchall Subsequence tag. In newer ACeDB databases, the
objects returned correspond to objects to the right of the S_Child
subtag using a tag[2] syntax, and may include Predicted_genes,
Sequences, Links, or other objects. The return value is a list of
<em>Ace::Sequence</em> objects.</p>
<p>
</p>
<h2><a name="features__"><a href="#features"><code>features()</code></a></a></h2>
<pre>
@features = $seq->features;
@features = $seq->features('exon','intron','Predicted_gene');
@features = $seq->features('exon:GeneFinder','Predicted_gene:hand.*');</pre>
<p><a href="#features"><code>features()</code></a> returns an array of <em>Sequence::Feature</em> objects. If
called without arguments, <a href="#features"><code>features()</code></a> returns all features that cross
the sequence region. You may also provide a filter list to select a
set of features by type and subtype. The format of the filter list
is:</p>
<pre>
type:subtype</pre>
<p>Where <em>type</em> is the class of the feature (the "feature" field of the
GFF format), and <em>subtype</em> is a description of how the feature was
derived (the "source" field of the GFF format). Either of these
fields can be absent, and either can be a regular expression. More
advanced filtering is not supported, but is provided by the Sanger
Centre's GFF module.</p>
<p>The order of the features in the returned list is not specified. To
obtain features sorted by position, use this idiom:</p>
<pre>
@features = sort { $a->start <=> $b->start } $seq->features;</pre>
<p>
</p>
<h2><a name="feature_list__"><code>feature_list()</code></a></h2>
<pre>
my $list = $seq->feature_list();</pre>
<p>This method returns a summary list of the features that cross the
sequence in the form of a <a href="/AcePerl/docs/Ace/Feature/List.html">the Ace::Feature::List manpage</a> object. From the
<a href="/AcePerl/docs/Ace/Feature/List.html">the Ace::Feature::List manpage</a> object you can obtain the list of feature names
and the number of each type. The feature list is obtained from the
ACeDB server with a single short transaction, and therefore has much
less overhead than <a href="#features"><code>features()</code></a>.</p>
<p>See <a href="/AcePerl/docs/Ace/Feature/List.html">the Ace::Feature::List manpage</a> for more details.</p>
<p>
</p>
<h2><a name="transcripts__"><code>transcripts()</code></a></h2>
<p>This returns a list of Ace::Sequence::Transcript objects, which are
specializations of Ace::Sequence::Feature. See <a href="/AcePerl/docs/./Ace/Sequence/Transcript.html">the Ace::Sequence::Transcript manpage</a>
for details.</p>
<p>
</p>
<h2><a name="clones__"><code>clones()</code></a></h2>
<p>This returns a list of Ace::Sequence::Feature objects containing
reconstructed clones. This is a nasty hack, because ACEDB currently
records clone ends, but not the clones themselves, meaning that we
will not always know both ends of the clone. In this case the missing
end has a synthetic position of -99,999,999 or +99,999,999. Sorry.</p>
<p>
</p>
<h2><a name="gff__"><code>gff()</code></a></h2>
<pre>
$gff = $seq->gff();
$gff = $seq->gff(-abs => 1,
-features => ['exon','intron:GeneFinder']);</pre>
<p>This method returns a GFF file as a scalar. The following arguments
are optional:</p>
<dl>
<dt><strong><a name="abs" class="item">-abs</a></strong>
<dd>
<p>Ordinarily the feature entries in the GFF file will be returned in
coordinates relative to the start of the <em>Ace::Sequence</em> object.
Position 1 will be the start of the sequence object, and the "+"
strand will be the sequence object's natural orientation. However if
a true value is provided to <strong>-abs</strong>, the coordinate system used will
be relative to the start of the source sequence, i.e. the native ACeDB
Sequence object (usually a cosmid sequence or a link).</p>
</dd>
<dd>
<p>If a reference sequence was provided when the <em>Ace::Sequence</em> was
created, it will be used by default to set the coordinate system.
Relative coordinates can be reenabled by providing a false value to
<strong>-abs</strong>.</p>
</dd>
<dd>
<p>Ordinarily the coordinate system manipulations automatically "do what
you want" and you will not need to adjust them. See also the <a href="#abs"><code>abs()</code></a>
method described below.</p>
</dd>
</li>
<dt><strong><a name="features" class="item">-features</a></strong>
<dd>
<p>The <strong>-features</strong> argument filters the features according to a list of
types and subtypes. The format is identical to the one described for
the <a href="#features"><code>features()</code></a> method. A single filter may be provided as a scalar
string. Multiple filters may be passed as an array reference.</p>
</dd>
</li>
</dl>
<p>See also the <code>GFF()</code> method described next.</p>
<p>
</p>
<h2><a name="gff__"><code>GFF()</code></a></h2>
<pre>
$gff_object = $seq->gff;
$gff_object = $seq->gff(-abs => 1,
-features => ['exon','intron:GeneFinder']);</pre>
<p>The <code>GFF()</code> method takes the same arguments as <code>gff()</code> described above,
but it returns a <em>GFF::GeneFeatureSet</em> object from the GFF.pm
module. If the GFF module is not installed, this method will generate
a fatal error.</p>
<p>
</p>
<h2><a name="absolute__"><code>absolute()</code></a></h2>
<pre>
$abs = $seq->absolute;
$abs = $seq->absolute(1);</pre>
<p>This method controls whether the coordinates of features are returned
in absolute or relative coordinates. "Absolute" coordinates are
relative to the underlying source or reference sequence. "Relative"
coordinates are relative to the <em>Ace::Sequence</em> object. By default,
coordinates are relative unless <code>new()</code> was provided with a reference
sequence. This default can be examined and changed using <code>absolute()</code>.</p>
<p>
</p>
<h2><a name="automerge__"><code>automerge()</code></a></h2>
<pre>
$merge = $seq->automerge;
$seq->automerge(0);</pre>
<p>This method controls whether groups of features will automatically be
merged together by the <a href="#features"><code>features()</code></a> call. If true (the default), then
the left and right end of clones will be merged into "clone" features,
introns, exons and CDS entries will be merged into
Ace::Sequence::Transcript objects, and similarity entries will be
merged into Ace::Sequence::GappedAlignment objects.</p>
<p>
</p>
<h2><a name="db__"><a href="#db"><code>db()</code></a></a></h2>
<pre>
$db = $seq->db;</pre>
<p>Returns the <a href="/AcePerl/docs/./Ace.html">the Ace manpage</a> database accessor associated with this sequence.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><a href="/AcePerl/docs/./Ace.html">the Ace manpage</a>, <a href="/AcePerl/docs/./Ace/Object.html">the Ace::Object manpage</a>, <a href="/AcePerl/docs/./Ace/Sequence/Feature.html">the Ace::Sequence::Feature manpage</a>,
<a href="/AcePerl/docs/./Ace/Sequence/FeatureList.html">the Ace::Sequence::FeatureList manpage</a>, <em>GFF</em></p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Lincoln Stein <<a href="mailto:lstein@cshl.org">lstein@cshl.org</a>> with extensive help from Jean
Thierry-Mieg <<a href="mailto:mieg@kaa.crbm.cnrs-mop.fr">mieg@kaa.crbm.cnrs-mop.fr</a>></p>
<p>Many thanks to David Block <<a href="mailto:dblock@gene.pbi.nrc.ca">dblock@gene.pbi.nrc.ca</a>> for finding and
fixing the nasty off-by-one errors.</p>
<p>Copyright (c) 1999, Lincoln D. Stein</p>
<p>This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself. See DISCLAIMER.txt for
disclaimers of warranty.</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
c0b2316b5320756fc35b43f35335d7ce
>
files
>
151
