Bio::DasI(3pm)

📦

version 1.7.8 · 3 versions

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

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 NAME 💖

Bio::DasI — DAS-style access to a feature database 🦋

(psst, it's the Bio::DasI(3pm) page, from the User Contributed Perl Documentation, and yes bestie, this is part 1 of 2 so buckle up 💅)

✨ SYNOPSIS ✨

okay so here's the vibe, literally just look at it:

# Open up a feature database somehow...
$db = Bio::DasI->new(@args);

@segments = $db->segment(-name  => 'NT_29921.4',
                         -start => 1,
                         -end   => 1000000);

# segments are Bio::Das::SegmentI - compliant objects

# fetch a list of features
@features = $db->features(-type=>['type1','type2','type3']);

# invoke a callback over features
$db->features(-type=>['type1','type2','type3'],
              -callback => sub { ... }
              );

$stream   = $db->get_seq_stream(-type=>['type1','type2','type3']);
while (my $feature = $stream->next_seq) {
   # each feature is a Bio::SeqFeatureI-compliant object
}

# get all feature types
@types   = $db->types;

# count types
%types   = $db->types(-enumerate=>1);

@feature = $db->get_feature_by_name($class=>$name);
@feature = $db->get_feature_by_target($target_name);
@feature = $db->get_feature_by_attribute($att1=>$value1,$att2=>$value2);
$feature = $db->get_feature_by_id($id);

$error = $db->error;

no cap, that's the whole mood right there 🔥

🌸 DESCRIPTION 🌸

Bio::DasI is a simplified alternative interface to sequence annotation databases — the ones the distributed annotation system uses (peep Bio::Das for that 🫶).

So the way this scheme works: the genome is represented as a series of features, and a subset of those features are named. And those named features? They're the reference points you use to pull back "segments" (check Bio::Das::SegmentI 💖), and those segments then become the basis for exploring the genome even further. It's giving ✨onion layers✨, bestie, one thing unlocks the next.

On top of a name, every feature also has a "class" — which is basically a namespace qualifier — and a "type", which describes what kind of feature it actually is. Das uses the GO consortium's ontology of feature types, so the type is actually an object of class Bio::Das::FeatureTypeI (see Bio::Das::FeatureTypeI, iykyk). And Bio::DasI gives you methods for interrogating the database for the types it contains, plus the counts of each type. iconic 💅

🫶 FEEDBACK 🫶

💌 Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules, fr fr. Send your comments and suggestions preferably to one of the Bioperl mailing lists — your participation is much appreciated, like genuinely 🥹

bioperl-l@bioperl.org

🧚 Support

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

and not to the module maintainer directly, bestie 🙈 Many experienced and reponsive experts will be able look at the problem and quickly address it. If at all possible, please include a thorough description of the problem with code and data examples. the more deets the better 💖

🐛 Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via the web:

https://github.com/bioperl/bioperl-live/issues

👑 AUTHOR - Lincoln Stein 👑

Email lstein@cshl.org 💌

okay that's the whole first chunk, and there's more coming so don't go anywhere 🌈💜

✨ APPENDIX ✨

okay bestie this is the part where we get into the actual methods, one by one, no skimming allowed. 💖 Internal methods usually start with an underscore, so if you see a _ at the front, that's the secret menu. iykyk.

🌸 new 🌸

Title   : new
Usage   : Bio::DasI->new(@args)
Function: Create new Bio::DasI object
Returns : a Bio::DasI object
Args    : see below

The new() method makes you a brand-new object, slay. 🎀 You hand it either one single argument that's a connection string, or this whole little list of -name=>value args:

-dsn — the connection string for the database 🗄️
-adaptor — name of an adaptor class to use when connecting
-aggregator — an array ref holding a list of aggregators, aka the "semantic mappers" to apply to the database
-user — authentication username
-pass — authentication password 🔐

and heads up, implementors of DasI are allowed to add other arguments on top of these. it's giving "menu has secret items". ✨

🦋 types 🦋

Title   : types
Usage   : $db->types(@args)
Function: return list of feature types in database
Returns : a list of Bio::Das::FeatureTypeI objects
Args    : see below

This routine hands you back a list of the feature types the database knows about. bonus: you can also find out how many times each feature shows up. 👑

Arguments are -option=>value pairs like this:

-enumerate — if true, count the features

The returned value is a list of Bio::Das::FeatureTypeI objects (go look at Bio::Das::FeatureTypeI).

and here's the lil plot twist 🫶: if -enumerate is true, the function returns a hash (not a hash reference, bestie, a real hash) where the keys are the stringified versions of Bio::Das::FeatureTypeI and the values are the number of times each feature appears in the database.

🧚 parse_types 🧚

Title   : parse_types
Usage   : $db->parse_types(@args)
Function: parses list of types
Returns : an array ref containing ['method','source'] pairs
Args    : a list of types in 'method:source' form
Status  : internal

This one takes an array of type names shaped like "method:source" and gives you back an array reference full of ['method','source'] pairs. it'll also happily accept a single argument that's an array reference containing the list of type names. versatile icon. 💅

🌈 segment 🌈

Title   : segment
Usage   : $db->segment(@args);
Function: create a segment object
Returns : segment object(s)
Args    : see below

This method generates a Bio::Das::SegmentI object (peep Bio::Das::SegmentI). once you've got that segment, you can use it to find overlapping features and the raw sequence. 🔥

When you make the segment() call, you tell it the ID of a sequence landmark (think an accession number, a clone, or a contig) plus a positional range relative to that landmark. If you don't give a range, the whole entire region the landmark spans gets used to generate the segment. no range, no problem.

Arguments are -option=>value pairs like so:

-name — ID of the landmark sequence.
-class — a namespace qualifier. the database does not have to honor namespace qualifiers, but if it does, this is where the qualifier goes.
-version — version number of the landmark. again, the database isn't required to honor versions, but if it does, this is where the version goes.
-start — start of the segment relative to the landmark. positions follow standard 1-based sequence rules. if you don't specify it, it defaults to the beginning of the landmark.
-end — end of the segment relative to the landmark. if you don't specify it, it defaults to the end of the landmark.

The return value is a list of Bio::Das::SegmentI objects. now here's the rule 🚨: if you call it in scalar context and there are no more than one segments that satisfy the request, then it's allowed to return the segment. otherwise? the method must throw a "multiple segment exception". it's giving strict, and honestly? respect.

⭐ features ⭐

Title   : features
Usage   : $db->features(@args)
Function: get all features, possibly filtered by type
Returns : a list of Bio::SeqFeatureI objects
Args    : see below
Status  : public

This routine grabs features out of the database regardless of position. use it to get everything, or just a subset based on their type. main character retrieval energy. 👑

Arguments are -option=>value pairs, as follows:

-types — list of feature types to return. the argument is an array of Bio::Das::FeatureTypeI objects, or a set of strings that can be converted into FeatureTypeI objects.
-callback — a callback to invoke on each feature. the subroutine gets passed each Bio::SeqFeatureI object in turn.
-attributes — a hash reference containing attributes to match.

The -attributes argument is a hashref holding one or more attributes to match against, like:

-attributes => { Gene => 'abc-1',
                 Note => 'confirmed' }

Attribute matching is plain simple exact string matching, and multiple attributes get ANDed together. want a fancier take on all this? go see Bio::DB::ConstraintsI.

If you provide a callback, it gets invoked on each feature in turn. and if that callback returns a false value, iteration will be interrupted. also — when a callback is provided, the method returns undef. so don't be out here expecting a list, bestie. 💀

🎀 get_feature_by_name 🎀

Title   : get_feature_by_name
Usage   : $db->get_feature_by_name(-class=>$class,-name=>$name)
Function: fetch features by their name
Returns : a list of Bio::SeqFeatureI objects
Args    : the class and name of the desired feature
Status  : public

Use this one to fetch named feature(s) out of the database. the -class and -name arguments mean the exact same thing they do in segment(), and it also accepts these lil short-cut forms:

one argument: the argument is treated as the feature name
two arguments: the arguments are treated as the class and name (note: this uses _rearrange() so the first argument must not begin with a hyphen or it'll be interpreted as a named argument). 🙈

This method may return zero, one, or several Bio::SeqFeatureI objects. and the implementor may allow the name to contain wildcards, in which case standard C-shell glob semantics are expected. ✨

💜 get_feature_by_target 💜

Title   : get_feature_by_target
Usage   : $db->get_feature_by_target($class => $name)
Function: fetch features by their similarity target
Returns : a list of Bio::SeqFeatureI objects
Args    : the class and name of the desired feature
Status  : public

Use this one to fetch a named feature from the database based on its similarity hit. the arguments are the same as get_feature_by_name(). and if this isn't implemented, the interface just defaults to using get_feature_by_name(). chill fallback, love that for it. 🫶

🌸 get_feature_by_id 🌸

Title   : get_feature_by_id
Usage   : $db->get_feature_by_target($id)
Function: fetch a feature by its ID
Returns : a Bio::SeqFeatureI objects
Args    : the ID of the feature
Status  : public

If the database hands out unique feature IDs, this is your girl for retrieving a single feature from the database. and if you don't override it? this interface calls get_feature_by_name() and returns the first element. easy. 💅

🦋 get_feature_by_attribute 🦋

Title   : get_feature_by_attribute
Usage   : $db->get_feature_by_attribute(attribute1=>value1,attribute2=>value2)
Function: fetch features by combinations of attribute values
Returns : a list of Bio::SeqFeatureI objects
Args    : the class and name of the desired feature
Status  : public

Use this one to fetch a whole set of features from the database. attributes are a list of name=>value pairs, and they get logically ANDed together. but wait — if an attribute value is an array reference, then the list of values inside that array is treated as an alternative set of values to be ORed together. and/or combos, we love a flexible queen. 👑

🧚 search_notes 🧚

Title   : search_notes
Usage   : $db->search_notes($search_term,$max_results)
Function: full-text search on features, ENSEMBL-style
Returns : an array of [$name,$description,$score]
Args    : see below
Status  : public

This routine does a full-text search on feature attributes (which attributes exactly? depends on the implementation, bestie) and hands you back a list of [$name,$description,$score], where $name is the feature ID, $description is a human-readable description like a locus line, and $score is the match strength. ✨

now listen — since this is a decidedly non-standard thing to do (but the generic genome browser uses it anyway 😭), the default method returns an empty list. so good news: you do not have to implement it. no cap.

🔥 get_seq_stream 🔥

Title   : get_seq_stream
Usage   : $seqio = $db->get_seq_stream(@args)
Function: Performs a query and returns an iterator over it
Returns : a Bio::SeqIO stream capable of returning Bio::SeqFeatureI objects
Args    : As in features()
Status  : public

This routine takes the same arguments as features(), but returns a Bio::SeqIO::Stream-compliant object instead. use it like this:

$stream = $db->get_seq_stream('exon');
while (my $exon = $stream->next_seq) {
   print $exon,"\n";
}

NOTE: in the interface this method is aliased to get_feature_stream(), because that name is just more descriptive. ✨

👑 refclass 👑

Title   : refclass
Usage   : $class = $db->refclass
Function: returns the default class to use for segment() calls
Returns : a string
Args    : none
Status  : public

For data sources that use namespaces to tell reference sequence accessions apart, this returns the default namespace (or "class") to use. and this interface defines a default of "Accession". that's it, that's the whole method, and she's iconic for it. 💖

and that's a wrap on Bio::DasI(3pm) bestie!! 🎉🦋 this page shipped as part of perl v5.32.1, dated 2021-08-15 — so go forth, query those features, and remember: every option we covered is exactly the option that's there, no more, no less. periodt. 💅✨🌸

📦 where this page comes from

debian bookworm: libbio-perl-perl 1.7.8-1 · Perl
debian trixie: libbio-perl-perl 1.7.8-1 · Perl
ubuntu jammy: libbio-perl-perl 1.7.8-1 · Perl
ubuntu noble: libbio-perl-perl 1.7.8-1 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms