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 Rsession 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)thermo object are documented below.
thermo$optList of operational parametersTr 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 (seemakeup)
E.units character The user's units of energy (cal(default) orJ)
T.units character The user's units of temperature (C(default) orK)
P.units character The user's units of pressure (bar(default) orMPa)
state character The default physical state for searching species (aqby default)
ionize logical Shouldaffinityperform ionization calculations for proteins?
water character Computational option for properties of water (SUPCRT(default) orIAPWS)
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 $^{\circ}$C and 1 bar for the element of charge (Z) was calculated from $S$(H2,g) + 2$S$(Z) = 2$S$(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 $^{\circ}$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 $^{12}$C)
s numeric Entropy of the compound of the element in its stable
state at 25 $^{\circ}$C and 1 bar (cal K$^{-1}$ mol$^{-1}$)
n numeric Number of atoms of the element in its stable
compound at 25 $^{\circ}$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:
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 $^{\circ}$C and 1 bar ($T_r$ and $P_r$) of the cr2 phase species of minerals were generated by first calculating those of the cr1 phase species at the transition temperature ($T_{tr}$) 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 $T_{tr}$, and taking account of the enthalpy of transition (${\Delta}H^{\circ}$, taken from the SUPCRT92 data file) to calculate the standard molar enthalpy of the cr2 phase species at $T_{tr}$. The standard molar properties of the cr2 phase species at $T_{tr}$ 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 $^{\circ}$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 ${\Delta}H^{\circ}$ 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 ($T_{tr}$) 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 ${^\circ}$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 $a_1\times10$ (cal mol$^{-1}$ bar$^{-1}$)
a2 numeric $a_2\times10^{-2}$ (cal mol$^{-1}$)
a3 numeric $a_3$ (cal K mol$^{-1}$ bar$^{-1}$)
a4 numeric $a_4\times10^{-4}$ (cal mol$^{-1}$ K)
c1 numeric $c_1$ (cal mol$^{-1}$ K$^{-1}$)
c2 numeric $c_2\times10^{-4}$ (cal mol$^{-1}$ K)
omega numeric $\omega\times10^{-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\times10^3$ (cal K$^{-2}$ mol$^{-1}$)
c numeric $c\times10^{-5}$ (cal K mol$^{-1}$)
d numeric $d$ (cal K$^{-0.5}$ mol$^{-1}$)
e numeric $e\times10^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 ... 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 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.add.protein and add.obigt for adding amino acid compositions of proteins and thermodynamic data from local .csv files.
## 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)
Cox, J. D., Wagman, D. D. and Medvedev, V. A., eds. (1989) CODATA Key Values for Thermodynamics. Hemisphere Publishing Corporation, New York, 271 p.
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.
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 1000$^{\circ}$C. Comp. Geosci. 18, 899--947.
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.
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:
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 C$_1$ and C$_2$ organic substances in SI units. J. Phys. Chem. Ref. Data 11 (supp. 2), 1--392.