TFBS::SiteSet(3pm)

💖 TFBS::SiteSet 💖

okay bestie, gather round, because today we're talking about TFBS::SiteSet — that's the Perl module, manual section (3pm), and this is the User Contributed Perl Documentation version, so you know it's giving community love. ✨

---

🌸 NAME 🌸

TFBS::SiteSet — a whole lil squad of TFBS::Site objects, living together, thriving together 🫶

---

✨ SYNOPSIS ✨

my $site_set = TFBS::SiteSet->new(@list_of_site_objects);

# add a TFBS::Site object to set:

$site_set->add_site($site_obj);

# append another TFBS::SiteSet contents:

$site_pair_set->add_site_set($site_obj);

# create an iterator:

my $it = $site_set->Iterator(-sort_by => 'start');

look at that. iconic. no notes. 💅

---

🦋 DESCRIPTION 🦋

So TFBS::SiteSet is an aggregate class, which is just fancy speak for "it's a container that holds a collection of TFBS::Site objects." You can make one fresh from scratch and fill it up with TFBS::Site objects yourself, no problem. 🎀

But also — plot twist — you don't always have to build it by hand, because it's literally handed back to you by the search_seq() method call of some TFBS::PatternI subclasses (for example, TFBS::Matrix::PWM). So sometimes it just shows up in your life, fully formed, main character energy. 👑

---

💌 FEEDBACK 💌

Found a bug? Got thoughts? Send your bug reports and any other comments straight to the author, bestie, they wanna hear it. 📬

---

🌈 AUTHOR - Boris Lenhard 🌈

Boris Lenhard — <Boris.Lenhard@cgb.ki.se> — absolute legend, wrote the whole thing. 👑

---

📖 APPENDIX 📖

The rest of this doc goes method by method through all the object methods. Heads up: internal methods are marked with a leading underscore, so if you see one of those, it's giving backstage pass, not public API. 🙈

---

🍓 add_site 🍓

• Title: add_site
• Usage:

$siteset->add_site($site_object)
$siteset->add_site(@list_of_site_objects)

• Function: adds TFBS::Site objects to an existing TFBS::SiteSet object
• Returns: $sitepair object (usually ignored — like, it's there, but we're all ignoring it, no cap)
• Args: a list of TFBS::Site objects to add

---

🧚 add_site_set 🧚

• Title: add_site_set
• Usage:

$siteset->add_site_set($site_set_object)
$siteset->add_site(@list_of_site_set_objects)

• Function: adds the contents of other TFBS::SiteSet objects to an existing TFBS::SiteSet object — basically a whole set absorbs a whole other set, family reunion style 💞
• Returns: $siteset object (usually ignored)
• Args: a list of TFBS::SiteSet objects whose contents should be added to $siteset

---

👑 size 👑

• Title: size
• Usage:

my $size = $siteset->size()

• Function: returns a number of TFBS::Site objects contained in the set
• Returns: a scalar (integer)
• Args: none. zero. nothing. it just knows. 🔮

---

🔥 Iterator 🔥

• Title: Iterator
• Usage:

my $siteset_iterator =
         $siteset->Iterator(-sort_by =>'start');
while (my $site = $siteset_iterator->next) {
    # do whatever you want with individual matrix objects
}

• Function: Returns an iterator object that can be used to go through all members of the set (TFBS::Site objects). It's your little tour guide through the whole squad. 🚶‍♀️✨
• Returns: an iterator object (currently undocumentened in TFBS — but understands the 'next' method)
• Args:

-sort_by # optional - currently it accepts
         #   (default sort order in parenthetse)
         #    'name' (pattern name, alphabetically)
         #    'ID' (pattern/matrix ID, alphabetically)
         #    'start' (site start in sequence,
         #             numerically,increasing order)
         #    'end' (site end in sequence,
         #           numerically, increasing order)
         #    'score' (numerically, decreasing order)

-reverse # optional - reverses the default sorting order if true

so yeah — -sort_by is optional, and -reverse is optional too, and if -reverse is true it flips whatever default sorting order you had going on. vibe check: reversed. 🔄

---

💜 GFF 💜

• Title: GFF
• Usage:

print $siteset->GFF();
print $siteset->GFF($gff_formatter)

• Function: returns a "standard" multiline GFF string
• Returns: a string (multiline, newline terminated)
• Args: a $gff_formatter function reference (optional)

---

💀 reminder, bestie: keep those internal underscore methods internal unless you know exactly what you're doing. respect the underscore. 🙏

---

okay that's the whole page!! 🎀 no cap, you now officially understand TFBS::SiteSet. slay. 💅✨

and for the cute sign-off: this doc came from the perl v5.42.3 distribution and it's dated 2026-08-21 — so yeah, timestamped and everything, we love a documented moment in time. 🦋💖