Import time series "Surface UV" data released by EUMETSAT AC SAF (Atmospheric Composition Monitoring) project from text files downloaded from the FMI server.
Usage
sUV_read_OUV_txt(
files,
vars.to.read = NULL,
add.geo = length(files) > 1,
keep.QC = TRUE,
verbose = interactive()
)
sUV_vars_OUV_txt(files, keep.QC = TRUE, set.oper = "intersect")
sUV_grid_OUV_txt(files, use.names = length(files) > 1)Arguments
- files
character A vector of file names, no other limitation in length than available memory to hold the data.
- vars.to.read
character A vector of variable names. If
NULLall the variables present in the first file are read.- add.geo
logical Add columns
LongitudeandLatitudeto returned data frame.- keep.QC
logical Add to the returned data frame or vector the quality control variables, always present in the files.
- verbose
logical Flag indicating if progress, and time and size of the returned object should be printed.
- set.oper
character One of
"intersect", or"union".- use.names
logical. Should row names be added to the returned data frame?
Value
sUV_read_OUV_txt() returns a data frame with columns named
"Date", "Longitude", "Latitude", and the data variables with their
original names (with no units). The data variables have no metadata stored
as R attributes. When reading multiple files, by default the format is
similar to that from function sUV_read_OUV_hdf5(). Column names are the
same but column order can differ. File headers are saved as a list in R
attribute file.headers. sUV_vars_OUV_txt() returns a character
vector of variable names, and sUV_grid_OUV_txt() a dataframe with two
numeric variables, Longitude and Latitude, and a single row.
Details
All information is in the files, including dates, and no
information is decoded from file names, that users will most likely want to
rename. Each file corresponds to a single geographic location. If not all
the files named in the argument to files are accessible, an error is
triggered early. If the files differ in the coordinates, an error is
triggered when reading the first mismatching file if coordinates are not
being added to the data frame. Missing variables named in vars.to.read
are currently ignored.
Data from multiple files are concatenated. By default, the geographic coordinates are added in such a case.
Note
When requesting the data from the EUMETSAT AC SAF FMI server at https://acsaf.org/ it is possible to select the variables to be included in the file, the period and the geographic coordinates of a single location. The data are returned as a .zip compressed file containing one text file with one row for each day in the range of dates selected. These files are fairly small.
This function's performance is not optimized for speed as these single location files are rather small. The example time series data included in the package are for one summer in Helsinki, Finland.
References
Kujanpää, J. (2019) PRODUCT USER MANUAL Offline UV Products v2 (IDs: O3M-450 - O3M-464) and Data Record R1 (IDs: O3M-138 - O3M-152). Ref. SAF/AC/FMI/PUM/001. 18 pp. EUMETSAT AC SAF.
See also
sUV_read_OUV_hdf5() supporting the same Surface UV data stored
in a gridded format.
Examples
# find location of one example file
one.file.name <-
system.file("extdata", "AC_SAF-Viikki-FI-6masl.txt",
package = "surfaceuv", mustWork = TRUE)
# Available variables
sUV_vars_OUV_txt(one.file.name)
#> [1] "Date" "DailyDoseUva" "DailyDoseUvb"
#> [4] "DailyMaxDoseRateUva" "DailyMaxDoseRateUvb" "QC_MISSING"
#> [7] "QC_LOW_QUALITY" "QC_MEDIUM_QUALITY" "QC_INHOMOG_SURFACE"
#> [10] "QC_POLAR_NIGHT" "QC_LOW_SUN" "QC_OUTOFRANGE_INPUT"
#> [13] "QC_NO_CLOUD_DATA" "QC_POOR_DIURNAL_CLOUDS" "QC_THICK_CLOUDS"
#> [16] "QC_ALB_CLIM_IN_DYN_REG" "QC_LUT_OVERFLOW" "QC_OZONE_SOURCE"
#> [19] "QC_NUM_AM_COT" "QC_NUM_PM_COT" "QC_NOON_TO_COT"
#> [22] "Algorithm version"
sUV_vars_OUV_txt(one.file.name, keep.QC = FALSE)
#> [1] "Date" "DailyDoseUva" "DailyDoseUvb"
#> [4] "DailyMaxDoseRateUva" "DailyMaxDoseRateUvb" "Algorithm version"
# Grid point coordinates
sUV_grid_OUV_txt(one.file.name)
#> Longitude Latitude
#> 1 25 60
# read all variables
summer_viikki.tb <-
sUV_read_OUV_txt(one.file.name)
dim(summer_viikki.tb)
#> [1] 153 22
colnames(summer_viikki.tb)
#> [1] "Date" "DailyDoseUva" "DailyDoseUvb"
#> [4] "DailyMaxDoseRateUva" "DailyMaxDoseRateUvb" "QC_MISSING"
#> [7] "QC_LOW_QUALITY" "QC_MEDIUM_QUALITY" "QC_INHOMOG_SURFACE"
#> [10] "QC_POLAR_NIGHT" "QC_LOW_SUN" "QC_OUTOFRANGE_INPUT"
#> [13] "QC_NO_CLOUD_DATA" "QC_POOR_DIURNAL_CLOUDS" "QC_THICK_CLOUDS"
#> [16] "QC_ALB_CLIM_IN_DYN_REG" "QC_LUT_OVERFLOW" "QC_OZONE_SOURCE"
#> [19] "QC_NUM_AM_COT" "QC_NUM_PM_COT" "QC_NOON_TO_COT"
#> [22] "Algorithm version"
str(sapply(summer_viikki.tb, class))
#> Named chr [1:22] "Date" "numeric" "numeric" "numeric" "numeric" "integer" ...
#> - attr(*, "names")= chr [1:22] "Date" "DailyDoseUva" "DailyDoseUvb" "DailyMaxDoseRateUva" ...
summary(summer_viikki.tb)
#> Date DailyDoseUva DailyDoseUvb DailyMaxDoseRateUva
#> Min. :2024-05-01 Min. : 150.1 Min. : 1.984 Min. : 6096
#> 1st Qu.:2024-06-08 1st Qu.: 811.5 1st Qu.:12.780 1st Qu.:29400
#> Median :2024-07-16 Median :1100.0 Median :16.660 Median :36820
#> Mean :2024-07-16 Mean :1054.0 Mean :16.587 Mean :34413
#> 3rd Qu.:2024-08-23 3rd Qu.:1391.5 3rd Qu.:21.225 3rd Qu.:42250
#> Max. :2024-09-30 Max. :1571.0 Max. :29.230 Max. :45860
#> NA's :2 NA's :2 NA's :2
#> DailyMaxDoseRateUvb QC_MISSING QC_LOW_QUALITY QC_MEDIUM_QUALITY
#> Min. : 102.7 Min. :0.00000 Min. :0.00000 Min. :0.00000
#> 1st Qu.: 577.6 1st Qu.:0.00000 1st Qu.:0.00000 1st Qu.:0.00000
#> Median : 707.5 Median :0.00000 Median :0.00000 Median :0.00000
#> Mean : 693.2 Mean :0.01307 Mean :0.01307 Mean :0.03922
#> 3rd Qu.: 831.7 3rd Qu.:0.00000 3rd Qu.:0.00000 3rd Qu.:0.00000
#> Max. :1099.0 Max. :1.00000 Max. :1.00000 Max. :1.00000
#> NA's :2
#> QC_INHOMOG_SURFACE QC_POLAR_NIGHT QC_LOW_SUN QC_OUTOFRANGE_INPUT
#> Min. :0.00000 Min. :0 Min. :0 Min. :0
#> 1st Qu.:0.00000 1st Qu.:0 1st Qu.:0 1st Qu.:0
#> Median :0.00000 Median :0 Median :0 Median :0
#> Mean :0.02614 Mean :0 Mean :0 Mean :0
#> 3rd Qu.:0.00000 3rd Qu.:0 3rd Qu.:0 3rd Qu.:0
#> Max. :1.00000 Max. :0 Max. :0 Max. :0
#>
#> QC_NO_CLOUD_DATA QC_POOR_DIURNAL_CLOUDS QC_THICK_CLOUDS QC_ALB_CLIM_IN_DYN_REG
#> Min. :0 Min. :0 Min. :0 Min. :0
#> 1st Qu.:0 1st Qu.:0 1st Qu.:0 1st Qu.:0
#> Median :0 Median :0 Median :0 Median :0
#> Mean :0 Mean :0 Mean :0 Mean :0
#> 3rd Qu.:0 3rd Qu.:0 3rd Qu.:0 3rd Qu.:0
#> Max. :0 Max. :0 Max. :0 Max. :0
#>
#> QC_LUT_OVERFLOW QC_OZONE_SOURCE QC_NUM_AM_COT QC_NUM_PM_COT
#> Min. :0 Min. :0.0000 Min. :0.000 Min. :0.0000
#> 1st Qu.:0 1st Qu.:1.0000 1st Qu.:2.000 1st Qu.:0.0000
#> Median :0 Median :1.0000 Median :2.000 Median :0.0000
#> Mean :0 Mean :0.9935 Mean :1.902 Mean :0.3464
#> 3rd Qu.:0 3rd Qu.:1.0000 3rd Qu.:2.000 3rd Qu.:1.0000
#> Max. :0 Max. :2.0000 Max. :3.000 Max. :1.0000
#>
#> QC_NOON_TO_COT Algorithm version
#> Min. :0.00000 Length:153
#> 1st Qu.:0.00000 Class :character
#> Median :0.00000 Mode :character
#> Mean :0.04575
#> 3rd Qu.:0.00000
#> Max. :1.00000
#>
attr(summer_viikki.tb, "file.headers")
#> $`AC_SAF-Viikki-FI-6masl.txt`
#> [1] "#AC SAF offline surface UV, time-series"
#> [2] "#OUV EXTRACTOR VERSION: 1.20"
#> [3] "#LONGITUDE: 25.000 (0-based index 410)"
#> [4] "#LATITUDE: 60.000 (0-based index 300)"
#> [5] "#COLUMN DEFINITIONS"
#> [6] "#0: Date [YYYYMMDD]"
#> [7] "#1: DailyDoseUva [kJ/m2]"
#> [8] "#2: DailyDoseUvb [kJ/m2]"
#> [9] "#3: DailyMaxDoseRateUva [mW/m2]"
#> [10] "#4: DailyMaxDoseRateUvb [mW/m2]"
#> [11] "#5: QC_MISSING"
#> [12] "#6: QC_LOW_QUALITY"
#> [13] "#7: QC_MEDIUM_QUALITY"
#> [14] "#8: QC_INHOMOG_SURFACE"
#> [15] "#9: QC_POLAR_NIGHT"
#> [16] "#10: QC_LOW_SUN"
#> [17] "#11: QC_OUTOFRANGE_INPUT"
#> [18] "#12: QC_NO_CLOUD_DATA"
#> [19] "#13: QC_POOR_DIURNAL_CLOUDS"
#> [20] "#14: QC_THICK_CLOUDS"
#> [21] "#15: QC_ALB_CLIM_IN_DYN_REG"
#> [22] "#16: QC_LUT_OVERFLOW"
#> [23] "#17: QC_OZONE_SOURCE"
#> [24] "#18: QC_NUM_AM_COT"
#> [25] "#19: QC_NUM_PM_COT"
#> [26] "#20: QC_NOON_TO_COT"
#> [27] "#21: Algorithm version"
#> [28] "#DATA"
#>
# read all data variables
summer_viikki_QCf.tb <-
sUV_read_OUV_txt(one.file.name, keep.QC = FALSE)
dim(summer_viikki_QCf.tb)
#> [1] 153 6
summary(summer_viikki_QCf.tb)
#> Date DailyDoseUva DailyDoseUvb DailyMaxDoseRateUva
#> Min. :2024-05-01 Min. : 150.1 Min. : 1.984 Min. : 6096
#> 1st Qu.:2024-06-08 1st Qu.: 811.5 1st Qu.:12.780 1st Qu.:29400
#> Median :2024-07-16 Median :1100.0 Median :16.660 Median :36820
#> Mean :2024-07-16 Mean :1054.0 Mean :16.587 Mean :34413
#> 3rd Qu.:2024-08-23 3rd Qu.:1391.5 3rd Qu.:21.225 3rd Qu.:42250
#> Max. :2024-09-30 Max. :1571.0 Max. :29.230 Max. :45860
#> NA's :2 NA's :2 NA's :2
#> DailyMaxDoseRateUvb Algorithm version
#> Min. : 102.7 Length:153
#> 1st Qu.: 577.6 Class :character
#> Median : 707.5 Mode :character
#> Mean : 693.2
#> 3rd Qu.: 831.7
#> Max. :1099.0
#> NA's :2
# read all data variables including geographic coordinates
summer_viikki_geo.tb <-
sUV_read_OUV_txt(one.file.name, keep.QC = FALSE, add.geo = TRUE)
dim(summer_viikki_geo.tb)
#> [1] 153 8
summary(summer_viikki_geo.tb)
#> Date DailyDoseUva DailyDoseUvb DailyMaxDoseRateUva
#> Min. :2024-05-01 Min. : 150.1 Min. : 1.984 Min. : 6096
#> 1st Qu.:2024-06-08 1st Qu.: 811.5 1st Qu.:12.780 1st Qu.:29400
#> Median :2024-07-16 Median :1100.0 Median :16.660 Median :36820
#> Mean :2024-07-16 Mean :1054.0 Mean :16.587 Mean :34413
#> 3rd Qu.:2024-08-23 3rd Qu.:1391.5 3rd Qu.:21.225 3rd Qu.:42250
#> Max. :2024-09-30 Max. :1571.0 Max. :29.230 Max. :45860
#> NA's :2 NA's :2 NA's :2
#> DailyMaxDoseRateUvb Algorithm version Longitude Latitude
#> Min. : 102.7 Length:153 Min. :25 Min. :60
#> 1st Qu.: 577.6 Class :character 1st Qu.:25 1st Qu.:60
#> Median : 707.5 Mode :character Median :25 Median :60
#> Mean : 693.2 Mean :25 Mean :60
#> 3rd Qu.: 831.7 3rd Qu.:25 3rd Qu.:60
#> Max. :1099.0 Max. :25 Max. :60
#> NA's :2
# read two variables
summer_viikki_2.tb <-
sUV_read_OUV_txt(one.file.name,
vars.to.read = c("DailyDoseUva", "DailyDoseUvb"))
dim(summer_viikki_2.tb)
#> [1] 153 3
summary(summer_viikki_2.tb)
#> Date DailyDoseUva DailyDoseUvb
#> Min. :2024-05-01 Min. : 150.1 Min. : 1.984
#> 1st Qu.:2024-06-08 1st Qu.: 811.5 1st Qu.:12.780
#> Median :2024-07-16 Median :1100.0 Median :16.660
#> Mean :2024-07-16 Mean :1054.0 Mean :16.587
#> 3rd Qu.:2024-08-23 3rd Qu.:1391.5 3rd Qu.:21.225
#> Max. :2024-09-30 Max. :1571.0 Max. :29.230
#> NA's :2 NA's :2