NAME

       Ace::Sequence::Multi - Combine Feature Tables from Multiple Databases

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";

DESCRIPTION

       Ace::Sequence::Multi transparently combines information stored about a sequence in a reference database
       with features tables from any number of annotation databases.  The resulting object can be used just like
       an Ace::Sequence object, except that the features remember their database of origin and go back to that
       database for information.

       This class will only work properly if the reference database and all annotation databases share the same
       cosmid map.

OBJECT CREATION

       You will use the new() method to create new Ace::Sequence::Multi objects.  The arguments are identical to
       the those in the Ace::Sequence parent class, with the addition of an option -secondary argument, which
       points to one or more secondary databases from which to fetch annotation information.

       -source
           The sequence source.  This must be an Ace::Object of the "Sequence" class, or be a sequence-like
           object containing the SMap tag (see below).

       -offset
           An offset from the beginning of the source sequence.  The retrieved Ace::Sequence will begin at this
           position.  The offset can be any positive or negative integer.  Offsets are 0-based.

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

       -refseq
           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 Ace::Object 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.

       -name
           As an alternative to using an Ace::Object with the -source argument, you may specify a source
           sequence using -name and -db.  The Ace::Sequence module will use the provided database accessor to
           fetch a Sequence object with the specified name. new() will return undef is no Sequence by this name
           is known.

       -db This argument is required if the source sequence is specified by name rather than by object
           reference.  It must be a previously opened handle to the reference database.

       -secondary
           This argument points to one or more previously-opened annotation databases.  You may use a scalar if
           there is only one annotation database.  Otherwise, use an array reference.  You may add and delete
           annotation databases after the object is created by using the add_secondary() and delete_secondary()
           methods.

       If new() is successful, it will create an Ace::Sequence::Multi object and return it.  Otherwise it will
       return undef and return a descriptive message in Ace->error().  Certain programming errors, such as a
       failure to provide required arguments, cause a fatal error.

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

       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.

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

           Delete one or more secondary databases from the list of annotation databases.  Databases not already
           in use will be silently ignored.

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.