Package 'photobiologyInOut'

photobiologyInOut: Read Spectral and Logged Data from Foreign Files

Description

Functions for reading, and in some cases writing, foreign files containing spectral data from spectrometers and their associated software, output from daylight simulation models in common use, and some spectral data repositories. As well as functions for exchange of spectral data with other R packages. Part of the 'r4photobiology' suite, Aphalo P. J. (2015) doi:10.19232/uv4pb.2015.1.14.

Data acquisition

The support for Ocean Insight, formerly Ocean Optics, spectrometers in package 'photobiologyInOut' is limited to the import of data acquired with Ocean Optics' software as is. In contrast, package 'ooacquire', part of these same suite, makes it possible to control, modify settings and acquire spectral data from Ocean Optics spectrometers directly from within R. 'ooacquire' also supports the conversion of raw-counts data into physical quantities.

Warning!

Most of the file formats supported are not standardized, and are a moving target because of changes in instrument firmware and support software. In addition the output format, especially with models, can depend on settings that users can alter. So do check that import is working as expected, and if not, please please raise an issue and upload one example of an incorrectly decoded file.

Note

From version 0.4.4 the time zone (tz) used for decoding dates and times in files imported defaults to "UTC". In most cases you will need to pass the tz (or the locale) where the file was created as an argument to the functions!

Author(s)

Maintainer: Pedro J. Aphalo [email protected] (ORCID)

Other contributors:

• Titta K. Kotilainen (ORCID) [contributor]

• Glenn Davis [email protected] [contributor]

References

Aphalo, Pedro J. (2015) The r4photobiology suite. UV4Plants Bulletin, 2015:1, 21-29. doi:10.19232/uv4pb.2015.1.14.

See Also

Useful links:

• https://docs.r4photobiology.info/photobiologyInOut/

• Report bugs at https://github.com/aphalo/photobiologyinout/issues/

---

Convert 'colorSpec::colorSpec' objects

Description

Convert 'colorSpec::colorSpec' objects into spectral objects (xxxx_spct, xxxx_mspct) as defined in package 'photobiology' and vice versa preserving as much information as possible.

Usage

colorSpec2mspct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.source_spct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.source_mspct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.response_spct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.response_mspct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.filter_spct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.filter_mspct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.reflector_spct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.reflector_mspct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.chroma_mspct(x, multiplier = 1, ...)

colorSpec2spct(x, multiplier = 1, ...)

colorSpec2chroma_spct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.chroma_spct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.chroma_mspct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.generic_spct(x, multiplier = 1, ...)

## S3 method for class 'colorSpec'
as.generic_mspct(x, multiplier = 1, ...)

Arguments

x	colorSpec object
multiplier	numeric A multiplier to be applied to the 'spc' data to do unit or scale conversion.
...	currently ignored.

Details

Objects of class colorSpec::colorSpec do not contain metadata or class data from which the units of expression could be obtained. When using function colorSpec2mspct the user needs to use parameter multiplier to convert the data to what is expected by the object constructors defined in package 'photobiology' but should only rarely need to use parameter spct.data.var to select the quantity.

colorSpec::colorSpec objects may use memory more efficiently than spectral objects of the classes for collections of spectra defined in package 'photobiology' as wavelengths are assumed to be the same for all member spectra, and stored only once while this assumption is not made for collections of spectra, allowing different wavelengths and lengths for the component spectra. When using as.colorSpec methods to convert collections of spectra into colorSpec objects, if the wavelengths of the individual spectra differe, only the shared range of wavelengths is retained and within the this range, wavelngth values are made consistent by interpolation.

Warning!

Always check the sanity of the imported or exported data values, as guessing is needed when matching the different classes, and the functions defined here are NOT guaranteed to return valid data without help from the user through optional function arguments.

Note

In generic_mspct objects, wavelengths are stored for each spectrum, individual generic_spct objects. However, as spectral classes are derived from 'tbl_df' in many cases no redundant copies of wavelength data will be made in memory in spite of the more flexible semantics of the objects.

Examples

# example run only if 'colorSpec' is available
if (requireNamespace("colorSpec", quietly = TRUE)) {
  library(colorSpec)
  colorSpec2mspct(Fs.5nm)
  colorSpec2spct(Fs.5nm)
  colorSpec2mspct(C.5nm)
  colorSpec2spct(C.5nm)
}

---

Convert 'hyperSpec::hyperSpec' objects

Description

Convert hyperSpec::hyperSpec objects containing VIS and UV radiation data into spectral objects (xxxx_spct, xxxx_mspct) as defined in package 'photobiology' and vice versa, preserving as much information as possible. As hyperSpec can contain other kinds of spectral data, it does make sense to use these functions only with objects containing data that can be handled by both packages.

Usage

hyperSpec2mspct(x, member.class, spct.data.var, multiplier = 1, ...)

hyperSpec2spct(x, multiplier = 1, ...)

mspct2hyperSpec(x, spct.data.var, multiplier = 1, ...)

spct2hyperSpec(x, spct.data.var = NULL, multiplier = 1, ...)

Arguments

x	hyperSpec object
member.class	character One of the spectrum classes defined in package 'photobiology'.
spct.data.var	character The name to be used for the 'spc' data when constructing the spectral objects.
multiplier	numeric A multiplier to be applied to the 'spc' data to do unit or scale conversion. For example "a.u." units in some examples in package 'hyperSpec' seem to have scale factors applied.
...	currently ignored.

Warning!

Always check the sanity of the imported or exported data values, as guessing is needed when matching the different classes, and the functions defined here are NOT guaranteed to return valid data wihtout help from the user through optional function arguments.

Note

Objects of class hyperSpec::hyperSpec contain metadata or class data from which the quantity measured and the units of expression can be obtained. However, units as included in the objects are not well documented making automatic conversion difficult. When using this function the user may need to use parameter multiplier to scale the data to what is expected by the object constructors defined in package 'photobiology' and use parameter spct.data.var to select the quantity.

hyperSpec::hyperSpec objects may use memory more efficiently than spectral objects of the classes for collections of spectra defined in package 'photobiology' as wavelengths are assumed to be the same for all member spectra, and stored only once while this assumption is not made for collections of spectra, allowing different wavelengths and lengths for the component spectra. Wavelengths are stored for each spectrum, but as spectral classes are derived from 'tbl_df' in many cases no redundant copies of wavelength data will be made in memory in spite of the more flexible semantics of the objects.

Examples

# example run only if 'hyperSpec' is available
if (requireNamespace("hyperSpec", quietly = TRUE)) {
  library(hyperSpec)
  data(laser)
  wl(laser) <- 
    list(wl = 1e7 / (1/405e-7 - wl (laser)),
         label = expression (lambda / nm))
  laser.mspct <- hyperSpec2mspct(laser, "source_spct", "s.e.irrad")
  class(laser.mspct)
}

---

Convert into 'colorSpec::colorSpec' objects

Description

Convert spectral objects (xxxx_spct, xxxx_mspct) as defined in package 'photobiology' into colorSpec objects preserving as much information as possible.

Usage

mspct2colorSpec(x, spct.data.var = NULL, multiplier = 1, ...)

spct2colorSpec(x, spct.data.var = NULL, multiplier = 1, ...)

chroma_spct2colorSpec(x, spct.data.var = NULL, multiplier = 1, ...)

