makeup: Chemical Formulas and Compositions

Description

Convert between representations of chemical composition.

Usage

makeup(compound = "", component = NULL)

Arguments

compound

character, the formula of a compound; other types are possible (see below).

component

numeric, coefficient used to sum makeups; other types are possible (see below).

Value

When this function is called with a single argument that is a string representation of a formula, the elemental composition, or makeup is returned as a dataframe of one column with $n$ rows, where $n$ is the number of elements present. If a single argument is other than character, or there is more than one argument, the action of the function is determined by the characteristics of the arguments. In the summary below, makeup indicates a dataframe, and formula refers to a string (character) representation of a formula. elements represents a dataframe of a single row.
(formula) Return makeup, the elemental composition of the formula.
(makeup,makeup) Return makeup, the sum of the two arguments.
(numeric,numeric) Return makeup, the sum of the makeups of the species identified in the first argument (corresponding to rownumber of thermo$obigt), each multiplied by the coefficient given in the second argument (taken as $1$ if missing).
(formula,numeric) Return a list which contains the word (name of or coefficient on an element) beginning at the position in the formula string specified by the second argument, and the length of the word.
(formula,formula) Return makeup, sum of the two arguments.
(makeup,character) Return elements: transpose makeup, using all the elements (if the second argument is ""), or only those specified in the second argument.
(makeup,TRUE) Return elements, not the elements, but the stoichiometry of the basis species in the formation reaction for this compound. Requires prior definition of basis species; see basis.
(elements,FALSE) Return elements, change entries in the dataframe that are less than the value in thermo$opt$cutoff to zero.
(formula,character) Return character, the unique elements contained by the formulas (character argument is necessary but ignored).
(list of makeup,character) Return character, the unique elements contained by the makeups (character argument is necessary but ignored).
(elements,character) Return character, a formula representation (i.e., "CO2") of the elements, (character argument must be "" or the names of elements to consider).

Details

This function performs operations on objects representing chemical compositions, or formulas, of compounds. In the simple case, when compound is a character object containing a chemical formula as a string, the return value is a dataframe object with a single column named count that lists the coefficients of each of the elements in the formula. With other combinations of arguments, this function can be used to sum compositions, count only specified elements, generate string representations of formulas from dataframes, or perform other operations listed in the table below.

The elements in a formula are symbolized by an uppercase letter followed by zero or more lowercase letters. Multiple pairs of parenthesis are allowed, but may not be nested. Coefficients after the elemental symbols can be non-integer values and/or negative. Charge is denoted (at the end of a formula, or preceding an asterisk or colon) by a value which can be non-integer, optionally preceded by + or - (Hence, Fe+3 stands for ferric iron; Fe3+ is interpreted as three iron atoms with a net charge of plus one). An asterisk or a colon indicates to add the composition that follows, which may have a leading numerical coefficient. Some examples of valid formulas are Rh(SO4)3-4, KAl3(OH)6(SO4)2 and Ca(Al2Si7)O18*6H2O.

Charge is treated here like a chemical element. Hence, Z can appear in chemical formulas, and has atomic number zero and oxidation state +1 (cf. function ZC, which calculates nominal carbon oxidation states from chemical formulas, including for charged species). For example, the formula of the ammonium ion is written commonly as NH4+; in CHNOSZ this same composition can also be identified with NH4Z. One reason for assigning an elemental symbol to charge is that it facilitates the representation of ionized chemical formulas in data objects. Consequently any computations that derive from the complete stoichiometries of species, if they impose conservation of mass, implicitly also account for conservation of charge. The chemical formula of the electron is represented by Z-1; the electron and charge can be considered to be the same element (with atomic number zero) in different oxidation states. (Note that following these conventions, the symbol for the electron, e-, does not appear in chemical formulas.)

Examples

Run this code

data(thermo)
  
  ## makeups (nrow = number of elements)
  # the composition of a single compound (ncol=1)
  makeup('CO2')
  # negative coefficients
  makeup('C-4O2')
  makeup('C-4O-2')  # interpreted as having charge -2
  makeup('C-4O-2+0') # no charge
  # sum the compositions			
  makeup(c('CO2','CH4'))
  # sum with coefficients	
  makeup(info(c('CO2','CH4')),c(-1,1))
  # this one adds up to zero
  makeup(c('C6H12O6','C2H5OH','CO2'),c(-1,2,2))

  ## formulas (ncol = number of elements)
  # as a dataframe	
  makeup('Zn(CH3CH2CH2CH2CO2)2','')
  print( t <- makeup(c('HCl','H2O'),'') )
  # as a character formula
  makeup(makeup(info('glycinium'),''),'')
  makeup(t,'')
  # C6H12O6
  makeup(makeup(makeup('CHO6H11C5'),''),'')

  ## charged species, electron
  # these return the same:
  makeup('NH4+')
  makeup('NH4Z')
  # constitution of the electron
  makeup(info('e-'))
  # this produce an INcorrect makeup for the electron, 
  # and gives a warning because 'e' is not in the
  # table of elements.
  makeup('e-')
  # compositions of made-up compounds
  makeup('CHNOS')
  makeup('CHNOSZ')
  makeup('CHNOSe')  # Se is an element

Run the code above in your browser using DataLab