MAGE::Experiment(3pm)

💖 MAGE::Experiment 💖

okay bestie, so this page is from the User Contributed Perl Documentation — it's the manual for MAGE::Experiment, and it's literally the friend group of classes that make up the Experiment package. pull up a chair, we're doing this together 🫶

---

✨ NAME ✨

Bio::MAGE::Experiment — the container module for the classes in the MAGE package called Experiment. it's giving "collective", it's giving "squad", no cap.

---

✨ SYNOPSIS ✨

use Bio::MAGE::Experiment;

that's it. that's the whole vibe. 💅

---

✨ DESCRIPTION ✨

so this is a package module — meaning it's the lil container that holds a whole bunch of classes in the Bio::MAGE hierarchy. those classes all belong to the Experiment package of the MAGE-OM object model. she's a mother, basically. 👑

---

✨ CLASSES ✨

the Bio::MAGE::Experiment module contains these Bio::MAGE classes, periodt:

• Experiment
• ExperimentDesign
• ExperimentalFactor
• FactorValue

four icons. no notes. 🌟

---

✨ CLASS METHODS ✨

these are the ones you call on the class itself, not on an instance. very "let's talk to the concept, not the object" of them.

• @class_list = Bio::MAGE::Experiment::classes(); — hands you back a list of the class names in this package, and ngl, they're not fully qualified — meaning there's no 'Bio::MAGE::' prefix glued on the front. short names only, bestie.
• $obj = class->new(%parameters) — this is the class constructor, the main character of every Perl module honestly.
  • Parameters: if you hand it a list of name/value pairs, the matching slots, attributes, or associations get their initial values set right there by the constructor. so thoughtful.
  • Return value: a reference to an object of the class. ✨
  • Side effects: it calls initialize() if the class defines one.
• @names = class->get_slot_names() — used to grab the names of all the slots defined in a given class.

NOTE: the list of names does not include attribute or association names. just slots. don't get it twisted. 🙈

• Return value: a list of the names of all slots defined for this class.
• Side effects: none. zero. nothing. clean.

• @name_list = get_attribute_names() — returns the list of attribute data members for this class.
• @name_list = get_association_names() — returns the list of association data members for this class.
• @class_list = get_superclasses() — returns the list of superclasses for this class. her ancestors, her lineage. 🌸
• @class_list = get_subclasses() — returns the list of subclasses for this class. her children, her legacy.
• $name = class_name() — returns the full class name for this class. the whole thing, no abbreviating.
• $package_name = package_name() — returns the base package name — like, with no 'namespace::' on the front — of the package that contains this class.
• %assns = associations() — returns the association meta-information as a hash. the keys are the association names, and the values are Association objects that hold the meta-information for that association. very meta, very slay.

---

✨ INSTANCE METHODS ✨

now we're talking to actual objects. this is where it gets personal. 💜

• $obj_copy = $obj->new() — plot twist!! when you call new() on an existing object reference instead of on a class name, it acts as a copy constructor — the new object starts out with all the same initial values as the existing one. she's her own twin. 😭
  • Parameters: no input parameters are used in the copy constructor — the initial values come straight from the object being copied.
  • Return value: a reference to an object of the class.
  • Side effects: it calls initialize() if the class defines one.
• $obj->set_slots(%parameters)
• $obj->set_slots(\@name_list, \@value_list) — set_slots() sets a bunch of slots at the same time, and it's got two whole invocation styles, because she contains multitudes. option one takes a named parameter list. option two takes two array references.
  • Return value: none.
  • Side effects: it will call croak() if you use a slot_name that the class doesn't define. so don't be messy. 💀
• @obj_list = $obj->get_slots(@name_list) — get_slots() grabs the values of a bunch of slots all at once. efficiency queen.
  • Return value: a list of instance objects.
  • Side effects: none.
• $val = $obj->set_slot($name,$val) — set_slot() sets the slot $name to the value $val.
  • Return value: the new value of the slot, i.e. $val.
  • Side effects: none.
• $val = $obj->get_slot($name) — get_slot() is used to get the values of a number of slots at the same time.
  • Return value: a single slot value, or undef if the slot hasn't been initialized yet. (that's her "idk her" era. 🙈)
  • Side effects: none.
• $val = $experiment->xml_lists()
• $inval = $experiment->xml_lists($inval) — the unified setter/getter for the xml_lists slot. if $inval is specified, the setter runs; with no parameters, the getter runs. one method, two moods.
  • Input parameters: the optional $inval will invoke the setter method.
  • Return value: for both setter and getter, the current value of the xml_lists slot.
  • Side effects: none.
  • Exceptions: none.
• $val = $experiment->tagname()
• $inval = $experiment->tagname($inval) — the unified setter/getter for the tagname slot. $inval present → setter. no params → getter.
  • Input parameters: the optional $inval will invoke the setter method.
  • Return value: for both setter and getter, the current value of the tagname slot.
  • Side effects: none.
  • Exceptions: none.
• $val = $experiment->experiment_list()
• $inval = $experiment->experiment_list($inval) — the unified setter/getter for the experiment_list slot. same energy: $inval → setter, nothing → getter.
  • Input parameters: the optional $inval will invoke the setter method.
  • Return value: for both setter and getter, the current value of the experiment_list slot.
  • Side effects: none.
  • Exceptions: none.
