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

💖 Bio::D...Loader — the manual page, but make it slay ✨

okay bestie, so this is Bio::DB::SeqFeature::Store::Loader from the User Contributed Perl Documentation section of the perl manpages (section 3pm, iykyk) — and it's literally the loader for SeqFeature stores. grab a boba, we're going in 🧋

---

🌸 NAME 🌸

Bio::DB::SeqFeature::Store::Loader — Loader 💅

---

✨ SYNOPSIS ✨

# non-instantiable base class

no cap, that's the whole synopsis. it's a base class. you don't instantiate it directly, bestie 🫶

---

🦋 DESCRIPTION 🦋

so this is the base class for three lil modules that do the actual work:

• Bio::DB::SeqFeature::Loader::GFF3Loader
• Bio::DB::SeqFeature::Loader::GFFLoader
• Bio::DB::SeqFeature::Loader::FeatureFileLoader

please go read the manual pages for those modules, okay? this one is just the parent vibes 👑

🎀 new 🎀

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

this method creates a new GFF3 loader and establishes its connection with a Bio::DB::SeqFeature::Store database. the arguments are -name=>$value pairs, like this:

...jk we don't do tables here, so here's the list bestie 💖:

• -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 information to standard error.
• -fast — if true, activate fast loading (see 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.
• -map_coords — a code ref that will transform a list of ($ref,[$start1,$end1]...) coordinates into a list of ($newref,[$newstart1,$newend1]...).
• -index_subfeatures — indicate true if subfeatures should be indexed. default is true.
• -summary_stats — rebuild summary stats at the end of loading (not incremental, so it takes a long time 😭).

when you call new(), a connection to a Bio::DB::SeqFeature::Store database should already have been established and the database initialized (if appropriate). no skipping steps, bestie 🫶

some combos of Bio::SeqFeatures and Bio::DB::SeqFeature::Store databases support a fast loading mode. rn 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 that contains subfeatures must occur in the GFF3 file before any of its subfeatures. otherwise the subfeatures that occurred before the parent feature will not be attached to the parent correctly. this restriction does not apply to normal (slow) loading. okay periodt 💅

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. this temporary database uses the "berkeleydb" adaptor. the -tmp option specifies the directory where that database gets created. if it's not present, it defaults to the system default tmp directory specified by File::Spec->tmpdir().

the -chunk_size option lets you tune the representation of DNA/Protein sequence in the Store database. by default, sequences get split into 2000 base/residue chunks and then reassembled as needed. this avoids the problem of pulling a whole chromosome into memory just to fetch a short subsequence from somewhere in the middle. depending on your usage patterns, you may wish to tune this parameter with a chunk size larger or smaller than the default. tune it, bestie, it's giving optimization 🎀

🌈 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 is created, invoke its load() method with a list of GFF3 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 beginning with http: or ftp: are treated as URLs and opened using the LWP GET program (which must be on your path). yes queen, it does the fetching for you ✨

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

🧚 accessors 🧚

the following read-only accessors return values passed 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 👑

the following methods are used internally and may be overridden by subclasses. (main character energy for subclass authors only, bestie)

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 that indicates 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 that indicates 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 GFF3 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.

build_summary

$loader->build_summary

call this to rebuild the summary coverage statistics. this is done automatically if new() was passed a true value for -summary_stats at create time.

do_load

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

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

load_line

$loader->load_line($data);

load a line of a GFF3 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_feature

$loader->handle_feature($data_line)

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

handle_meta

$loader->handle_meta($data_line)

this method is called to process a single data 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}.

parse_attributes

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

this method parses the information contained in the $attribute_line into two hashrefs, one containing the values of reserved attribute tags (e.g. ID) and the other containing 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 doing the right thing. 💅

loaded_ids

my $ids    = $loader->loaded_ids;
my $id_cnt = @$ids;

after performing a load, this returns an array ref containing all the feature primary ids that were created during the load.

local_ids

my $ids    = $self->local_ids;
my $id_cnt = @$ids;

after performing a load, this returns an array ref containing all the load file IDs that were contained within the file just loaded.

time

my $time = $loader->time

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

unescape

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

this is an internal utility. it's the same as CGI::Util::unescape, but 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. (not me being the bug reporter, bestie, use the tracker 🙈)

---

🫶 SEE ALSO 🫶

• bioperl
• Bio::DB::SeqFeature::Store
• Bio::DB::SeqFeature::Segment
• Bio::DB::SeqFeature::NormalizedFeature
• Bio::DB::SeqFeature::Store::GFF3Loader
• Bio::DB::SeqFeature::Store::DBI::mysql
• Bio::DB::SeqFeature::Store::berkeleydb

---

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

---

and that's the whole page, bestie 🎀 sign-off time: this was perl v5.40.0, dated 2024-10-11, from the Bio::D...Loader(3pm) manual. go load some features, you've got this 💖✨🦋