Bio::S...O::sim4(3pm)

💖 Bio::S...O::sim4(3pm) 💖

okay bestie, gather round, because this is the manual page for Bio::S...O::sim4(3pm) — straight out of the User Contributed Perl Documentation section, no cap. She's a Perl module, she parses Sim4 alignments, and she is so much chiller than she looks. let's get into it 🫶

---

✨ NAME ✨

Bio::SearchIO::sim4 — the parser for Sim4 alignments. that's the whole vibe. she parses, she aligns, she serves 💅

---

🌸 SYNOPSIS 🌸

# do not use this module directly, it is a driver for SearchIO
use Bio::SearchIO;
my $searchio = Bio::SearchIO->new(-file => 'results.sim4',
                                  -format => 'sim4');

while ( my $result = $searchio->next_result ) {
    while ( my $hit = $result->next_hit ) {
        while ( my $hsp = $hit->next_hsp ) {
            # ...
        }
    }
}

like, look at those nested whiles. that's main character energy right there. the triple loop is giving "i contain multitudes" 😭💖

---

🦋 DESCRIPTION 🦋

so here's the tea: this is a driver for the SearchIO system, and its whole job is parsing Sim4. that's it, that's the gig. lowkey iconic.

there's a website if you wanna go deeper, and you should:

http://globin.cse.psu.edu/html/docs/sim4.html

🚨 big heads up bestie: she Cannot parse LAV or 'exon file' formats (A=2 or A=5). so if that's what you're feeding her, she's gonna be like "girl what". don't do it. 🙈

---

💌 FEEDBACK 💌

📬 Mailing Lists

user feedback is genuinely part of the evolution of this module and every other Bioperl module, fr fr. so if you have comments or suggestions, send them along! your participation is much appreciated, and i mean that.

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

🫶 Support

okay so for usage questions and support issues, please direct them to the mailing list:

bioperl-l@bioperl.org

not straight to the module maintainer. like, i know, i know, you want the direct line, but the mailing list is where the experienced and responsive experts hang out and they will look at your problem and quickly address it. that's the whole point. 💜

and please, if at all possible, include a thorough description of the problem with code and data examples. the more context you give, the faster someone can help you. it's giving "help me help you" and honestly? correct.

🐛 Reporting Bugs

found a bug? report it to the Bioperl bug tracking system so they can keep track of the bugs and their resolution — that's literally what it's for. bug reports can be submitted via the web:

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

no cap, just click it and tell them everything. ✨

---

👑 AUTHOR - Jason Stajich 👑

Email jason-at-bioperl-dot-org

(yes, that's the email exactly as written, with the -at- and -dot- — copy it verbatim bestie, don't get cute with it. 💅)

---

🌈 CONTRIBUTORS 🌈

Luc Gauthier (lgauthie@hotmail.com)

thank you for your service, king 🫡

---

🎀 APPENDIX 🎀

the rest of this documentation details each of the object methods. and real quick, an important note: internal methods are usually preceded with a _ — so if you see an underscore, that's the module's business, not yours. mind ya business bestie 😌

---

⭐ new

• Title: new
• Usage: my $obj = Bio::SearchIO::sim4->new();
• Function: Builds a new Bio::SearchIO::sim4 object. brand new baby module, freshly constructed, adorable.
• Returns: an instance of Bio::SearchIO::sim4
• Args: (none listed)

---

⭐ next_result

• Title: next_result
• Usage: my $result = $searchio->next_result;
• Function: Returns the next Result from a search. one at a time, like a responsible snacker.
• Returns: Bio::Search::Result::ResultI object
• Args: none

---

⭐ start_element

• Title: start_element
• Usage: $eventgenerator->start_element
• Function: Handles a start element event. it's the "we're so back" of element events.
• Returns: none
• Args: hashref with at least 2 keys 'Data' and 'Name'

---

⭐ end_element

• Title: start_element

🫠 yes bestie, the original says start_element here in the Title field. that's not me, that's just how the page is. i am simply the messenger. keep it as-is.

• Usage: $eventgenerator->end_element
• Function: Handles an end element event. the "it's over" counterpart to the above.
• Returns: none
• Args: hashref with at least 2 keys 'Data' and 'Name'

---

⭐ element

• Title: element
• Usage: $eventhandler->element({'Name' => $name, 'Data' => $str});
• Function: a convenience method that calls start_element, characters, end_element — the whole trilogy in one go, a real triple threat.
• Returns: none
• Args: Hash ref with the keys 'Name' and 'Data'

---

⭐ characters

• Title: characters
• Usage: $eventgenerator->characters($str)
• Function: Send a character events
• Returns: none
• Args: string

---

⭐ within_element

• Title: within_element
• Usage: if( $eventgenerator->within_element($element) ) {}
• Function: Test if we are within a particular element. This is different than 'in' because within can be tested for a whole block. so like, within sees the whole era, not just the moment. 💅
• Returns: boolean
• Args: string element name

---

⭐ in_element

• Title: in_element
• Usage: if( $eventgenerator->in_element($element) ) {}
• Function: Test if we are in a particular element. This is different than 'in' because within can be tested for a whole block.

🙈 again, that's exactly what the original says — this one's copied verbatim from the within_element description above. keeping it real, keeping it accurate, not my problem.

• Returns: boolean
• Args: string element name

---

⭐ start_document

• Title: start_document
• Usage: $eventgenerator->start_document
• Function: Handle a start document event. the opening credits 🎬
• Returns: none
• Args: none

---

⭐ end_document

• Title: end_document
• Usage: $eventgenerator->end_document
• Function: Handles an end document event. roll credits, she's done.
• Returns: Bio::Search::Result::ResultI object
• Args: none

---

⭐ _will_handle

• Title: _will_handle
• Usage: Private method. For internal use only.

if( $self->_will_handle($type) ) { ... }

• Function: Provides an optimized way to check whether or not an element of a given type is to be handled. she's efficient, she's streamlined, she's that girl.
• Returns: Reference to EventHandler object if the element type is to be handled. undef if the element type is not to be handled.
• Args: string containing type of element.

✨ Optimizations ✨

1. Using the cached pointer to the EventHandler to minimize repeated lookups.
2. Caching the will_handle status for each type that is encountered so that it only need be checked by calling handler->will_handle($type) once.

so real talk, this does not lead to a major savings by itself — only 5-10%. that's like, a lil snack, not a full meal. 🍓

but — in combination with other optimizations, or for large parse jobs, the savings good be significant.

💀 yes, "good be significant." that's what the page says. it's a typo in the source and i refuse to gaslight you about it. copy/paste that at your own risk, bestie.

and if you ever wanna test against the unoptimized version? here's the move: remove the parentheses from around the third term in the ternary " ? : " operator and add two calls to $self->_eventHandler().

periodt. that's the whole optimization section. go forth and benchmark. 🔥

---

🌟 the sign-off 🌟

and that's the page, bestie!! this one's from perl v5.32.1, dated 2021-08-15, and it's filed under Bio::S...O::sim4(3pm) — same name as the top, because symmetry is beautiful and also that's just how manpages work. 💖✨🎀

go parse something iconic. i'm obsessed with you. bye!! 🦋💅