read_lisst: Read LISST data

In AlexCast/lisst: Functions for manipulation of the Laser In-Situ Scattering and Transmissometry (LISST) data

Description

Read LISST processed or binary data files.

Usage

read_lisst(fl, sn, pl, zscat, yr, out, model, tz = "UTC", trant = TRUE)

Arguments

fl	Path to processed or binary file (e.g., *.DAT for the LISST-100(X)).
sn	Serial number of the instrument. Optionally, can be omitted when reading a LISST-SOP processed file or when out = 'raw' (binary files). In this case, instrument model must be supplied to argument model. Ignored for LISST_200X binary files.
pl	Path length in meters. If not provided the function will assume standard path length for the instrument model (with a warning), i.e., no path reduction module in use.
zscat	Background data. Might be provided as a raw lisst object or as a path to file (e.g., *.asc for LISST-100(X)). This is required for processing binary files, with the exception of out = 'raw'. It is optional for the LISST-200X, if it is desired to process the binary file with a different zscat than the internaly stored.
yr	The year of first measurement in the data file. Only necessary for LISST-100(X). If not provided, function will make a best guess (with a warning). See details.
out	The output format. Valid options are 'raw', 'cor', 'cal', 'vsf', 'vol' and 'pnc'. See details.
model	A character vector of the instrument model. The detector type must be included in the name (e.g., "100C" or "100XC"). Ignored if sn is provided and for LISST-200X files.
tz	Time zone to interpret time indexing. Defaults to UTC.
trant	Logical. Should a optical transmittance threshold be applied? If TRUE, ring values for a given sample with transmittance < 0.3 are set to NA.

Details

The function will determine the file type based on its extenssion. Processed files created from LISST SOP for the LISST-100(X) have extension .asc and for the LISST-200X, extension .csv. Binary files have extension .DAT and .RBN for the LISST-100(X) and LISST-200X, respectivelly.

The parameter out determine the level of processing of the returned object. For binary files out can be 'raw' for the raw digital counts, 'cor' for the corrected digital counts, 'cal' for values in calibrated physical units or 'vsf' for the volume scattering function. The corrected digital counts are the raw counts de-attenuated for the particle and water extinction, background subtracted and compensated for area deviations from nominal values. 'cal' applies the instrument specific calibration constants to 'cor' (for all variables). Aditionally, the transmittance and the particle beam attenuation are added in 'cal' type lisst objects. The particle volume scattering function is the calibrated values normalized by the detector solid angle, length of the path generating the signal and energy entering the path. If out is not provided, 'vsf' will be returned for a binary file input. For processed files, out can be 'vol' for the volume concentration (ppm) or 'pnc' for the number concentration (1/L/µm). If not provided, 'vol' will be returned for processed files. As of this version, is not possible to direcly retrieve the particle size distribution (PSD) from binary data (inversion model not implemented), so 'vol' and 'pnc' can only be selected for processed files. Functions lget, lgetraw, lgetcor, lgetcal, lgetvsf, lgetvol and lgetpnc allow to switch between types without need to read again from disk.

If the background data is saved as a binary file, it must be opened first with read_lisst and aggregated to one row lisst object with lstat before being passed to a new read_lisst call to open the data itself.

A time indexing, with date/time in POSIX format is added to all created objects. If yr is missing when reading a LISST-100(X) file, the function will 'guess' its value, by acessing the file system modification date information. The modification date is used to be consistent across platforms, since UNIX-type systems do not register creation date. Still, those are expected to be equivalent since the files are not expected to be modified since their creation by the LISST instrument (binary) or the LISST-SOP (processed). In the case of binary file, the year will be then precise for the year of last measurement and the function will handle it appropriatly. For a processed file the logic will break down in cases that the file is processed in a different year than the final measurement. It is always better to specify all necessary information.

Value

The function returns an object of class lisst, an S3 Class inheriting from classes data.frame and units. Essentially the data is stored as units objects in a data.frame, with LISST metadata stored as attributes. For consistency with SOP and MatLab functions provided by Sequoia, all data columns are kept, including original time columns and the LISST-200X unused data column.

The attributes are not expected to be manipulated directly, but functions are available to extract some relevant metadata (?) information so are only briefly described:

• type - The type of data in the lisst object;

• lproc - Processing type (rs or ss) if any;

• linst - Instrument specific data;

• lmodl - Model specific data;

• zscat - Background scattering values.

References

MATLAB source code provided by Sequoia Scientific, Inc, and available at: https://www.sequoiasci.com/product/lisst-100x/, https://www.sequoiasci.com/product/lisst-200x/

See Also

lget, lgetraw, lgetcor, lgetcal, lgetvsf, lgetvol and lgetpnc.

Examples

flp <- system.file("extdata", "DN_27_rs.asc", package = "lisst")
flb <- system.file("extdata", "DN_27.DAT", package = "lisst")

# For a unregistered LISST instrument:
model <- "100CX" 
lop <- read_lisst(flp, model = model)
lob <- read_lisst(flb, out = 'raw', model = model)

# If other levels of processing, including VSF, are required, first
# register a LISST instrument:
path  <- system.file("extdata", package = "lisst")
model <- 100
lisst_reg(model, path)

sn    <- 1298
pl    <- 0.05
yr    <- 2018
out   <- 'vol'
zscat <- system.file("extdata", "bg_20180326.asc", package = "lisst")

# For a processed file:
lop <- read_lisst(flp, sn, pl, zscat, yr, out)
lop <- read_lisst(flp, sn, pl, zscat, yr)
lop <- read_lisst(flp, sn, pl, zscat)
lop <- read_lisst(flp, sn, pl)
lop <- read_lisst(flp, sn) # minimum information

# For a binary file:
lob <- read_lisst(flb, sn, pl, zscat, yr, out = 'raw')
lob <- read_lisst(flb, sn, pl, zscat, yr, out = 'cor')
lob <- read_lisst(flb, sn, pl, zscat, yr, out = 'cal')
lob <- read_lisst(flb, sn, pl, zscat, yr)
lob <- read_lisst(flb, sn, pl, zscat)
lob <- read_lisst(flb, sn, zscat = zscat) # minimum information for full capability

AlexCast/lisst documentation built on July 17, 2021, 12:58 a.m.