MAGE::...ontents(3pm)

📦 version 20030502.3, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 MAGE::...ontents(3pm) 💖

okay so the page you're reading is MAGE::...ontents(3pm) from the User Contributed Perl Documentation crowd, and the class it's actually about is Bio::MAGE::HigherLevelAnalysis::NodeContents. bestie, it is a whole thing. this is part 1 of 3, so we are not even close to done, stay with me 🫶

✨ NAME ✨

Bio::MAGE::HigherLevelAnalysis::NodeContents — a class for the MAGE-OM API. that's it, that's the name, iconic behavior honestly 👑

🎀 SYNOPSIS 🎀

here's the vibe check on how you'd actually use it, verbatim:

use Bio::MAGE::HigherLevelAnalysis::NodeContents

# creating an empty instance
my $nodecontents = Bio::MAGE::HigherLevelAnalysis::NodeContents->new();

# creating an instance with existing data
my $nodecontents = Bio::MAGE::HigherLevelAnalysis::NodeContents->new(
      designElementDimension=>$designelementdimension_ref,
      bioAssayDimension=>$bioassaydimension_ref,
      descriptions=>\@description_list,
      auditTrail=>\@audit_list,
      security=>$security_ref,
      propertySets=>\@namevaluetype_list,
      quantitationDimension=>$quantitationtypedimension_ref,
);

# 'designElementDimension' association
my $designelementdimension_ref = $nodecontents->designElementDimension(); # getter
$nodecontents->designElementDimension($designelementdimension_ref); # setter

# 'bioAssayDimension' association
my $bioassaydimension_ref = $nodecontents->bioAssayDimension(); # getter
$nodecontents->bioAssayDimension($bioassaydimension_ref); # setter

# 'descriptions' association
my $description_array_ref = $nodecontents->descriptions(); # getter
$nodecontents->descriptions(\@description_list); # setter

# 'auditTrail' association
my $audit_array_ref = $nodecontents->auditTrail(); # getter
$nodecontents->auditTrail(\@audit_list); # setter

# 'security' association
my $security_ref = $nodecontents->security(); # getter
$nodecontents->security($security_ref); # setter

# 'propertySets' association
my $namevaluetype_array_ref = $nodecontents->propertySets(); # getter
$nodecontents->propertySets(\@namevaluetype_list); # setter

# 'quantitationDimension' association
my $quantitationtypedimension_ref = $nodecontents->quantitationDimension(); # getter
$nodecontents->quantitationDimension($quantitationtypedimension_ref); # setter

see how every association gets a getter and a setter? yeah. that's the whole pattern. getters read, setters write, we love a consistent queen 💅

🦋 DESCRIPTION 🦋

straight from the MAGE-OM documentation for the NodeContents class, and I am quoting here so nobody comes for me:

The contents of a node for any or all of the three Dimensions. If a node only contained genes just the DesignElementDimension would be defined.

lowkey that's the entire concept. a node can hold stuff from any of the three Dimensions, or all of them, and if it's just genes then only DesignElementDimension gets filled in. flexible, honestly 🌸

🌈 INHERITANCE 🌈

Bio::MAGE::HigherLevelAnalysis::NodeContents has these superclasses, i.e. the family it came from:

Bio::MAGE::Describable

so everything Describable can do? yeah, this class inherits that energy. it's giving nepotism but make it object-oriented 🧚

✨ CLASS METHODS ✨

okay so here's the cute part — all of these can be called without an instance first, using the Bio::MAGE::HigherLevelAnalysis::NodeContents->methodname() syntax. no new required, no waiting around 💅

`new()`, `new(%args)`

the object constructor new() takes these optional named-value style arguments, and yes, they're all optional, live your truth:

descriptions — sets the value of the descriptions association (this one was inherited from Bio::MAGE::Describable, a little hand-me-down but make it fashion).
- the value must be of type: array of Bio::MAGE::Description::Description.
bioAssayDimension — sets the value of the bioAssayDimension association.
- the value must be of type: instance of Bio::MAGE::BioAssayData::BioAssayDimension.
designElementDimension — sets the value of the designElementDimension association.
- the value must be of type: instance of Bio::MAGE::BioAssayData::DesignElementDimension.
security — sets the value of the security association (inherited from Bio::MAGE::Describable).
- the value must be of type: instance of Bio::MAGE::AuditAndSecurity::Security.
auditTrail — sets the value of the auditTrail association (also inherited from Bio::MAGE::Describable).
- the value must be of type: array of Bio::MAGE::AuditAndSecurity::Audit.
propertySets — sets the value of the propertySets association (inherited from Bio::MAGE::Extendable).
- the value must be of type: array of Bio::MAGE::NameValueType.
quantitationDimension — sets the value of the quantitationDimension association.
- the value must be of type: instance of Bio::MAGE::BioAssayData::QuantitationTypeDimension.

