CHNOSZ (version 0.9-6)

CHNOSZ-package: Chemical Thermodynamics and Activity Diagrams

Description

CHNOSZ is a package for thermodynamic calculations, primarily with applications in geochemistry and biochemistry. It can be used to calculate the standard molal thermodynamic properties and chemical affinities of reactions relevant to geobiochemical processes, and to visualize the equilibrium activities of species on chemical speciation and predominance diagrams. The package can be used interactively -- variations on a single command line can be used to calculate the standard thermodynamic properties of any number of reactions involving proteins and/or inorganic species such as minerals -- and in batch mode, through the use of R source files containing a sequence of commands. The major features of the package are outlined below, with links to specific help topics in this document, which constitutes the primary technical description of the package. If you are a new user, the anintro vignette (An Introduction to CHNOSZ) may offer a more comfortable way to get started with using the package.

Compatibility

The package dependency is Rversion 2.10.0 or greater (to read compressed data files). Before this, the package dependency was given as Rversion 2.7.0 or greater (major update of the X11 device in 2.7.0). However, without accessing the compressed data files in extdata it should be possible to run CHNOSZ under Rversions 2.4.0 or greater (availability of the stringsAsFactors argument to data.frame).

Acknowledgements

This package was made possible by the fearless leadership of the late Professor Harold C. Helgeson. He took no heed of disciplinary boundaries, and encouraged the author to pursue unconventional problems. Hal, and those in his research group, are in some way responsible for many parts of this package, such as the aqueous equations of state used here, the thermodynamic parameters for many species, and actual computer code (H2O92D.f, borrowed from the SUPCRT92 program). Work on this project at U.C. Berkeley (through 2008) was supported by research grants from the U.S. National Science Foundation and Department of Energy. Effective starting in 2009: This material is based upon work supported by the National Science Foundation under grant EAR-0847616 (http://www.nsf.gov/awardsearch/showAward.do?AwardNumber=0847616).

Details

Major features in CHNOSZ:

• Thermodynamic database - assembles literature values of the standard thermodynamic properties and equations of state parameters of minerals, aqueous organic and inorganic species, gases and liquids (thermo).
• Group additivity for proteins - estimate the standard thermodynamic properties and equations of state parameters for unfolded proteins from their amino acid composition; includes an additive calculation of ionization state of proteins as a function of temperature and pH (protein).
• File and internet access - read protein sequences from FASTA files, and download sequence information from UniProt (read.fasta,protein).
• Equations of state - calculate the standard thermodynamic properties of proteins or other species in the database, and reactions between them, as a function of temperature and pressure (hkf,cgl).
• Stoichiometry - count elements in chemical formulas of species, check and optionally correct mass balance of chemical reactions (makeup).
• System of interest - define the basis species for a system together with one or more species of interest; compute the stoichiometries of the formation reactions of the species of interest (basis,species).
• Chemical affinity - calculate the chemical affinities of the formation reactions of the species of interest at a single point, or as a function of one or more of chemical activities of the basis species, temperature and/or pressure (affinity).
• Chemical activity - calculate the equilibrium activities of the species of interest as a function of the same variables used in the affinity calculation, using a reference state transformation (either the Boltzmann distribution or a reaction matrix approach). These are often (in organic systems particularly) metastable equilibrium activities (i.e., the species of interest are less stable than the basis species). (diagram,equil.react,equil.boltz).
• Buffer calculations - compute the values of the activities of basis species that are determined by a buffer of one or more species (e.g., pyrite-pyrrhotite-magnetite; acetic acid-CO2) (buffer).
• Activity diagrams - plot the metastable equilibrium activities at a single point (as barcharts), or as a function of one (species activity diagrams) or two (predominance diagrams) variables (diagram).
• Activity statistics - calculate statistical quantities for metastable equilibrium activities of species. Examples of summary statistics: standard deviation, coefficient of variation, correlation with a (log)normal distribution, richness (number of species with activities above a defined minimum). Can also use a set of reference values in order to calculate root mean square deviation (RMSD), Pearson or Spearman correlation coefficients (revisit).
• Multidimensional optimization (new in 0.9-3) - using an iterative gridded optimization, find a combination of chemical activities of basis species, temperature and/or pressure that maximize or minimize the value of a target statistic (above) (findit).
• Mass transfer calculations (experimental) - calculate changes in solution composition and formation of secondary species as a function of incremental reaction of a mineral (or protein) (transfer).

Here are some tips for new users:

• Install the package from the command line withR CMD INSTALL CHNOSZ_0.9-6.tar.gz. You need the proper build environment on your machine because there is a FORTRAN source file in the package. Or, if you have gotten the binary distribution (e.g., for Windows or Mac), use theInstall packages from local zip filesoption from the GUI.
• To begin working with the package after installation, typelibrary(CHNOSZ)at the command line (or select the name of the package from the GUI menu).
• Running the examples shown in the various help topics is a great way to become more familiar with the usage of the functions. Type the commandexamples()to run all the examples provided inCHNOSZ. This takes about ten minutes depending on your system. You should receive some warning messages when the examples are finished; don't worry, they mean the functions are functioning as intended.
• To view the documentation, usehelp.start()(or chooseRhelp in the GUI) to launch a browser, and selectPackagesthenCHNOSZ. You can copy the text of individual examples from the browser window into the command line interface. The documentation topics are arranged alphabetically; to read them in a more logical order, use this sequence (identical to the order of theexamples):CHNOSZ-package,thermo,util.*,info,eos,water,subcrt,nuts,makeup,basis,species,affinity,diagram,buffer,protein,ionize,get.protein,revisit,transfer,eqdata.
• Parts of some of the examples require internet or file access or user intervention, or are intentionally written to demonstrate conditions that lead to errors. This offensive code is hidden fromR's package checking mechanism using thedontruntag. The user can experiment withdontrunexamples by pasting the code to the command line interface.
• To learn how to update the thermodynamic database, look at its documentation inthermo.
• The thermodynamic database, the system definition, and compositional data for proteins are stored in an object namedthermo, which is added into the global search space when you load the package. The commanddata(thermo)is your friend, as it causes the program to reinitialize the object. This is useful for quickly "starting over" and in some cases it is the only effective solution to errors that may occur when configuring a calculation.

Examples

data(thermo)

  ### Getting Started
  
  ## standard thermodynamic properties of species
  subcrt("H2O")
  subcrt("alanine")
  # names of proteins have an underscore
  subcrt("LYSC_CHICK")  
  # custom temperature range
  T <- seq(0,500,100)
  subcrt("H2O",T=T,P=1000)
  # temperature - pressure grid
  P <- seq(1000,4000,1000)
  subcrt("H2O",T=T,P=P,grid="P")
  
  ## information about species
  # query the database using formulas
  info("C6H12O6")
  info("SiO2")
  # query using names
  info("quartz")
  si <- info(c("glucose","mannose"))
  # show the equations of state parameters
  info(si)
  # approximate matches for names or formulas
  info("acid ")
  info("SiO2 ")

  ## standard thermodynamic properties of reactions
  # fermentation example
  info(c("fructose","ethanol"))
  subcrt(c("fructose","C2H5OH","CO2"),c(-1,2,2))
  # weathering example -- also see transfer()
  subcrt(c("k-feldspar","H2O","H+","kaolinite","K+","SiO2"),
    c(-2,-1,-2,1,2,4))
  # partial reaction auto-completion is possible
  basis(c("SiO2","H2O","K+","H+","O2"))
  subcrt(c("k-feldspar","kaolinite"),c(-2,1))
 
  ## chemical affinities
  # basis species
  basis(c("CO2","H2O","O2"))
  # species of interest
  species(c("CH4","C2H4O2","CO2"))
  # chemical affinities of formation reactions
  # take off $values for complete output
  affinity()$values
  affinity(O2=c(-90,-60,5))$values