write.openfluor: Export a PARAFAC model for the OpenFluor database

Description

Prepares a fitted PARAFAC model for submission to OpenFluor - an online spectral database of fluorescence by environmental organic compounds.

Usage

write.openfluor(
  model, filename, name = "?", creator = "?", doi = "?",
  reference = "?", unit = "?", toolbox =, date =, fluorometer = "?",
  constraints =, validation = "?", methods = "?", preprocess = "?",
  sources = "?", ecozones = "?", description = "",
  shift = FALSE, scale = TRUE
)

Arguments

model

A feemparafac object.

filename

Path to the text file to create from the model argument.

name

Short name of the model.

creator

Name of the creator of the model.

doi

Digital object identifier of the referenced source. Can also be “ISBN:...” for books.

reference

Full citation for the referenced source using the following style: “Author AA, Author BB, Author CC, (year), ‘Title’, Journal Abbrev, Vol, pages”.

unit

Units the fluorescence was measured in. Typically, one of “RU”, “QSE”, “AU”.

toolbox

Defaults to “albatross version, multiway version”.

date

Defaults to today, in “yyyy-mm-dd” format.

fluorometer

The model of the instrument that produced the data.

constraints

Constraints applied to the PARAFAC model. Defaults to model$const, but please edit it to a more human-readable form.

validation

Validation method used for the PARAFAC model, examples include: “Split-Half Analysis”, “core-consistency”.

methods

The sequence of steps taken to handle the samples and to ensure proper fluorescence intensity measurement. Examples include:

Sampling: Filtration GF/F
Sampling: Filtration x um
Sampling: samples frozen
Instrument spectral bias correction: Ex
Instrument spectral bias correction: Em
Instrument spectral bias correction: Ex & Em
Inner filter effect correction: absorbance method
Inner filter effect correction: dilution
Inner filter effect correction: CDA
Inner filter effect correction: other (please describe)
Internal calibration: Raman Peak area
Internal calibration: Raman Peak height
Internal calibration: Blank Subtraction
External calibration: Quinine Sulphate dilution series
External calibration: STARNA reference standards
External calibration: NIST reference standards
External calibration: other (please describe)

preprocess

PARAFAC-specific pre-processing steps applied to the dataset. Examples include (but are not limited to):

Outliers removed
Scatter region excised (replaced with NaNs)
Scatter region smoothed (replaced with interpolated values)
Sample mode normalised to DOC concentration
Sample mode normalised to unit variance

sources

Should preferably include one or more of the following keywords:

river
stream
lake
wetland
reservoir
estuary
ocean - coastal and shelf seas
ocean - surface off-shore
ocean - deep off-shore
freshwater
seawater
groundwater
wastewater
drinking water
treated water
recycled water
ballast water
sediment
mudflat
mangrove
aquarium
mesocosm

ecozones

List all major or minor terrestrial, freshwater and marine ecozones and ecoregions that apply. The full set of possible options is too large to include here, but see https://en.wikipedia.org/wiki/Lists_of_ecoregions for a source of inspiration.

description

Brief description of the model and its source data in $\le 256$ characters.

shift, scale

If shift is specified (default FALSE), the loadings are first shifted by subtracting min(x) to ensure that the minimal value is $0$.

If scale is specified (default TRUE), the loadings are then rescaled by dividing by max(x) so that the maximal value is $1$.

Note that OpenFluor clamps values outside the $[0, 1]$ range and uses scale-invariant (but not shift-invariant) Tucker's congruence coefficient to find matches.

Details

Provided the model and the filename arguments, this function exports the loadings into a file that passes OpenFluor syntax check and is suitable for further editing. Alternatively, some or all of the fields may be specified programmatically.

The fields constraints, methods, preprocess, sources, ecozones can be specified as character vectors (to be comma-separated on output); others should be single strings.

References

albatross:::.Rdreference('Murphy2014')

https://openfluor.lablicate.com/

Examples

Run this code

  data(feems)
  cube <- feemscale(feemscatter(cube, c(24, 14)), na.rm = TRUE)
  factors <- feemparafac(cube, nfac = 3, ctol = 1e-4)
  # all defaults
  write.openfluor(factors, f1 <- tempfile(fileext = '.txt'))
  if (interactive()) file.show(f1)
  unlink(f1)
  # all non-default arguments
  write.openfluor(
    factors, f2 <- tempfile(fileext = '.txt'), name = 'example',
    creator = 'J. Doe', doi = '10.1000/1', reference = paste(
      'Upper D, (1973),', "'The unsuccessful self-treatment of a case",
      "of \"writer's block\"',", 'J Appl Behav Anal, 7(3), 497'
    ), unit = 'AU', toolbox = 'all calculations done by hand',
    date = '2038-01-19', fluorometer = 'Acme Fluor-o-matic 9000',
    constraints = 'non-negative', validation = 'prior knowledge',
    methods = 'Instrument spectral bias correction: Ex & Em',
    preprocess = 'Scatter region excised (replaced with NaNs)',
    sources = 'freshwater', ecozones = 'Balkash',
    description = 'not a real model', shift = FALSE, scale = TRUE
  )
  if (interactive()) file.show(f2)
  unlink(f2)