basis: Define Basis Species

View source: R/basis.R

basisR Documentation

Define Basis Species

Description

Define the basis species of a chemical system.

Usage

  basis(species = NULL, state = NULL, logact = NULL,
    delete = FALSE, add = FALSE)

Arguments

species

character, names or formulas of species, or numeric, indices of species

state

character, physical states or names of buffers

logact

numeric, logarithms of activities or fugacities

delete

logical, delete the current basis definition?

add

logical, add species to the current basis definition?

Details

The basis species represent the possible range of chemical compositions for all the species of interest. As used here, a set of basis species is valid only if it satisifes two conditions: 1) the number of basis species is the same as the number of chemical elements (including charge) in those species and 2) the square matrix representing the elemental stoichiometries of the basis species has a real inverse.

To create a basis definition, call basis with the names or formulas of the basis species in the species argument, or all numeric values as species indices (rownumbers in thermo()$OBIGT). The special names ‘⁠pH⁠’, ‘⁠pe⁠’ and ‘⁠Eh⁠’ can also be used; they get translated into the names of the proton (‘⁠H+⁠’) and electron (‘⁠e-⁠’) as appropriate. If desired, include the state for the named species and the logarithms of activity (fugacity for gases) in logact. The latter defaults to zero (unit activity) if not specified.

To modify an existing basis definition, the physical states or logarithms of activities of species can be changed by calling basis with a species argument that has the formulas (not names) or indices of species in the existing basis. If either of the second or third arguments to basis is of type character, it refers to the physical state (if present in thermo()$OBIGT$state) or a chemical activity buffer (if present in thermo()$buffers$name). If either of these arguments is numeric it specifies the logarithms of activities (or fugacities for gases) of the basis species. In case ‘⁠pH⁠’, ‘⁠pe⁠’ or ‘⁠Eh⁠’ is named, the logarithm of activity of the basis species is converted from these values. For example, a value of 7 for pH is stored as a logarithm of activity of -7.

If add is TRUE, then the function attempts to add the indicated species to the basis definition. This only works if the enlarged set of species is a valid basis set as described above. If the formed species are currently defined, their formation reactions are modified accordingly (with zeroes for the newly added basis species).

If add is FALSE, and if basis is called with NULL values of both state and logact, the new set of species, if they are a valid basis set, completely replaces any existing basis definition. When this occurs, any existing species definition (created by the species function) is deleted. Call basis with delete set to TRUE or species set to ‘⁠""⁠’ to clear the basis definition and that of the species, if present.

If the value of basis is one of the keywords in the following table, the corresponding set of basis species is loaded, and their activities are given preset values. The basis species identified by these keywords are aqueous except for \H2O (liq), \O2 (gas) and \Fe2O3 (hematite).

CHNOS \CO2, \H2O, \NH3, \H2S, \O2
CHNOS+ \CO2, \H2O, \NH3, \H2S, \O2, \Hplus
CHNOSe \CO2, \H2O, \NH3, \H2S, \eminus, \Hplus
CHNOPS+ \CO2, \H2O, \NH3, \H3PO4, \H2S, \O2, \Hplus
CHNOPSe \CO2, \H2O, \NH3, \H3PO4, \H2S, \eminus, \Hplus
MgCHNOPS+ \Mgplus2, \CO2, \H2O, \NH3, \H3PO4, \H2S, \O2, \Hplus
MgCHNOPSe \Mgplus2, \CO2, \H2O, \NH3, \H3PO4, \H2S, \eminus, \Hplus
FeCHNOS \Fe2O3, \CO2, \H2O, \NH3, \H2S, \O2
FeCHNOS+ \Fe2O3, \CO2, \H2O, \NH3, \H2S, \O2, \Hplus
QEC4 cysteine, glutamic acid, glutamine, \H2O, \O2
QEC cysteine, glutamic acid, glutamine, \H2O, \O2
QEC+ cysteine, glutamic acid, glutamine, \H2O, \O2, \Hplus
QCa glutamine, cysteine, acetic acid, \H2O, \O2
QCa+ glutamine, cysteine, acetic acid, \H2O, \O2, \Hplus

The logarithms of activities of amino acids in the ‘⁠QEC4⁠’ basis are -4 (i.e., basis II in Dick, 2016); those in ‘⁠QEC⁠’ and ‘⁠QEC+⁠’ are set to approximate concentrations in human plasma (see Dick, 2017).

Value

Returns the value of thermo()$basis after any modifications; or, if delete is TRUE, its value before deletion (invisibly).

References

Dick, J. M. (2016) Proteomic indicators of oxidation and hydration state in colorectal cancer. PeerJ 4:e2238. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.7717/peerj.2238")}

Dick, J. M. (2017) Chemical composition and the potential for proteomic transformation in cancer, hypoxia, and hyperosmotic stress. PeerJ 5:e3421 \Sexpr[results=rd]{tools:::Rd_expr_doi("10.7717/peerj.3421")}

See Also

info to query the thermodynamic database in order to find what species are available. makeup is used by basis to generate the stoichiometric matrix from chemical formulas. swap.basis is used to change the chemical compounds (species formulas) used in the basis definition while keeping the chemical potentials of the elements unaltered. species for setting up the formation reactions from basis species.

Examples


## Define basis species
# with one, two or three elements
basis("O2")
basis(c("H2O", "O2"))
basis(c("H2O", "O2", "H+"))
## Clear the basis species
basis("")

## Not run: 
## Marked dontrun because they produce errors
# Fewer species than elements
basis(c("H2O", "H+"))
# More species than elements
basis(c("H2O", "O2", "H2", "H+"))
# Non-independent species
basis(c("CO2", "H2O", "HCl", "Cl-", "H+"))
## End(Not run)

## Specify activities and states
basis(c("H2O", "O2", "CO2"), c(-2, -78, -3), c("liq", "aq", "aq"))
# Change logarithms of activities/fugacities	
basis(c("H2O", "O2"), c(0, -80))	
# Change state of CO2
basis("CO2", "gas")

CHNOSZ documentation built on May 29, 2024, 3:30 a.m.