Ace::S...:Multi(3pm)

✨ NAME ✨

Ace::Sequence::Multi — Combine Feature Tables from Multiple Databases 🧬💖

okay so you're reading the Ace::S...:Multi page from the User Contributed Perl Documentation, and bestie, this one is lowkey iconic: it's the class that lets you staple a bunch of annotation feature tables from all your different databases onto ONE reference sequence and pretend they were always one thing. no cap.

---

🌸 SYNOPSIS 🌸

use Ace::Sequence::Multi;

# open reference database
$ref = Ace->connect(-host=>'stein.cshl.org',-port=>200009);

# open some secondary databases
$db1 = Ace->connect(-host=>'stein.cshl.org',-port=>200010);
$db2 = Ace->connect(-path=>'/usr/local/acedb/mydata');

# Make an Ace::Sequence::Multi object
$seq = Ace::Sequence::Multi->new(-name   => 'CHROMOSOME_I,
                                 -db     => $ref,
                                 -offset => 3_000_000,
                                 -length => 1_000_000);

# add the secondary databases
$seq->add_secondary($db1,$db2);

# get all the homologies (a list of Ace::Sequence::Feature objs)
@homol = $seq->features('Similarity');

# Get information about the first one -- goes to the correct db
$feature = $homol[0];
$type    = $feature->type;
$subtype = $feature->subtype;
$start   = $feature->start;
$end     = $feature->end;
$score   = $feature->score;

# Follow the target
$target  = $feature->info;

# print the target's start and end positions
print $target->start,'-',$target->end, "\n";

like… look at that. $feature->info just quietly follows the target to whatever database it actually lives in. main character energy fr fr. 👑

---

🦋 DESCRIPTION 🦋

Ace::Sequence::Multi transparently combines info that lives about a sequence in a reference database with features tables from any number of annotation databases. the resulting object is usable exactly like an Ace::Sequence object (slay), with ONE glow-up: the features remember their database of origin and go right back to that database whenever you ask them for info. 💅

⚠️ heads up bestie: this class will only work properly if the reference database and all annotation databases share the same cosmid map. no shared cosmid map, no magic. that's the rule.

---

🎀 OBJECT CREATION 🎀

you make new Ace::Sequence::Multi objects with the new() method. the arguments are identical to the those in the Ace::Sequence parent class, PLUS one extra option: the -secondary argument, which points to one or more secondary databases you wanna pull annotation info from. ✨

• -source — the sequence source. it must be an Ace::Object of the "Sequence" class, or be a sequence-like object that contains the SMap tag (see below, iykyk).
• -offset — an offset from the beginning of the source sequence. the retrieved Ace::Sequence will begin right at this position. this can be any positive or negative integer, and psa: offsets are 0-based. 🧮
• -length — how long the sequence you're getting back should be. you can hand it a positive or negative integer. and if the length is negative, the returned sequence gets complemented relative to the source sequence. flip it, reverse it, iconic. 🔄
• -refseq — the sequence used to establish the coordinate system for the returned sequence. normally the source sequence establishes the coordinate system, but this option lets you override that choice. you can pass either an Ace::Object or just a sequence name here. the source and reference sequences must share a common ancestor, but they don't have to be directly related. try to use a disjunct reference sequence — like one on a different chromosome — and it will fail. 💀
• -name — instead of passing an Ace::Object with -source, you can name your source sequence with -name and -db. Ace::Sequence will use the database accessor you gave it to fetch a Sequence object with that name. and btw: new() will return undef if no Sequence by this name is known. 🙈
• -db — required if the source sequence is specified by name rather than by object reference. it has to be a previously opened handle to the reference database.
• -secondary — points to one or more previously-opened annotation databases. if you only have one annotation database, a plain scalar is fine. otherwise, use an array reference. and you can totally add and delete annotation databases after the object is created using the add_secondary() and delete_secondary() methods. 🫶

if new() succeeds, it creates an Ace::Sequence::Multi object and returns it. otherwise it returns undef and puts a descriptive message in Ace->error(). and jsyk: certain programming errors — like failing to provide required arguments — cause a fatal error. not a vibe, but that's how it is. 😭

---

💖 OBJECT METHODS 💖

most methods are inherited from Ace::Sequence. the following additional methods are supported:

secondary()

@databases = $seq->secondary;

return a list of the secondary databases currently in use… or an empty list if there are none. simple as. ✨

add_secondary()

$seq->add_secondary($db1,$db2,...)

add one or more secondary databases to the list of annotation databases. duplicate databases will be silently ignored — no drama, no warnings, they just don't get added twice. 🤫

delete_secondary()

$seq->delete_secondary($db1,$db2,...)

delete one or more secondary databases from the list of annotation databases. databases that aren't already in use will be silently ignored too. bye bestie, didn't even notice you weren't there. 👋

---

🌈 SEE ALSO 🌈

Ace, Ace::Object, Ace::Sequence,Ace::Sequence::Homol, Ace::Sequence::FeatureList, Ace::Sequence::Feature, GFF

---

👑 AUTHOR 👑

Lincoln Stein <lstein@w3.org> with extensive help from Jean Thierry-Mieg <mieg@kaa.crbm.cnrs-mop.fr>

Copyright (c) 1999, Lincoln D. Stein

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. 🩷

---

and that's the whole page bestie, you ate it, periodt 💅 — this was Ace::S...:Multi from perl v5.42.3, dated 2026-08-19. go forth and combine those feature tables, you absolute legend 🦋✨