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

📦

version 1.7.5 · 4 versions

1.7.5 · ubuntu resolute, ubuntu stonking (latest)
1.7.4 · ubuntu jammy
1.7.4 · debian bookworm, ubuntu noble
1.7.5 · debian trixie

okay bestie, sit down, hydrate, and let me tell you about Bio::D...Loader(3pm) — that's a page from the User Contributed Perl Documentation section of the manual, and the full gorgeous name of the thing is Bio::DB::SeqFeature::Store::GFF2Loader. she's long, she's useful, and she's here to help. 💅

🌸 NAME 🌸

Bio::DB::SeqFeature::Store::GFF2Loader — it's literally the GFF2 file loader for Bio::DB::SeqFeature::Store. that's the whole vibe. she takes your GFF2 files and feeds them to your sequence feature store. no cap. 🧚

✨ SYNOPSIS ✨

here's the little ritual you perform, bestie — copy it, love it, make it yours:

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

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

my $loader = Bio::DB::SeqFeature::Store::GFF2Loader->new(-store    => $db,
                                                         -verbose  => 1,
                                                         -fast     => 1);

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

so like, walk through it with me: 🫶

you pull in Bio::DB::SeqFeature::Store and Bio::DB::SeqFeature::Store::GFF2Loader with use — gotta have both, they're a package deal.
you open your sequence database by making a new store: -adaptor => 'DBI::mysql', -dsn => 'dbi:mysql:test', and crucially -write => 1 because girl, you are about to WRITE. 👑
you spin up a loader with -store => $db, -verbose => 1 (so she talks to you), and -fast => 1 (so she zooms).
and then the main character moment: $loader->load('./my_genome.gff'); — boom, loaded. periodt. 💖

that's the intro, babe — the rest of this page keeps going, so stay tuned. more parts incoming. ✨

✨ DESCRIPTION ✨

okay so bestie, listen up 💖 The Bio::DB::SeqFeature::Store::GFF2Loader object parses GFF2-format sequence annotation files and loads them into Bio::DB::SeqFeature::Store databases. And for certain combos of SeqFeature classes and SeqFeature::Store databases, it has a whole "fast load" mode that will speed up your GFF2 loading by a factor of 5-10. yes really. slay. 🔥

The GFF2 file format got extended very slightly to make room for Bio::DB::SeqFeature::Store. First thing: the loader recognizes a brand new directive:

# #index-subfeatures [0|1]

pro tip: you can totally put a space between the two #s so that GFF2 validators stop being dramatic and complaining.

If this is true, then subfeatures are indexed (which is the default) so you can retrieve them with a query. Go peek at Bio::DB::SeqFeature::Store for the explanation of that. If it's false, then subfeatures can only be reached through their parent feature. Default = index all subfeatures. periodt. 💅

Second thing: the loader recognizes a new attribute tag called index, which — if it's present — controls indexing of the current feature. Example:

ctg123 . TF_binding_site 1000 1012 . + . ID=tfbs00001;index=1

Use this to flip indexing on and off, overriding the default for one specific feature. 👑

🎀 new

Title   : new
Usage   : $loader = Bio::DB::SeqFeature::Store::GFF2Loader->new(@options)
Function: create a new parser
Returns : a Bio::DB::SeqFeature::Store::GFF2Loader gff2 parser and loader
Args    : several - see below
Status  : public

This method makes a new GFF2 loader and hooks it up to a Bio::DB::SeqFeature::Store database. The arguments are -name=>$value pairs, described in this little table:

-store — a writable Bio::DB::SeqFeature::Store database handle.
-seqfeature_class — the name of the type of Bio::SeqFeatureI object to create and store in the database (Bio::DB::SeqFeature by default).
-sf_class — a shorter alias for -seqfeature_class.
-verbose — send progress info to standard error.
-fast — if true, activate fast loading (more on that below).
-chunk_size — set the storage chunk size for nucleotide/protein sequences (default 2000 bytes).
-tmp — indicate a temporary directory to use when loading non-normalized features.

