basis: Define Basis Species

Description Usage Arguments Details Value Side Effects References See Also Examples

View source: R/basis.R


Define the basis species of a chemical system. Change their physical states or chemical activities or fugacities. Get the reaction coefficients of basis species in formation reactions of species.


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



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


character, physical states or names of buffers


numeric, logarithms of activities or fugacities


logical, delete the current basis species definition?


basis is used to define the basis species in a thermodynamic system.

The basis species represent the possible range of chemical compositions for all the species of interest. Any valid set of basis species used here must meet 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 first argument. Alternatively, the first argument may consist of numeric values indicating the species indices (rownumbers in thermo$obigt), but a mixture of character and numeric values will generate an error. The special names pH, pe and Eh can be included in the species argument; they get translated into the names of the proton (H+) and electron (e-) as appropriate.

The physical states or logarithms of activities of species in the basis definition can be changed by calling basis with the formulas of species that are in the basis set, or their species indices. If either of the second or third arguments to basis is of type character, it refers to the name of a state (if present in thermo$obigt$state) or to the name of 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.

Whenever 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. If this occurs, any existing species definition (created by the species function) is deleted. However, swap.basis can be used to change the species (the compositions and/or physical states thereof) in the basis set while maintaining the list of species of interest, with the added benefit of equivalence of the chemical potentials of the elements before and after the swap.

Call basis with delete set to TRUE to clear the basis definition. Any current basis definition (before being deleted) is returned by this call or by calling basis with all default arguments.

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. This approach is used by many of the examples in the package. The basis species identified by these keywords are aqueous except for \H2O (liq), \O2 (gas) and \Fe2O3 (hematite, cr1).

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, \eminus, \Hplus
MgCHNOPS+ \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

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).


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

Side Effects

If the new basis definition meets all requirements, it is stored in thermo$basis, replacing any previous basis definition.


Dick, J. M. (2016) Proteomic indicators of oxidation and hydration state in colorectal cancer. PeerJ 4:e2238.

Dick, J. M. (2017) Chemical composition and the potential for proteomic transformation in cancer, hypoxia, and hyperosmotic stress. PeerJ 5:e3421

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.


## define basis species
# one, two and three element examples
basis(c("H2O", "O2"))
basis(c("H2O", "O2", "H+"))
## clear the basis species

## 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 June 7, 2017, 3:01 a.m.

Search within the CHNOSZ package
Search all R packages, documentation and source code