## S3 method for class 'generic_mspct'
as.colorSpec(x, spct.data.var = NULL, multiplier = 1, ...)

## S3 method for class 'generic_spct'
as.colorSpec(x, spct.data.var = NULL, multiplier = 1, ...)

## S3 method for class 'chroma_spct'
as.colorSpec(x, spct.data.var = NULL, multiplier = 1, ...)

Arguments

x	R object
spct.data.var	character The name of the variable to read spectral data from.
multiplier	numeric A multiplier to be applied to the 'spc' data to do unit or scale conversion.
...	currently ignored.

Methods (by class)

• as.colorSpec(generic_spct):

• as.colorSpec(chroma_spct):

Warning!

Always check the sanity of the returned data values, as guessing is needed when matching the different classes, and the functions defined here are NOT guaranteed to return valid data without help from the user through optional function arguments.

Note

Objects of class colorSpec::colorSpec do not contain metadata or class data from which the units of expression could be obtained. When using this function the user needs to use parameter multiplier to convert the data to what is expected by the object constructors defined in package 'photobiology' but should only rarely need to use parameter spct.data.var to select the quantity.

colorSpec::colorSpec objects may use memory more efficiently than spectral objects of the classes for collections of spectra defined in package 'photobiology' as wavelengths are assumed to be the same for all member spectra, and stored only once while this assumption is not made for collections of spectra, allowing different wavelengths and lengths for the component spectra. Wavelengths are stored for each spectrum, but as spectral classes are derived from 'tbl_df' in many cases no redundant copies of wavelength data will be made in memory in spite of the more flexible semantics of the objects.

Examples

if (requireNamespace("colorSpec", quietly = TRUE)) {
  library(colorSpec)
  as.colorSpec(polyester.spct)
  as.colorSpec(sun.spct)
  as.colorSpec(filter_mspct(list(polyester.spct, yellow_gel.spct)))
}

---

Convert spectra into 'fda.usc::fdata' objects

Description

Convert spectral objects (xxxx_spct, xxxx_mspct) as defined in package 'photobiology' into fda.usc::fdata objects, preserving as much information as possible. As fdata objects can contain other kinds of data, the reverse conversion is supported (experimentally) and mainly for 'fdata' objects returned by the functional data analysis methods from package fda.usc to spectral data previosuly exported in the opposite direction.

Usage

mspct2fdata(x, spct.data.var = NULL, multiplier = 1, ...)

spct2fdata(x, spct.data.var = NULL, multiplier = 1, ...)

fdata2spct(x, multiplier = 1, member.class = NULL, drop.idx = FALSE, ...)

fdata2mspct(x, multiplier = 1, member.class = NULL, drop.idx = FALSE, ...)

Arguments

x	generic_mspct or generic_spct object or an object belonging to a derived class, or an object of class 'fdata' depending on the function.
spct.data.var	character The name of the column containing data to export. If NULL the first spectral data column found is used.
multiplier	numeric A multiplier to be applied to the 'spc' data to do unit or scale conversion.
...	possibly additional named arguments passed to object constructors.
member.class	character Name of the class of the spectrum or of the members of the collection of spectra.
drop.idx	logical Flag indicating whether to drop or keep idx.var in the collection members.

Warning!

When converting multiple spectra, all the spectra to be included in the fdata object must share the same wavelength values. Spectra that do not fulfil this condition will be skipped. The data variable needs also to be present in all individual spectra as no conversions are applied automatically by this function. If a different name, indicating a different quantity or a different base of expression is encountered, the affected spectrum is skipped with a warning.

Examples

if (requireNamespace("fda.usc", quietly = TRUE)) {
# from spectra to fdata
  sun.fdata <- spct2fdata(sun.spct)
  str(sun.fdata)
  polyester.fdata <- spct2fdata(polyester.spct)
  str(polyester.fdata)
# from fdata to spectra
  fdata2spct(sun.fdata)
  fdata2spct(sun.fdata, drop.idx = TRUE)
  fdata2spct(polyester.fdata, drop.idx = TRUE)
}

---

Clouds descriptor

Description

Constructor of a named list of parameter values to be used as argument to parameter clouds of function qtuv_s.e.irrad().

Usage

qtuv_clouds(cloud.type = "clear.sky")

Arguments

cloud.type

character One of "clear.sky", "cirrus", "stratocumulus" or "overcast".

Details

This function provide a rough approximation for parameter values. In reality there is large variation in the cloud optical depths (COD) and in the elevation at which clouds are located, within each type of cloud. The TUV model assumes a continuous uniform cloud layer, thus the normally discontinuous cover of cumulus clouds cannot be described.

Value

A one-row data frame with members "optical.depth", "base", "top" and "label".

Examples

qtuv_clouds("clear.sky")
qtuv_clouds("cirrus")
qtuv_clouds(c("clear.sky", "cirrus"))

---

Spectral irradiance from the Quick TUV calculator

Description

Call the Quick TUV calculator web server and return a source_spct object with the simulated spectral energy irradiance data.

Usage

qtuv_s.e.irrad(
  w.length = list(wStart = 280, wStop = 420, wIntervals = 140),
  sun.elevation = NULL,
  geocode = data.frame(lon = 0, lat = 51.5, address = "Greenwich"),
  time = lubridate::now(),
  tz = NULL,
  locale = readr::default_locale(),
  ozone.du = 300,
  albedo = 0.1,
  ground.altitude = 0,
  measurement.altitude = NULL,
  clouds = data.frame(optical.depth = 0, base = 4, top = 5),
  aerosols = data.frame(optical.depth = 0.235, ssaaer = 0.99, alpha = 1),
  num.streams = 2,
  spectra = list(direct = 1, diffuse.down = 1, diffuse.up = 0),
  added.vars = NULL,
  label = "",
  server.url = "https://www.acom.ucar.edu/cgi-bin/acom/TUV/V5.3/tuv",
  file = NULL
)

qtuv_m_s.e.irrad(
  w.length = list(wStart = 280, wStop = 420, wIntervals = 140),
  sun.elevation = NULL,
  geocode = data.frame(lon = 0, lat = 51.5, address = "Greenwich"),
  time = lubridate::now(),
  tz = NULL,
  locale = readr::default_locale(),
  ozone.du = 300,
  albedo = 0.1,
  ground.altitude = 0,
  measurement.altitude = NULL,
  clouds = data.frame(optical.depth = 0, base = 4, top = 5),
  aerosols = data.frame(optical.depth = 0.235, ssaaer = 0.99, alpha = 1),
  num.streams = 2,
  spectra = list(direct = 1, diffuse.down = 1, diffuse.up = 0),
  added.vars = NULL,
  label = "",
  server.url = "https://www.acom.ucar.edu/cgi-bin/acom/TUV/V5.3/tuv",
  file = NULL
)

Arguments