When you call new(), a connection to a Bio::DB::SeqFeature::Store database should already have been established, and the database initialized (if that's appropriate). no cap.

Some combos of Bio::SeqFeatures and Bio::DB::SeqFeature::Store databases support a fast loading mode. Currently the only reliable implementation of fast loading is the combination of DBI::mysql with Bio::DB::SeqFeature. The other big restriction on fast loading is that a feature containing subfeatures must occur in the GFF2 file before any of its subfeatures. Otherwise, the subfeatures that showed up before the parent feature will not be attached to the parent correctly. 😭 This restriction does not apply to normal (slow) loading. good to know.

If you use an unnormalized feature class, like Bio::SeqFeature::Generic, then the loader needs to create a temporary database to cache features in until all their parts and subparts have been seen. That temporary database uses the "berkeleydb" adaptor. The -tmp option tells it which directory to create that database in. If it's not there, it defaults to the system default tmp directory specified by File::Spec->tmpdir().

The -chunk_size option lets you tune how DNA/Protein sequence is represented in the Store database. By default, sequences get split into 2000 base/residue chunks and then reassembled as needed. This dodges the whole problem of pulling an entire chromosome into memory just to fetch a short subsequence from somewhere in the middle. Depending on your usage patterns, you may want to tune this parameter with a chunk size bigger or smaller than the default. 🌸

🎀 load

Title   : load
Usage   : $count = $loader->load(@ARGV)
Function: load the indicated files or filehandles
Returns : number of feature lines loaded
Args    : list of files or filehandles
Status  : public

Once the loader exists, call its load() method with a list of GFF2 or FASTA file paths, or previously-opened filehandles, to load them into the database. Compressed files ending with .gz, .Z and .bz2 are automatically recognized and uncompressed on the fly. Paths starting with http: or ftp: get treated as URLs and opened using the LWP GET program (which has to be on your path, bestie).

FASTA files are recognized by their initial ">" character. Do not feed the loader a file that's neither GFF2 nor FASTA; I don't know what will happen, but it will probably not be what you expect. 💀

🎀 accessors

These read-only accessors return values passed in or created during new():

store() — the long-term Bio::DB::SeqFeature::Store object
tmp_store() — the temporary Bio::DB::SeqFeature::Store object used during loading
sfclass() — the Bio::SeqFeatureI class
fast() — whether fast loading is active
seq_chunk_size() — the sequence chunk size
verbose() — verbose progress messages

🎀 Internal Methods

These methods are used internally and may be overridden by subclasses. 🧚

default_seqfeature_class

$class = $loader->default_seqfeature_class

Return the default SeqFeatureI class (Bio::DB::SeqFeature).

subfeatures_normalized

$flag = $loader->subfeatures_normalized([$new_flag])

Get or set a flag indicating that the subfeatures are normalized. This is deduced from the SeqFeature class information.

subfeatures_in_table

$flag = $loader->subfeatures_in_table([$new_flag])

Get or set a flag indicating that feature/subfeature relationships are stored in a table. This is deduced from the SeqFeature class and Store information.

load_fh

$count = $loader->load_fh($filehandle)

Load the GFF2 data at the other end of the filehandle and return true if successful. Internally, load_fh() invokes:

start_load();
do_load($filehandle);
finish_load();

start_load, finish_load

These methods are called at the start and end of a filehandle load.

do_load

$count = $loader->do_load($fh)

This is called by load_fh() to load the GFF2 file's filehandle and return the number of lines loaded.

load_line

$loader->load_line($data);

Load a line of a GFF2 file. You must bracket this with calls to start_load() and finish_load()! 🙈

$loader->start_load();
$loader->load_line($_) while <FH>;
$loader->finish_load();

handle_meta

$loader->handle_meta($meta_directive)

This method is called to handle meta-directives such as ##sequence-region. The method will receive the directive with the initial ## stripped off.

handle_feature

$loader->handle_feature($gff2_line)

This method is called to process a single GFF2 line. It manipulates information stored in a data structure called $self->{load_data}.

store_current_feature

$loader->store_current_feature()

This method is called to store the currently active feature in the database. It uses a data structure stored in $self->{load_data}.

build_object_tree

$loader->build_object_tree()

This method gathers together features and subfeatures and builds the graph that connects them.

build_object_tree_in_tables

$loader->build_object_tree_in_tables()

This method gathers together features and subfeatures and builds the graph that connects them, assuming that parent/child relationships will be stored in a database table.

build_object_tree_in_features

$loader->build_object_tree_in_features()

This method gathers together features and subfeatures and builds the graph that connects them, assuming that parent/child relationships are stored in the seqfeature objects themselves.

attach_children

$loader->attach_children($store,$load_data,$load_id,$feature)

This recursively adds children to features and their subfeatures. It's called when subfeatures are directly contained within other features, rather than stored in a relational table.

fetch

my $feature = $loader->fetch($load_id)

Given a load ID (from the ID= attribute) this method returns the feature from the temporary database or the permanent one, depending on where it's stored.

add_segment

$loader->add_segment($parent,$child)

This method is used to add a split location to the parent.

parse_attributes

($reserved,$unreserved) = $loader->parse_attributes($attribute_line)

This method parses the information in the $attribute_line into two hashrefs — one holding the values of reserved attribute tags (e.g. ID) and the other holding the values of unreserved ones.

start_or_finish_sequence

$loader->start_or_finish_sequence('Chr9')

This method is called at the beginning and end of a fasta section.

load_sequence

$loader->load_sequence('gatttcccaaa')

This method is called to load some amount of sequence after start_or_finish_sequence() is first called.

open_fh

my $io_file = $loader->open_fh($filehandle_or_path)

This method opens up the indicated file or pipe, using some intelligence to recognize compressed files and URLs and do the right thing.

time

my $time = $loader->time

This method returns the current time in seconds, using Time::HiRes if available.

unescape

my $unescaped = GFF2Loader::unescape($escaped)

This is an internal utility. It's the same as CGI::Util::unescape, but it doesn't change pluses into spaces and ignores unicode escapes.

💀 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::Store, Bio::DB::SeqFeature::Segment, Bio::DB::SeqFeature::NormalizedFeature, Bio::DB::SeqFeature::GFF3Loader, Bio::DB::SeqFeature::Store::DBI::mysql, Bio::DB::SeqFeature::Store::berkeleydb

👑 AUTHOR

Lincoln Stein <lstein@cshl.org>.

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

and that's a wrap, bestie ✨ this page is from perl v5.40.0, dated 2024-10-11 — go forth and load those features, you absolute icon 🎀💖

📦 where this page comes from

ubuntu resolute: libbio-db-seqfeature-perl 1.7.5-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libbio-db-seqfeature-perl 1.7.5-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms