Bio::S...attener(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

okay so bestie, welcome to the Bio::SeqFeature::Tools::Unflattener manpage — the header calls it Bio::S...attener(3pm) and it's from User Contributed Perl Documentation. This is part 1 and it's giving “let’s decode GenBank chaos together” energy. No cap, we’re keeping every detail. 💖

✨ NAME ✨

Bio::SeqFeature::Tools::Unflattener — turns a flat list of genbank-sourced features into a nested SeqFeatureI hierarchy. periodt. 👑

🦋 SYNOPSIS 🦋

okay so standard / generic use — unflatten a genbank record. copy exactly:

  # standard / generic use - unflatten a genbank record
  use Bio::SeqIO;
  use Bio::SeqFeature::Tools::Unflattener;

  # generate an Unflattener object
  $unflattener = Bio::SeqFeature::Tools::Unflattener->new;

  # first fetch a genbank SeqI object
  $seqio =
    Bio::SeqIO->new(-file=>'AE003644.gbk',
                    -format=>'GenBank');
  my $out =
    Bio::SeqIO->new(-format=>'asciitree');
  while ($seq = $seqio->next_seq()) {

    # get top level unflattended SeqFeatureI objects
    $unflattener->unflatten_seq(-seq=>$seq,
                                -use_magic=>1);
    $out->write_seq($seq);

    @top_sfs = $seq->get_SeqFeatures;
    foreach my $sf (@top_sfs) {
        # do something with top-level features (eg genes)
    }
  }

🌸 DESCRIPTION 🌸

Most GenBank entries for annotated genomic DNA contain a flat list of features. These features can be parsed into an equivalent flat list of Bio::SeqFeatureI objects using the standard Bio::SeqIO classes. However, it is often desirable to unflatten this list into something resembling actual gene models, in which genes, mRNAs and CDSs are nested according to the nature of the gene model.

The BioPerl object model allows us to store these kind of associations between SeqFeatures in containment hierarchies -- any SeqFeatureI object can contain nested SeqFeatureI objects. The Bio::SeqFeature::Tools::Unflattener object facilitates construction of these hierarchies from the underlying GenBank flat-feature-list representation.

For example, if you were to look at a typical GenBank DNA entry, say, AE003644, you would see a flat list of features:

source

gene CG4491
mRNA CG4491-RA
CDS CG4491-PA

gene tRNA-Pro
tRNA tRNA-Pro

gene CG32954
mRNA CG32954-RA
mRNA CG32954-RC
mRNA CG32954-RB
CDS CG32954-PA
CDS CG32954-PB
CDS CG32954-PC

These features have sequence locations, but it is not immediately clear how to write code such that each mRNA is linked to the appropriate CDS (other than relying on IDs which is very bad).

We would like to convert the above list into the containment hierarchy, shown below:

source
gene
  mRNA CG4491-RA
    CDS CG4491-PA
    exon
    exon
gene
  tRNA tRNA-Pro
    exon
gene
  mRNA CG32954-RA
    CDS CG32954-PA
    exon
    exon
  mRNA CG32954-RC
    CDS CG32954-PC
    exon
    exon
  mRNA CG32954-RB
    CDS CG32954-PB
    exon
    exon

Where each feature is nested underneath its container. Note that exons have been automatically inferred (even for tRNA genes).

We do this using a call on a Bio::SeqFeature::Tools::Unflattener object

  @sfs = $unflattener->unflatten_seq(-seq=>$seq);

This would return a list of the top level (i.e. container) SeqFeatureI objects - in this case, genes. Other top level features are possible; for instance, the source feature which is always present, and other features such as variation or misc_feature types.

The containment hierarchy can be accessed using the get_SeqFeature() call on any feature object - see Bio::SeqFeature::FeatureHolderI. The following code will traverse the containment hierarchy for a feature:

  sub traverse {
    $sf = shift;   #  $sf isa Bio::SeqfeatureI

    # ...do something with $sf!

    # depth first traversal of containment tree
    @contained_sfs = $sf->get_SeqFeatures;
    traverse($_) foreach @contained_sfs;
  }

Once you have built the hierarchy, you can do neat stuff like turn the features into 'rich' feature objects (eg Bio::SeqFeature::Gene::GeneStructure) or convert to a suitable format such as GFF3 or chadoxml (after mapping to the Sequence Ontology); this step is not described here.

🔮 USING MAGIC 🔮

Due to the quixotic nature of how features are stored in GenBank/EMBL/DDBJ, there is no guarantee that the default behaviour of this module will produce perfect results. Sometimes it is hard or impossible to build a correct containment hierarchy if the information provided is simply too lossy, as is often the case. If you care deeply about your data, you should always manually inspect the resulting containment hierarchy; you may have to customise the algorithm for building the hierarchy, or even manually tweak the resulting hierarchy. This is explained in more detail further on in the document.

However, if you are satisfied with the default behaviour, then you do not need to read any further. Just make sure you set the parameter use_magic - this will invoke incantations which will magically produce good results no matter what the idiosyncracies of the particular GenBank record in question.

For example

  $unflattener->unflatten_seq(-seq=>$seq,
                              -use_magic=>1);

The success of this depends on the phase of the moon at the time the entry was submitted to GenBank. Note that the magical recipe is being constantly improved, so the results of invoking magic may vary depending on the bioperl release.

If you are skeptical of magic, or you wish to exact fine grained control over how the entry is unflattened, or you simply wish to understand more about how this crazy stuff works, then read on!

💀 PROBLEMATIC DATA AND INCONSISTENCIES 💀

Occasionally the Unflattener will have problems with certain records. For example, the record may contain inconsistent data - maybe there is an exon entry that has no corresponding mRNA location.

The default behaviour is to throw an exception reporting the problem, if the problem is relatively serious - for example, inconsistent data.

You can exert more fine grained control over this - perhaps you want the Unflattener to do the best it can, and report any problems. This can be done - refer to the methods.

  • error_threshold()
  • get_problems()
  • report_problems()
  • ignore_problems()

✨ ALGORITHM ✨

okay so this is the default algorithm, bestie — and the whole point is that you're supposed to be able to override any lil piece of it to make it yours. Customisation era 💅

The core of it is literally just two parts:

  1. Partitioning the flat feature list into groups
  2. Resolving the feature containment hierarchy for each group

And then there are other optional steps that happen after those two, like inferring exons. Let's get into the details, fr fr 🦋

🌸 Partitioning into groups

First things first: the flat feature list gets partitioned into groups.

The default way of doing this is to use the gene attribute. Look at two features from GenBank accession AE003644.3:

 gene            20111..23268
                 /gene="noc"
                 /locus_tag="CG4491"
                 /note="last curated on Thu Dec 13 16:51:32 PST 2001"
                 /map="35B2-35B2"
                 /db_xref="FLYBASE:FBgn0005771"
 mRNA            join(20111..20584,20887..23268)
                 /gene="noc"
                 /locus_tag="CG4491"
                 /product="CG4491-RA"
                 /db_xref="FLYBASE:FBgn0005771"

Both these features share the same /gene tag, which is "noc", so they correspond to the same gene model. (the CDS feature isn't shown here, but it also has a tag-value /gene="noc" — so yes, it's in the club too 💖)

Not every group has to correspond to a gene model, but honestly that's the most common use case. We'll get into customising the grouping later, don't worry.

Sometimes you gotta use other tags tho. Like, if you look at the entire record for AE003644.3, you'll see you actually need to use the /locus_tag attribute. plot twist: this attribute is actually not present in most records! 😭

You can override it like this:

  $collection->unflatten_seq(-seq=>$seq, -group_tag=>'locus_tag');

Alternatively, if you -use_magic, the object will try and make a guess as to what the correct group_tag should be. ✨ magic ✨

At the end of this step, we should have a list of groups — and there is no structure within a group; the group just serves to partition the flat features. For the example data above, we'd have the following groups:

  [ source ]
  [ gene mRNA CDS ]
  [ gene mRNA CDS ]
  [ gene mRNA CDS ]
  [ gene mRNA mRNA mRNA CDS CDS CDS ]

🎀 Multicopy Genes

Multicopy genes are usually rRNAs or tRNAs that are duplicated across the genome. Because they're functionally equivalent, and usually have the same sequence, they usually have the same group_tag (ie gene symbol) — and they often have a /note tag giving copy number. Which means... they end up in the same group. 🙈

This is undesirable, because they are spatially disconnected.

So there's another step, which involves splitting spatially disconnected groups into distinct groups. This would turn this:

 [gene-rrn3 rRNA-rrn3 gene-rrn3 rRNA-rrn3]

into this:

 [gene-rrn3 rRNA-rrn3] [gene-rrn3 rRNA-rrn3]

based on the coordinates. slay, coordinates doing the work 💅

🦋 What next?

The next step is to add some structure to each group, by making containment hierarchies — trees that represent how the features interrelate. 🌈

💜 Resolving the containment hierarchy

After the grouping is done, we end up with a list of groups which probably contain features of type 'gene', 'mRNA', 'CDS' and so on.

Singleton groups (eg the 'source' feature) are ignored at this stage. not their moment, sorry

Each group is itself flat; we need to add an extra level of organisation. Usually this is because different spliceforms (represented by the 'mRNA' feature) can give rise to different protein products (indicated by the 'CDS' feature). We want to correctly associate mRNAs to CDSs. 👑

We want to go from a group like this:

  [ gene mRNA mRNA mRNA CDS CDS CDS ]

to a containment hierarchy like this:

  gene
    mRNA
      CDS
    mRNA
      CDS
    mRNA
      CDS

In which each CDS is nested underneath the correct corresponding mRNA. nested. underneath. the correct one. periodt 💖

For entries that contain no alternate splicing, this is simple; we know that the group

  [ gene mRNA CDS ]

must resolve to the tree

  gene
    mRNA
      CDS

How can we do this in entries with alternate splicing? okay so the bad news first: there is no guaranteed way of doing this correctly for any GenBank entry. Occasionally the submission will have been done in such a way as to reconstruct the containment hierarchy. However, this is not consistent across databank entries, so no generic solution can be provided by this object. This module does provide the framework within which you can customise a solution for the particular dataset you're interested in — see later. 🫶

the good news tho: there is an inference we can do that should produce pretty good results the vast majority of the time. It uses splice coordinate data — this is the default behaviour of this module, and it's described in detail below. ✨

🌟 Using splice site coordinates to infer containment

If an mRNA is to be the container for a CDS, then the splice site coordinates (or intron coordinates, depending on how you look at it) of the CDS must fit inside the splice site coordinates of the mRNA.

Ambiguities can still arise, but the results produced should still be reasonable and consistent at the sequence level. Look at this fake example:

  mRNA    XXX---XX--XXXXXX--XXXX         join(1..3,7..8,11..16,19..23)
  mRNA    XXX-------XXXXXX--XXXX         join(1..3,11..16,19..23)
  CDS                 XXXX--XX           join(13..16,19..20)
  CDS                 XXXX--XX           join(13..16,19..20)

[obviously the positions have been scaled down]

We cannot unambiguously match mRNA with CDS based on splice sites, since both CDS share the splice site locations 16^17 and 18^19. However, the consequences of making a wrong match are probably not very severe. Any annotation data attached to the first CDS is probably identical to the seconds CDS, other than identifiers. so like... it's giving fine, honestly 😭

The default behaviour of this module is to make an arbitrary call where it is ambiguous (the mapping will always be bijective; i.e. one mRNA -> one CDS).

[TODO: NOTE: not tested on EMBL data, which may not be bijective; ie two mRNAs can share the same CDS??] 🧚

This completes the building of the containment hierarchy; other optional step follow 💖

🎀 POST-GROUPING STEPS 🎀

🌸 Inferring exons from mRNAs

This step always occurs if -use_magic is invoked. always, bestie

In a typical GenBank entry, the exons are implicit. That is they can be inferred from the mRNA location.

For example:

     mRNA            join(20111..20584,20887..23268)

This tells us that this particular transcript has two exons. In bioperl, the mRNA feature will have a 'split location'.

If we call

  $unflattener->feature_from_splitloc(-seq=>$seq);

this will generate the necessary exon features, and nest them under the appropriate mRNAs. Note that the mRNAs will no longer have split locations — they will have simple locations spanning the extent of the exons. This is intentional, to avoid redundancy. 💅

Occasionally a GenBank entry will have both implicit exons (from the mRNA location) and explicit exon features.

In this case, exons will still be transferred. Tag-value data from the explicit exon will be transferred to the implicit exon. If exons are shared between mRNAs these will be represented by different objects. Any inconsistencies between implicit and explicit will be reported. receipts will be provided 🔥

🦋 tRNAs and other noncoding RNAs

exons will also be generated from these features

💜 Inferring mRNAs from CDS

Some GenBank entries represent gene models using features of type gene, mRNA and CDS; some entries just use gene and CDS.

If we only have gene and CDS, then the containment hierarchies will look like this:

  gene
    CDS

If we want the containment hierarchies to be uniform, like this

  gene
    mRNA
      CDS

then we must create an mRNA feature. This will have identical coordinates to the CDS. The assumption is that there is either no untranslated region, or it is unknown. 🙈

To do this, we can call

   $unflattener->infer_mRNA_from_CDS(-seq=>$seq);

This is taken care of automatically, if -use_magic is invoked. ✨ magic stays undefeated ✨

✨ ADVANCED ✨

🎀 Customising the grouping of features 🎀

So the default behaviour? It's giving "built for protein-coding genes and noncoding genes from genbank genomic DNA submissions". That's its whole main character moment. 💅

Wanna switch up which tag gets used to partition the feature? Just pass in a different group_tag argument — peep the unflatten_seq() method for the deets.

But lowkey, other behaviour might be what you actually want. Example: SNPs (those are features of type 'variation' in GenBank) aren't technically part of the gene model, right? But it could still be super desirable to group SNPs that overlap or are nearby gene models. 👀

It should certainly be possible to extend this module to do that. HOWEVER — I have yet to code this part!!! 😭 If anyone would find this useful, let me know fr fr.

In the meantime? You could write your own grouping subroutine, and feed the results into unflatten_groups() [see the method documentation below].

🦋 Customising the resolution of the containment hierarchy 🦋

Once the flat list of features has been partitioned into groups, the method unflatten_group() gets called on each group to build a tree.

The algorithm for doing this is described above; ambiguities are resolved by using splice coordinates. And as we discussed, this can be ambiguous. 🙈

Some submissions may contain information in tags/attributes that hint as to the mapping that needs to be made between the features.

For example, with the Drosophila Melanogaster release 3 submission, we see that CDS features in alternately spliced mRNAs have a form like this:

     CDS             join(145588..145686,145752..146156,146227..146493)
                     /locus_tag="CG32954"
                     /note="CG32954 gene product from transcript CG32954-RA"
                                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
                     /codon_start=1
                     /product="CG32954-PA"
                     /protein_id="AAF53403.1"
                     /db_xref="GI:7298167"
                     /db_xref="FLYBASE:FBgn0052954"
                     /translation="MSFTLTNKNVIFVAGLGGIGLDTSKELLKRDLKNLVILDRIENP..."

Here the /note tag provides the clue we need to link CDS to mRNA (highlighted with ^^^^). We just need to find the mRNA with the tag

  /product="CG32954-RA"

I have no idea how consistent this practice is across submissions; it is consistent for the fruitfly genome submission.

We can customise the behaviour of unflatten_group() by providing our own resolver method. This obviously requires a bit of extra programming, but there is no way to get around this. 💀

Here is an example of how to pass in your own resolver; this example basically checks the parent (container) /product tag to see if it matches the required string in the child (contained) /note tag.

       $unflattener->unflatten_seq(-seq=>$seq,
                                 -group_tag=>'locus_tag',
                                 -resolver_method=>sub {
                                     my $self = shift;
                                     my ($sf, @candidate_container_sfs) = @_;
                                     if ($sf->has_tag('note')) {
                                         my @notes = $sf->get_tag_values('note');
                                         my @trnames = map {/from transcript\s+(.*)/;
                                                            $1} @notes;
                                         @trnames = grep {$_} @trnames;
                                         my $trname;
                                         if (@trnames == 0) {
                                             $self->throw("UNRESOLVABLE");
                                         }
                                         elsif (@trnames == 1) {
                                             $trname = $trnames[0];
                                         }
                                         else {
                                             $self->throw("AMBIGUOUS: @trnames");
                                         }
                                         my @container_sfs =
                                           grep {
                                               my ($product) =
                                                 $_->has_tag('product') ?
                                                   $_->get_tag_values('product') :
                                                     ('');
                                               $product eq $trname;
                                           } @candidate_container_sfs;
                                         if (@container_sfs == 0) {
                                             $self->throw("UNRESOLVABLE");
                                         }
                                         elsif (@container_sfs == 1) {
                                             # we got it!
                                             return $container_sfs[0];
                                         }
                                         else {
                                             $self->throw("AMBIGUOUS");
                                         }
                                     }
                                 });

the resolver method is only called when there is more than one spliceform. ✨

🌸 Parsing mRNA records 🌸

Some of the entries in sequence databanks are for mRNA sequences as well as genomic DNA. We may want to build models from these too.

NOT YET DONE - IN PROGRESS!!! 🚧

Open question — what would these look like? 🤔

Ideally we would like a way of combining a mRNA record with the corresponding SeFeature entry from the appropriate genomic DNA record. This could be problemmatic in some cases — for example, the mRNA sequences may not match 100% (due to differences in strain, assembly problems, sequencing problems, etc). What then...? 😭

👑 SEE ALSO 👑

Feature table description

  http://www.ebi.ac.uk/embl/Documentation/FT_definitions/feature_table.html

💖 FEEDBACK 💖

🌈 Mailing Lists 🌈

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the Bioperl mailing lists — your participation is much appreciated. 🫶

  bioperl-l@bioperl.org                         - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

🎀 Support 🎀

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

bioperl-l@bioperl.org

rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible. 🥺

🦋 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 - Chris Mungall ⭐

Email: cjm@fruitfly.org

📎 APPENDIX 📎

okay bestie, this is the deep lore part — the rest of the docs break down every single object method, one by one. and psst: internal methods are usually preceded with an _, so if you see a leading underscore, that's the "don't touch unless you know what you're doing" section 💅

🎀 new

  • Title: new
  • Usage:
$unflattener = Bio::SeqFeature::Tools::Unflattener->new();
$unflattener->unflatten_seq(-seq=>$seq);
  • Function: constructor
  • Example: (nothing supplied here, we keep it moving)
  • Returns: a new Bio::SeqFeature::Tools::Unflattener
  • Args: see below

🫶 Arguments

  • -seq — a Bio::SeqI object, optional. it's the sequence you want to unflatten, and you can also hand it over later when you call unflatten_seq(). either way works, no stress.
  • -group_tag — a string that represents the /tag used to partition flat features (the whole discussion above explains this one, iykyk).

🦋 seq

  • Title: seq
  • Usage: $unflattener->seq($newval)
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: value of seq (a Bio::SeqI)
  • Args: on set, new value (a Bio::SeqI, optional)

so your Bio::SeqI object should be holding a flat list of Bio::SeqFeatureI objects — that's literally the list that's gonna get unflattened. lowkey the whole point of the operation.

and fr fr, you can also set the sequence object when you call unflatten_seq(), so you're not locked into doing it here.

🌸 group_tag

  • Title: group_tag
  • Usage: $unflattener->group_tag($newval)
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: value of group_tag (a scalar)
  • Args: on set, new value (a scalar or undef, optional)

this is the tag used to scoop elements out of the flat feature list and clump them into groups. like, imagine two absolutely typical GenBank features:

     gene            20111..23268
                     /gene="noc"
                     /locus_tag="CG4491"
                     /note="last curated on Thu Dec 13 16:51:32 PST 2001"
                     /map="35B2-35B2"
                     /db_xref="FLYBASE:FBgn0005771"
     mRNA            join(20111..20584,20887..23268)
                     /gene="noc"
                     /locus_tag="CG4491"
                     /product="CG4491-RA"
                     /db_xref="FLYBASE:FBgn0005771"

see how they're the same gene model? they share the same /gene attribute, and that's the receipt 🧾 — so we wanna collect them together in groups.

setting group_tag is optional. the default is to use 'gene'. and in that example above? you could also use /locus_tag if you felt like it. main character choice, honestly.

🧚 partonomy

  • Title: partonomy
  • Usage: $unflattener->partonomy({mRNA=>'gene', CDS=>'mRNA')
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: value of partonomy (a scalar)
  • Args: on set, new value (a scalar or undef, optional)

a hash that represents the containment structure your seq_feature nesting is supposed to conform to ✨ each key is the contained (child) type, and each value is the container (parent) type. parent holds child, child stays in its lane.

👑 structure_type

  • Title: structure_type
  • Usage: $unflattener->structure_type($newval)
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: value of structure_type (a scalar)
  • Args: on set, new value (an int or undef, optional)

GenBank entries come in different flavours — a.k.a. structure types. some have mRNAs, some simply do not. it's giving variety, it's giving chaos.

right now there are only two base structure types defined. if you set the structure type, the appropriate unflattening action gets taken for you. and heads up: the presence or absence of explicit exons does not affect the structure type. not even a little.

if you invoke -use_magic then this gets set automatically, based on the content of the record. magic doing magic things 🪄

⭐ Type 0 (DEFAULT)

typically contains

source
gene
mRNA
CDS

with this structure type, we want the seq_features to be nested like this

gene
  mRNA
  CDS
    exon

exons and introns are implicit from the mRNA 'join' location.

to get exons from the mRNAs, you will need this call (see below):

$unflattener->feature_from_splitloc(-seq=>$seq);

⭐ Type 1

typically contains

source
gene
CDS
exon [optional]
intron [optional]

there are no mRNA features here. none. zero.

with this structure type, we want the seq_features to be nested like this

gene
  CDS
    exon
    intron

exon and intron may or may not be present; they may be implicit from the CDS 'join' location.

😭 get_problems

  • Title: get_problems
  • Usage: @probs = get_problems()
  • Function: Get the list of problem(s) for this object.
  • Example: (nothing supplied)
  • Returns: An array of [severity, description] pairs
  • Args: (nothing supplied)

while unflattening a record, problems can happen. some of these problems are non-fatal and can just be ignored, bestie, breathe.

problems are represented as arrayrefs containing a pair [severity, description].

  • severity is a number — the higher it is, the more severe the problem. simple math.
  • the description is a text string.

🍓 clear_problems

  • Title: clear_problems
  • Usage: (nothing supplied)
  • Function: resets the problem list to empty
  • Example: (nothing supplied)
  • Returns: (nothing supplied)
  • Args: (nothing supplied)

🌈 report_problems

  • Title: report_problems
  • Usage: $unflattener->report_problems(\*STDERR);
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: (nothing supplied)
  • Args: FileHandle (defaults to STDERR)

🙈 ignore_problems

  • Title: ignore_problems
  • Usage: $obj->ignore_problems();
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: (nothing supplied)
  • Args: (nothing supplied)

the Unflattener is very particular about the problems it finds along the way. like, it notices everything. if you've set the error_threshold so that less severe problems don't cause exceptions, the Unflattener still expects you to call report_problems() at the end, so that whoever's using the module knows about any inconsistencies or problems with the data. it's not being dramatic, it's being responsible.

in fact, a warning will be produced if there are unreported problems. to silence this warning, call the ignore_problems() method before the Unflattener object is destroyed. that's the move 💅

🔥 error_threshold

  • Title: error_threshold
  • Usage: $obj->error_threshold($severity)
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: value of error_threshold (a scalar)
  • Args: on set, new value (an integer)

sets the threshold above which errors cause this module to throw an exception. the default is 0; all problems with a severity > 0 will cause an exception. zero tolerance era, honestly.

if you raise the threshold to 1, then the unflattening process will be more lax; problems of severity==1 are generally non-fatal, but they may indicate that the results should be inspected — for example, to make sure there is no data loss. so like, chill, but not too chill 👀

🫶 unflatten_seq

  • Title: unflatten_seq
  • Usage: @sfs = $unflattener->unflatten_seq($seq);
  • Function: turns a flat list of features into a list of holder features
  • Example: (nothing supplied)
  • Returns: list of Bio::SeqFeatureI objects
  • Args: see below

partitions a list of features and then arranges them in a nested tree; the full explanation lives above ☝️

⚠️ note — the Bio::SeqI object you pass in will be modified. not a copy. the actual thing. just so you know.

💖 Arguments

  • -seq — a Bio::SeqI object; must contain Bio::SeqFeatureI objects. this is optional if seq has already been set.
  • -use_magic — if TRUE (ie non-zero) then magic will be invoked; see the discussion above.
  • -resolver_method — a CODE reference. see the documentation above for an example of a subroutine that can be used to resolve hierarchies within groups. this is optional — if nothing is supplied, a default subroutine will be used (see below).
  • -group_tag — a string. [ see the group_tag() method ]. this overrides the default group_tag which is 'gene'.

✨ unflatten_groups

  • Title: unflatten_groups
  • Usage: (nothing supplied)
  • Function: iterates over groups, calling unflatten_group() [see below]
  • Example: (nothing supplied)
  • Returns: list of Bio::SeqFeatureI objects that are holders
  • Args: see below

🌸 Arguments

  • -groups — list of list references; the inner list is of Bio::SeqFeatureI objects, e.g. ( [$sf1], [$sf2, $sf3, $sf4], [$sf5, ...], ...)
  • -resolver_method — a CODE reference. see the documentation above for an example of a subroutine that can be used to resolve hierarchies within groups. this is optional — a default subroutine will be used.
💀 NOTE: you should not need to call this method, unless you want fine grained control over how the unflattening process goes. hands off the wheel unless you're driving on purpose.

🧬 unflatten_group

  • Title: unflatten_group
  • Usage: (nothing supplied)
  • Function: nests a group of features into a feature containment hierarchy
  • Example: (nothing supplied)
  • Returns: Bio::SeqFeatureI objects that holds other features
  • Args: see below

🎀 Arguments

  • -group — reference to list of Bio::SeqFeatureI objects
  • -resolver_method — a CODE reference. see the documentation above for an example of a subroutine that can be used to resolve hierarchies within groups. this is optional — a default subroutine will be used.
💀 NOTE: you should not need to call this method, unless you want fine grained control over how the unflattening process goes. same energy as above.

🦋 feature_from_splitloc

  • Title: feature_from_splitloc
  • Usage: $unflattener->feature_from_splitloc(-features=>$sfs);
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: (nothing supplied)
  • Args: see below

at this time all this method does is generate exons for mRNA or other RNA features. that's it. that's the whole job.

🌈 Arguments:

  • -feature — a Bio::SeqFeatureI object (that conforms to Bio::FeatureHolderI)
  • -seq — a Bio::SeqI object that contains Bio::SeqFeatureI objects
  • -features — an arrayref of Bio::SeqFeatureI object

💜 infer_mRNA_from_CDS

  • Title: infer_mRNA_from_CDS
  • Usage: (nothing supplied)
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: (nothing supplied)
  • Args: (nothing supplied)

given a "type 1" containment hierarchy

gene
  CDS
    exon

this will infer the uniform "type 0" containment hierarchy

gene
  mRNA
    CDS
    exon

all the children of the CDS will be moved to the mRNA. relocation era 📦

and btw, a "type 2" containment hierarchy is mixed type "0" and "1" (for example, see ftp.ncbi.nih.gov/genomes/Schizosaccharomyces_pombe/).

🍓 remove_types

  • Title: remove_types
  • Usage: $unf->remove_types(-seq=>$seq, -types=>["mRNA"]);
  • Function: (nothing supplied)
  • Example: (nothing supplied)
  • Returns: (nothing supplied)
  • Args: (nothing supplied)

removes features of a set type. super useful for pre-filtering a genbank record — eg to get rid of STSs.

also, there is no way to unflatten ftp.ncbi.nih.gov/genomes/Schizosaccharomyces_pombe/ UNLESS the bogus mRNAs in these records are removed (or changed to a different type) — they just confuse things too much. like, genuinely too much. they are the problem 💀

and that's a wrap on the whole page, bestie 🫶 you made it all the way through the appendix, which is honestly iconic behavior. this doc lives in perl v5.32.1 and was dated 2021-08-15 — so when you cite it, give the version and the date their flowers 🌸 mwah, go unflatten something gorgeous 💖

📦 where this page comes from