1Ace::Sequence(3)      User Contributed Perl Documentation     Ace::Sequence(3)
2
3
4

NAME

6       Ace::Sequence - Examine ACeDB Sequence Objects
7

SYNOPSIS

9           # open database connection and get an Ace::Object sequence
10           use Ace::Sequence;
11
12           $db  = Ace->connect(-host => 'stein.cshl.org',-port => 200005);
13           $obj = $db->fetch(Predicted_gene => 'ZK154.3');
14
15           # Wrap it in an Ace::Sequence object
16           $seq = Ace::Sequence->new($obj);
17
18           # Find all the exons
19           @exons = $seq->features('exon');
20
21           # Find all the exons predicted by various versions of "genefinder"
22           @exons = $seq->features('exon:genefinder.*');
23
24           # 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
29           # Find the region 1000 kb upstream of the first exon
30           $sub = Ace::Sequence->new(-seq=>$exons[0],
31                                     -offset=>-1000,-length=>1000);
32
33           # Find all features in that area
34           @features = $sub->features;
35
36           # Print its DNA
37           print $sub->dna;
38
39           # 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
43           # Get the GFF dump as a text string
44           $gff = $seq->gff;
45
46           # Limit dump to Predicted_genes
47           $gff_genes = $seq->gff(-features=>'Predicted_gene');
48
49           # Return a GFF object (using optional GFF.pm module from Sanger)
50           $gff_obj = $seq->GFF;
51

DESCRIPTION

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
57       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
67       This class builds on top of Ace and Ace::Object.  Please see their
68       manual pages before consulting this one.
69

Creating New Ace::Sequence Objects, the new() Method

71        $seq = Ace::Sequence->new($object);
72
73        $seq = Ace::Sequence->new(-source  => $object,
74                                  -offset  => $offset,
75                                  -length  => $length,
76                                  -refseq  => $reference_sequence);
77
78        $seq = Ace::Sequence->new(-name    => $name,
79                                  -db      => $db,
80                                  -offset  => $offset,
81                                  -length  => $length,
82                                  -refseq  => $reference_sequence);
83
84       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
92       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
99       In the named-parameter form of new(), the following arguments are
100       recognized:
101
102       -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
107       -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
112       -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
118       -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
128       -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
135       -db This argument is required if the source sequence is specified by
136           name rather than by object reference.
137
138       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
143   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
152       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
160       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
167       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
178       If an Ace::Sequence object is used to create a new Ace::Sequence
179       object, then the original object's source is inherited.
180

Object Methods

182       Once an Ace::Sequence object is created, you can query it using the
183       following methods:
184
185   asString()
186         $name = $seq->asString;
187
188       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
194   source_seq()
195         $source = $seq->source_seq;
196
197       Return the source of the Ace::Sequence.
198
199   parent_seq()
200         $parent = $seq->parent_seq;
201
202       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
207       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
213   refseq([$seq])
214         $refseq = $seq->refseq;
215
216       Returns the reference sequence, if one is defined.
217
218         $seq->refseq($new_ref);
219
220       Set the reference sequence. The reference sequence must share the same
221       ancestor with $seq.
222
223   start()
224         $start = $seq->start;
225
226       Start of this sequence, relative to the source sequence, using 1-based
227       indexing.
228
229   end()
230         $end = $seq->end;
231
232       End of this sequence, relative to the source sequence, using 1-based
233       indexing.
234
235   offset()
236         $offset = $seq->offset;
237
238       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
243   length()
244         $length = $seq->length;
245
246       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
251   abslength()
252         $length = $seq->abslength;
253
254       Return the absolute value of the length of the sequence.
255
256   strand()
257         $strand = $seq->strand;
258
259       Returns +1 for a sequence oriented in the natural direction of the
260       genomic reference sequence, or -1 otherwise.
261
262   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
266   dna()
267         $dna = $seq->dna;
268
269       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
273       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
278   name()
279         $name = $seq->name;
280
281       Return the name of the source sequence as a string.
282
283   get_parent()
284         $parent = $seq->parent;
285
286       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
290   get_children()
291         @children = $seq->get_children();
292
293       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
301   features()
302         @features = $seq->features;
303         @features = $seq->features('exon','intron','Predicted_gene');
304         @features = $seq->features('exon:GeneFinder','Predicted_gene:hand.*');
305
306       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
311         type:subtype
312
313       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
320       The order of the features in the returned list is not specified.  To
321       obtain features sorted by position, use this idiom:
322
323         @features = sort { $a->start <=> $b->start } $seq->features;
324
325   feature_list()
326         my $list = $seq->feature_list();
327
328       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
335       See Ace::Feature::List for more details.
336
337   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
342   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
349   gff()
350         $gff = $seq->gff();
351         $gff = $seq->gff(-abs      => 1,
352                          -features => ['exon','intron:GeneFinder']);
353
354       This method returns a GFF file as a scalar.  The following arguments
355       are optional:
356
357       -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
366           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
371           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
375       -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
382       See also the GFF() method described next.
383
384   GFF()
385         $gff_object = $seq->gff;
386         $gff_object = $seq->gff(-abs      => 1,
387                          -features => ['exon','intron:GeneFinder']);
388
389       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
393   absolute()
394        $abs = $seq->absolute;
395        $abs = $seq->absolute(1);
396
397       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
404   automerge()
405         $merge = $seq->automerge;
406         $seq->automerge(0);
407
408       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
415   db()
416         $db = $seq->db;
417
418       Returns the Ace database accessor associated with this sequence.
419

SEE ALSO

421       Ace, Ace::Object, Ace::Sequence::Feature, Ace::Sequence::FeatureList,
422       GFF
423

AUTHOR

425       Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
426       Mieg <mieg@kaa.crbm.cnrs-mop.fr>
427
428       Many thanks to David Block <dblock@gene.pbi.nrc.ca> for finding and
429       fixing the nasty off-by-one errors.
430
431       Copyright (c) 1999, Lincoln D. Stein
432
433       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.
436
437
438
439perl v5.28.1                      2004-12-01                  Ace::Sequence(3)
Impressum