Bio::D...:Store(3pm)

📦
version 1.7.5 · 4 versions
, in ubuntu resolute, ubuntu stonking

okay bestie, welcome to the Bio::DB::SeqFeature::Store(3pm) page — yep, it's User Contributed Perl Documentation, and it's literally the blueprint for storing and fetching sequence annotation data. 💖

✨ NAME ✨

Bio::DB::SeqFeature::Store -- Storage and retrieval of sequence annotation data. periodt. 💅

💖 SYNOPSIS 💖

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

         # Open the feature database
         my $db = Bio::DB::SeqFeature::Store->new( -adaptor => 'DBI::mysql',
                                                   -dsn     => 'dbi:mysql:test',
                                                   -create  => 1 );

         # Get a feature from somewhere
         my $feature = Bio::SeqFeature::Generic->new(...);

         # Store it
         $db->store($feature) or die "Couldn't store!";

         # If absent, a primary ID is added to the feature when it is stored in the
         # database. Retrieve the primary ID
         my $id = $feature->primary_id;

         # Get the feature back out
         my $feature = $db->fetch($id);

         # .... which is identical to
         my $feature = $db->get_feature_by_primary_id($id);

         # Change the feature and update it
         $f->start(100);
         $db->store($f) or die "Couldn't update!";

         # Get all features at once
         my @features = $db->features( );

         # Retrieve multiple features by primary id
         my @features = $db->fetch_many(@list_of_ids);

         # ...by name
         @features = $db->get_features_by_name('ZK909');

         # ...by alias
         @features = $db->get_features_by_alias('sma-3');

         # ...by type
         @features = $db->get_features_by_type('gene');

         # ...by location
         @features = $db->get_features_by_location(-seq_id=>'Chr1',-start=>4000,-end=>600000);

         # ...by attribute
         @features = $db->get_features_by_attribute({description => 'protein kinase'})

         # ...by the GFF "Note" field
         @result_list = $db->search_notes('kinase');

         # ...by arbitrary combinations of selectors
         @features = $db->features(-name => $name,
                                   -type => $types,
                                   -seq_id => $seqid,
                                   -start  => $start,
                                   -end    => $end,
                                   -attributes => $attributes);

         # Loop through the features using an iterator
         my $iterator = $db->get_seq_stream(-name => $name,
                                            -type => $types,
                                            -seq_id => $seqid,
                                            -start  => $start,
                                            -end    => $end,
                                            -attributes => $attributes);

         while (my $feature = $iterator->next_seq) {
           # do something with the feature
         }

         # ...limiting the search to a particular region
         my $segment  = $db->segment('Chr1',5000=>6000);
         my @features = $segment->features(-type=>['mRNA','match']);

         # Getting coverage statistics across a region
         my $summary = $db->feature_summary('Chr1',10_000=>1_110_000);
         my ($bins)  = $summary->get_tag_values('coverage');
         my $first_bin = $bins->[0];

         # Getting & storing sequence information
         # Warning: this returns a string, and not a PrimarySeq object
         $db->insert_sequence('Chr1','GATCCCCCGGGATTCCAAAA...');
         my $sequence = $db->fetch_sequence('Chr1',5000=>6000);

         # What feature types are defined in the database?
         my @types    = $db->types;

         # Create a new feature in the database
         my $feature = $db->new_feature(-primary_tag => 'mRNA',
                                        -seq_id      => 'chr3',
                                        -start      => 10000,
                                        -end        => 11000);

         # Load an entire GFF3 file, using the GFF3 loader...
         my $loader = Bio::DB::SeqFeature::Store::GFF3Loader->new(-store    => $db,
                                                                  -verbose  => 1,
                                                                  -fast     => 1);

         $loader->load('./my_genome.gff3');

🌸 DESCRIPTION 🌸

okay so Bio::DB::SeqFeature::Store implements the Bio::SeqFeature::CollectionI interface so you can persistently store Bio::SeqFeatureI objects in a database and then retrieve them with a whole variety of searches. It's giving older Bio::DB::GFF module energy, but with these differences:

  1. No limitation on Bio::SeqFeatureI implementations — Unlike Bio::DB::GFF, Bio::DB::SeqFeature::Store works with any Bio::SeqFeatureI object.
  2. No limitation on nesting of features & subfeatures — Bio::DB::GFF is limited to features that have at most one level of subfeature. Bio::DB::SeqFeature::Store can work with features that have unlimited levels of nesting.
  3. No aggregators — The aggregator architecture, which was necessary to impose order on the GFF2 files that Bio::DB::GFF works with, does not apply to Bio::DB::SeqFeature::Store. It is intended to store features that obey well-defined ontologies, such as the Sequence Ontology (http://song.sourceforge.net).
  4. No relative locations — All locations defined by this module are relative to an absolute sequence ID, unlike Bio::DB::GFF which allows you to define the location of one feature relative to another.

We'll discuss major concepts in Bio::DB::SeqFeature::Store and then describe how to use the module. periodt.

🦋 Adaptors 🦋

Bio::DB::SeqFeature::Store is designed to work with a variety of storage back ends called "adaptors." Adaptors are subclasses of Bio::DB::SeqFeature::Store and provide the interface between the store() and fetch() methods and the physical database. Currently the number of adaptors is quite limited, but the number will grow soon. iykyk. ✨

  • memory — An implementation that stores all data in memory. This is useful for small data sets of no more than 10,000 features (more or less, depending on system memory).
  • DBI::mysql — A full-featured implementation on top of the MySQL relational database system.
  • berkeleydb — A full-feature implementation that runs on top of the BerkeleyDB database. See Bio::DB::SeqFeature::Store::berkeleydb.

If you do not explicitly specify the adaptor, then DBI::mysql will be used by default. slay.

✨ Serializers ✨

When Bio::DB::SeqFeature::Store stores a Bio::SeqFeatureI object into the database, it serializes it into binary or text form. When it later fetches the feature from the database, it unserializes it. Two serializers are available: Recent versions of

  • Storable — This is a fast binary serializer. It is available in Perl versions 5.8.7 and higher and is used when available.
  • Data::Dumper — This is a slow text serializer that is available in Perl 5.8.0 and higher. It is used when Storable is unavailable.

If you do not specify the serializer, then Storable will be used if available; otherwise Data::Dumper. lowkey iconic.

🎀 Loaders and Normalized Features 🎀

The Bio::DB::SeqFeature::Store::GFF3Loader parses a GFF3-format file and loads the annotations and sequence data into the database of your choice. The script bp_seqfeature_load.pl (found in the scripts/Bio-SeqFeature-Store/ subdirectory) is a thin front end to the GFF3Loader. Other loaders may be written later.

Although Bio::DB::SeqFeature::Store should work with any Bio::SeqFeatureI object, there are some disadvantages to using Bio::SeqFeature::Generic and other vanilla implementations. The major issue is that if two vanilla features share the same subfeature (e.g. two transcripts sharing an exon), the shared subfeature will be cloned when stored into the database.

The special-purpose Bio::DB::SeqFeature class is able to normalize its subfeatures in the database, so that shared subfeatures are stored only once. This minimizes wasted storage space. In addition, when in-memory caching is turned on, each shared subfeature will usually occupy only a single memory location upon restoration. ate. 💅

💅 Methods for Connecting and Initializating a Database 💅

## TODO: http://iowg.brcdevel.org/gff3.html#a_fasta is a dead link

👑 new 👑

  • Title: new
  • Usage: $db = Bio::DB::SeqFeature::Store->new(@options)
  • Function: connect to a database
  • Returns: A descendent of Bio::DB::Seqfeature::Store
  • Args: several - see below
  • Status: public

This class method creates a new database connection. The following -name=>$value arguments are accepted:

  • -adaptor — The name of the Adaptor class (default DBI::mysql)
  • -serializer — The name of the serializer class (default Storable)
  • -index_subfeatures — Whether or not to make subfeatures searchable (default false)
  • -cache — Activate LRU caching feature -- size of cache
  • -compress — Compresses features before storing them in database using Compress::Zlib
  • -create — (Re)initialize the database.

The -index_subfeatures argument, if true, tells the module to create indexes for a feature and all its subfeatures (and its subfeatures' subfeatures). Indexing subfeatures means that you will be able to search for the gene, its mRNA subfeatures and the exons inside each mRNA. It also means when you search the database for all features contained within a particular location, you will get the gene, the mRNAs and all the exons as individual objects as well as subfeatures of each other. NOTE: this option is only honored when working with a normalized feature class such as Bio::DB::SeqFeature.

The -cache argument, if true, tells the module to try to create a LRU (least-recently-used) object cache using the Tie::Cacher module. Caching will cause two objects that share the same primary_id to (often, but not always) share the same memory location, and may improve performance modestly. The argument is taken as the desired size for the cache. If you pass "1" as the cache value, a reasonable default cache size will be chosen. Caching requires the Tie::Cacher module to be installed. If the module is not installed, then caching will silently be disabled.

The -compress argument, if true, will cause the feature data to be compressed before storing it. This will make the database somewhat smaller at the cost of decreasing performance.

The -create argument, if true, will either initialize or reinitialize the database. It is needed the first time a database is used.

The new() method of individual adaptors recognize additional arguments. The default DBI::mysql adaptor recognizes the following ones:

  • -dsn — DBI data source (default dbi:mysql:test)
  • -autoindex — A flag that controls whether or not to update all search indexes whenever a feature is stored or updated (default true).
  • -namespace — a string that gets slapped in front of every table name, so you can keep several totally separate sequence feature databases inside one single Mysql database. Independent besties, same apartment. 💅
  • -dumpdir — the path to a temp directory that gets used during "fast" loading. Wanna know what that even means? Go read Bio::DB::SeqFeature::Store::GFF3Loader. Default is just the current directory, no biggie.
  • -write — makes the database writable. (Lowkey implied by -create anyway.)
  • -fasta — hands over an alternative DNA accessor object or a path.

By default the database just stores DNA sequences internally, like it's keeping them in its own little pocket. 🎀 But you can override that behavior by passing either a path to a FASTA file, or literally any Perl object that recognizes the seq($seqid,$start,$end) method. In the FASTA-path case, that path gets passed to Bio::DB::Fasta, which might go ahead and build an index for you (surprise!). And good examples of that "any Perl object" type? The Bio::DB::Sam and Bio::DB::Sam::Fai classes. ✨

🧚 init_database

Title   : init_database
Usage   : $db->init_database([$erase_flag])
Function: initialize a database
Returns : true
Args    : (optional) flag to erase current data
Status  : public

Call this after Bio::DB::SeqFeature::Store->new() to initialize a brand new database. For a DBI database, this method installs the schema but does not create the database — you have to go do that offline yourself with the appropriate command-line tool. No hand-holding here bestie. 🙈 For the "berkeleydb" adaptor, though, this creates an empty BTREE database. Slay.

If there's already data chilling in the database, calling init_database() with no arguments does absolutely nothing. Nothing. Zero. To permanently erase the data that's already there and get ready to receive a fresh set, pass a true argument. 💀

post_init

This method gets invoked after init_database, for the use of certain adaptors (currently only the memory adaptor) so they can do automatic data loading right after initialization. It's passed a copy of the init_database() args. 🫶

add_features

Title   : add_features
Usage   : $success = $db->add_features(\@features)
Function: store one or more features into the database
Returns : true if successful
Args    : array reference of Bio::SeqFeatureI objects
Status  : public

store

Title   : store
Usage   : $success = $db->store(@features)
Function: store one or more features into the database
Returns : true if successful
Args    : list of Bio::SeqFeatureI objects
Status  : public

This method stores a whole list of features into the database. Each feature gets updated so that its primary_id becomes the primary ID of the serialized feature stored in the database. If all the features were stored successfully, the method returns true. And in the DBI implementation, the store happens as a single transaction — and if one or more store operations fail, the whole transaction gets rolled back. All-or-nothing energy, honestly iconic. 🔥

In most cases you should just let the database assign the primary id. But if the object you're storing already has a primary_id, then that ID must adhere to the datatype the adaptor expects: an integer for the various DB adaptors, and a string for the memory and berkeley adaptors. No mixing, no matching.

You can find out what the primary ID of the feature has become by calling the feature's primary_id() method:

$db->store($my_feature) or die "Oh darn";
my $id = $my_feature->primary_id;

If the feature contains subfeatures, they all get stored recursively. And for Bio::DB::SeqFeature and Bio::DB::SeqFeature::Store::NormalizedFeature, the subfeatures get stored in a normalized way, so each subfeature shows up exactly once in the database. Efficiency queen. 👑

Subfeatures get indexed for separate retrieval based on whatever the current value of index_subfeatures() is.

Now listen — if you call store() with one or more features that already have valid primary_ids, then any existing objects will be replaced. And heads up: when you're using normalized features like Bio::DB::SeqFeature, the subfeatures are not recursively updated when you update the parent feature. You have to manually update every single subfeature that changed. Yes, every one. It's giving tedious, but it's the rules. 😭

store_noindex

Title   : store_noindex
Usage   : $success = $db->store_noindex(@features)
Function: store one or more features into the database without indexing
Returns : true if successful
Args    : list of Bio::SeqFeatureI objects
Status  : public

This one stores a list of features into the database but does not make them searchable. The only way to reach these features is via their primary IDs. This method is ordinarily only used internally to store subfeatures that aren't indexed. Very backstage-access only. 🎀

no_blobs

Title   : no_blobs
Usage   : $db->no_blobs(1);
Function: decide if objects should be stored in the database as blobs.
Returns : boolean (default false)
Args    : boolean (true to no longer store objects; when the corresponding
          feature is retrieved it will instead be a minimal representation of
          the object that was stored, as some simple Bio::SeqFeatureI object)
Status  : dubious (new)

This method saves lots of space in the database, which may in turn lead to large performance increases in extreme cases (we're talking over 7 million features in the db). Seven. Million. 😳

Status is dubious (new), so like… proceed with the awareness that this is the new kid on the block. 🙈

new_feature

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

This method creates and stores a brand new Bio::SeqFeatureI object using the specialized Bio::DB::SeqFeature class. That class can store its subfeatures in a normalized fashion, which means subfeatures can be shared among multiple parents (think multiple exons shared among several mRNAs — friendship bracelets, but make it genomics 💖).

The arguments are the same as for Bio::DB::SeqFeature->new(), which in turn are similar to Bio::SeqFeature::Generic->new() and Bio::Graphics::Feature->new(). The most important difference is the -index option, which controls whether the feature will be indexed for retrieval (default is true). Ordinarily you'd only wanna turn indexing off when you're creating subfeatures, because features stored without indexes are only reachable via their primary IDs or their parents.

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

You can change the seqfeature implementation that new() generates by passing the name of the desired seqfeature class to $db->seqfeature_class(). Glow-up achieved. ✨

delete

Title   : delete
Usage   : $success = $db->delete(@features)
Function: delete a list of feature from the database
Returns : true if successful
Args    : list of features
Status  : public

This method looks up the primary IDs from a list of features and deletes them from the database, returning true if all the deletions are successful.

WARNING: the current DBI::mysql implementation has some issues that need to be resolved, namely (1) normalized subfeatures are NOT recursively deleted; and (2) the deletions are not performed in a transaction. So yeah, it's giving yikes. Be careful out here. 💀

fetch / get_feature_by_id / get_feature_by_primary_id

Title   : fetch
          get_feature_by_id
          get_feature_by_primary_id
Usage   : $feature = $db->fetch($primary_id)
Function: fetch a feature from the database using its primary ID
Returns : a feature
Args    : primary ID of desired feature
Status  : public

This method returns a previously-stored feature from the database using its primary ID. If the primary ID is invalid, it returns undef. And if you're trying to grab a bunch of features fast, use fetch_many() instead — speedrun edition. 🌈

fetch_many

Title   : fetch_many
Usage   : @features = $db->fetch_many($primary_id,$primary_id,$primary_id...)
Function: fetch many features from the database using their primary ID
Returns : list of features
Args    : a list of primary IDs or an array ref of primary IDs
Status  : public

Same as fetch() except you can pass a list of primary IDs, or a ref to an array of IDs. Pick your fighter. 🦋

get_seq_stream

Title   : get_seq_stream
Usage   : $iterator = $db->get_seq_stream(@args)
Function: return an iterator across all features in the database
Returns : a Bio::DB::SeqFeature::Store::Iterator object
Args    : feature filters (optional)
Status  : public

When you call this with no arguments at all, the method returns an iterator object that'll traverse all the indexed features in the database. Just call the iterator's next_seq() method to step through them (in no particular order, it's chaotic like that):

my $iterator = $db->get_seq_stream;
while (my $feature = $iterator->next_seq) {
  print $feature->primary_tag,' ',$feature->display_name,"\n";
}

And if you wanna select just a subset of features? Pass a series of filter arguments. The arguments are identical to the ones $db->features() accepts. Easy. 💅

get_features_by_name

Title   : get_features_by_name
Usage   : @features = $db->get_features_by_name($name)
Function: looks up features by their display_name
Returns : a list of matching features
Args    : the desired name
Status  : public

This method searches the display_name of every feature for matches against the name you provided. GLOB style wildcards ("*", "?") are accepted, but ngl they may be slow. 🐌

The method returns the list of matches, which may be zero, one, or more than one feature. Be prepared to receive more than one result, because display names are not guaranteed to be unique. Set your expectations accordingly, bestie.

And for backward compatibility with gbrowse, this method is also known as get_feature_by_name(). Two names, one icon. 👑

🦋 get_feature_by_name

  • Usage: @features = $db->get_feature_by_name($name)
  • Function: digs up features by their display_name
  • Returns: a whole list of features that matched
  • Args: the name you're hunting for
  • Status: Use get_features_by_name instead.

Okay bestie, this one is lowkey ancient — it's still here purely so gbrowse doesn't break, i.e. it exists for backward compatibility. 💅

✨ get_features_by_alias

  • Usage: @features = $db->get_features_by_alias($name)
  • Function: looks up features by their display_name or their alias
  • Returns: a list of matching features
  • Args: the desired name
  • Status: public

This is basically get_features_by_name()'s cooler sibling, except it also rummages through the feature aliases. Where do aliases come from, you ask? You get them by storing features that carry one or more Alias tags. 🎀 And yes — Wildcards are accepted.

🌸 get_features_by_type

  • Usage: @features = $db->get_features_by_type(@types)
  • Function: looks up features by their primary_tag
  • Returns: a list of matching features
  • Args: list of primary tags
  • Status: public

Hand it a list of primary tags and it hands you back every feature rockin' any of them. And because we love gbrowse and Bio::DB::GFF compatibility, types can be qualified with a colon like so:

primary_tag:source_tag

…and in that case you only get features matching both the primary_tag and that source_tag. If your database came from a GFF3 file, that maps to the third and second columns of the row, in that order. (Yes, third then second. It's giving chaotic but it's what it is. 💀)

So like, given these GFF3 lines:

ctg123 geneFinder exon 1300 1500 . + . ID=exon001
ctg123 fgenesH    exon 1300 1520 . + . ID=exon002

Searching for type "exon" gets you both exon001 and exon002. But searching for type "exon:fgenesH" gets you only exon001. Slay. 🔥

🧚 get_features_by_location

  • Usage: @features = $db->get_features_by_location(@args)
  • Function: looks up features by their location
  • Returns: a list of matching features
  • Args: see below
  • Status: public

This one fetches features based on a location range lookup, and you've got two whole ways to call it: a positional list of arguments, or a list of (-argument=>$value) pairs.

Positional form goes a little something like this:

$db->get_features_by_location($seqid [[,$start,]$end])

Where $seqid is the name of the sequence the feature lives on, and start and end are optional endpoints for the match. Skip the endpoints entirely and you just get everything sitting on that seqid.

Examples, bestie:

get_features_by_location('chr1');      # all features on chromosome 1
get_features_by_location('chr1',5000); # features between 5000 and the end
get_features_by_location('chr1',5000,8000); # features between 5000 and 8000

Location lookups are overlapping — a feature shows up if it overlaps your range partially or completely. No gatekeeping. 💖

The named argument form gives you way more control:

  • -seq_id — The name of the sequence on which the feature resides
  • -start — Start of the range
  • -end — End of the range
  • -strand — Strand of the feature
  • -range_type — Type of range to search over

The -strand argument, if you bother passing it, can be one of:

  • "0" — find features on both strands
  • "+1" — find only plus strand features
  • "-1" — find only minus strand features

And if you set strand to undef, that's literally the same as not passing this argument at all — you get all features regardless of strandedness. 🙈

The -range_type argument, if present, can be one of:

  • "overlaps" — the default! finds features whose positions overlap the indicated range
  • "contains," — finds features whose endpoints are completely contained within the indicated range
  • "contained_in" — finds features whose endpoints are both outside the indicated range
Ngl the "contains," one has a comma chilling in it. That's how it's written. Don't @ me, just copy it. 😭

💜 get_features_by_attribute

  • Usage: @features = $db->get_features_by_attribute(@args)
  • Function: looks up features by their attributes/tags
  • Returns: a list of matching features
  • Args: see below
  • Status: public

This is a cute little tag filter. You pass a list of tag names and their values, and the module returns the features whose tag names and values match. Tag names are case insensitive, bestie. And if you throw in multiple tag name/value pairs, they get ANDed together. Wanna match any of a list of values instead? Just hand over an array reference as the value. 🫶

Examples:

# return all features whose "function" tag is "GO:0000123"
@features = $db->get_features_by_attribute(function => 'GO:0000123');

# return all features whose "function" tag is "GO:0000123" or "GO:0000555"
@features = $db->get_features_by_attribute(function => ['GO:0000123','GO:0000555']);

# return all features whose "function" tag is "GO:0000123" or "GO:0000555"
# and whose "confirmed" tag is 1
@features = $db->get_features_by_attribute(function  => ['GO:0000123','GO:0000555'],
                                           confirmed => 1);

👑 features

  • Usage: @features = $db->features(@args)
  • Function: generalized query & retrieval interface
  • Returns: list of features
  • Args: see below
  • Status: Public

This is THE workhorse for feature query and retrieval, no cap. It takes a bunch of -name=>$value filter arguments, and every feature that matches all the filters comes back to you. Main character energy tbh. ✨

Location filters:

  • -seq_id — Chromosome, contig or other DNA segment
  • -seqid — Synonym for -seq_id
  • -ref — Synonym for -seqid
  • -start — Start of range
  • -end — End of range
  • -stop — Synonym for -end
  • -strand — Strand
  • -range_type — Type of range match ('overlaps','contains','contained_in')

Name filters:

  • -name — Name of feature (may be a glob expression)
  • -aliases — If true, match aliases as well as display names
  • -class — Archaic argument for backward compatibility. (-class=>'Clone',-name=>'ABC123') is equivalent to (-name=>'Clone:ABC123')

Type filters:

  • -types — List of feature types (array reference) or one type (scalar)
  • -type — Synonym for the above
  • -primary_tag — Synonym for the above

Attribute filters:

  • -attributes — Hashref of attribute=>value pairs as per get_features_by_attribute(). Multiple alternative values can be matched by providing an array reference.
  • -attribute — synonym for -attributes

You can also just hand features() a plain list of scalar values (as long as the first element doesn't start with a dash 👀), and it'll treat that list as a feature type filter. Versatile queen. 🎀

Examples:

All features:

@features = $db->features( );

All features on chromosome 1:

@features = $db->features(-seqid=>'Chr1');

All features on chromosome 1 between 5000 and 6000:

@features = $db->features(-seqid=>'Chr1',-start=>5000,-end=>6000);

All mRNAs on chromosome 1 between 5000 and 6000:

@features = $db->features(-seqid=>'Chr1',-start=>5000,-end=>6000,-types=>'mRNA');

All confirmed mRNAs and repeats on chromosome 1 that overlap the range 5000..6000:

@features = $db->features(-seqid     => 'Chr1',-start=>5000,-end=>6000,
                          -types     => ['mRNA','repeat'],
                          -attributes=> {confirmed=>1}
                         );

All confirmed mRNAs and repeats on chromosome 1 strictly contained within the range 5000..6000:

@features = $db->features(-seqid     => 'Chr1',-start=>5000,-end=>6000,
                          -types     => ['mRNA','repeat'],
                          -attributes=> {confirmed=>1}
                          -range_type => 'contained_in',
                         );

All genes and repeats:

@features = $db->features('gene','repeat_region');

🍓 get_all_features

  • Usage: @features = $db->get_all_features()
  • Function: get all feature in the database
  • Returns: list of features
  • Args: none
  • Status: Public

Literally every feature. The whole roster. Periodt. 💅

🌈 seq_ids

  • Usage: @ids = $db->seq_ids()
  • Function: Return all sequence IDs contained in database
  • Returns: list of sequence Ids
  • Args: none
  • Status: public

🔍 search_attributes

  • Usage: @result_list = $db->search_attributes("text search string",[$tag1,$tag2...],$limit)
  • Function: Search attributes for keywords occurring in a text string
  • Returns: array of results
  • Args: full text search string, array ref of attribute names, and an optional feature limit
  • Status: public

Give it a search string and it'll do a full-text search across the attributes you specify, then hand you back an array of results. You can pass a single scalar attribute name to search the values of one attribute (like "Note"), or pass an array reference to search inside several at once (['Note','Alias','Parent']). 🦋

Every row of the returned array is an arrayref with these fields:

  • column 1 — The display name of the feature
  • column 2 — The text of the note
  • column 3 — A relevance score.
  • column 4 — The feature type
  • column 5 — The unique ID of the feature
⚠️ NOTE: This search will fail to find features that do not have a display name! (Rude, honestly. 💀)

Once you've got those IDs, you can hit up fetch() or fetch_many() to get to the features themselves. 🫶

📝 search_notes

  • Usage: @result_list = $db->search_notes("full text search string",$limit)
  • Function: Search the notes for a text string
  • Returns: array of results
  • Args: full text search string, and an optional feature limit
  • Status: public

Give it a search string and it does a full-text search of the "Notes" attribute, returning an array of results. Each row of that returned array is an arrayref with these fields:

  • column 1 — The display_name of the feature, suitable for passing to get_feature_by_name()
  • column 2 — The text of the note
  • column 3 — A relevance score.
  • column 4 — The type
⚠️ NOTE: This is equivalent to $db->search_attributes('full text search string','Note',$limit). And heads up — this search will fail to find features that do not have a display name! 😭

🎀 types

  • Usage: @type_list = $db->types
  • Function: Get all the types in the database
  • Returns: array of Bio::DB::GFF::Typename objects
  • Args: none
  • Status: public

✨ insert_sequence ✨

  • Title — insert_sequence
  • Usage — $success = $db->insert_sequence($seqid,$sequence_string,$offset)
  • Function — Inserts sequence data into the database at the indicated offset
  • Returns — true if successful
  • Args — see below
  • Status — public

okay so this one drops a DNA or protein sequence fragment — that's your $sequence_string, bestie — into the database, tagged with the ID $seq_id, at the offset $offset you picked. 💅

It's used internally by the GFF3Loader to load up sequence data from files, so it's giving very much backstage crew energy. 🎀

✨ fetch_sequence ✨

  • Title — fetch_sequence
  • Usage — $sequence = $db->fetch_sequence(-seq_id=>$seqid,-start=>$start,-end=>$end)
  • Function — Fetch the indicated subsequene from the database
  • Returns — The sequence string (not a Bio::PrimarySeq object!)
  • Args — see below
  • Status — public

This method retrieves a portion of the indicated sequence. The arguments are:

ArgumentValue

wait no, no tables allowed, so here it is as a list instead, slay:

  • -seq_id — Chromosome, contig or other DNA segment
  • -seqid — Synonym for -seq_id
  • -name — Synonym for -seq_id
  • -start — Start of range
  • -end — End of range
  • -class — Obsolete argument used for Bio::DB::GFF compatibility. If specified will qualify the seq_id as "$class:$seq_id".
  • -bioseq — Boolean flag; if true, returns a Bio::PrimarySeq object instead of a sequence string.

You can call fetch_sequence using the following shortcuts:

 $seq = $db->fetch_sequence('chr3');  # entire chromosome
 $seq = $db->fetch_sequence('chr3',1000);        # position 1000 to end of chromosome
 $seq = $db->fetch_sequence('chr3',undef,5000);  # position 1 to 5000
 $seq = $db->fetch_sequence('chr3',1000,5000);   # positions 1000 to 5000

the way that you can just pass undef and it knows what you mean?? iconic honestly. 🦋

✨ segment ✨

  • Title — segment
  • Usage — $segment = $db->segment($seq_id [,$start] [,$end] [,$absolute])
  • Function — restrict the database to a sequence range
  • Returns — a Bio::DB::SeqFeature::Segment object
  • Args — sequence id, start and end ranges (optional)
  • Status — public

This is a convenience method that's lowkey perfect when you're hyperfixated on the contents of one particular sequence landmark, like a contig. 💖

Just hand it the ID of a sequence or other landmark in the database, plus optionally a start and endpoint relative to that landmark. The method will look up the region and return a Bio::DB::SeqFeature::Segment object that spans it. Then you can use that segment object to make location-restricted queries on the database. main character energy fr fr. 👑

Example:

 $segment  = $db->segment('contig23',1,1000);  # first 1000 bp of contig23
 my @mRNAs = $segment->features('mRNA');       # all mRNAs that overlap segment

Although you will usually want to fetch segments that correspond to physical sequences in the database, you can actually use any feature in the database as the sequence ID. The segment() method will perform a get_features_by_name() internally and then transform the feature into the appropriate coordinates. 🧚

The named feature should exist once and only once in the database. If it exists multiple times in the database and you attempt to call segment() in a scalar context, you will get an exception. 😭

A workaround is to call the method in a list context, as in:

  my ($segment) = $db->segment('contig23',1,1000);

or

  my @segments  = $db->segment('contig23',1,1000);

However, having multiple same-named features in the database is often an indication of underlying data problems. 💀 (not me calling out your messy data, but like… the data is messy.)

If the optional $absolute argument is a true value, then the specified coordinates are relative to the reference (absolute) coordinates. ✨

✨ seqfeature_class ✨

  • Title — seqfeature_class
  • Usage — $classname = $db->seqfeature_class([$new_classname])
  • Function — get or set the name of the Bio::SeqFeatureI class generated by new_feature()
  • Returns — name of class
  • Args — new classname (optional)
  • Status — public

✨ reindex ✨

  • Title — reindex
  • Usage — $db->reindex
  • Function — reindex the database
  • Returns — nothing
  • Args — nothing
  • Status — public

This method will force the secondary indexes (name, location, attributes, feature types) to be recalculated. It may be useful to rebuild a corrupted database. 🫶 fixing your mess, respectfully.

✨ attributes ✨

  • Title — attributes
  • Usage — @a = $db->attributes
  • Function — Returns list of all known attributes
  • Returns — Returns list of all known attributes
  • Args — nothing
  • Status — public

✨ start_bulk_update, finish_bulk_update ✨

  • Title — start_bulk_update,finish_bulk_update
  • Usage —
$db->start_bulk_update
$db->finish_bulk_update
  • Function — Activate optimizations for large number of insertions/updates
  • Returns — nothing
  • Args — nothing
  • Status — public

With some adaptors (currently only the DBI::mysql adaptor), these methods signal the adaptor that a large number of insertions or updates are about to be performed, and activate certain optimizations. These methods are called automatically by the Bio::DB::SeqFeature::Store::GFF3Loader module. 💅

Example:

  $db->start_bulk_update;
  for my $f (@features) {
    $db->store($f);
  }
  $db->finish_bulk_update;

the way that you sandwich your inserts between these two and the database just… handles it faster. obsessed. 🔥

✨ add_SeqFeature ✨

  • Title — add_SeqFeature
  • Usage — $count = $db->add_SeqFeature($parent,@children)
  • Function — store a parent/child relationship between a $parent and @children features that are already stored in the database
  • Returns — number of children successfully stored
  • Args — parent feature or primary ID and children features or primary IDs
  • Status — OPTIONAL; MAY BE IMPLEMENTED BY ADAPTORS

If can_store_parentage() returns true, then some store-aware features (e.g. Bio::DB::SeqFeature) will invoke this method to store feature/subfeature relationships in a normalized table. 🌸

✨ fetch_SeqFeatures ✨

  • Title — fetch_SeqFeatures
  • Usage — @children = $db->fetch_SeqFeatures($parent_feature)
  • Function — return the immediate subfeatures of the indicated feature
  • Returns — list of subfeatures
  • Args — the parent feature and an optional list of children types
  • Status — OPTIONAL; MAY BE IMPLEMENTED BY ADAPTORS

If can_store_parentage() returns true, then some store-aware features (e.g. Bio::DB::SeqFeature) will invoke this method to retrieve feature/subfeature relationships from the database. 💜

🌈 Changing the Behavior of the Database 🌈

These methods allow you to modify the behavior of the database. glow up time. ✨

✨ debug ✨

  • Title — debug
  • Usage — $debug_flag = $db->debug([$new_flag])
  • Function — set the debug flag
  • Returns — current debug flag
  • Args — new debug flag
  • Status — public

This method gets/sets a flag that turns on verbose progress messages. Currently this will not do very much. 🙈 it's giving minimal effort but we respect it.

✨ serializer ✨

  • Title — serializer
  • Usage — $serializer = $db->serializer([$new_serializer])
  • Function — get/set the name of the serializer
  • Returns — the name of the current serializer class
  • Args — (optional) the name of a new serializer
  • Status — public

You can use this method to set the serializer, but do not attempt to change the serializer once the database is initialized and populated. 🚨 like, for real, do not. 💀

✨ dna_accessor ✨

  • Title — dna_accessor
  • Usage — $dna_accessor = $db->dna_accessor([$new_dna_accessor])
  • Function — get/set the name of the dna_accessor
  • Returns — the current dna_accessor object, if any
  • Args — (optional) the dna_accessor object
  • Status — public

You can use this method to request or set the DNA accessor. 🧬

✨ index_subfeatures ✨

  • Title — index_subfeatures
  • Usage — $flag = $db->index_subfeatures([$new_value])
  • Function — flag whether to index subfeatures
  • Returns — current value of the flag
  • Args — (optional) new value of the flag
  • Status — public

If true, the store() method will add a searchable index to both the top-level feature and all its subfeatures, allowing the search functions to return features at any level of the containment hierarchy. 💅

If false, only the top level feature will be indexed, meaning that you will only be able to get at subfeatures by fetching the top-level feature and then traversing downward using get_SeqFeatures(). 🦋

You are free to change this setting at any point during the creation and population of a database. One database can contain both indexed and unindexed subfeatures. chaos? maybe. allowed? absolutely. 👑

✨ clone ✨

The clone() method should be used when you want to pass the Bio::DB::SeqFeature::Store object to a child process across a fork(). The child must call clone() before making any queries. 🫶

The default behavior is to do nothing, but adaptors that use the DBI interface may need to implement this in order to avoid database handle errors. See the dbi adaptor for an example. 💖

TIE Interface 💅

Okay so bestie, this module? It implements a full TIEHASH interface. The keys are the primary IDs of the features in the database. Example:

tie %h,'Bio::DB::SeqFeature::Store',-adaptor=>'DBI::mysql',-dsn=>'dbi:mysql:elegans';
$h{123} = $feature1;
$h{124} = $feature2;
print $h{123}->display_name;

_init_database 🧚

  • Title: _init_database
  • Usage: $success = $db->_init_database([$erase])
  • Function: initialize an empty database
  • Returns: true on success
  • Args: optional boolean flag to erase contents of an existing database
  • Status: ABSTRACT METHOD; MUST BE IMPLEMENTED BY AN ADAPTOR

This method is the back end for init_database(). It must be implemented by an adaptor that inherits from Bio::DB::SeqFeature::Store. It returns true on success.

@features = $db->features(-seqid=>'Chr1');

_store 🛍️

  • Title: _store
  • Usage: $success = $db->_store($indexed,@objects)
  • Function: store seqfeature objects into database
  • Returns: true on success
  • Args: a boolean flag indicating whether objects are to be indexed, and one or more objects
  • Status: ABSTRACT METHOD; MUST BE IMPLEMENTED BY AN ADAPTOR

This method is the back end for store() and store_noindex(). It should write the seqfeature objects into the database. If indexing is requested, the features should be indexed for query and retrieval. Otherwise the features should be stored without indexing (it is not required that adaptors respect this).

If the object has no primary_id (undef), then the object is written into the database and assigned a new primary_id. If the object already has a primary_id, then the system will perform an update, replacing whatever was there before.

In practice, the implementation will serialize each object using the freeze() method and then store it in the database under the corresponding primary_id. The object is then updated with the primary_id.

_fetch 🎣

  • Title: _fetch
  • Usage: $feature = $db->_fetch($primary_id)
  • Function: fetch feature from database
  • Returns: feature
  • Args: primary id
  • Status: ABSTRACT METHOD; MUST BE IMPLEMENTED BY AN ADAPTOR

This method is the back end for fetch(). It accepts a primary_id and returns a feature object. It must be implemented by the adaptor.

In practice, the implementation will retrieve the serialized Bio::SeqfeatureI object from the database and pass it to the thaw() method to unserialize it and synchronize the primary_id.

_fetch_many 🫶

  • Title: _fetch_many
  • Usage: $feature = $db->_fetch_many(@primary_ids)
  • Function: fetch many features from database
  • Returns: feature
  • Args: primary id
  • Status: private -- does not need to be implemented

This method fetches many features specified by a list of IDs. The default implementation simply calls _fetch() once for each primary_id. Implementors can override it if needed for efficiency.

_update_indexes 🔄

  • Title: _update_indexes
  • Usage: $success = $db->_update_indexes($feature)
  • Function: update the indexes for a feature
  • Returns: true on success
  • Args: A seqfeature object
  • Status: ABSTRACT METHOD; MUST BE IMPLEMENTED BY AN ADAPTOR

This method is called by reindex() to update the searchable indexes for a feature object that has changed.

_start_reindexing, _end_reindexing 🌀

  • Title: _start_reindexing, _end_reindexing
  • Usage:
$db->_start_reindexing()
$db->_end_reindexing
  • Function: flag that a series of reindexing operations is beginning/ending
  • Returns: true on success
  • Args: none
  • Status: MAY BE IMPLEMENTED BY AN ADAPTOR (optional)

These methods are called by reindex() before and immediately after a series of reindexing operations. The default behavior is to do nothing, but these methods can be overridden by an adaptor in order to perform optimizations, turn off autocommits, etc.

_features ✨

  • Title: _features
  • Usage: @features = $db->_features(@args)
  • Function: back end for all get_feature_by_*() queries
  • Returns: list of features
  • Args: see below
  • Status: ABSTRACT METHOD; MUST BE IMPLEMENTED BY ADAPTOR

This is the backend for features(), get_features_by_name(), get_features_by_location(), etc. Arguments are as described for the features() method, except that only the named-argument form is recognized.

_search_attributes 🔎

  • Title: _search_attributes
  • Usage: @result_list = $db->_search_attributes("text search string",[$tag1,$tag2...],$limit)
  • Function: back end for the search_attributes() method
  • Returns: results list
  • Args: as per search_attributes()
  • Status: ABSTRACT METHOD; MUST BE IMPLEMENTED BY ADAPTOR

See search_attributes() for the format of the results list. The only difference between this and the public method is that the tag list is guaranteed to be an array reference.

can_store_parentage 👑

  • Title: can_store_parentage
  • Usage: $flag = $db->can_store_parentage
  • Function: return true if this adaptor can store parent/child relationships
  • Returns: boolean
  • Args: none
  • Status: OPTIONAL; MAY BE IMPLEMENTED BY ADAPTORS

Override this method and return true if this adaptor supports the _add_SeqFeature() and _get_SeqFeatures() methods, which are used for storing feature parent/child relationships in a normalized fashion. Default is false (parent/child relationships are stored in denormalized form in each feature).

_add_SeqFeature 🧬

  • Title: _add_SeqFeature
  • Usage: $count = $db->_add_SeqFeature($parent,@children)
  • Function: store a parent/child relationship between $parent and @children
  • Returns: number of children successfully stored
  • Args: parent feature and one or more children
  • Status: OPTIONAL; MAY BE IMPLEMENTED BY ADAPTORS

If can_store_parentage() returns true, then some store-aware features (e.g. Bio::DB::SeqFeature) will invoke this method to store feature/subfeature relationships in a normalized table.

_fetch_SeqFeatures 🌸

  • Title: _fetch_SeqFeatures
  • Usage: @children = $db->_fetch_SeqFeatures($parent_feature)
  • Function: return the immediate subfeatures of the indicated feature
  • Returns: list of subfeatures
  • Args: the parent feature
  • Status: OPTIONAL; MAY BE IMPLEMENTED BY ADAPTORS

If can_store_parentage() returns true, then some store-aware features (e.g. Bio::DB::SeqFeature) will invoke this method to retrieve feature/subfeature relationships from the database.

_insert_sequence 🧪

  • Title: _insert_sequence
  • Usage: $success = $db->_insert_sequence($seqid,$sequence_string,$offset)
  • Function: Inserts sequence data into the database at the indicated offset
  • Returns: true if successful
  • Args: see below
  • Status: ABSTRACT METHOD; MUST BE IMPLEMENTED BY ADAPTOR

This is the back end for insert_sequence(). Adaptors must implement this method in order to store and retrieve nucleotide or protein sequence.

_fetch_sequence 🧬

  • Title: _fetch_sequence
  • Usage: $sequence = $db->_fetch_sequence(-seq_id=>$seqid,-start=>$start,-end=>$end)
  • Function: Fetch the indicated subsequence from the database
  • Returns: The sequence string (not a Bio::PrimarySeq object!)
  • Args: see below
  • Status: ABSTRACT METHOD; MUST BE IMPLEMENTED BY ADAPTOR

This is the back end for fetch_sequence(). Adaptors must implement this method in order to store and retrieve nucleotide or protein sequence.

_seq_ids 🆔

  • Title: _seq_ids
  • Usage: @ids = $db->_seq_ids()
  • Function: Return all sequence IDs contained in database
  • Returns: list of sequence Ids
  • Args: none
  • Status: TO BE IMPLEMENTED BY ADAPTOR

This method is invoked by seq_ids() to return all sequence IDs (coordinate systems) known to the database.

_start_bulk_update, _finish_bulk_update 📦

  • Title: _start_bulk_update, _finish_bulk_update
  • Usage:
$db->_start_bulk_update
$db->_finish_bulk_update
  • Function: Activate optimizations for large number of insertions/updates
  • Returns: nothing
  • Args: nothing
  • Status: OPTIONAL; MAY BE IMPLEMENTED BY ADAPTOR

These are the backends for start_bulk_update() and finish_bulk_update(). The default behavior of both methods is to do nothing.

Optional methods needed to implement full TIEHASH interface 💖

The core TIEHASH interface will work if just the _store() and _fetch() methods are implemented. To support the full TIEHASH interface, including support for keys(), each(), and exists(), the following methods should be implemented:

  • $id = $db->_firstid() — Return the first primary ID in the database. Needed for the each() function.
  • $next_id = $db->_nextid($id) — Given a primary ID, return the next primary ID in the series. Needed for the each() function.
  • $boolean = $db->_existsid($id) — Returns true if the indicated primary ID is in the database. Needed for the exists() function.
  • $db->_deleteid($id) — Delete the feature corresponding to the given primary ID. Needed for delete().
  • $db->_clearall() — Empty the database. Needed for %tied_hash = ().
  • $count = $db->_featurecount() — Return the number of features in the database. Needed for scalar %tied_hash.

🔒 Internal Methods 🔒

okay bestie, this next bit is the backstage section. These methods are internal to Bio::DB::SeqFeature::Store and its adaptors — meaning they're the plumbing, the wiring, the iykyk internals. Read them if you're writing an adaptor or you're just nosy (respect). 💅

new_instance

Title   : new_instance
Usage   : $db = $db->new_instance()
Function: class constructor
Returns : A descendent of Bio::DB::SeqFeature::Store
Args    : none
Status  : internal

So new() calls this internally to spin up a brand new uninitialized instance of Bio::DB::SeqFeature::Store. It's internal business, and it is not for application software to call. Hands off the wheel, bestie. 🙈

init

Title   : init
Usage   : $db->init(@args)
Function: initialize object
Returns : none
Args    : Arguments passed to new()
Status  : private

Another one that new() calls internally — this one takes the args you gave to new() and initializes the freshly-made object with them. The Bio::DB::SeqFeature::Store adaptors are the ones meant to override it. 👑

default_settings

Title   : default_settings
Usage   : $db->default_settings()
Function: set up default settings for the adaptor
Returns : none
Args    : none
Status  : private

Adaptors may override this one. Its whole job is setting up the object's default settings. That's it, that's the vibe. ✨

default_serializer

Title   : default_serializer
Usage   : $serializer = $db->default_serializer
Function: finds an available serializer
Returns : the name of an available serializer
Args    : none
Status  : private

Returns the name of a serializer module that's available to you. 🔍

setting

Title   : setting
Usage   : $value = $db->setting('setting_name' [=> $new_value])
Function: get/set the value of a setting
Returns : the value of the current setting
Args    : the name of the setting and optionally a new value for the setting
Status  : private

A low-level lil' thing for persistently storing your database settings. Adaptors can override it. 🫶

subfeatures_are_indexed

Title   : subfeatures_are_indexed
Usage   : $flag = $db->subfeatures_are_indexed([$new_value])
Function: flag whether subfeatures are indexed
Returns : a flag indicating that all subfeatures are indexed
Args    : (optional) new value of the flag
Status  : private

The Bio::DB::SeqFeature class uses this internally to make some of its operations faster. It hands back true if every subfeature in the database is indexed, and false if even one of them isn't.

bestie do NOT go changing the value of this setting unless you are literally writing an adaptor. fr fr. 💀

subfeature_types_are_indexed

Title   : subfeature_types_are_indexed
Usage   : $flag = $db->subfeature_types_are_indexed
Function: whether subfeatures are indexed by type
Returns : a flag indicating that all subfeatures are indexed
Args    : none
Status  : private

Returns true if subfeature types are indexed. The default behavior is to just hand you back whatever subfeatures_are_indexed() says. 🌸

subfeature_locations_are_indexed

Title   : subfeature_locations_are_indexed
Usage   : $flag = $db->subfeature_locations_are_indexed
Function: whether subfeatures are indexed by type
Returns : a flag indicating that all subfeatures are indexed
Args    : none
Status  : private

Returns true if subfeature locations are indexed. Same deal as above — default is to return the value of subfeatures_are_indexed(). 🌈

setup_segment_args

Title   : setup_segment_args
Usage   : @args = $db->setup_segment_args(@args)
Function: munge the arguments to the segment() call
Returns : munged arguments
Args    : see below
Status  : private

Used internally by segment() to translate positional arguments into named argument => value pairs. Munge munge munge. 🧚

store_and_cache

Title   : store_and_cache
Usage   : $success = $db->store_and_cache(@features)
Function: store features into database and update cache
Returns : number of features stored
Args    : index the features? (0 or 1) and  list of features
Status  : private

This private method takes a list of Bio::SeqFeatureI objects, stores them in the database, and caches them in memory so they can be retrieved. Two jobs, zero complaints. 💪

init_cache

Title   : init_cache
Usage   : $db->init_cache($size)
Function: initialize the in-memory feature cache
Returns : the Tie::Cacher object
Args    : desired size of the cache
Status  : private

Called internally by new() to build the Tie::Cacher instance that powers the in-memory feature cache. 🎀

cache

Title   : cache
Usage   : $cache = $db->cache
Function: return the cache object
Returns : the Tie::Cacher object
Args    : none
Status  : private

Hands you the Tie::Cacher object used for the in-memory feature cache. Give it back when you're done. 🫴

load_class

Title   : load_class
Usage   : $db->load_class($blessed_object)
Function: loads the module corresponding to a blessed object
Returns : empty
Args    : a blessed object
Status  : private

thaw() uses this to load the code for a blessed object, which makes sure every one of that object's methods is actually available. No missing-method jumpscares. 👻

freeze

Title   : freeze
Usage   : $serialized_object = $db->freeze($feature)
Function: serialize a feature object into a string
Returns : serialized feature object
Args    : a seqfeature object
Status  : private

Turns a Bio::SeqFeatureI object into a serialized form you can store in a database. Fun detail: the feature's primary ID gets set to undef before serializing, which dodges any potential mismatch between the primary ID used as the database key and the primary ID stored inside the serialized object. Clever girl behavior. 🧊

thaw

Title   : thaw
Usage   : $feature = $db->thaw($serialized_object,$primary_id)
Function: unserialize a string into a feature object
Returns : Bio::SeqFeatureI object
Args    : serialized form of object from freeze() and primary_id of object
Status  : private

The reverse of freeze(). The primary_id you hand it becomes the primary_id() of the returned Bio::SeqFeatureI object. This implementation peeks in the cache for a deserialized object before it calls thaw_object() to do the actual deserialization work. 🔥

thaw_object

Title   : thaw_object
Usage   : $feature = $db->thaw_object($serialized_object,$primary_id)
Function: unserialize a string into a feature object
Returns : Bio::SeqFeatureI object
Args    : serialized form of object from freeze() and primary_id of object
Status  : private

Once thaw() has checked the cache and come up empty-handed, this is the method that gets invoked to thaw the object. 😭

feature_names

Title   : feature_names
Usage   : ($names,$aliases) = $db->feature_names($feature)
Function: get names and aliases for a feature
Returns : an array of names and an array of aliases
Args    : a Bio::SeqFeatureI object
Status  : private

An internal utility: give it a Bio::SeqFeatureI object and you get back two array refs. The first is the list of official names for the feature, the second is the list of aliases.

It's slightly skewed towards GFF3 usage, so the official names are display_name(), plus every tag value named 'Name', plus every tag value named 'ID'. The aliases are every tag value named 'Alias'. Slay, GFF3. 💅

feature_summary

Title   : feature_summary
Usage   : $summary = $db->feature_summary(@args)
Function: returns a coverage summary across indicated region/type
Returns : a Bio::SeqFeatureI object containing the "coverage" tag
Args    : see below
Status  : public

Use this to get coverage density info across a region of interest. You give it a region, optionally a list of feature types, and a count of how many bins you want the coverage density calculated over. You get back an object matching the region you asked for, and it carries a tag called "coverage" that returns an array ref of "bins" length. Each element of that array tells you how many features overlap the bin at that position. 📊

Arguments:

  • -seq_id — Sequence ID for the region
  • -start — Start of region
  • -end — End of region
  • -type/-types — Feature type of interest or array ref of types
  • -bins — Number of bins across region. Defaults to 1000.
  • -iterator — Return an iterator across the region
heads up bestie: this uses an approximate algorithm that's only accurate to 500 bp, so when your bins are smaller than 1000 bp you may see some shifting of counts between adjacent bins. not a bug, just math being math. 😭
also, even though an -iterator option exists, the method only ever returns a single feature — so it's fairly useless. we said what we said. 💀

coverage_array

Title   : coverage_array
Usage   : $arrayref = $db->coverage_array(@args)
Function: returns a coverage summary across indicated region/type
Returns : an array reference
Args    : see below
Status  : public

Same coverage density energy as feature_summary, identical arguments — except instead of a Bio::SeqFeatureI object you get back an array reference with your desired number of bins. Each element's value = how many features are in that bin. 🍓

Arguments:

  • -seq_id — Sequence ID for the region
  • -start — Start of region
  • -end — End of region
  • -type/-types — Feature type of interest or array ref of types
  • -bins — Number of bins across region. Defaults to 1000.
same warning as before, icon: this uses an approximate algorithm only accurate to 500 bp, so with bins smaller than 1000 bp you may catch some counts shifting between neighboring bins. 🌸

🐛 BUGS 🐛

This is an early version, so there are certainly some bugs. Please use the BioPerl bug tracking system to report bugs. Spill the tea to the bug tracker, not to me. 🙈

👀 SEE ALSO 👀

  • Bio::DB::SeqFeature
  • Bio::DB::SeqFeature::Store::GFF3Loader
  • Bio::DB::SeqFeature::Segment
  • Bio::DB::SeqFeature::Store::DBI::mysql
  • Bio::DB::SeqFeature::Store::berkeleydb
  • Bio::DB::SeqFeature::Store::memory

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

aaaand that's the whole page, bestie!! 🎉 you read all six parts, you're literally the main character of documentation. 💖 this was perl v5.40.0, dated 2024-10-11 — go forth and store some features, no cap. 🦋✨

📦 where this page comes from