• $array_ref = $experiment->getExperiment_list() — this one handles the list for the Bio::MAGE::Experiment::Experiment class. it returns a reference to an array of the class objects that have been associated with the package instance.

it's literally so useful when you're retrieving data from a parsed MAGE-ML file. that's the whole point, bestie. 🍓

• $experiment->addExperiment(@vals) — this is the interface for adding Bio::MAGE::Experiment::Experiment objects to the experiment_list list. it's generally used by generic methods like the ones in the XMLWriter. she's a helper, a team player. 🫶
  • Input parameters: the list of values @vals to add to the owner association. NOTE: submitting a single value is permitted. yes, one is enough, she's flexible.
  • Return value: none.
  • Side effects: none.
  • Exceptions: will call croak() if no input parameters are specified, or if any of the objects in @vals is not a subclass of the class Bio::MAGE::Experiment::Experiment. no fakes allowed. 💅
• $experiment->obj2xml($writer) — writes out this object, and all sub-objects, as XML, using the supplied $writer to actually do the formatting. the writer does the heavy lifting, she just directs.
  • Input parameters: $writer must be an XML writer, e.g. an instance of Bio::MAGE::XML::Writer. it must have the methods: write_start_tag(), write_end_tag(), and obj2xml().
  • Return value: none.
  • Side effects: all writing is delegated to the $writer — its write_start_tag() and write_end_tag() methods get invoked with the appropriate data, and all class sub-objects of the Bio::MAGE::Experiment instance will have their obj2xml() methods invoked in turn. by letting the $writer do the actual formatting of the output XML, it enables the user to precisely control the format. that's the whole flex. 🔥
  • Exceptions: will call croak() if no identifier has been set for the Bio::MAGE::Experiment instance. she needs a name, okay?!
• $experiment->register($obj) — stores an object for later writing as XML. putting it on the waitlist, essentially. ✨
  • Input parameters: the object to be added to the list of registered objects.
  • Return value: none.
  • Side effects: if $obj needs to be stored by this class, a reference will be stored in the correct XML list for this class.
  • Exceptions: none.

---

✨ SLOTS, ATTRIBUTES, AND ASSOCIATIONS ✨

okay so in the Perl implementation of MAGE-OM classes, there are three types of class data members: "slots", "attributes", and "associations". three flavors, all valid. 🌈

🌸 SLOTS 🌸

this API uses the term "slot" for a data member of the class that was not present in the UML model — it's used mainly for internal purposes, so like… only touch it if you genuinely understand the inner workings of the API. i'm serious, bestie. 🙈 most often, slots are used by generic methods like the ones in the XML writing and reading classes.

slots are implemented using unified getter/setter methods:

• $var = $obj->slot_name(); — retrieves the current value of the slot.
• $new_var = $obj->slot_name($new_var); — stores $new_var in the slot — and the return value is also $new_var. cute, she echoes back.
• @names = $obj->get_slot_names() — returns the list of all slots in the class.

DATA CHECKING: No data type checking is made for these methods. none. zero. she trusts you completely. 💀

🌸 ATTRIBUTES AND ASSOCIATIONS 🌸

the terms "attribute" and "association" indicate data members of the class that were specified directly from the UML model. these are the legit ones, the ones with paperwork. 📝

in the Perl implementation of MAGE-OM classes, association and attribute accessors are implemented using three separate methods:

• get* — retrieves the current value.

NOTE: for associations, if the association has list cardinality, an array reference is returned. DATA CHECKING: ensures that no argument is provided.

• set* — sets the current value, replacing any existing value.

NOTE: for associations, if the association has list cardinality, the argument must be an array reference. because of that, you probably should be using the add* methods instead. just saying. 👀 DATA CHECKING: for attributes, ensures that a single value is provided as the argument. for associations, if the association has list cardinality, ensures that the argument is a reference to an array of instances of the correct MAGE-OM class — otherwise, ensures that there's a single argument of the correct MAGE-OM class.

• add*

NOTE: only present in associations with list cardinality.

appends a list of objects to any values that may already be stored in the association.

DATA CHECKING: ensures that all arguments are of the correct MAGE-OM class.

🌸 GENERIC METHODS 🌸

the unified base class of all MAGE-OM classes, Bio::MAGE::Base, provides a set of generic methods that will operate on slots, attributes, and associations. equal opportunity methods, we love to see it. 👑

$val = $obj->get_slot($name)
\@list_ref = $obj->get_slots(@name_list);
$val = $obj->set_slot($name,$val)
$obj->set_slots(%parameters)
$obj->set_slots(\@name_list, \@value_list)

see elsewhere on this page for a detailed description of these methods — they're all up in the INSTANCE METHODS section, bestie, go look. 💖

---

✨ BUGS ✨

found a bug? please send bug reports to the project mailing list: (mged-mage 'at' lists 'dot' sf 'dot' net). she's listening, she wants to hear you out. 🫶

---

✨ AUTHOR ✨

Jason E. Stewart (jasons 'at' cpan 'dot' org) — the icon, the legend. 👑

---

✨ SEE ALSO ✨

perl(1).

---

and that's the whole page, bestie!! 🎀 this was MAGE::Experiment(3pm) from perl v5.32.0, dated 2020-11-27. go forth and build your experiments, you absolute main character. slay 💅✨🦋