Provided by: gbrowse_2.54+dfsg-2build1_all bug

SYNOPSIS

        # override feature type, method, source and attribute fields
        # with the contents of a simple text index file

        use Bio::DB::SeqFeature::Store::Alias;
        use Bio::DB::SeqFeature::Store;
        my $db = Bio::DB::SeqFeature::Store->new(-adaptor=>'DBI::mysql',
                                                 -dsn    =>'testdb');
        my $meta = Bio::DB::SeqFeature::Store::Alias->new(-store => $db,
                                                           -index => '/usr/local/testdb/meta.index',
                                                           -default_type => 'example_feature',
           );
        my @features = $meta->get_seq_stream(-seq_id => 'I',
                                             -attributes => {foo => 'bar'});

       meta.index  has the following structure

        [feature_name_1]
        :dbid        = f101
        :selected    = 1
        display_name = My First Feature
        type         = some_type1
        method       = my_method1
        source       = my_source1
        some_attribute    = value1
        another_attribute = value2

        [feature_name_2]
        :dbid        = f102
        :selected    = 1
        display_name = My Second Feature
        type         = some_type2
        method       = my_method2
        source       = my_source2
        some_attribute    = value3
        another_attribute = value4

        [feature_name_3]
        :dbid        = f103
        type         = some_type2
        method       = my_method2
        source       = my_source2
        some_attribute    = value5
        another_attribute = value6

DESCRIPTION

       This module can be used as a wrapper around any BioPerl database that supports the
       get_feature_by_name() method. It allows you to dynamically override the type, source,
       method and display name of each feature, as well as to assign new metadata attributes to
       each one.

       It is used by GBrowse to create subtracks for tracks that have a small number of named
       features, primarily wiggle tracks.

   Metadata Format
       The wrapper is associated with a text file that contains metadata about each feature. You
       can use any name for the text file, but it must follow this format:

        [feature_name_1]
        :dbid        = f101
        :selected    = 1
        type         = some_type1
        method       = my_method1
        source       = my_source1
        some_attribute    = value1
        another_attribute = value2

        [feature_name_2]
        :dbid        = f102
        :selected    = 1
        type         = some_type2
        method       = my_method2
        source       = my_source2
        some_attribute    = value3
        another_attribute = value4

        [feature_name_3]
        :dbid        = f103
        type         = some_type2
        method       = my_method2
        source       = my_source2
        some_attribute    = value5
        another_attribute = value6

       Each [stanza] begins with the name of a feature as it is represented in the underlying
       database. A call to the database's get_feature_by_name() method with the [stanza] heading
       contents (e.g. "feature_name_2") and a genomic position should return one and only one
       feature.

       Below each [stanza] heading are a series of tag=value pairs. The following tag names have
       special meaning:

        :dbid          Unique identifier for the feature, used by GBrowse to process
                         clicks on the feature.
        :selected      If true, this subtrack is selected by default when the
                         containing track is turned on.
        display_name   Display name for the feature. If not present, will
                         default to the feature's native display name
                         (i.e. the one in the [stanza]).
        type           What is returned by calling the feature's type()
                         method.
        method         What is returned by calling the feature's method()
                         method.
        source         What is returned by calling the feature's source()
                         method.
        score         What is returned by calling the feature's score() method.

       Any other tags become sortable attributes which are displayed by the GBrowse subtrack
       selection dialog box. For this to work properly, each tag must be present in each stanza.
       Tags that are present in some stanzas and not others are ignored.

METHODS

   $aliasdb = Bio::DB::SeqFeature::Store::Alias->new(-metadata=>$path,-store=>$db,-type=>$type)
       new() creates the Alias database. The arguments are:

         -metadata       Full path to the metadata file.
         -store          Previously opened handle to the feature database
                           (e.g. Bio::SeqFeature::Store, Bio::DB::GFF,
                            Bio::DB::Chado)
         -type           Default type to use for features in this database.

   $type = $aliasdb->default_type([$type])
       Gets or sets the default type.

   $store = $aliasdb->store
       Gets the underlying feature database specified during new() (immutable).

   $index = $aliasdb->index
       Returns the path to the metadata description file.

   $meta = $aliasdb->metadata
       Return a hashref in which the keys are the feature IDs (or an arbitrary numeric value if
       :dbid was not specified), and the values are a hashref of attribute/value pairs.

   $f = $aliasdb->get_feature($name)
       Calls the underlying database's get_feature_by_name() method and returns a list of
       response.

   @f = $aliasdb->features(@args)
       Same as calling the underlying database's features() method, except that the values you
       specified in the metadata file for display_name, type, method, source, score and other
       attributes will override the original values.

   $segment = $aliasdb->segment(@args)
       Creates a segment object (see Bio::DB::SeqFeature::Store->segment()), which records a
       genomic range for use in further query refinement:

         $chr1 = $aliasdb->segment(-seqid=>'chr1');
         @f    = $chr1->features;

   $iterator = $aliasdb->get_seq_stream(@args)
       This method is similar to the underlying database's get_seq_stream() method, except that
       it wraps each feature. Example:

        $iterator = $aliasdb->get_seq_stream(-type=>'some_type2');
        while (my $seq = $iterator->next_seq) {
           # do something with the seq object.
        }

   @f = $aliasdb->get_features_by_location(@args)
       This method is similar to the underlying database's get_features_by_location() method.

        $iterator = $aliasdb->get_seq_stream(-type=>'some_type2');
        while (my $seq = $iterator->next_seq) {
           # do something with the seq object.
        }

   @f = $aliasdb->get_features_by_name(@args)
       This method is similar to the underlying database's get_features_by_location() method.

   @f = $aliasdb->get_features_by_name(@args)
       This method is similar to the underlying database's get_features_by_location() method.

   @f = $aliasdb->get_features_by_alias(@args);
       This method is similar to the underlying database's get_features_by_alias() method.

   @f = $aliasdb->get_features_by_attribute(@args);
       This method is similar to the underlying database's get_features_by_attribute() method.

BUGS

       Please report them.

SEE ALSO

       Bio::SeqFeature::Store, Bio::DB::GFF, Bio::SeqI, Bio::SeqFeatureI, Bio::Das,
       Bio::Graphics::Browser2

AUTHOR

       Copyright (c) 2012 Ontario Institute for Cancer Research

       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.