w.length	list of parameters describing the wavelengths, or a numeric vector from which the parameters will be constructed.
sun.elevation	numeric Angle in degrees above the horizon. If NULL its value is computed from geocode and time, otherwise arguments passed to these two parameters are ignored.
geocode	data.frame with variables lon and lat as numeric values (degrees), and character variable address; nrow > 1, allowed for collections.
time	A "vector" of POSIXct time, with any valid time zone (TZ) is allowed, default is current time.
tz	character Time zone is by default read from the file.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
ozone.du	numeric Ozone column in Dobson units.
albedo	numeric Surface albedo (= reflectance) as a fraction of one.
measurement.altitude, ground.altitude	numeric Altitudes above sea level expressed in km.
clouds	data.frame Parameters optical.depth (vertical), top and base expressed in km; nrow > 1, allowed for collections.
aerosols	data.frame Parameters optical.depth (total extinction), ssaaer (cloud single scattering albedo) and alpha (wavelength dependence of optical depth); nrow > 1, allowed for collections.
num.streams	integer Number of streams used in computations, 2 or 4.
spectra	named list with weights for the different components of the spectrum.
added.vars	character vector Accepted member values are "sun.elevation", zenith.angle, "date" and "ozone.du".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
server.url	character The URL used to access the Quick TUV calculator server.
file	character The name under which the file returned by the server is locally saved. If NULL a temporary file is used and discarded immediately. File paths are supported when valid.

Details

The Quick TUV calculator, is an on-line freely accessible server running the TUV atmospheric chemistry and radiation transfer model with a simplified user interface. In this case, version 5.3 is called passing the parameter values passed as arguments in the call to qtuv_s.e.irrad(). The response is saved in a text file that is subsequently read with function read_qtuv_txt() into a source_spct object.

Function qtuv_m_s.e.irrad() calls qtuv_s.e.irrad() repeatedly accepting a numeric vector longer than one as argument, for parameters: sun.elevation, time or ozone.du, and data frames with nrow >= 1. In a given call, only one parameter at a time can obey multiple values, with others currently truncated to the first value.

The formal parameter names are informative and consistent with other functions in the R for Photobiology Suite and differ from the short names used for the parameters in the FORTRAN code of the TUV model. In the case of w.length two ways of specifying wavelengths are supported. Some defaults also differ from those of the Quick TUV calculator.

In the current implementation, qtuv_m_s.e.irrad(), accepts multiple values as arguments for only one parameter at a time. In the case of elevation, both 'ground.elevation' and 'measurement.elevation' can have each one or more values. When too many values are passed in the call, only the first one is used.

Value

In the case of qtuv_s.e.irrad(), a source_spct object obtained by finding the center of each wavelength interval in the Quick TUV output file, and adding the variables listed in added.vars. In the case of qtuv_m_s.e.irrad(), a source_mspct object containing a collection of such spectra.

Side effect

If a file name is passed as argument, the data as downloaded are saved into persistent files, one file per spectrum. The names of the saved files always end in '.txt'.

Warning!

This function connects to a server managed by UCAR, the University Corporation for Atmospheric Research located in the U.S.A. to obtain simulated spectral data. UCAR manages the U.S. National Science Foundation National Center for Atmospheric Research (NSF NCAR) on behalf of NSF. As any download with the HTTPS protocol, using this function entails some risk. To minimize the risk, the returned page is saved as plain text, checked for conformity with the expected content, and if valid decoded into an R data object. When using the default argument file = NULL, the file used is a temporary one and is deleted before the function returns the call, irrespective of it being conformant or not.

The administrators of the Quick TUV Calculator at UCAR suggest a maximum load of approximately 100 spectral simulations per day and user. For larger workloads they encourage the local installation of the TUV model which is open-source and freely available. A local installation, also allows access to the full set of input parameters and outputs. Currently a local instance of the TUV model can be called from R with package 'foqat'.

Note

The Quick TUV calculator has multiple output modes that return different types of computed values. The use of output mode 5 is hard-coded in this function as other modes return summary values rather than spectral data. Package 'foqat' provides a more flexible alternative supporting other output modes in addition to mode 5.

If the argument passed to w.length is a numeric vector, the range and length are used to reconstruct the accepted parameters. The returned spectrum has always a uniformly spaced wavelengths.

When using this function, more detailed metadata are available than when reading an output file, as not all the simulation input parameters are listed in the output text.

In interactive use of the Quick TUV Calculator, the same parameters as accepted by qtuv_s.e.irradiance() as arguments are entered through the web interface at https://www.acom.ucar.edu/Models/TUV/Interactive_TUV/. This page together with its documentation, can be consulted for additional information on the parameters and the model.

References

https://www.acom.ucar.edu/Models/TUV/Interactive_TUV/. This URL could change in the future as well as the server URL. The formal parameter server.url was included only for use in such a case.

Sasha Madronich (2017-2021) Tropospheric Ultraviolet and Visible radiation (TUV) model. https://www2.acom.ucar.edu/modeling/tropospheric-ultraviolet-and-visible-tuv-radiation-model. Visited on 2024-08-29.

---

Read File downloaded from ASTER data base.

Description

Reads and parses the header of a test file as available through the ASTER reflectance database. The Name field is retrieved and copied to attribute "what.measured". The header of the file is preserved as a comment.

Usage

read_ASTER_txt(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  npixels = Inf
)

Arguments

file	character string
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Ignored.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
npixels	integer Number of pixels in spectral data.

Value

A raw_spct object.

Note

The header in these files has metadata information, but mostly on the origin of the data. For a date and/or geocode are to be added to the return object it must be supplied by the user. as well as the date-time. Some metadata is extracted and added as attributes, while the whole header is copied to the comment attribute.

References

https://speclib.jpl.nasa.gov

Baldridge, A.; Hook, S.; Grove, C. & Rivera, G. (2009) The ASTER spectral library version 2.0. Remote Sensing of Environment. 113, 711-715

Examples

file.name <- 
   system.file("extdata", "drygrass-spectrum.txt", 
               package = "photobiologyInOut", mustWork = TRUE)
                
 fred.spct <- read_ASTER_txt(file = file.name, npixels = Inf)
 
 fred.spct
 getWhatMeasured(fred.spct)
 cat(comment(fred.spct))

---

Read '.csv' File Saved by Avantes' Software for AvaSpec.

Description

Reads and parses the header of a processed data file as output by the program Avaspec and then imports wavelength and spectral irradiance values. The file header has little useful metadata information.

Usage

