Skip to contents

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 NULL all the variables present in the first file are read.

add.geo

logical Add columns Longitude and Latitude to 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