info: Search the Thermodynamic Database

Description

Search for species by name or formula, and retrieve their thermodynamic properties and parameters.

Usage

info(species = NULL, states = NULL, quiet = FALSE, file = "", 
    return.approx = TRUE)

Arguments

species

character, names or formulas of species, or numeric, indices of species in the thermodynamic database.

states

numeric, physical states of the species.

quiet

logical, produce fewer messages and make fewer tests?

file

character, name of file to which to write test output.

return.approx

logical, return the indices of approximately matching species?

Value

If species is character of length $n$ and no approximate matches are found, the invisible return is a numeric vector of length $n$ containing for each species its index in the thermodynamic database or NA. If two or more approximate matches are located for any of the species, the return value is instead a list of length $n$, each element of which contains the matching index or indices of the species or NA. If species is numeric, the corresponding rows of the thermodynamic database are visibly returned, after removing order-of-magnitude multipliers. If species is NULL, a table of species that did not pass the consistency check.

Details

This function searches the names or chemical formulas of species in the thermodynamic database (thermo$obigt). Searches can optionally be limited to certain physical states (among aq, cr, gas, liq as well as cr1, cr2 etc.) For each of the species that is matched, the index of that species is appended to the return value. If an exact match of a species is not located, info searches the database for similar names or formulas; if any of these are found, the results are summarized on the screen, and the the indices of the approximately matching species are included in the return value (if return.approx is TRUE). Species that have no exact or approximate matches are indicated by NA in the return value.

If states is NULL (the default) and there are multiple matches for the name of a species, the species whose state is that in thermo$opt$state (aq by default) is selected, or failing that, the first matching species is taken. Exceptions to this are O2 and H2, for which the state defaults to gas.

If species is numeric instead of character, the corresponding rows of the thermodynamic database are returned, after removing any order-of-magnitude scaling factors. If these species are all aqueous or are all not aqueous, the compound column names used in the thermodynamic database are replaced with names appropriate for the corresponding equations of state.

The names of proteins are distinguished from those of other species in that they contain an underscore character, as in LYSC_CHICK. If the name of a protein is provided to info and the composition of the protein can be found using protein, the thermodyamic properties and parameters of the nonionized protein (calculated using protein) are added to the thermodynamic database. Included in the return value, as for other species, is the index of the protein in the thermodynamic database or NA if the protein is not found. Names of proteins and other species can be mixed.

If quiet is FALSE, several checks of self consistency among the thermodynamic properties and parameters are performed. A missing value of one of the standard molal Gibbs energy (G) or enthalpy (H) of formation from the elements or entropy (S) is calculated from the other two, if available. In addition, the value of G calculated from those of H and S is compared with the tabulated value and a message printed if the difference exceeds 1000 cal mol$^{-1}$. Likewise, if the values of standard molal heat capacity or volume calculated from the equations-of-state parameters differ (by greater than 1 cal mol K$^{-1}$ or 1 cm$^3$ mol$^{-1}$) from the tabulated values, messages to this effect are printed.

If info is called with a NULL value for species, the function performs the self-consistency checks on all the species in the thermodynamic database in sequence and writes any messages to the screen or to a file named in file, and returns a table summarizing those species for which the parameters are not self-consistent within the limits described above.

Examples

Run this code

data(thermo)

  ## basic operation

  # view the license and news file
  # marked dontrun because they open pagers 
  # that wait for the user to close them
  info('licence')
  info('CHNOSZ')
  # run a consistency check on each species in the database
  # (marked dontrun because it takes a while)
  info()

  ## species information
  # search for something named (or whose formula is) 'Fe'
  t <- info('Fe')
  # use the number to get the full record
  info(t)
  # it is possible to get a range of records
  info(t:(t+3))

  ## dealing with states
  # default order of preference for names: aq > gas > cr,liq
  info(c('methane','ethanol','glycinate'))  # aq, aq, aq
  info(c('adenosine','alanine','hydroxyapatite'))  # aq, aq, cr
  # state argument overrides the default
  info(c('ethanol','adenosine'),state=c('gas','cr'))
  # formulas default to aqueous species, if available
  info(c('CH4','CO2','CS2','MgO'))  # aq, aq, gas, cr
  # state argument overrides the default
  info(c('CH4','CO2','MgO'),'gas')  # gas, gas, NA
  # exceptions to the aqueous default are O2 and H2 
  info('O2')  # gas
 
  ## partial name or formula searches
  info('ATP')
  info('thiol')
  info('MgC')
  # add an extra character to refine a search
  # or to search on terms that have exact matches
  info('MgC?')
  info('acetate?') 
  info('acetate ')  # same as previous
  info('XH2O')

  ## consistency check of properties and parameters
  ## of each species in database
  # makred dontrun because it takes a while
    info()