compoundFactory: Create 'gangsta' objects

In FluvialLandscapeLab/gangsta: The Generalized Algorithm for Nutrient, Growth, Stoichiometric and Thermodynamic Analysis

Description

compoundFactory and processFactory are the primary functions used to create gangsta objects. compoundFactory is a function that creates a compound object and all associated pool objects for use by the gangsta package. processFactory creates a process object and all associated transfer objects.

Usage

compoundFactory(compoundName, molarRatios, initialMolecules,
  respirationRate = NA, infiniteCompound = F)

processFactory(gangstaObjects, processName, energyTerm, fromCompoundNames,
  toCompoundNames, molarTerms, transferOptions = NULL, organismName = "",
  limitToInitMolecules = T)

Arguments

compoundName	A character vector of length = 1 containing the name of the compound to be created.
molarRatios	A named numeric vector. Vector names are the names of the chemical elements (think 'periodic table in chemistry') that are in the compound and that are to be tracked by gangsta. Values in the vector are the ratios for the number of atoms of each element in the compound.
initialMolecules	The number of mols (or umols, etc.) of the compound available at the beginning of the simulation. If the compound is of type infiniteCompound, then initialMolecules must be set to 0.
respirationRate	The respiration rate (in units of energy per unit of biomass per model timestep); applies to organism objects. When respirationRate is numeric, an organism object is returned. When NA, a compound object is returned. respirationRate values must be negative (i.e., energy cost to the organisms).
infiniteCompound	Boolean when set to TRUE tags a compound as being unlimited in supply. infiniteCompounds represent sources/sinks. When infiniteCompound is set to TRUE, initialMolecules must be set to 0.
gangstaObjects	A list of objects of class gangsta representing the organisms, compounds, pools, processes, and transfers to be included in the model. These objects are created using compoundFactory and processFactory. compoundFactory must be executed before processFactory because gangstaObjects for all compounds involved in a process must be created before processFactory can create the process.
processName	A character vector of the name of the process to be created.
energyTerm	The chemical affinity of the processs. A positive number represents a process that yeilds energy, a negative number represents a process that consumes energy. Units are kJ (or J, etc.) of energy per mol (or umol, etc.) of the reaction.
fromCompoundNames	Named list where the name of each list member is the a chemical element derived from the compound. For instance, to track carbon flux from the oxidation of glucose, the fromCompoundNames list might be list(C = "C6H12O6", O = "O2")
toCompoundNames	See fromCompoundNames. To track carbon flux from the oxidation of glucose, the toCompoundNames list might be list(C = "CO2", O = "Ox") (where Ox is a undifferentiated sink for oxygen comprised of H2O and CO2). The names of toCompoundNames must be the same and in the same order as those of fromCompoundNames.
molarTerms	Named list containing the mols (or umols, etc.) of each element that are transfered by the process. The names of molarTerms must be the same and in the same order as those of fromCompoundNames and toCompoundNames.
transferOptions	When transferOptions is NULL, processFactory will create these automatically. transferOptions consist of a list of integer or numeric vectors containing the indicies of transfers in a process. This specification is appropriate when each from pool has exactly one to pool. However, these must be specified when more than one to pool exists for any transfer involved in a process, i.e., indicies are grouped when transfers represent optional pathways. For instance, if a process has four transfers (fromA -> toA, fromB -> toB1, fromB -> toB2, fromC -> toC), the second and third transfers can represent an option. fromB can go to either toB1 or toB2, so long as the sum of the two options is in stoichiometric balance with the A and C tranfers. To represent such an option, the transferOption list would be list(1, 2:3, 4).
organismName	Name of the organism carrying out the process.

Details

The gangsta uses several classes of S3 objects to represent biogeochemical systems. All S3 objects in gangsta are built atop named lists with the class arribute set. The list's names are used as attribute names and the values in the lists are the attribute values.

compound objects represent chemical species (e.g., SO4 and HS) that generally contain one or more chemical elements; the mols (or umols, etc.) of each element of interest (i.e., tracked element) within a compound are tracked using a pool. Each pool records the mols of a tracked element in the compound.

The molarRatios describe the chemical composition of the tracked elements contained in compounds. For example, the molarRatios for water could be represented as c(H = 2, O = 1) because a molecule of water is composed of two hydrogen atoms and one oxygen atom.

Not all elements in a compound must be tracked. The model developer only creates pools for the elements of interest. For instance, when creating a compound for SO4, passing c(S=1) to compoundFactory as the molarRatios vector would create only a pool for sulfur, not for oxygen. Two pools, one for sulfur and one for oxygen, would be created by passing c(S=1, O=4).

compound objects have attributes named name, initialMolecules which are the starting values for the model run, and infiniteCompound which is a Boolean indicating whether the compound is a source/sink.

compound objects are also used to represent organisms (which assimilate elements as they grow) in gangsta-derived models. organism objects inherit from compound and contain an extra attribute called respirationRate For organisms, the respirationRate is energy (J, KJ, etc.) per mol (or umol, etc.) of compound per timestep.

pool objects have attributes called name, elementName which is the chemical element stored in the pool, compoundName which indicates the compound with which the pool is associated, and molarRatio which describes the ratio of atoms in the pool per unit molecule, i.e., compound.

process objects have attributes called name, energyTerm which is equal to the energy generated or consumed by the process, organismName which is the name of the organism carrying out the process, and transferOptions which are indices for the transfers associated with each process. Each process with nonzero energyTerm is of class "metabolic."

transfer objects have attributes called name, from which is the pool from which atoms are being transfered, to which is the pool to which atoms are being transfered, molarTerm which enforces the stoichiometry of the process, molarAffinity which is equal to the energyTerm of the process divided by the molarTerm of the transfer, processName which is the name of the process that the transfer is associated with, and limitToInitMolecules which is a Boolean that inherits from process.

gangsta-derived models can operate using any unit of atomic count unit (mols, umols, etc.), unit of energy (Joules, KJ, etc.) over any time unit defined by the user. However, it is critical that all units for values passed to the model be consistent. For example, the units of respirationRate and the units of atomic count used by pool objects must be consistent with the units of all other values passed to functions in the gangsta package.

Value

compoundFactory returns a list of compound and pool objects. processFactory return a list of process and transfer objects.

FluvialLandscapeLab/gangsta documentation built on May 6, 2019, 5:05 p.m.