Provided by: libace-perl_1.92-7_amd64 bug


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


           use Ace::Sequence::Multi;

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

           # open some secondary databases
           $db1 = Ace->connect(-host=>'',-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

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


       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.


       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.

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

           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.

           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.

           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.

           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.

           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.


       Most methods are inherited from Ace::Sequence.  The following additional methods are

             @databases = $seq->secondary;

           Return a list of the secondary databases currently in use, or an empty list if none.


           Add one or more secondary databases to the list of annotation databases.  Duplicate
           databases will be silently ignored.


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


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


       Lincoln Stein <> with extensive help from Jean Thierry-Mieg

       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.