1Ace::Sequence(3) User Contributed Perl Documentation Ace::Sequence(3)
2
6 Ace::Sequence - Examine ACeDB Sequence Objects
7
9 # open database connection and get an Ace::Object sequence
10 use Ace::Sequence;
11 $db = Ace->connect(-host => 'stein.cshl.org',-port => 200005);
13 $obj = $db->fetch(Predicted_gene => 'ZK154.3');
14 # Wrap it in an Ace::Sequence object
16 $seq = Ace::Sequence->new($obj);
17 # Find all the exons
19 @exons = $seq->features('exon');
20 # Find all the exons predicted by various versions of "genefinder"
22 @exons = $seq->features('exon:genefinder.*');
23 # Iterate through the exons, printing their start, end and DNA
25 for my $exon (@exons) {
26 print join "\t",$exon->start,$exon->end,$exon->dna,"\n";
27 }
28 # Find the region 1000 kb upstream of the first exon
30 $sub = Ace::Sequence->new(-seq=>$exons[0],
31 -offset=>-1000,-length=>1000);
32 # Find all features in that area
34 @features = $sub->features;
35 # Print its DNA
37 print $sub->dna;
38 # Create a new Sequence object from the first 500 kb of chromosome 1
40 $seq = Ace::Sequence->new(-name=>'CHROMOSOME_I',-db=>$db,
41 -offset=>0,-length=>500_000);
42 # Get the GFF dump as a text string
44 $gff = $seq->gff;
45 # Limit dump to Predicted_genes
47 $gff_genes = $seq->gff(-features=>'Predicted_gene');
48 # Return a GFF object (using optional GFF.pm module from Sanger)
50 $gff_obj = $seq->GFF;
51
53 Ace::Sequence, and its allied classes Ace::Sequence::Feature and
54 Ace::Sequence::FeatureList, provide a convenient interface to the ACeDB
55 Sequence classes and the GFF sequence feature file format.
56 Using this class, you can define a region of the genome by using a
58 landmark (sequenced clone, link, superlink, predicted gene), an offset
59 from that landmark, and a distance. Offsets and distances can be
60 positive or negative. This will return an Ace::Sequence object. Once
61 a region is defined, you may retrieve its DNA sequence, or query the
62 database for any features that may be contained within this region.
63 Features can be returned as objects (using the Ace::Sequence::Feature
64 class), as GFF text-only dumps, or in the form of the GFF class defined
65 by the Sanger Centre's GFF.pm module.
66 This class builds on top of Ace and Ace::Object. Please see their
68 manual pages before consulting this one.
69
71 $seq = Ace::Sequence->new($object);
72 $seq = Ace::Sequence->new(-source => $object,
74 -offset => $offset,
75 -length => $length,
76 -refseq => $reference_sequence);
77 $seq = Ace::Sequence->new(-name => $name,
79 -db => $db,
80 -offset => $offset,
81 -length => $length,
82 -refseq => $reference_sequence);
83 In order to create an Ace::Sequence you will need an active Ace
85 database accessor. Sequence regions are defined using a "source"
86 sequence, an offset, and a length. Optionally, you may also provide a
87 "reference sequence" to establish the coordinate system for all
88 inquiries. Sequences may be generated from existing Ace::Object
89 sequence objects, from other Ace::Sequence and Ace::Sequence::Feature
90 objects, or from a sequence name and a database handle.
91 The class method named new() is the interface to these facilities. In
93 its simplest, one-argument form, you provide new() with a previously-
94 created Ace::Object that points to Sequence or sequence-like object
95 (the meaning of "sequence-like" is explained in more detail below.)
96 The new() method will return an Ace::Sequence object extending from the
97 beginning of the object through to its natural end.
98 In the named-parameter form of new(), the following arguments are
100 recognized:
101 -source
103 The sequence source. This must be an Ace::Object of the "Sequence"
104 class, or be a sequence-like object containing the SMap tag (see
105 below).
106 -offset
108 An offset from the beginning of the source sequence. The retrieved
109 Ace::Sequence will begin at this position. The offset can be any
110 positive or negative integer. Offets are 0-based.
111 -length
113 The length of the sequence to return. Either a positive or
114 negative integer can be specified. If a negative length is given,
115 the returned sequence will be complemented relative to the source
116 sequence.
117 -refseq
119 The sequence to use to establish the coordinate system for the
120 returned sequence. Normally the source sequence is used to
121 establish the coordinate system, but this can be used to override
122 that choice. You can provide either an Ace::Object or just a
123 sequence name for this argument. The source and reference
124 sequences must share a common ancestor, but do not have to be
125 directly related. An attempt to use a disjunct reference sequence,
126 such as one on a different chromosome, will fail.
127 -name
129 As an alternative to using an Ace::Object with the -source
130 argument, you may specify a source sequence using -name and -db.
131 The Ace::Sequence module will use the provided database accessor to
132 fetch a Sequence object with the specified name. new() will return
133 undef is no Sequence by this name is known.
134 -db This argument is required if the source sequence is specified by
136 name rather than by object reference.
137 If new() is successful, it will create an Ace::Sequence object and
139 return it. Otherwise it will return undef and return a descriptive
140 message in Ace->error(). Certain programming errors, such as a failure
141 to provide required arguments, cause a fatal error.
142 Reference Sequences and the Coordinate System
144 When retrieving information from an Ace::Sequence, the coordinate
145 system is based on the sequence segment selected at object creation
146 time. That is, the "+1" strand is the natural direction of the
147 Ace::Sequence object, and base pair 1 is its first base pair. This
148 behavior can be overridden by providing a reference sequence to the
149 new() method, in which case the orientation and position of the
150 reference sequence establishes the coordinate system for the object.
151 In addition to the reference sequence, there are two other sequences
153 used by Ace::Sequence for internal bookeeping. The "source" sequence
154 corresponds to the smallest ACeDB sequence object that completely
155 encloses the selected sequence segment. The "parent" sequence is the
156 smallest ACeDB sequence object that contains the "source". The parent
157 is used to derive the length and orientation of source sequences that
158 are not directly associated with DNA objects.
159 In many cases, the source sequence will be identical to the sequence
161 initially passed to the new() method. However, there are exceptions to
162 this rule. One common exception occurs when the offset and/or length
163 cross the boundaries of the passed-in sequence. In this case, the
164 ACeDB database is searched for the smallest sequence that contains both
165 endpoints of the Ace::Sequence object.
166 The other common exception occurs in Ace 4.8, where there is support
168 for "sequence-like" objects that contain the "SMap" ("Sequence Map")
169 tag. The "SMap" tag provides genomic location information for
170 arbitrary object -- not just those descended from the Sequence class.
171 This allows ACeDB to perform genome map operations on objects that are
172 not directly related to sequences, such as genetic loci that have been
173 interpolated onto the physical map. When an "SMap"-containing object
174 is passed to the Ace::Sequence new() method, the module will again
175 choose the smallest ACeDB Sequence object that contains both end-points
176 of the desired region.
177 If an Ace::Sequence object is used to create a new Ace::Sequence
179 object, then the original object's source is inherited.
180
182 Once an Ace::Sequence object is created, you can query it using the
183 following methods:
184 asString()
186 $name = $seq->asString;
187 Returns a human-readable identifier for the sequence in the form
189 Source/start-end, where "Source" is the name of the source sequence,
190 and "start" and "end" are the endpoints of the sequence relative to the
191 source (using 1-based indexing). This method is called automatically
192 when the Ace::Sequence is used in a string context.
193 source_seq()
195 $source = $seq->source_seq;
196 Return the source of the Ace::Sequence.
198 parent_seq()
200 $parent = $seq->parent_seq;
201 Return the immediate ancestor of the sequence. The parent of the top-
203 most sequence (such as the CHROMOSOME link) is itself. This method is
204 used internally to ascertain the length of source sequences which are
205 not associated with a DNA object.
206 NOTE: this procedure is a trifle funky and cannot reliably be used to
208 traverse upwards to the top-most sequence. The reason for this is that
209 it will return an Ace::Sequence in some cases, and an Ace::Object in
210 others. Use get_parent() to traverse upwards through a uniform series
211 of Ace::Sequence objects upwards.
212 refseq([$seq])
214 $refseq = $seq->refseq;
215 Returns the reference sequence, if one is defined.
217 $seq->refseq($new_ref);
219 Set the reference sequence. The reference sequence must share the same
221 ancestor with $seq.
222 start()
224 $start = $seq->start;
225 Start of this sequence, relative to the source sequence, using 1-based
227 indexing.
228 end()
230 $end = $seq->end;
231 End of this sequence, relative to the source sequence, using 1-based
233 indexing.
234 offset()
236 $offset = $seq->offset;
237 Offset of the beginning of this sequence relative to the source
239 sequence, using 0-based indexing. The offset may be negative if the
240 beginning of the sequence is to the left of the beginning of the source
241 sequence.
242 length()
244 $length = $seq->length;
245 The length of this sequence, in base pairs. The length may be negative
247 if the sequence's orientation is reversed relative to the source
248 sequence. Use abslength() to obtain the absolute value of the sequence
249 length.
250 abslength()
252 $length = $seq->abslength;
253 Return the absolute value of the length of the sequence.
255 strand()
257 $strand = $seq->strand;
258 Returns +1 for a sequence oriented in the natural direction of the
260 genomic reference sequence, or -1 otherwise.
261 reversed()
263 Returns true if the segment is reversed relative to the canonical
264 genomic direction. This is the same as $seq->strand < 0.
265 dna()
267 $dna = $seq->dna;
268 Return the DNA corresponding to this sequence. If the sequence length
270 is negative, the reverse complement of the appropriate segment will be
271 returned.
272 ACeDB allows Sequences to exist without an associated DNA object (which
274 typically happens during intermediate stages of a sequencing project.
275 In such a case, the returned sequence will contain the correct number
276 of "-" characters.
277 name()
279 $name = $seq->name;
280 Return the name of the source sequence as a string.
282 get_parent()
284 $parent = $seq->parent;
285 Return the immediate ancestor of this Ace::Sequence (i.e., the sequence
287 that contains this one). The return value is a new Ace::Sequence or
288 undef, if no parent sequence exists.
289 get_children()
291 @children = $seq->get_children();
292 Returns all subsequences that exist as independent objects in the ACeDB
294 database. What exactly is returned is dependent on the data model. In
295 older ACeDB databases, the only subsequences are those under the
296 catchall Subsequence tag. In newer ACeDB databases, the objects
297 returned correspond to objects to the right of the S_Child subtag using
298 a tag[2] syntax, and may include Predicted_genes, Sequences, Links, or
299 other objects. The return value is a list of Ace::Sequence objects.
300 features()
302 @features = $seq->features;
303 @features = $seq->features('exon','intron','Predicted_gene');
304 @features = $seq->features('exon:GeneFinder','Predicted_gene:hand.*');
305 features() returns an array of Sequence::Feature objects. If called
307 without arguments, features() returns all features that cross the
308 sequence region. You may also provide a filter list to select a set of
309 features by type and subtype. The format of the filter list is:
310 type:subtype
312 Where type is the class of the feature (the "feature" field of the GFF
314 format), and subtype is a description of how the feature was derived
315 (the "source" field of the GFF format). Either of these fields can be
316 absent, and either can be a regular expression. More advanced
317 filtering is not supported, but is provided by the Sanger Centre's GFF
318 module.
319 The order of the features in the returned list is not specified. To
321 obtain features sorted by position, use this idiom:
322 @features = sort { $a->start <=> $b->start } $seq->features;
324 feature_list()
326 my $list = $seq->feature_list();
327 This method returns a summary list of the features that cross the
329 sequence in the form of a Ace::Feature::List object. From the
330 Ace::Feature::List object you can obtain the list of feature names and
331 the number of each type. The feature list is obtained from the ACeDB
332 server with a single short transaction, and therefore has much less
333 overhead than features().
334 See Ace::Feature::List for more details.
336 transcripts()
338 This returns a list of Ace::Sequence::Transcript objects, which are
339 specializations of Ace::Sequence::Feature. See
340 Ace::Sequence::Transcript for details.
341 clones()
343 This returns a list of Ace::Sequence::Feature objects containing
344 reconstructed clones. This is a nasty hack, because ACEDB currently
345 records clone ends, but not the clones themselves, meaning that we will
346 not always know both ends of the clone. In this case the missing end
347 has a synthetic position of -99,999,999 or +99,999,999. Sorry.
348 gff()
350 $gff = $seq->gff();
351 $gff = $seq->gff(-abs => 1,
352 -features => ['exon','intron:GeneFinder']);
353 This method returns a GFF file as a scalar. The following arguments
355 are optional:
356 -abs
358 Ordinarily the feature entries in the GFF file will be returned in
359 coordinates relative to the start of the Ace::Sequence object.
360 Position 1 will be the start of the sequence object, and the "+"
361 strand will be the sequence object's natural orientation. However
362 if a true value is provided to -abs, the coordinate system used
363 will be relative to the start of the source sequence, i.e. the
364 native ACeDB Sequence object (usually a cosmid sequence or a link).
365 If a reference sequence was provided when the Ace::Sequence was
367 created, it will be used by default to set the coordinate system.
368 Relative coordinates can be reenabled by providing a false value to
369 -abs.
370 Ordinarily the coordinate system manipulations automatically "do
372 what you want" and you will not need to adjust them. See also the
373 abs() method described below.
374 -features
376 The -features argument filters the features according to a list of
377 types and subtypes. The format is identical to the one described
378 for the features() method. A single filter may be provided as a
379 scalar string. Multiple filters may be passed as an array
380 reference.
381 See also the GFF() method described next.
383 GFF()
385 $gff_object = $seq->gff;
386 $gff_object = $seq->gff(-abs => 1,
387 -features => ['exon','intron:GeneFinder']);
388 The GFF() method takes the same arguments as gff() described above, but
390 it returns a GFF::GeneFeatureSet object from the GFF.pm module. If the
391 GFF module is not installed, this method will generate a fatal error.
392 absolute()
394 $abs = $seq->absolute;
395 $abs = $seq->absolute(1);
396 This method controls whether the coordinates of features are returned
398 in absolute or relative coordinates. "Absolute" coordinates are
399 relative to the underlying source or reference sequence. "Relative"
400 coordinates are relative to the Ace::Sequence object. By default,
401 coordinates are relative unless new() was provided with a reference
402 sequence. This default can be examined and changed using absolute().
403 automerge()
405 $merge = $seq->automerge;
406 $seq->automerge(0);
407 This method controls whether groups of features will automatically be
409 merged together by the features() call. If true (the default), then
410 the left and right end of clones will be merged into "clone" features,
411 introns, exons and CDS entries will be merged into
412 Ace::Sequence::Transcript objects, and similarity entries will be
413 merged into Ace::Sequence::GappedAlignment objects.
414 db()
416 $db = $seq->db;
417 Returns the Ace database accessor associated with this sequence.
419
421 Ace, Ace::Object, Ace::Sequence::Feature, Ace::Sequence::FeatureList,
422 GFF
423
425 Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
426 Mieg <mieg@kaa.crbm.cnrs-mop.fr>
427 Many thanks to David Block <dblock@gene.pbi.nrc.ca> for finding and
429 fixing the nasty off-by-one errors.
430 Copyright (c) 1999, Lincoln D. Stein
432 This library is free software; you can redistribute it and/or modify it
434 under the same terms as Perl itself. See DISCLAIMER.txt for
435 disclaimers of warranty.
436perl v5.32.0 2020-07-28 Ace::Sequence(3)