| thermo {CHNOSZ} | R Documentation |
The core data files provided with CHNOSZ are in the data directory of the package. These *.csv files are used to build the thermo data object on loading the package. Additional (extra) data files, supporting the examples and vignettes, are documented separately at extdata.
The thermo object holds the thermodynamic database of properties of species, some thermodynamic constants and operational parameters for functions in CHNOSZ, the properties of elements, references to literature sources of thermodynamic data, compositions of chemical activity buffers, and amino acid compositions of proteins. The thermo object also holds intermediate data used in calculations, in particular the definitions of basis species and species of interest input by the user, and the calculated properties of water so that subsequent calculations at the same temperature-pressure conditions can be accelerated.
The thermo object is a list composed of data.frames or lists each representing a class of data. The object is created in the global environment upon loading the package (by .onAttach). At any time, the user can restore the data object to its initial state by calling data(thermo). This is sometimes a useful command to use during an interactive session, when previous definitions of basis species and species of interest are longer desired.
The function add.obigt is available to update the thermodynamic database in use in a running session. Using this function is the recommended way for users to incorporate custom additions or changes to thermodynamic data. For example, one can run add.obigt("mydata.csv") after loading the package, and the data in that file will be added to the database. The format of this file must be the same as the OBIGT.csv file provided with CHNOSZ. Although changes made using add.obigt are lost when the current R session is closed, the data can always be restored the next time as long as the user has the mydata.csv (or other) file available.
The first example below shows how to find the installation locations of OBIGT.csv and other *.csv files. Making changes to these files is not recommended, because incompatible changes can leave the package unusable; also, the files will be overwritten whenver the package is installed (or updated). Instead, use these files as templates for creating your own database files.
data(thermo)
The items in the thermo object are documented below.
thermo$opt
List of operational parameters
Tr | numeric | Reference temperature (K) |
Pr | numeric | Reference pressure (bar) |
Theta | numeric | Theta in the revised HKF equations of state (K) |
Psi | numeric | Psi in the revised HKF equations of state (bar) |
cutoff | numeric | Cutoff below which values are taken to be zero (see makeup) |
E.units | character | The user's units of energy (cal (default) or J) |
T.units | character | The user's units of temperature (C (default) or K) |
P.units | character | The user's units of pressure (bar (default) or MPa) |
state | character | The default physical state for searching species (aq by default) |
ionize | logical | Should affinity perform ionization calculations for proteins? |
water | character | Computational option for properties of water (SUPCRT (default) or IAPWS) |
online | logical | Allow online searches of protein composition? Default (NA) is to ask the user. |
thermo$element
Dataframe containing the thermodynamic properties of elements taken from Cox et al., 1989 and Wagman et al., 1982. The standard molal entropy (S(Z)) at 25 degrees C and 1 bar for the element of charge (Z) was calculated from S(H2,g) + 2S(Z) = 2S(H+), where the standard molal entropies of H2,g and H+ were taken from Cox et al., 1989. The mass of Z is taken to be zero. Accessing this dataframe using element will select the first entry found for a given element; i.e., values from Wagman et al., 1982 will only be retrieved if the properties of the element are not found from Cox et al., 1989.
element | character | Symbol of element |
state | character | Stable state of element at 25 degrees C and 1 bar |
source | character | Source of data |
mass | numeric | Mass of element (in natural isotopic distribution; |
| referenced to a mass of 12 for 12C) | ||
s | numeric | Entropy of the compound of the element in its stable |
| state at 25 degrees C and 1 bar (cal K^-1 mol^-1) | ||
n | numeric | Number of atoms of the element in its stable |
| compound at 25 degrees C and 1 bar |
thermo$obigt
This dataframe is a thermodynamic database of standard molal thermodynamic properties and equations of state parameters of species. OBIGT is an acronym for OrganoBioGeoTherm, which refers to a software package produced by Harold C. Helgeson and coworkers at the Laboratory of Theoretical Geochemistry and Biogeochemistry at the University of California, Berkeley. (There may be an additional meaning for the acronym: “One BIG Table” of thermodynamic data.)
As of CHNOSZ version 0.7, the data in OBIGT.csv represent 179 minerals, 16 gases, and 294 aqueous (largely inorganic) species taken from the data file included in the SUPCRT92 distribution (Johnson et al., 1992), an additional 14 minerals, 6 gases, and 1049 aqueous organic and inorganic species from the slop98.dat file (Shock et al., 1998), and approximately 50 other minerals, 175 crystalline organic and biochemical species, 220 organic gases, 300 organic liquids, 650 aqueous inorganic, organic, and biochemical species, and 40 organic groups taken from the recent literature. Each entry is referenced to one or two literature sources listed in thermo$refs. Note the following additional modifications:
Z, see above).
These modifications are indicated in OBIGT.csv by having CHNOSZ as one of the sources of data. Note also that some data appearing in the slop98.dat file (Shock et al., 1998) were corrected or modified as noted in that file, and are indicated in OBIGT.csv by having SLOP98 as one of the sources of data.
In order to represent thermodynamic data for minerals with phase transitions, the different phases of these minerals are represented as phase species that have states denoted by cr1, cr2, etc. The standard molar thermodynamic properties at 25 degrees C and 1 bar (Pr and Pr) of the cr2 phase species of minerals were generated by first calculating those of the cr1 phase species at the transition temperature (Ttr) and 1 bar then taking account of the volume and entropy of transition (the latter can be retrieved by combining the former with the Clausius-Clapeyron equation and values of (dP/dT) of transitions taken from the SUPCRT92 data file) to calculate the standard molar entropy of the cr2 phase species at Ttr, and taking account of the enthalpy of transition (DeltaH0, taken from the SUPCRT92 data file) to calculate the standard molar enthalpy of the cr2 phase species at Ttr. The standard molar properties of the cr2 phase species at Ttr and 1 bar calculated in this manner were combined with the equations-of-state parameters of the species to generate values of the standard molar properties at 25 degrees C and 1 bar. This process was repeated as necessary to generate the standard molar properties of phase species represented by cr3 and cr4, referencing at each iteration the previously calculated values of the standard molar properties of the lower-temperature phase species (i.e., cr2 and cr3). A consequence of tabulating the standard molar thermodynamic properties of the phase species is that the values of (dP/dT) and DeltaH0 of phase transitions can be calculated using the equations of state and therefore do not need to be stored in the thermodynamic database. However, the transition temperatures (Ttr) generally can not be assessed by comparing the Gibbs energies of phase species and are tabulated in the database.
The identification of species and their standard molal thermodynamic properties at 25 degrees C and 1 bar are located in the first 12 columns of thermo$obigt:
name | character | Species name |
abbrv | character | Species abbreviation |
formula | character | Species formula |
state | character | Physical state |
ref1 | character | Primary source |
ref2 | character | Secondary source |
date | character | Date of data entry |
G | numeric | Standard molal Gibbs energy of formation |
| from the elements (cal mol^-1) | ||
H | numeric | Standard molal enthalpy of formation |
| from the elements (cal mol^-1) | ||
S | numeric | Standard molal entropy (cal mol^-1 K^-1) |
Cp | numeric | Standard molal isobaric heat capacity (cal mol^-1 K^-1) |
V | numeric | Standard molal volume (cm^3 mol^-1) |
The meanings of the remaining columns depend on the physical state of a particular species. If it is aqueous, the values in these columns represent parameters in the revised HKF equations of state (see hkf), otherwise they denote parameters in a general equations for crystalline, gas and liquid species (see cgl). The names of these columns are compounded from those of the parameters in each of the equations of state (for example, column 13 is named a1.a). Scaling of the values by orders of magnitude is adopted for some of the parameters, following common usage in the literature.
Columns 13-20 for aqueous species (parameters in the revised HKF equations of state):
a1 | numeric | a1 * 10 (cal mol^-1 bar^-1) |
a2 | numeric | a2 * 10^{-2} (cal mol^-1) |
a3 | numeric | a3 (cal K mol^-1 bar^-1) |
a4 | numeric | a4 * 10^-4 (cal mol^-1 K) |
c1 | numeric | c1 (cal mol^-1 K^-1) |
c2 | numeric | c2 * 10^-4 (cal mol^-1 K) |
omega | numeric | omega * 10^-5 (cal mol^-1) |
Z | numeric | Charge
|
Columns 13-20 for crystalline, gas and liquid species (Cp = a + bT + cT^-2 + dT^-0.5 + eT^2 + fT^lambda).
a | numeric | a (cal K^-1 mol^-1) |
b | numeric | b * 10^3 (cal K^-2 mol^-1) |
c | numeric | c * 10^-5 (cal K mol^-1) |
d | numeric | d (cal K^-0.5 mol^-1) |
e | numeric | e * 10^5 (cal K^-3 mol^-1) |
f | numeric | f (cal K-lambda-1 mol^-1) |
lambda | numeric | lambda (exponent on the f term) |
T | numeric | Temperature of phase transition or upper |
| temperature limit of validity of extrapolation (K) |
thermo$source
Dataframe of references to sources of thermodynamic data.
key | character | Source key |
author | character | Author(s) |
year | character | Year |
citation | character | Citation (journal title, volume, and article number or pages; or book or report title) |
URL | character | URL |
thermo$buffers
Dataframe which contains definitions of buffers of chemical activity. Each named buffer can be composed of one or more species, which may include any species in the thermodynamic database and/or any protein. The calculations provided by buffer do not take into account phase transitions of minerals, so individual phase species of such minerals must be specified in the buffers.
name | character | Name of buffer |
species | character | Name of species |
state | character | Physical state of species |
logact | numeric | Logarithm of activity (fugacity for gases) |
thermo$protein
Dataframe of amino acid compositions of selected proteins. Many of the compositions were taken from the SWISS-PROT/UniProt online database (Boeckmann et al., 2003) and the protein and organism names usually follow the conventions adopted there. In some cases different isoforms of proteins are identified using modifications of the protein names; for example, MOD5.M and MOD5.N proteins of YEAST denote the mitochondrial and nuclear isoforms of this protein. Note that get.protein and get.expr can both be used to add proteins to this table using some of the extdata files provided with the package. add.protein is available to add proteins from local files provided by the user.
protein | character | Identification of protein |
organism | character | Identification of organism |
ref | character | Reference key for source of compositional data |
abbrv | character | Abbreviation or other ID for protein |
chains | numeric | Number of polypeptide chains in the protein |
Ala...Tyr | numeric | Number of each amino acid in the protein |
thermo$stress
Dataframe listing proteins identified in selected proteomic stress response experiments. The names of proteins begin at row 3, and columns are all the same length (padded as necessary at the bottom by NAs). Names correspond to ordered locus names (for SGD) or gene names (for ECO). The column names and first two rows give the following information:
colname | character | Name of the experiment |
organism | character | Name of the organism (SGD or ECO) |
ref | character | Reference key for source of the data |
thermo$groups
This is a dataframe with 22 columns for the amino acid sidechain, backbone and protein backbone groups ([Ala]..[Tyr],[AABB],[UPBB]) whose rows correspond to the elements C, H, N, O, S. It is used to quickly calculate the chemical formulas of proteins that are selected using the iprotein argument in affinity.
thermo$basis
Initially NULL, reserved for a dataframe written by basis upon definition of the basis species. The number of rows of this dataframe is equal to the number of columns in “...” (one for each element).
... | numeric | One or more columns of stoichiometric |
| coefficients of elements in the basis species | ||
ispecies | numeric | Rownumber of basis species in thermo$obigt |
logact | numeric | Logarithm of activity or fugacity of basis species |
state | character | Physical state of basis species |
thermo$species
Initially NULL, reserved for a dataframe generated by species to define the species of interest. The number of columns in “...” is equal to the number of basis species (i.e., rows of thermo$basis).
... | numeric | One or more columns of stoichiometric |
| coefficients of basis species in the species of interest | ||
ispecies | numeric | Rownumber of species in thermo$obigt |
logact | numeric | Logarithm of activity or fugacity of species |
state | character | Physical state of species |
name | character | Name of species |
thermo$water
The properties calculated with water at multiple T, P points (minimum of 26) are stored here so that repeated calculations at the same conditions can be done more quickly.
thermo$Psat
The values of Psat calculated with water.SUPCRT at multiple T points (minimum of 26) are stored here.
thermo$water2
The properties calculated with water.SUPCRT at multiple T, P points (minimum of 26) are stored here.
Amend, J. P. and Helgeson, H. C. (1997b) Calculation of the standard molal thermodynamic properties of aqueous biomolecules at elevated temperatures and pressures. Part 1. L-alpha-amino acids. J. Chem. Soc., Faraday Trans. 93, 1927–1941. http://dx.doi.org/10.1039/a608126f
Cox, J. D., Wagman, D. D. and Medvedev, V. A., eds. (1989) CODATA Key Values for Thermodynamics. Hemisphere Publishing Corporation, New York, 271 p. http://www.worldcat.org/oclc/18559968
Dick, J. M., LaRowe, D. E. and Helgeson, H. C. (2006) Temperature, pressure, and electrochemical constraints on protein speciation: Group additivity calculation of the standard molal thermodynamic properties of ionized unfolded proteins. Biogeosciences 3, 3110–336. http://www.biogeosciences.net/3/311/2006/bg-3-311-2006.html
Johnson, J. W., Oelkers, E. H. and Helgeson, H. C. (1992) SUPCRT92: A software package for calculating the standard molal thermodynamic properties of minerals, gases, aqueous species, and reactions from 1 to 5000 bar and 0 to 1000degrees C. Comp. Geosci. 18, 899–947. http://dx.doi.org/10.1016/0098-3004(92)90029-Q
Shock, E. L. and Koretsky, C. M. 1995 Metal-organic complexes in geochemical processes: Estimation of standard partial molal thermodynamic properties of aqueous complexes between metal cations and monovalent organic acid ligands at high pressures and temperatures. Geochim. Cosmochim. Acta 59, 1497–1532. http://dx.doi.org/10.1016/0016-7037(95)00058-8
Shock, E. L. et al. 1998 SLOP98.dat (computer data file). http://geopig.asu.edu/supcrt92_data/slop98.dat, accessed on 2005-11-05. Current location: http://geopig.asu.edu/sites/default/files/slop98.dat.
Wagman, D. D., Evans, W. H., Parker, V. B., Schumm, R. H., Halow, I., Bailey, S. M., Churney, K. L. and Nuttall, R. L. (1982) The NBS tables of chemical thermodynamic properties. Selected values for inorganic and C1 and C2 organic substances in SI units. J. Phys. Chem. Ref. Data 11 (supp. 2), 1–392. http://www.nist.gov/srd/PDFfiles/jpcrdS2Vol11.pdf
add.protein and add.obigt for adding amino acid compositions of proteins and thermodynamic data from local .csv files.
## where are OBIGT.csv and the other data
## files on your installation?
system.file("data",package="CHNOSZ")
## exploring thermo$obigt
# what physical states there are
unique(thermo$obigt$state)
# formulas of ten random species
n <- nrow(thermo$obigt)
thermo$obigt$formula[runif(10)*n]
## make a table of duplicated species
name <- thermo$obigt$name
state <- thermo$obigt$state
ref <- thermo$obigt$ref1
species <- paste(name,state)
dups <- species[which(duplicated(species))]
id <- numeric()
for(i in 1:length(dups)) id <- c(id,which(species %in% dups[i]))
data.frame(name=name[id],state=state[id],ref=ref[id])
# give an error if there are any duplicates
stopifnot(length(id) > 0)