Provided by: libbio-perl-perl_1.7.2-3_all bug

NAME

       Bio::DB::SeqFeature::NormalizedFeature -- Normalized feature for use with
       Bio::DB::SeqFeature::Store

SYNOPSIS

        use Bio::DB::SeqFeature::Store;
        # Open the sequence database
        my $db      = Bio::DB::SeqFeature::Store->new( -adaptor => 'DBI::mysql',
                                                       -dsn     => 'dbi:mysql:test');
        my ($feature)   = $db->get_features_by_name('ZK909');
        my @subfeatures = $feature->get_SeqFeatures();
        my @exons_only  = $feature->get_SeqFeatures('exon');

        # create a new object
        $db->seqfeature_class('Bio::DB::SeqFeature::NormalizedFeature');
        my $new = $db->new_feature(-primary_tag=>'gene',
                                   -seq_id     => 'chr3',
                                   -start      => 10000,
                                   -end        => 11000);

        # add a new exon
        $feature->add_SeqFeature($db->new_feature(-primary_tag=>'exon',
                                                  -seq_id     => 'chr3',
                                                  -start      => 5000,
                                                  -end        => 5551));

DESCRIPTION

       The Bio::DB::SeqFeature::NormalizedFeature object is an alternative representation of
       SeqFeatures for use with Bio::DB::SeqFeature::Store database system. It is identical to
       Bio::DB::SeqFeature, except that instead of storing feature/subfeature relationships in a
       database table, the information is stored in the object itself. This actually makes the
       objects somewhat inconvenient to work with from SQL, but does speed up access somewhat.

       To use this class, pass the name of the class to the Bio::DB::SeqFeature::Store object's
       seqfeature_class() method. After this, $db->new_feature() will create objects of type
       Bio::DB::SeqFeature::NormalizedFeature. If you are using the GFF3 loader, pass
       Bio::DB::SeqFeature::Store::GFF3Loader->new() the -seqfeature_class argument:

         use Bio::DB::SeqFeature::Store::GFF3Loader;

         my $store  = connect_to_db_somehow();
         my $loader = Bio::DB::SeqFeature::Store::GFF3Loader->new(
                       -store=>$db,
                       -seqfeature_class => 'Bio::DB::SeqFeature::NormalizedFeature'
                      );

   new
        Title   : new
        Usage   : $feature = Bio::DB::SeqFeature::NormalizedFeature->new(@args)
        Function: create a new feature
        Returns : the new seqfeature
        Args    : see below
        Status  : public

       This method creates and, if possible stores into a database, a new
       Bio::DB::SeqFeature::NormalizedFeature object using the specialized Bio::DB::SeqFeature
       class.

       The arguments are the same to Bio::SeqFeature::Generic->new() and
       Bio::Graphics::Feature->new(). The most important difference is the -store option, which
       if present creates the object in a Bio::DB::SeqFeature::Store database, and he -index
       option, which controls whether the feature will be indexed for retrieval (default is
       true). Ordinarily, you would only want to turn indexing on when creating top level
       features, and off only when storing subfeatures. The default is on.

       Arguments are as follows:

         -seq_id       the reference sequence
         -start        the start position of the feature
         -end          the stop position of the feature
         -display_name the feature name (returned by seqname)
         -primary_tag  the feature type (returned by primary_tag)
         -source       the source tag
         -score        the feature score (for GFF compatibility)
         -desc         a description of the feature
         -segments     a list of subfeatures (see Bio::Graphics::Feature)
         -subtype      the type to use when creating subfeatures
         -strand       the strand of the feature (one of -1, 0 or +1)
         -phase        the phase of the feature (0..2)
         -url          a URL to link to when rendered with Bio::Graphics
         -attributes   a hashref of tag value attributes, in which the key is the tag
                         and the value is an array reference of values
         -store        a previously-opened Bio::DB::SeqFeature::Store object
         -index        index this feature if true

       Aliases:

         -id           an alias for -display_name
         -seqname      an alias for -display_name
         -display_id   an alias for -display_name
         -name         an alias for -display_name
         -stop         an alias for end
         -type         an alias for primary_tag

   Bio::SeqFeatureI methods
       The following Bio::SeqFeatureI methods are supported:

        seq_id(), start(), end(), strand(), get_SeqFeatures(),
        display_name(), primary_tag(), source_tag(), seq(),
        location(), primary_id(), overlaps(), contains(), equals(),
        intersection(), union(), has_tag(), remove_tag(),
        add_tag_value(), get_tag_values(), get_all_tags()

       Some methods that do not make sense in the context of a genome annotation database system,
       such as attach_seq(), are not supported.

       Please see Bio::SeqFeatureI for more details.

   add_SeqFeature
        Title   : add_SeqFeature
        Usage   : $flag = $feature->add_SeqFeature(@features)
        Function: Add subfeatures to the feature
        Returns : true if successful
        Args    : list of Bio::SeqFeatureI objects
        Status  : public

       Add one or more subfeatures to the feature. For best results, subfeatures should be of the
       same class as the parent feature (i.e. don't try mixing
       Bio::DB::SeqFeature::NormalizedFeature with other feature types).

       An alias for this method is add_segment().

   update
        Title   : update
        Usage   : $flag = $feature->update()
        Function: Update feature in the database
        Returns : true if successful
        Args    : none
        Status  : public

       After changing any fields in the feature, call update() to write it to the database. This
       is not needed for add_SeqFeature() as update() is invoked automatically.

   get_SeqFeatures
        Title   : get_SeqFeature
        Usage   : @subfeatures = $feature->get_SeqFeatures([@types])
        Function: return subfeatures of this feature
        Returns : list of subfeatures
        Args    : list of subfeature primary_tags (optional)
        Status  : public

       This method extends the Bio::SeqFeatureI get_SeqFeatures() slightly by allowing you to
       pass a list of primary_tags, in which case only subfeatures whose primary_tag is contained
       on the list will be returned. Without any types passed all subfeatures are returned.

   object_store
        Title   : object_store
        Usage   : $store = $feature->object_store([$new_store])
        Function: get or set the database handle
        Returns : current database handle
        Args    : new database handle (optional)
        Status  : public

       This method will get or set the Bio::DB::SeqFeature::Store object that is associated with
       the feature. After changing the store, you should probably unset the feature's
       primary_id() and call update() to ensure that the object is written into the database as a
       new feature.

   overloaded_names
        Title   : overloaded_names
        Usage   : $overload = $feature->overloaded_names([$new_overload])
        Function: get or set overloading of object strings
        Returns : current flag
        Args    : new flag (optional)
        Status  : public

       For convenience, when objects of this class are stringified, they are represented in the
       form "primary_tag(display_name)". To turn this feature off, call overloaded_names() with a
       false value. You can invoke this on an individual feature object or on the class:

         Bio::DB::SeqFeature::NormalizedFeature->overloaded_names(0);

   segment
        Title   : segment
        Usage   : $segment = $feature->segment
        Function: return a Segment object corresponding to feature
        Returns : a Bio::DB::SeqFeature::Segment
        Args    : none
        Status  : public

       This turns the feature into a Bio::DB::SeqFeature::Segment object, which you can then use
       to query for overlapping features. See Bio::DB::SeqFeature::Segment.

   AUTOLOADED methods
        @subfeatures = $feature->Exon;

       If you use an unknown method that begins with a capital letter, then the feature
       autogenerates a call to get_SeqFeatures() using the lower-cased method name as the
       primary_tag. In other words $feature->Exon is equivalent to:

        @subfeature s= $feature->get_SeqFeatures('exon')

       If you use an unknown method that begins with Tag_(tagname), Att_(tagname) Is_(tagname),
       then it will be the same as calling the each_tag_value() method with the tagname. In a
       list context, these autogenerated procedures return the list of results. In scalar
       context, they return the first item in the list!!

   load_id
        Title   : load_id
        Usage   : $id = $feature->load_id
        Function: get the GFF3 load ID
        Returns : the GFF3 load ID (string)
        Args    : none
        Status  : public

       For features that were originally loaded by the GFF3 loader, this method returns the GFF3
       load ID. This method may not be supported in future versions of the module.

   notes
        Title   : notes
        Usage   : @notes = $feature->notes
        Function: get contents of the GFF3 Note tag
        Returns : List of GFF3 Note tags
        Args    : none
        Status  : public

       For features that were originally loaded by the GFF3 loader, this method returns the
       contents of the Note tag as a list. This is a convenience for Bio::Graphics, which looks
       for notes() when it constructs a default description line.

   primary_id
        Title   : primary_id
        Usage   : $id = $feature->primary_id([$new_id])
        Function: get/set the feature's database ID
        Returns : the current primary ID
        Args    : none
        Status  : public

       This method gets or sets the primary ID of the feature in the underlying
       Bio::DB::SeqFeature::Store database. If you change this field and then call update(), it
       will have the effect of making a copy of the feature in the database under a new ID.

   target
        Title   : target
        Usage   : $segment = $feature->target
        Function: return the segment correspondent to the "Target" attribute
        Returns : a Bio::DB::SeqFeature::Segment object
        Args    : none
        Status  : public

       For features that are aligned with others via the GFF3 Target attribute, this returns a
       segment corresponding to the aligned region. The CIGAR gap string is not yet supported.

   Internal methods
       $feature->as_string()
           Internal method used to implement overloaded stringification.

       $boolean = $feature->type_match(@list_of_types)
           Internal method that will return true if the feature's primary_tag and source_tag
           match any of the list of types (in primary_tag:source_tag format) provided.

BUGS

       This is an early version, so there are certainly some bugs. Please use the BioPerl bug
       tracking system to report bugs.

SEE ALSO

       bioperl, Bio::DB::SeqFeature, Bio::DB::SeqFeature::Store, Bio::DB::SeqFeature::Segment,
       Bio::DB::SeqFeature::GFF3Loader, Bio::DB::SeqFeature::Store::DBI::mysql,
       Bio::DB::SeqFeature::Store::bdb

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2006 Cold Spring Harbor Laboratory.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.