`$obj = class->new(%parameters)`

new() is the class constructor. main character energy, obviously.

Parameters: if you hand it a list of name/value parameters, the corresponding slots, attributes, or associations get their initial values set right there by the constructor. one-stop shopping ✨
Return value: a reference to an object of the class.
Side effects: it invokes the initialize() method if the class defines one.

`@names = class->get_slot_names()`

get_slot_names() grabs the name of every slot defined in a given class.

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

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

`@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.

`@class_list = get_subclasses()`

returns the list of subclasses for this class.

`$name = class_name()`

returns the full class name for this class.

`$package_name = package_name()`

returns the base package name (i.e. no namespace::) of the package that contains this class.

`%assns = associations()`

returns the association meta-information in a hash where the keys are the association names and the values are Association objects that provide the meta-information for the association. very meta, very chic 💜

🫶 INSTANCE METHODS 🫶

`$obj_copy = $obj->new()`

when you invoke new() on an existing object reference and not on a class name, it acts as a copy constructor — the new object's initial values get set to those of the existing object. clone era 💅

Parameters: no input parameters are used in the copy constructor, the initial values are taken directly from the object to be copied.
Return value: a reference to an object of the class.
Side effects: it invokes the initialize() method if it is defined by the class.

`$obj->set_slots(%parameters)`

`$obj->set_slots(\@name_list, \@value_list)`

set_slots() sets a bunch of slots at the same time. it has two different invocation methods — the first takes a named parameter list, and the second takes two array references. pick your fighter ✨

Return value: none.
Side effects: will call croak() if a slot_name is used that the class does not define. so like, don't make up slot names. it will notice. 😭

`@obj_list = $obj->get_slots(@name_list)`

get_slots() gets the values of a number of slots at the same time.

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 has not been initialized.
Side effects: none.

🎀 ATTRIBUTES 🎀

attributes are simple data types that belong to a single instance of a class. in the Perl implementation of the MAGE-OM classes, the interface to attributes is implemented using separate setter and getter methods for each attribute — one to write, one to read, no multitasking 🦋

Bio::MAGE::HigherLevelAnalysis::NodeContents has the following attribute accessor methods:

(and that's it. that's the list. this class has none. slay, an empty list, iconic minimalism 💅)

🌸 ASSOCIATIONS 🌸

associations are references to other classes. every association in MAGE-OM has a cardinality that determines the minimum and maximum number of instances of the 'other' class that may be included in the association. here's the decoder ring:

1 — there must be exactly one item in the association, i.e. this is a mandatory data field.
0..1 — there may be one item in the association, i.e. this is an optional data field.
1..N — there must be one or more items in the association, i.e. this is a mandatory data field, with list cardinality.
0..N — there may be one or more items in the association, i.e. this is an optional data field, with list cardinality.

Bio::MAGE::HigherLevelAnalysis::NodeContents has the following association accessor methods:

`descriptions`

methods for the descriptions association.

from the MAGE-OM documentation:

Free hand text descriptions. Makes available the associations of Description to an instance of Describable.

`$array_ref = $nodecontents->setDescriptions($array_ref)`

the restricted setter method for the descriptions association.

Input parameters: the value to which the descriptions association will be set : a reference to an array of objects of type Bio::MAGE::Description::Description.
Return value: the current value of the descriptions association : a reference to an array of objects of type Bio::MAGE::Description::Description.
Side effects: none.
Exceptions: will call croak() if no input parameters are specified, or if too many input parameters are specified, or if $array_ref is not a reference to an array class Bio::MAGE::Description::Description instances. so like, get it right or get croaked 💀

`$array_ref = $nodecontents->getDescriptions()`

the restricted getter method for the descriptions association.

Input parameters: none.
Return value: the current value of the descriptions association : a reference to an array of objects of type Bio::MAGE::Description::Description.
Side effects: none.
Exceptions: will call croak() if any input parameters are specified. yeah, zero arguments only, it's not negotiable 🙈

`$val = $nodecontents->addDescriptions(@vals)`

because the descriptions association has list cardinality, it may store more than one value. this method adds the current list of objects in the descriptions association.

Input parameters: the list of values @vals to add to the descriptions association. NOTE: submitting a single value is permitted.
Return value: the number of items stored in the slot after adding @vals.
Side effects: none.
Exceptions: will call croak() if no input parameters are specified, or if any of the objects in @vals is not an instance of class Bio::MAGE::Description::Description