as_OpenSpecy: Create `OpenSpecy` objects

Description

Functions to check if an object is an OpenSpecy, or coerce it if possible.

Usage

as_OpenSpecy(x, ...)
# S3 method for OpenSpecy
as_OpenSpecy(x, session_id = FALSE, ...)
# S3 method for list
as_OpenSpecy(x, ...)
# S3 method for hyperSpec
as_OpenSpecy(x, ...)
# S3 method for data.frame
as_OpenSpecy(x, colnames = list(wavenumber = NULL, spectra = NULL), ...)
# S3 method for default
as_OpenSpecy(
  x,
  spectra,
  metadata = list(file_name = NULL, user_name = NULL, contact_info = NULL, organization =
    NULL, citation = NULL, spectrum_type = NULL, spectrum_identity = NULL, material_form
    = NULL, material_phase = NULL, material_producer = NULL, material_purity = NULL,
    material_quality = NULL, material_color = NULL, material_other = NULL, cas_number =
    NULL, instrument_used = NULL, instrument_accessories = NULL, instrument_mode = NULL,
    intensity_units = NULL, spectral_resolution = NULL, laser_light_used = NULL,
    number_of_accumulations = NULL, 
     total_acquisition_time_s = NULL,
    data_processing_procedure = NULL, level_of_confidence_in_identification = NULL,
    other_info = NULL, license = "CC BY-NC"),
  attributes = list(intensity_unit = NULL, derivative_order = NULL, baseline = NULL,
    spectra_type = NULL),
  coords = "gen_grid",
  session_id = FALSE,
  comma_decimal = FALSE,
  ...
)
is_OpenSpecy(x)
check_OpenSpecy(x)
OpenSpecy(x, ...)
gen_grid(n)

Value

as_OpenSpecy() and OpenSpecy() returns three part lists described in details. is_OpenSpecy() returns TRUE if the object is an OpenSpecy and FALSE if not. gen_grid() returns a data.table with x and y

coordinates to use for generating a spatial grid for the spectra if one is not specified in the data.

Arguments

x: depending on the method, a list with all OpenSpecy parameters, a vector with the wavenumbers for all spectra, or a data.frame with a full spectrum in the classic Open Specy format.
session_id: logical. Whether to add a session ID to the metadata. The session ID is based on current session info so metadata of the same spectra will not return equal if session info changes. Sometimes that is desirable.
colnames: names of the wavenumber column and spectra column, makes assumptions based on column names or placement if NULL.
spectra: spectral intensities formatted as a data.table with one column per spectrum.
metadata: metadata for each spectrum with one row per spectrum, see details.
attributes: a list of attributes describing critical aspects for interpreting the spectra. see details.
coords: spatial coordinates for the spectra.
comma_decimal: logical(1) whether commas may represent decimals.
n: number of spectra to generate the spatial coordinate grid with.
...: additional arguments passed to submethods.

Author

Zacharias Steinmetz, Win Cowger

Details

as_OpenSpecy() converts spectral datasets to a three part list; the first with a vector of the wavenumbers of the spectra, the second with a data.table of all spectral intensities ordered as columns, the third item is another data.table with any metadata the user provides or is harvested from the files themselves.

The metadata argument may contain a named list with the following details (* = minimum recommended).

file_name*: The file name, defaults to basename() if not specified
user_name*: User name, e.g. "Win Cowger"
contact_info: Contact information, e.g. "1-513-673-8956, wincowger@gmail.com"
organization: Affiliation, e.g. "University of California, Riverside"
citation: Data citation, e.g. "Primpke, S., Wirth, M., Lorenz, C., & Gerdts, G. (2018). Reference database design for the automated analysis of microplastic samples based on Fourier transform infrared (FTIR) spectroscopy. Analytical and Bioanalytical Chemistry. tools:::Rd_expr_doi("10.1007/s00216-018-1156-x")"
spectrum_type*: Raman or FTIR
spectrum_identity*: Material/polymer analyzed, e.g. "Polystyrene"
material_form: Form of the material analyzed, e.g. textile fiber, rubber band, sphere, granule
material_phase: Phase of the material analyzed (liquid, gas, solid)
material_producer: Producer of the material analyzed, e.g. Dow
material_purity: Purity of the material analyzed, e.g. 99.98%
material_quality: Quality of the material analyzed, e.g. consumer product, manufacturer material, analytical standard, environmental sample
material_color: Color of the material analyzed, e.g. blue, #0000ff, (0, 0, 255)
material_other: Other material description, e.g. 5 µm diameter fibers, 1 mm spherical particles
cas_number: CAS number, e.g. 9003-53-6
instrument_used: Instrument used, e.g. Horiba LabRam
instrument_accessories: Instrument accessories, e.g. Focal Plane Array, CCD
instrument_mode: Instrument modes/settings, e.g. transmission, reflectance
intensity_units*: Units of the intensity values for the spectrum, options transmittance, reflectance, absorbance
spectral_resolution: Spectral resolution, e.g. 4/cm
laser_light_used: Wavelength of the laser/light used, e.g. 785 nm
number_of_accumulations: Number of accumulations, e.g 5
total_acquisition_time_s: Total acquisition time (s), e.g. 10 s
data_processing_procedure: Data processing procedure, e.g. spikefilter, baseline correction, none
level_of_confidence_in_identification: Level of confidence in identification, e.g. 99%
other_info: Other information
license: The license of the shared spectrum; defaults to "CC BY-NC" (see https://creativecommons.org/licenses/by-nc/4.0/ for details). Any other creative commons license is allowed, for example, CC0 or CC BY
session_id: A unique user and session identifier; populated automatically with paste(digest(Sys.info()), digest(sessionInfo()), sep = "/")
file_id: A unique file identifier; populated automatically with digest(object[c("wavenumber", "spectra")])

The attributes argument may contain a named list with the following details, when set, they will be used to automate transformations and warning messages:

intensity_units: supported options include "absorbance", "transmittance", or "reflectance"
derivative_order: supported options include "0", "1", or "2"
baseline: supported options include "raw" or "nobaseline"
spectra_type: supported options include "ftir" or "raman"

Examples

Run this code

data("raman_hdpe")

# Inspect the spectra
raman_hdpe # see how OpenSpecy objects print.
raman_hdpe$wavenumber # look at just the wavenumbers of the spectra.
raman_hdpe$spectra # look at just the spectral intensities data.table.
raman_hdpe$metadata # look at just the metadata of the spectra.

# Creating a list and transforming to OpenSpecy
as_OpenSpecy(list(wavenumber = raman_hdpe$wavenumber,
                  spectra = raman_hdpe$spectra,
                  metadata = raman_hdpe$metadata[,-c("x", "y")]))

# If you try to produce an OpenSpecy using an OpenSpecy it will just return
# the same object.
as_OpenSpecy(raman_hdpe)

# Creating an OpenSpecy from a data.frame
as_OpenSpecy(x = data.frame(wavenumber = raman_hdpe$wavenumber,
                            spectra = raman_hdpe$spectra$intensity))

# Test that the spectrum is formatted as an OpenSpecy object.
is_OpenSpecy(raman_hdpe)
is_OpenSpecy(raman_hdpe$spectra)

Run the code above in your browser using DataLab