Read the spectral data and parse the header of a energy irradiance, a reflectance, a transmittance data, a raw-detector-counts data or arbitrary data file as output by the text conversion tool for ASD spectrometers when set for tab-, comma- or semicolon-separated output. ASD's field spectrometers measure VIS and SWIR radiation.
Usage
read_asd_txt(
file,
date = NULL,
geocode = NULL,
label = NULL,
tz = NULL,
locale = readr::default_locale(),
s.qty = NULL,
scale.factor = 1,
range = NULL
)Arguments
- file
character string Path to the file to be read, following R's use of forward slashes as separator for folder names.
- date
a
POSIXctobject to use to set the"when.measured"attribute. IfNULL, the default, the date is extracted from the file header.- geocode
A data frame with columns
lonandlat, and optionallyaddressused to set attribute"where.measured".- label
character string to which to set the
"what.measured"attribute. IfNULLthe value ofbasename(file)is used, and ifNAthe"what.measured"attribute is not set.- tz
character A time zone recognized by R. If
NULLit is extracted fromlocale. If"", the default, the local time zone is used.- locale
The locale controls defaults that vary from place to place. The default locale is US-centric (like R), with time in UTC but you can use
localeto create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names. Its value must match that used to write the imported file, which is not necessarily the default one or the local one.- s.qty
character string The name of the quantity to be read as by object constructors from 'photobiology'. If
NULLquantity is guessed from file header.- scale.factor
numeric Multiplier to be applied to the spectral data so that it matches
s.qtyin base of expression and units. In most cases the default of 1.0 is correct.- range
a numeric vector of length two, or any other object for which function
range()will return a range of wavelengths expressed in nanometres.
Value
A source_spct object with a column s.e.irrad with
spectral energy irradiance in \(W m^{-2} nm^{-1}\), or a
reflector_spct object with a column Rfr with fractional
reflectance, or a filter_spct object with a column Tfr with
fractional total transmittance. In all cases a column w.length
contains wavelengths in nanometres and the attributes comment,
what.measured, when.measured, how.measured,
where.measured and file.header containing metadata for the
spectrum.
Details
The header of the file is first decoded and parsed to extract the
time of data acquisition and serial number of the spectrometer, to locate
the start of the spectral data and to detect the column separator used. The
time in the header is the local time with no time zone information. Thus
with the default tz = "" the time is re-expressed as UTC with a
correction. When file import takes place on a different time zone than the
measurement the measurement time zone must be supplied by the user as an
argument to parameter tz or as part of the locale after
setting tz = NULL. The metadata fields in the header are located by
text matching.
Spectral irradiance is returned as an object of class
source_spct, reflectance as
reflector_spct, transmittance as
filter_spct, raw detector counts as
raw_spct, and arbitrary spectral values as
generic_spct objects with metadata stored in
attributes when.measured, what.measured, and
how.measured. The spectral quantity is guessed from the header
metadata by default, but an argument to s.qty can be passed to
override this default.
The value stored in the how.measured attribute includes the
spectrometer serial number extracted from the file header. If an argument
is passed to parameter geocode, its value is saved in attribute
where.measured (currently the geocode is not extracted from the file
header). The object's comment always gives a text that includes the
file name, time of import, function name and the version of packages
'photobiology' and 'photobiologyInOut' used. The file header in whole is
copied to attribute file.header.
Note
Some files with ASD spectral data contain nul ASCII characters
in the header. These are ignored with a warning while the data are still
read. Depending on the program used to view these data files, only the top
three lines will be displayed, or the file will be detected as containing
binary data and not displayed.
Examples
# energy spectral irradiance file
file.name <-
system.file("extdata", "asd-e-irrad-sky.tsv",
package = "photobiologyInOut",
mustWork = TRUE)
asd.source_spct <-
read_asd_txt(file = file.name,
tz = "Europe/Helsinki")
class_spct(asd.source_spct)
#> [1] "source_spct" "generic_spct"
summary(asd.source_spct)
#> Summary of source_spct [2,150 x 2] object: asd.source_spct
#> Wavelength range 351-2500 nm, step 1 nm
#> Label: File: asd-e-irrad-sky.tsv
#> Qty: 'rad_sky-00073.asd'
#> Measured on 2024-05-21 08:33:07 UTC
#> Variables:
#> w.length: Wavelength [nm]
#> s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
#> --
#> w.length s.e.irrad
#> Min. : 351.0 Min. :-7.3028
#> 1st Qu.: 888.2 1st Qu.: 0.0362
#> Median :1425.5 Median : 0.1274
#> Mean :1425.5 Mean : 0.2529
#> 3rd Qu.:1962.8 3rd Qu.: 0.3927
#> Max. :2500.0 Max. : 6.7763
getWhenMeasured(asd.source_spct)
#> [1] "2024-05-21 08:33:07 UTC"
getWhatMeasured(asd.source_spct)
#> [1] "File: asd-e-irrad-sky.tsv\nQty: 'rad_sky-00073.asd'"
getHowMeasured(asd.source_spct)
#> [1] "Measured with ASD spectrometer with s.n. 18875/1 and ASD software."
cat(comment(asd.source_spct))
#> Imported ASD text-converted file 'asd-e-irrad-sky.tsv' with quantity name 'rad_sky-00073.asd' imported on 2026-03-13 22:40:56 UTC with function 'read_asd_txt()'.
#> R packages 'photobiologyInOut' 0.4.33 and 'photobiology' 0.14.1.9003 were used.
e_irrad(asd.source_spct)
#> E_Total
#> 543.0536
#> attr(,"time.unit")
#> [1] "second"
#> attr(,"radiation.unit")
#> [1] "total energy irradiance"
q_irrad(asd.source_spct, w.band = c(400, 700),
scale.factor = 1e6)
#> Q_range.400.700
#> 1125.945
#> attr(,"time.unit")
#> [1] "second"
#> attr(,"radiation.unit")
#> [1] "total photon irradiance"
asd_clipped.source_spct <-
read_asd_txt(file = file.name,
tz = "Europe/Helsinki",
range = c(400, 700))
class_spct(asd_clipped.source_spct)
#> [1] "source_spct" "generic_spct"
summary(asd_clipped.source_spct)
#> Summary of source_spct [301 x 2] object: asd_clipped.source_spct
#> Wavelength range 400-700 nm, step 1 nm
#> Label: File: asd-e-irrad-sky.tsv
#> Qty: 'rad_sky-00073.asd'
#> Measured on 2024-05-21 08:33:07 UTC
#> Variables:
#> w.length: Wavelength [nm]
#> s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
#> --
#> w.length s.e.irrad
#> Min. :400 Min. :0.5207
#> 1st Qu.:475 1st Qu.:0.7773
#> Median :550 Median :0.8392
#> Mean :550 Mean :0.8151
#> 3rd Qu.:625 3rd Qu.:0.8852
#> Max. :700 Max. :0.9437
# spectral reflectance file
file.name <-
system.file("extdata", "asd-Rfr-panel-50pc.tsv",
package = "photobiologyInOut",
mustWork = TRUE)
asd.reflector_spct <-
read_asd_txt(file = file.name,
tz = "Europe/Helsinki")
#> Found 36/2150 off-range 'Rfr' values [-1.25..4.92] instead of [0..1]
class_spct(asd.reflector_spct)
#> [1] "reflector_spct" "generic_spct"
summary(asd.reflector_spct)
#> Summary of reflector_spct [2,150 x 2] object: asd.reflector_spct
#> Wavelength range 351-2500 nm, step 1 nm
#> Label: File: asd-Rfr-panel-50pc.tsv
#> Qty: 'reflec_panels-00015.asd'
#> Measured on 2024-05-21 08:14:40 UTC
#> Variables:
#> w.length: Wavelength [nm]
#> Rfr: Total spectral reflectance [/1]
#> --
#> w.length Rfr
#> Min. : 351.0 Min. :-1.2452
#> 1st Qu.: 888.2 1st Qu.: 0.4675
#> Median :1425.5 Median : 0.4802
#> Mean :1425.5 Mean : 0.4950
#> 3rd Qu.:1962.8 3rd Qu.: 0.4904
#> Max. :2500.0 Max. : 4.9194
getWhenMeasured(asd.reflector_spct)
#> [1] "2024-05-21 08:14:40 UTC"
getWhatMeasured(asd.reflector_spct)
#> [1] "File: asd-Rfr-panel-50pc.tsv\nQty: 'reflec_panels-00015.asd'"
getHowMeasured(asd.reflector_spct)
#> [1] "Measured with ASD spectrometer with s.n. 18875/1 and ASD software."
cat(comment(asd.reflector_spct))
#> Imported ASD text-converted file 'asd-Rfr-panel-50pc.tsv' with quantity name 'reflec_panels-00015.asd' imported on 2026-03-13 22:40:56 UTC with function 'read_asd_txt()'.
#> R packages 'photobiologyInOut' 0.4.33 and 'photobiology' 0.14.1.9003 were used.
asd_clipped.reflector_spct <-
read_asd_txt(file = file.name,
tz = "Europe/Helsinki",
range = c(400, 700))
#> Found 36/2150 off-range 'Rfr' values [-1.25..4.92] instead of [0..1]
class_spct(asd_clipped.reflector_spct)
#> [1] "reflector_spct" "generic_spct"
summary(asd_clipped.reflector_spct)
#> Summary of reflector_spct [301 x 2] object: asd_clipped.reflector_spct
#> Wavelength range 400-700 nm, step 1 nm
#> Label: File: asd-Rfr-panel-50pc.tsv
#> Qty: 'reflec_panels-00015.asd'
#> Measured on 2024-05-21 08:14:40 UTC
#> Variables:
#> w.length: Wavelength [nm]
#> Rfr: Total spectral reflectance [/1]
#> --
#> w.length Rfr
#> Min. :400 Min. :0.4896
#> 1st Qu.:475 1st Qu.:0.4923
#> Median :550 Median :0.4950
#> Mean :550 Mean :0.4962
#> 3rd Qu.:625 3rd Qu.:0.4992
#> Max. :700 Max. :0.5077
# Raw-counts data
file.name <-
system.file("extdata", "asd-raw-gravel.tsv",
package = "photobiologyInOut",
mustWork = TRUE)
asd.raw_spct <-
read_asd_txt(file = file.name,
tz = "Europe/Helsinki")
class_spct(asd.raw_spct)
#> [1] "raw_spct" "generic_spct"
summary(asd.raw_spct)
#> Summary of raw_spct [2,150 x 2] object: asd.raw_spct
#> Wavelength range 351-2500 nm, step 1 nm
#> Label: File: asd-raw-gravel.tsv
#> Qty: 'reflec_penels3-00125.asd'
#> Measured on 2024-05-23 14:17:01 UTC
#> Data acquired with 'NA' s.n. NA
#> grating 'NA', slit 'NA'
#> diffuser 'unknown'
#> integ. time (s): NA
#> total time (s): NA
#> counts @ peak (% of max): NAVariables:
#> w.length: Wavelength [nm]
#> counts: Raw detector counts [number]
#> --
#> w.length counts
#> Min. : 351.0 Min. : -177.2
#> 1st Qu.: 888.2 1st Qu.: 215.5
#> Median :1425.5 Median : 1001.0
#> Mean :1425.5 Mean : 2156.4
#> 3rd Qu.:1962.8 3rd Qu.: 2227.7
#> Max. :2500.0 Max. :14982.6
getWhenMeasured(asd.raw_spct)
#> [1] "2024-05-23 14:17:01 UTC"
getWhatMeasured(asd.raw_spct)
#> [1] "File: asd-raw-gravel.tsv\nQty: 'reflec_penels3-00125.asd'"
getHowMeasured(asd.raw_spct)
#> [1] "Measured with ASD spectrometer with s.n. 18875/1 and ASD software."
cat(comment(asd.raw_spct))
#> Imported ASD text-converted file 'asd-raw-gravel.tsv' with quantity name 'reflec_penels3-00125.asd' imported on 2026-03-13 22:40:56 UTC with function 'read_asd_txt()'.
#> R packages 'photobiologyInOut' 0.4.33 and 'photobiology' 0.14.1.9003 were used.