read_avaspec_csv(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

read_avaspec_xls(
  path,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

Arguments

file	character string
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone used for interpreting times saved in the file header.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
path	Path to the xls/xlsx file

Value

A source_spct object.

References

https://www.avantes.com/

Examples

file.name <- 
    system.file("extdata", "spectrum-avaspec.csv", 
                package = "photobiologyInOut", mustWork = TRUE)
                
 avaspec.spct <- read_avaspec_csv(file = file.name)
 
 avaspec.spct
 getWhatMeasured(avaspec.spct)
 cat(comment(avaspec.spct))

---

Read File Saved by CID's SpectraVue.

Description

Read wavelength and spectral data from Measurements.CSV files exported from CID Bio-Sciences' SpectraVue CI-710s (not the older CI-710!) leaf spectrometer, importing them into R. Available metadata is also extracted from the file. read_cid_spectravue_csv() only accepts "row oriented" CSV files. These may contain multiple spectra, one per row.

Usage

read_cid_spectravue_csv(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  range = c(380, 1100),
  simplify = TRUE,
  absorbance.to = "object",
  strict.range = NA,
  ...
)

Arguments

file	character
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date and time are extracted from the file.
geocode	A data frame with columns lon and lat used to set attribute "where.measured". If NULL, the default, the geocode is extracted from the file, if present, and if NA the "where.measured" attribute is not set.
label	character string. If NULL, the default, the value of the "tag" present in the file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone is by default that of the machine's locale.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
range	numeric A vector of length two, or any other object for which function range() will return range of wavelengths expressed in nanometres.
simplify	logical If TRUE, single spectra are returned as individual spectra instead of collections of length one.
absorbance.to	character Affects only absorbance measurements: "object", "all" or "A".
strict.range	logical Flag indicating whether off-range values result in an error (TRUE) instead of a warning (FALSE), or the test is disabled (NA).
...	additional arguments passed to the constructor of the 'filter_spct' object.

Details

SpectraVue's row-wise spectral Measurements.CSV files contain columns with metadata on the right edge, followed by columns with data for each of the 2048 pixels or wavelengths. The value in column "Mode" indicates the quantity measured, decoded into variables Tpc, Rpc or A. The data the rows in the CSV file are read and stored in filter_spct, reflector_spct or object_spct objects. These objects are collected into a single filter_mspct, reflector_mspct, object_mspct or generic_spct object and returned.

Spectral data outside the range 400 nm to 1000 nm are very noisy and thus outside the valid range for the measurements. Out-of-range spectral data can also be cause by calibration drift. Consequently, reading of data is done always with the range check disabled, while whether a check is used before returning the collection of spectra depends on the argument passed to strict.range which by default is set to disable checks. This is done, because in most cases measurements from this instrument tend to require further processing before they comply with theoretical expectations of $Tfr + Rfr + Afr = 1$.

Value

An object of class filter_spct, relector_spct, object_spct or generic_mspct.

Internal vs. total transmittance and absorbance

Spectravue returns transmittance values labelled with Transmittance as Mode. Transmittance values are not total as most of the scattered light transmitted is not detected. Absorbance (Abs) values returned labelled with Absorbance as Mode are for absorbance computed from the Transmittance. This estimate of absorbance overestimates real absorbance in the case of scattering materials like plant leaves. It is best to save spectral data acquired as absorbance into objects of class 'object_spct' containing reflectance and transmittance, the default, as this preserves all the acquired data.

Specular vs. total reflectance

This function assumes that SpectraVue returns close to total reflectance readings. Given the optics of the instrument this is likely only an approximation.

Warning!!

CID's support has answered on 2022-05-19 that the extremely biased (plainly wrong!) values of transmittance measured by this instrument are due to a design flaw and that they are working on a solution for the problem. In practice, reflectance seems biased but usable as an instrument-specific quantity with arbitrary units. Transmittance and absorbance seem useless as values are wrong by about an order of magnitude.

Note

SpectraVue creates three or four .CSV files for each series of measurements saved. Of these files, this function reads the one with name ending in Measurements.CSV. The first part of the file name gives the time of the session, but as the files can contain multiple spectra measured at different times, the time metadata is extracted separately for each spectrum. We provide a default argument for range that discards data for short and long wavelengths because values outside this range are according to the instrument's manual outside the usable range and in practice extremely noisy.

References

https://cid-inc.com/

Examples

# read file containing a single reflectaance spectrum

 file.name <-
   system.file("extdata", "cid-spectravue-Rpc-Measurements.csv",
               package = "photobiologyInOut", mustWork = TRUE)

 cid_filter.spct <-
   read_cid_spectravue_csv(file = file.name)
 summary(cid_filter.spct)

 cid_filter.spct <-
   read_cid_spectravue_csv(file = file.name, simplify = FALSE)
 summary(cid_filter.spct)

 # read data measured as absorbance (A, Rpc and Tpc)

 file.name <-
   system.file("extdata", "cid-spectravue-Abs-Measurements.csv",
               package = "photobiologyInOut", mustWork = TRUE)
 cid.object_spct <-
   read_cid_spectravue_csv(file = file.name)
 summary(cid.object_spct)

 cid_A.filter_spct <-
   read_cid_spectravue_csv(file = file.name, absorbance.to = "A")
 summary(cid_A.filter_spct)

---

Read '.CSV' files from CIE

Description

Reads a CSV spectral data file and its companion JSON file with metadata as published by International Commission on Illumination (CIE) and then imports wavelengths and spectral values into one the classes for spectral data defined in package 'photobiology.

Usage

read_CIE_csv(file.name, label = NULL, simplify = FALSE)

Arguments

file.name	character string
label	character string, but if NULL metadata read from the JSON file is used, and if NA the "what.measured" attribute is not set, and if a character string is passed, it is used to set the "what.measured" attribute.
simplify	logical If TRUE and the read file contained a single spectrum, extract the spectral object from the collection.

Details

The CSV file contains only numbers encoded as character strings, and the JSON file contains extensive metadata. The type of spectral data is encoded as part of the file name. If the original file name of the CSV file is passed as argument to parameter file, the function can retrieve all data and metadata, enough to return an R object of the correct class. The JSON file must be located in the same folder.

Value

Depending on the contents of the file, a source_spct object, a response_spct object, or a chroma_spct object, containing both data and metadata.

References

https://cie.co.at/data-tables

Examples

file.name <- 
  system.file("extdata", "CIE_illum_C.csv", 
              package = "photobiologyInOut", mustWork = TRUE)

CIE_illum_C.spct <- read_CIE_csv(file.name)
CIE_illum_C.spct
   
file.name <- 
  system.file("extdata", "CIE_sle_photopic.csv", 
              package = "photobiologyInOut", mustWork = TRUE)

CIE_sle_photopic.spct <- read_CIE_csv(file.name)
CIE_sle_photopic.spct

---

Read '.DAT' file(s) saved by modern Campbell Scientific loggers.

Description

Reads and parses the header of a processed data file as output by the PC400 or PC200W programmes extracting variable names, units and quantities from the header. Uses the comment attribute to store the metadata.

Usage

read_csi_dat(
  file,
  geocode = NULL,
  label = NULL,
  data_skip = 0,
  n_max = Inf,
  locale = readr::default_locale(),
  na = c("", "NA", "NAN"),
  ...
)

Arguments

file	Path to file as a character string.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
data_skip	integer Number of records (rows) to skip from the actual data block.
n_max	integer Maximum number of records to read.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
na	character Vector of strings to interpret as missing values. Set this option to character() to indicate no missing values.
...	Further named arguments currently passed to read_csv().

Value

read_csi_dat() returns a tibble::tibble object.

Note

This function is not useful for .DAT and .PRN files from old CSI loggers and software. Those were simple files, lacking metadata, which was stored in separate .FLD files.

References

https://www.campbellsci.eu/

---

Read daily cummulated solar spectrum data file(s).

Description

Read one or more cumulated daily spectral irradiance file as output by Anders Lindors' model based on libRadTrans. Dates are read from the file header and parsed with the function suplied as date.f.

Usage

read_fmi_cum(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = "UTC",
  locale = readr::default_locale(),
  .skip = 3,
  .n_max = -1,
  .date.f = lubridate::ymd
)

read_m_fmi_cum(
  files,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = "UTC",
  .skip = 3,
  .n_max = -1,
  .date.f = lubridate::ymd
)

Arguments

file	Either a path to a file, a connection, or literal data (either a single string or a raw vector).
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone used for interpreting times saved in the file header.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
.skip	Number of lines to skip before reading data—i.e. the number of rows in the header.
.n_max	Maximum number of records to read.
.date.f	A function for extracting a date-time from the file header passed as charecter sring to its first argument and which returns a POSIXct object.
files	list or vector of paths each one with the same requirements as described for argument file.

Value

read_fmi_cum() returns a source_spct object with time.unit attribute set to "day" and when.measured attribute set to the date-time extracted from the header at the top of the read file.

read_m_fmi_cum returns a source_mspct containing one source_spct object for each one of the multiple files read.

Note

See read_table for details of acceptable values for file.

Examples

file.name <- system.file("extdata", "2014-08-21_cum.hel", 
                         package = "photobiologyInOut", mustWork = TRUE)
fmi.spct <- read_fmi_cum(file = file.name)

---

Read multiple solar spectra from a data file.

Description

Read spectral irradiance file as output by Anders Lindors' model based on libRadTrans for hourly simulation, or measured data from FMI's Brewer spectrometer.

Usage

read_fmi2mspct(
  file,
  scale.factor = 0.001,
  geocode = NULL,
  what.measured = NULL,
  how.measured = NULL,
  date.field = 2L,
  time.field = 3L,
  date.format = "ymd",
  time.format = "hms",
  tz = NULL,
  time.shift.min = 0,
  locale = readr::default_locale(),
  .skip = 0,
  .n_max = -1
)

Arguments

file	Either a path to a file, a connection, or literal data (either a single string or a raw vector).
scale.factor	numeric A multiplier to be applied to the spectral irradiance values.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
what.measured	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
how.measured	character string, but if NULL or NA the "how.measured" attribute is not set.
date.field, time.field	integer. Word positions in the header line.
date.format	character string. One of "ymd", "ydm", "dmy", or "mdy".
time.format	character string. One of "hms", "hm".
tz	character Time zone used for interpreting times saved in the file header.
time.shift.min	numeric. Time shift with respect to TZ in minutes.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
.skip	Number of lines to skip before reading data.
.n_max	Maximum number of records to read.

Value

read_fmi2mspct() returns a source_mspct object containing source_spct objects as members, time.unit attribute set to "second" and when.measured attribute set to the date-time values extracted from the file body.

Note

See read_table for details of acceptable values for file. Individual spectra are names based on time and date in ISO format, at the time zone given by tz but the time shift subtracted. Say for times expressed in headers at UTC + 120 min, we use tz = UTC and time.shift.min = 120 to convert times to UTC. This is different from using tz = EET, which is not invariant through the course of the year because of daylight saving time. Local time zones is not necessarily consistent across years because of changes in legislation. In contrast UTC is more consistent, making it preferable for time series.

---

Read multiple foreign files with spectral data

Description

Read spectra from a homogeneous list of files based on a path and a list of filenames or a path and a search pattern for files. The imported spectra are returned as a single object of one of the collection of spectra classes from package 'photobiology'.

Usage

read_foreign2mspct(path = ".", list = NULL, pattern = NULL, .fun, ...)

Arguments

path	character A path point to the location of the files.
list	character A vector or list of character strings pointing to files relative to path,
pattern	character A search pattern to select files within path. See list.files which is used internally. Argument ignored is list is non-null.
.fun	function One of the functions exported by this package for reading spectral data.
...	Named arguments passed ot the call to .fun.

Details

This function iterates over a list of file names reading them with the function passed as argument to '.fun' and combines the spectra as a collection of spectra of a class suitable for the spectral objects returned by the argument to '.fun'. This function can either return for each file read either a single spectrum as an object of class 'generic_spct' or a class derived from it, or a collection of spectra of class 'generic_mspct' or a class derived from it. The class of the returned object depends on the class of the member spectra.

Value

An object of class 'generic_mspct' or a class derived from it, containing a collection of member spectra of class 'generic_spct' or of one of the classes derived from it.

---

Read '.CSV' FReD database.

Description

Reads a CSV data file downloaded from the FReD (Floral Reflectance Database) and then imports wavelengths and spectral reflectance values and flower ID.

Usage

read_FReD_csv(
  file,
  date = NA,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

Arguments

file	character string
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone used for interpreting times saved in the file header.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names. Those relevant should match the format of the CSV file being read.

Value

A reflectance_spct object.

References

http://www.reflectance.co.uk Arnold SEJ, Faruq S, Savolainen V, McOwan PW, Chittka L, 2010 FReD: The Floral Reflectance Database - A Web Portal for Analyses of Flower Colour. PLoS ONE 5(12): e14287. doi:10.1371/journal.pone.0014287

Examples

file.name <- 
    system.file("extdata", "FReDflowerID_157.csv", 
                package = "photobiologyInOut", mustWork = TRUE)
                
  fred.spct <- read_FReD_csv(file = file.name)
  
  fred.spct
  getWhatMeasured(fred.spct)
  cat(comment(fred.spct))

---

Read '.TXT' File(s) Saved by LI-COR's LI-180 spectroradiometer.

Description

Reads and parses the header of a data file as output by the LI-180 spectrometer (not to be confused with the LI-1800 spectrometer released in the 1980's by LI-COR) to extract the whole header remark field and also decode whether data is in photon or energy based units. This is a new instrument released in year 2020.

Usage

read_li180_txt(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  s.qty = "s.e.irrad"
)

read_m_li180_txt(
  files,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = Sys.timezone(),
  locale = readr::default_locale(),
  s.qty = NULL
)

Arguments

file	Path to file as a character string.
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone used for interpreting times saved in the file header.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
s.qty	character The name of the spectral quantity to be read. One of "s.e.irrad" or "s.q.irrad".
files	A list or vector of character strings.

Details

Function read_m_licor_espd() calls red_licor_espd() for each file in files. See read.table for a description of valid arguments for files.

Value

read_licor_espd() returns a source_spct object with time.unit attribute set to "second" and when.measured attribute set to the date-time extracted from the file header, or supplied by the user. Spectrometer model, serial number and integration time are stored in attributes. The whole file header is saved as a comment while the footer is discarded.

Function read_m_licor_espd() returns a source_mspct object containing one spectrum per file read.

Note

The LI-180 spectroradiometer stores little information of the instrument and settings, possibly because they cannot be altered by the user or configured. The length of the file header does not seem to be fixed, so the start of the spectral data is detected by searching for "380nm".

References

LI-COR Biosciences, Environmental. https://www.licor.com/env/

Examples

file.name <- 
    system.file("extdata", "LI-180-irradiance.txt", 
                package = "photobiologyInOut", mustWork = TRUE)
                
  licor180.spct <- read_li180_txt(file = file.name)
  
  licor180.spct
  getWhenMeasured(licor180.spct)
  getWhatMeasured(licor180.spct)
  cat(comment(licor180.spct))

---

Read '.PRN' File(s) Saved by LI-COR's PC1800 Program.

Description

Read and parse the header of a processed data file as output by the PC1800 program to extract the whole header remark field and also decode whether data is irradiance in photon or energy based units, transmittance, reflectance or absorbance and then extract the wavelength and spectral data. PC1800 is an MS-DOS program provided for use with the LI-1800 spectrometer. This instrument was released in the 1980's and was sold until the early 2000's. It was very popular and several of them remain in use. (It should not be confused with the LI-180, a new spectrometer released released in 2020.)

Usage

read_licor_prn(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  s.qty = NULL
)

read_m_licor_prn(
  files,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  s.qty = NULL
)

Arguments

file	Path to file as a character string.
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone used for interpreting times saved in the file header.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
s.qty	character The name of the spectral quantity to be read. One of "s.irrad", "Tfr", or "Rfr".
files	A list or vector of character strings.

Details

Function read_m_licor_prn() calls red_licor_prn() for each file in files. See read_table for a description of valid arguments for files.

Value

read_licor_prn() returns a source_spct object with time.unit attribute set to "second" and when.measured attribute set to the date-time extracted from the file name, or supplied.

Function read_m_licor_prn() returns a source_mspct object containing one spectrum per file read.

Note

The LI-1800 spectroradiometer does not store the year as part of the data, only month, day, and time of day. Because of this, in the current version, if NULL is the argument to date, year is set to 0000. In addition, the argument passed to tz does not recognize "summer-time" shifts if the year is unknown (date read from the file header).

References

LI-COR Biosciences, Environmental. https://www.licor.com/env/

Examples

file.name <- 
   system.file("extdata", "spectrum.PRN", 
               package = "photobiologyInOut", mustWork = TRUE)
                
 licor.spct <- read_licor_prn(file = file.name)
 
 licor.spct
 getWhenMeasured(licor.spct)
 getWhatMeasured(licor.spct)
 cat(comment(licor.spct))

---

Read '.DTA' File Saved by Macam's Software.

Description

Reads and parses the header of a processed data file as output by the PC program to extract the time and date fields and a user label if present, and then imports wavelengths and spectral energy irradiance values.

Usage

read_macam_dta(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

Arguments

file	character string
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone used for interpreting times saved in the file header.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

Value

A source_spct object.

References

https://www.irradian.co.uk/

Examples

file.name <- 
   system.file("extdata", "spectrum.DTA", 
               package = "photobiologyInOut", mustWork = TRUE)
                
 macam.spct <- read_macam_dta(file = file.name)
 
 macam.spct
 getWhenMeasured(macam.spct)
 getWhatMeasured(macam.spct)
 cat(comment(macam.spct))

---

Read Files Saved by Ocean Optics' Jaz spectrometer.

Description

Reads and parses the header of processed data text files output by Jaz instruments extracting the spectral data from the body of the file and the metadata, including time and date of measurement from the header. Jaz modular spectrometers were manufactured by Ocean Optics. The company formerly named Ocean Optics is now called Ocean Insight.

Usage

read_oo_jazirrad(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

read_oo_jazpc(
  file,
  qty.in = "Tpc",
  Tfr.type = c("total", "internal"),
  Rfr.type = c("total", "specular"),
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

read_oo_jazdata(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

Arguments

file	character string.
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone used for interpreting times saved in the file header.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
qty.in	character string, one of "Tpc" (spectral transmittance, %), "A" (spectral absorbance), or "Rpc" (spectral reflectance, %).
Tfr.type	character string, either "total" or "internal".
Rfr.type	character string, either "total" or "specular".

Details

Function read_oo_jazirrad can read processed irradiance output files. Function read_oo_jazpc can read processed transmittance and reflectance output files (expressed as %s). Function read_oo_jazdata can read raw-counts data.

Value

A source_spct object, a filter_spct object, a reflector_spct object or a raw_spct object.

Note

Although the parameter is called date a date time is accepted and expected. Time resolution is < 1 s if seconds are entered with a decimal fraction, such as "2021-10-05 10:10:10.1234".

References

https://www.oceanoptics.com/

Examples

file.name <- 
   system.file("extdata", "spectrum.jaz", 
               package = "photobiologyInOut", mustWork = TRUE)
                
 jaz.spct <- read_oo_jazpc(file = file.name)
 
 jaz.spct
 getWhenMeasured(jaz.spct)
 getWhatMeasured(jaz.spct)
 cat(comment(jaz.spct))

---

Read File Saved by Ocean Optics' Raspberry Pi software.

Description

Reads and parses the header of a raw data file as output by the server running on a Raspberry Pi board to extract the whole header remark field. The time field is retrieved and decoded. The company formerly named Ocean Optics is now called Ocean Insight.

Usage

read_oo_pidata(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  npixels = Inf,
  spectrometer.sn = "FLMS00673"
)

Arguments

file	character string
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is set to the file modification date.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone is not saved to the file.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
npixels	integer Number of pixels in spectral data.
spectrometer.sn	character The serial number of the spectrometer needs to be supplied by the user as it is not included in the file header.

Value

A raw_spct object.

Note

The header in these files has very little information. The file contains a time in milliseconds but as the Raspberry Pi board contains no real-time clock, it seems to default to number of milliseconds since the Pi was switched on. The user may wish to supply the date-time as an argument, but if no argument is passed to date this attribute is set to the file modification date obtained with file.mtime(). This date-time gives an upper limit to the real time of measurement as in some operating systems it is reset when the file is copied or even without any good apparent reason. The user may need to supply the number of pixels in the array although the default of npixels = Inf usually works and triggers no warnings.

References

https://www.oceanoptics.com/ https://www.raspberrypi.org/

Examples

file.name <- 
   system.file("extdata", "spectrum.pi", 
               package = "photobiologyInOut", mustWork = TRUE)
                
 oopi.spct <- read_oo_pidata(file = file.name)
 
 oopi.spct
 getWhenMeasured(oopi.spct)
 getWhatMeasured(oopi.spct)
 cat(comment(oopi.spct))

---

Read File Saved by Ocean Optics' SpectraSuite.

Description

Reads and parses the header of a processed data file as output by SpectraSuite to extract the whole header remark field. The time field is retrieved and decoded. SpectraSuite was a program, now replaced by OceanView. The company formerly named Ocean Optics is now called Ocean Insight.

Usage

read_oo_ssirrad(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

read_oo_ssdata(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

Arguments

file	character string
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone is by default read from the file.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

Value

A source_spct object.

A raw_spct object.

References

https://www.oceanoptics.com/

Examples

file.name <- 
   system.file("extdata", "spectrum.SSIrrad", 
               package = "photobiologyInOut", mustWork = TRUE)
                
 ooss.spct <- read_oo_ssirrad(file = file.name)
 
 ooss.spct
 getWhenMeasured(ooss.spct)
 getWhatMeasured(ooss.spct)
 cat(comment(ooss.spct))

---

Read Quick TUV output file.

Description

Reads and parses the header of a text file output by the Quick TUV on-line web front-end at UCAR to extract the header and spectral data. The time field is converted to a date.

Usage

read_qtuv_txt(
  file,
  ozone.du = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  added.vars = NULL
)

Arguments

file	character string with the name of a text file.
ozone.du	numeric Ozone column in Dobson units.
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone is by default read from the file.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
added.vars	character vector Accepted member values are "sun.elevation", zenith.angle, "time" and "ozone.du".

Value

a source_spct object obtained by finding the center of wavelength intervals in the Quick TUV output file, and adding the variables listed in added.vars. To obtain the same value as in version (<= 0.4.28) pass added.vars = c("angle", "date") in the call.

Note

The ozone column value used in the simulation cannot be retrieved from the file. Tested files from Quick TUV version 5.2 on 2018-07-30 and also with more recent files in early 2024. This function can be expected to be robust to variations in the position of lines in the imported file and resistant to the presence of extraneous text or even summaries. By default web browsers save the output returned by the Quick TUV calculator as an HTML output, some of them with minimal headers and other with more extensive ones. In some cases, character escapes replace actual new lines. In most cases these HTML files are decoded correctly, but if not, use "save as" in the browser and select "text" when saving. As a last recourse, messed up files can be manually edited before import.

References

https://www.acom.ucar.edu/Models/TUV/Interactive_TUV/

---

Read '.CSV' File Saved by PSI's Software.

Description

Reads and parses the header of a processed .CSV file as output by the by the PSI (Photon Systems Instruments, Czech Republic) SpectraPen miniature spectrometer.

Usage

read_spectrapen_csv(
  file,
  start.row = 1,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

Arguments

file	character string.
start.row	integer The first line to read, counting from the top of the file.
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured". If NULL, the default, the location is extracted from the file header.
label	character string, but if NULL the label from file header is used, if the label is missing, the index is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone used for interpreting times saved in the file header.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

Value

A source_mspct object.

References

https://psi.cz/

Examples

# fetch path to example file to read
 file.name <-
   system.file("extdata", "spectrum-psi-spectrapen-SP.csv",
               package = "photobiologyInOut", mustWork = TRUE)

 spectrapen.mspct <- read_spectrapen_csv(file = file.name)

 spectrapen.mspct
 getWhenMeasured(spectrapen.mspct)
 getWhatMeasured(spectrapen.mspct)
 cat(comment(spectrapen.mspct))

---

Read TUV output file.

Description

Reads and parses the header of a text file output by the TUV program to extract the header and spectral data. The time field is converted to a date.

Usage

read_tuv_usrout(
  file,
  ozone.du = NULL,
  date = lubridate::today(),
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

read_tuv_usrout2mspct(
  file,
  ozone.du = NULL,
  date = lubridate::today(),
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale()
)

Arguments

file	character string
ozone.du	numeric Ozone column in Dobson units.
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone is by default read from the file.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

Value

a source_spct object obtained by 'melting' the TUV file, and adding a factor spct.idx, and variables zenith.angle and date.

Note

The ozone column value used in the simulation cannot be retrieved from the file. Tested only with TUV version 5.0.

References

https://www2.acom.ucar.edu/modeling/tropospheric-ultraviolet-and-visible-tuv-radiation-model

---

Read libRadtran's uvspec output file.

Description

Read and parse a text file output by libRadtran's uvspec routine for a solar spectrum simulation. The output of uvspec depends among other things on the solver used. We define a family of functions, each function for a different solver.

Usage

read_uvspec_disort(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  multiplier = 0.001,
  qty = "irradiance"
)

Arguments

file	character string
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone is by default read from the file.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
multiplier	numeric A multiplier for conversion into W m-2 nm-1, as the units of expression of the output from "uvspec" depend on the units in which the extraterrestrial solar spectrum data is expressed.
qty	character "uvspec" returns both irradiance and intensity with solver "disort".

Value

A source_spct object.

Note

Currently only "irradiance" is suported as qty argument as intensity is not supported by classes and methods in package 'photobiology'.

Tested only with libRadtran version 2.0

References

https://www.r4photobiology.info http://www.libradtran.org

---

Read libRadtran's uvspec output file from batch job.

Description

Reads and parses the header and body of a text file output by a script used to run libRadtran's uvspec in a batch joib for a set of solar spectrum simulations. The header and time and date fields are converted into a datetime object.

Usage

read_uvspec_disort_vesa(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  multiplier = 1e-06,
  simplify = TRUE
)

Arguments

file	character string
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date is extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone is by default read from the file.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
multiplier	numeric A multiplier for conversion into W m-2 nm-1, as the units of expression of the output from "uvspec" depend on the units in which the extraterrestrial solar spectrum data is expressed.
simplify	logical Remove redundant columns from returned object.

Value

a source_spct object, possibly containing several spectra in long form and a datetime column.

References

http://www.libradtran.org

---

Read File Saved by Wasatch's Enlighten.

Description

Read wavelength and spectral data from the data section of a file as output by Enlighten importing them into R. Parse the header of a file to extract the acquisition time, instrument name and serial number, as well additional metadata related to the instrument and its settings. Function read_wasatch_csv() only accepts "column oriented" CSV files.

Usage

read_wasatch_csv(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  s.qty = NULL,
  extra.cols = "keep",
  scale.factor = 1,
  simplify = TRUE,
  ...
)

Arguments

file	character
date	a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date and time are extracted from the file header.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
tz	character Time zone is by default that of the machine's locale.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.
s.qty	character, possibly named. The name of the quantity using the conventions accepted used in package 'photobiology' that is to be imported from column "Processed" from the file.
extra.cols	character What to do non-processed data columns if present in file. One of "keep", "drop.pixel", "drop" or "split".
scale.factor	numeric vector of length 1, or length equal to the number of rows (= detector pixels). Numeric multiplier applied to returned spectral values.
simplify	logical If TRUE, single spectra are returned as individual spectra instead of collections of length one.
...	additional arguments passed to the constructor of the spectrum object.

Details

Enlighten's column-wise CSV files contain at least two columns, Wavelength and Processed. In the header the Technique used is recorded. Additional data columns can be present. Column Pixel contains the pixel index in the array as integers. Columns Raw, Dark and Reference contain detector counts data. Technique is used to guess the type of spectrum stored in the column named Processed, which can be detector counts or derived values. By default the data are read into a single spectrum object and all columns retained, but only the data in Processed are interpreted as spectral data corresponding to the class of the object. If passed extra.cols = "drop", only Wavelength and Processed are copied to the returned object, while if passed extra.cols = "drop.pixel" only the contents of column Pixel are discarded. If passed extra.cols = "split" all columns containing spectral data are each read into a separate spectrum, these are collected and a "generic_mspct" object containing them returned. extra.cols can be a named vector of mappings, of length at least one but possibly longer. If longer a "generic_mspct" is returned, otherwise a spectrum object as inferred from the name each column is mapped to.

Value

An object of a class derived from generic_spct such as raw_spct or filter_spct. generic_spct is derived from tibble and data frame.

Acknowledgements

We thank Ruud Niesen from Photon Mission (https://photonmission.com/) for organizing the loan of the spectrometer used to produce the various files needed for the development of this function.

Note

Enlighten, the free software from Wasatch Photonics can save spectra in a variety of additional formats: different types of CSV files, plain text and JSON. Plain text files contain no metadata or even column headers and if the need arises can be read with R function read.table(). JSON files contain the most detailed metadata.

References

https://wasatchphotonics.com/ https://wasatchphotonics.com/product-category/software/

Examples

file.name <- 
   system.file("extdata", "enlighten-wasatch-scope.csv",
               package = "photobiologyInOut", mustWork = TRUE)
              
 wasatch.raw.spct <- 
   read_wasatch_csv(file = file.name)
 summary(wasatch.raw.spct)

 wasatch.raw.spct <- 
   read_wasatch_csv(file = file.name, s.qty = "counts")
 summary(wasatch.raw.spct)

 wasatch.raw.spct <- 
   read_wasatch_csv(file = file.name, s.qty = c(Processed = "counts"))
 summary(wasatch.raw.spct)

 wasatch.raw.spct <- 
   read_wasatch_csv(file = file.name, extra.cols = "drop")
 summary(wasatch.raw.spct)

---

Read '.CSV' file(s) downloaded from YoctoPuce modules.

Description

Reads and parses the header of processed data CSV files as output by the virtual- or hardware-hubs and modules from Yoctopuce. Uses the comment attribute to store the metadata.

Usage

read_yoctopuce_csv(
  file,
  geocode = NULL,
  label = NULL,
  data_skip = 0,
  n_max = Inf,
  locale = readr::default_locale()
)

Arguments

file	Path to file as a character string.
geocode	A data frame with columns lon and lat used to set attribute "where.measured".
label	character string, but if NULL the value of file is used, and if NA the "what.measured" attribute is not set.
data_skip	integer Number of records (rows) to skip from the actual data block.
n_max	integer Maximum number of records to read.
locale	The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

Details

Yoctopuce modules are small USB connected and USB powered, but isolated, very high quality miniature data acquisition and interface modules. All modules capable of data acquisition can log measured data autonomously and these data can be locally or remotely downloaded as a CSV file. (It is also possible and very easy to access these modules from R using package 'reticulate' and the Python library provided by Yoctopuce, or to send commands and retrieve data through the built-in HTML server of the modules or dedicated hubs.)

Value

read_yoctopuce_csv() returns a tibble::tibble object, with the number of columns dependent on the CSV file read.

Note

This function should be able to read data log files from any YoctoPuce USB interface module with data logging capabilities as the format is consistent among them.

References

https://www.yoctopuce.com/

Examples

# We read a CSV file previously downloaded from a YoctoMeteo module.

 file.name <- 
   system.file("extdata", "yoctopuce-data.csv", 
               package = "photobiologyInOut", mustWork = TRUE)
                
 yoctopc.tb <- read_yoctopuce_csv(file = file.name)
 
 yoctopc.tb
 cat(comment(yoctopc.tb))

---

Convert "pavo::rspec" objects

Description

Convert between 'pavo::rspec' objects containing spectral reflectance data into spectral objects (xxxx_spct, xxxx_mspct) as defined in package 'photobiology'.

Usage

rspec2mspct(
  x,
  member.class = "reflector_spct",
  spct.data.var = "Rpc",
  multiplier = 1,
  ...
)

rspec2spct(x, multiplier = 1, ...)

Arguments

x	rspec object
member.class	character One of the spectrum classes defined in package 'photobiology'.
spct.data.var	character The name to be used for the 'spc' data when constructing the spectral objects.
multiplier	numeric A multiplier to be applied to the 'rspc' data to do unit or scale conversion.
...	currently ignored.

Warning!

Always check the sanity of the imported or exported data values, as guessing is needed when matching the different classes, and the functions defined here are NOT guaranteed to return valid data wihtout help from the user through optional function arguments.

Note

Objects of class pavo::rspec do not contain metadata or class data from which the quantity measured and the units of expression could be obtained. When using this function the user needs to use parameter multiplier to convert the data to what is expected by the object constructors defined in package 'photobiology' and use parameter spct.data.var to select the quantity.

pavo::rspec objects may use memory more efficiently than spectral objects of the classes for collections of spectra defined in package 'photobiology' as wavelengths are assumed to be the same for all member spectra, and stored only once while this assumption is not made for collections of spectra, allowing different wavelengths and lengths for the component spectra. Wavelengths are stored for each spectrum, but as spectral classes are derived from 'tbl_df' in many cases no redundant copies of wavelength data will be made in memory in spite of the more flexible semantics of the objects.

Examples

# example run only if 'pavo' is available
if (requireNamespace("pavo", quietly = TRUE)) {
  library(pavo)
  data(sicalis, package = "pavo")
  sicalis.mspct <- rspec2mspct(sicalis)
  class(sicalis.mspct)

  data(teal, package = "pavo")
  teal.spct <- rspec2spct(teal)
  class(teal.spct)
  levels(teal.spct[["spct.idx"]])
  angles <- seq(from = 15, to = 75, by = 5) # from teal's documentation
  teal.spct[["angle"]] <- angles[as.numeric(teal.spct[["spct.idx"]])]
  teal.spct
}

---

Correlated color temperature

Description

Wrapper on function computeCCT from package 'colorSpec' that accepts source_spct objects.

Usage

spct_CCT(
  spct,
  isotherms = "robertson",
  locus = "robertson",
  strict = FALSE,
  named = FALSE
)

Arguments

spct	source_spct A single light source spectrum.
isotherms	character A vector whose elements match one of the available isotherm families: 'robertson', 'mccamy', and 'native'. Matching is partial and case-insensitive. When more than one family is given, a matrix is returned, see Value. When isotherms = 'native' the isotherms are defined implicitly as lines perpendicular to the locus, see Details in CCTfromXYZ. The character NA (NA_character_) is taken as a synonym for 'native'.
locus	character Valid values are 'robertson' and 'precision', see above. Matching is partial and case-insensitive.
strict	logical The CIE considers the CCT of a chromaticity uv to be meaningful only if the distance from uv to the Planckian locus is less than or equal to 0.05 (in CIE UCS 1960). If strict=FALSE, then this condition is ignored. Otherwise, the distance is computed along the corresponding isotherm, and if it exceeds 0.05 the returned CCT is set to NA.
named	logical Whether to set the name attribute of the returned value to the name of the spectrum passed as argument if possible.

Details

Please see computeCCT for the details of the computations and references.

Value

A numeric value for "color temperature " in degrees Kelvin.

Examples

spct_CCT(white_led.source_spct)
spct_CCT(sun.spct)

---

Color reproduction index

Description

Wrapper on function computeCRI from package 'colorSpec' that accepts source_spct objects.

Usage

spct_CRI(spct, adapt = TRUE, attach = FALSE, tol = 0.0054, named = FALSE)

Arguments

spct	source_spct A single light source spectrum.
adapt	logical If TRUE, then a special chromatic adaption is performed, see Details in computeCRI.
attach	logical If TRUE, then a large list of intermediate calculations is attached to the returned number, as attribute data. This attached list includes data for all special 14 color samples, although the last 6 do not affect the returned CRI
tol	numeric For the CRI to be meaningful the chromaticities of the test and reference illuminants must be sufficiently close in the CIE 1960 uniform chromaticity space. If the tolerance is exceeded, the function returns NA. The default tol=5.4e-3 is the one recommended by the CIE, but the argument allows the user to override it.
named	logical Whether to set the name attribute of the returned value to the name of the spectrum passed as argument if possible.

Details

Please see computeCRI for the details of the computations and references.

Value

A numeric value between zero and 100, or NA if the light is not white enough.

Examples

spct_CRI(white_led.source_spct)
spct_CRI(sun.spct)

---

Spectral (color) similarity index

Description

Wrapper on function computeSSI from package 'colorSpec' that accepts source_spct objects.

Usage

spct_SSI(
  spct,
  reference.spct = NULL,
  digits = 0,
  isotherms = "mccamy",
  locus = "robertson",
  named = FALSE
)

Arguments

spct, reference.spct	source_spct Single light source spectra.
digits	integer The number of digits after the decimal point in the returned vector. According to Holm the output should be rounded to the nearest integer, which corresponds to digits = 0. To return full precision, set digits = Inf.
isotherms	character This is only used when reference=NULL. It is passed to computeCCT in order to compute the CCT of each test spectrum.
locus	character This is only used when reference=NULL. It is passed to computeCCT in order to compute the CCT of each test spectrum.
named	logical Whether to set the name attribute of the returned value to the name of the spectrum passed as argument if possible.

Details

Please see computeSSI for the details of the computations and references.

Value

A numeric value between zero and 100.

Examples

spct_SSI(white_led.source_spct, sun.spct)

---