Skip to contents

Import gridded "Surface UV" data released by FMI/NASA from NetCDF4 files downloaded from the NASA EARTHDATA server.

Usage

sUV_read_OMUVBd_nc4(
  files,
  vars.to.read = NULL,
  fill = NA_real_,
  verbose = interactive()
)

sUV_vars_OMUVBd_nc4(files, set.oper = "intersect")

sUV_grid_OMUVBd_nc4(files, expand = FALSE)

sUV_date_OMUVBd_nc4(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.

fill

numeric The R value used to replace the fill value used in the file, which is retrieved from the file metadata, and also used to fill missing variables.

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".

expand

logical Flag indicating whether to return ranges or a full grid.

use.names

logical. Should names be added to the returned vector?

Value

Function sUV_read_OMUVBd_nc4() returns a data frame with columns named "Date", "Longitude", "Latitude", and the data variables with their original names. The data variables have their metadata stored as R attributes. sUV_vars_OMUVBd_nc4() returns a character vector of variable names, sUV_grid_OMUVBd_nc4() returns a data frame with two numeric variables, Longitude and Latitude, with two rows or an expanded grid depending on the argument passed to expand, while sUV_date_OMUVBd_nc4() returns a, by default named, vector of class Date, with file names as names.

Details

Function sUV_read_OMUVBd_nc4() can be used to read the data stored in a file, either in full or selected variables. Query functions sUV_vars_OMUVBd_nc4(), sUV_grid_OMUVBd_nc4() and sUV_date_OMUVBd_nc4() extract the names of the variables, the range of the grid and the dates of measurements much more efficiently than by using sUV_read_OMUVBd_nc4(). The dates are decoded from the file names, expecting these to be those set by the data provider. The grid is expected to be identical in all files that are imported in a call to sUV_read_OMUVBd_nc4(), and grid subsetting is currently not supported. If not all the files named in the argument to files are accessible, an error is triggered early. If the files differ in the grid, an error is triggered when reading the first mismatching file. Missing variables named in vars.to.read if detected when reading the first file, are filled with the fill value, otherwise they trigger an error when an attempt is made to read them.

Note

The constraint on the consistency among all files to be read allows very fast reading into a single data frame. If the files differ in the grid or set of variables, this function can be used to read the files individually into separate data frames. These data frames can later be row-bound together.

This function's performance is fast as long as there is enough RAM available to hold the data frame and the files are read from a reasonably fast SSD. The example data included in the package are only for Spain and five summer days. They are used in examples and automated tests.

References

Jari Hovila, Antti Arola, and Johanna Tamminen (2013), OMI/Aura Surface UVB Irradiance and Erythemal Dose Daily L3 Global Gridded 1.0 degree x 1.0 degree V3, NASA Goddard Space Flight Center, Goddard Earth Sciences Data and Information Services Center (GES DISC).

See also

sUV_read_OMUVBd_he5() supporting the same Surface UV data as stored in the original HDF5 files with a global geographic scope.

Examples

# find location of one example file
path.to.files <-
   system.file("extdata",
               package = "surfaceuv", mustWork = TRUE)

file.names <- list.files(path.to.files, pattern = "*.nc4$", full.names = TRUE)
one.file.name <- file.names[1]

# available variables
sUV_vars_OMUVBd_nc4(one.file.name)
#>  [1] "Date"                  "Longitude"             "Latitude"             
#>  [4] "CloudOpticalThickness" "ErythemalDailyDose"    "ErythemalDoseRate"    
#>  [7] "Irradiance305"         "Irradiance310"         "Irradiance324"        
#> [10] "Irradiance380"         "UVindex"              

# available grid
sUV_grid_OMUVBd_nc4(one.file.name)
#>   Longitude Latitude
#> 1      24.5     58.5
#> 2      26.5     60.5
sUV_grid_OMUVBd_nc4(one.file.name, expand = TRUE)
#>   Longitude Latitude
#> 1      24.5     58.5
#> 2      25.5     58.5
#> 3      26.5     58.5
#> 4      24.5     59.5
#> 5      25.5     59.5
#> 6      26.5     59.5
#> 7      24.5     60.5
#> 8      25.5     60.5
#> 9      26.5     60.5

# decode date from file name
sUV_date_OMUVBd_nc4(one.file.name)
#> OMI-Aura_L3-OMUVBd_2023m1001_v003.nc4 
#>                          "2023-10-01" 
sUV_date_OMUVBd_nc4(one.file.name, use.names = FALSE)
#> [1] "2023-10-01"

# read all variables
midsummer_spain.tb <- sUV_read_OMUVBd_nc4(one.file.name)
dim(midsummer_spain.tb)
#> [1]  9 11
summary(midsummer_spain.tb)
#>       Date              Longitude       Latitude    CloudOpticalThickness
#>  Min.   :2023-10-01   Min.   :24.5   Min.   :58.5   Min.   :0.5107       
#>  1st Qu.:2023-10-01   1st Qu.:24.5   1st Qu.:58.5   1st Qu.:0.9730       
#>  Median :2023-10-01   Median :25.5   Median :59.5   Median :1.1728       
#>  Mean   :2023-10-01   Mean   :25.5   Mean   :59.5   Mean   :1.3821       
#>  3rd Qu.:2023-10-01   3rd Qu.:26.5   3rd Qu.:60.5   3rd Qu.:1.6853       
#>  Max.   :2023-10-01   Max.   :26.5   Max.   :60.5   Max.   :2.4806       
#>  ErythemalDailyDose ErythemalDoseRate Irradiance305   Irradiance310  
#>  Min.   :653.3      Min.   :32.80     Min.   :4.786   Min.   :15.97  
#>  1st Qu.:686.6      1st Qu.:34.48     1st Qu.:5.025   1st Qu.:16.76  
#>  Median :769.5      Median :38.68     Median :5.745   Median :18.86  
#>  Mean   :757.1      Mean   :38.09     Mean   :5.734   Mean   :18.66  
#>  3rd Qu.:813.2      3rd Qu.:40.99     3rd Qu.:6.367   3rd Qu.:20.27  
#>  Max.   :861.1      Max.   :43.34     Max.   :6.669   Max.   :21.31  
#>  Irradiance324   Irradiance380      UVindex     
#>  Min.   :117.6   Min.   :240.8   Min.   :1.309  
#>  1st Qu.:123.8   1st Qu.:255.4   1st Qu.:1.376  
#>  Median :137.5   Median :290.4   Median :1.543  
#>  Mean   :134.6   Mean   :281.4   Mean   :1.523  
#>  3rd Qu.:143.0   3rd Qu.:300.6   3rd Qu.:1.648  
#>  Max.   :151.3   Max.   :321.2   Max.   :1.739  

# read only UVindex
midsummer_spain_daily.tb <-
  sUV_read_OMUVBd_nc4(one.file.name,
                    vars.to.read = "UVindex")
dim(midsummer_spain_daily.tb)
#> [1] 9 4
summary(midsummer_spain_daily.tb)
#>       Date              Longitude       Latitude       UVindex     
#>  Min.   :2023-10-01   Min.   :24.5   Min.   :58.5   Min.   :1.309  
#>  1st Qu.:2023-10-01   1st Qu.:24.5   1st Qu.:58.5   1st Qu.:1.376  
#>  Median :2023-10-01   Median :25.5   Median :59.5   Median :1.543  
#>  Mean   :2023-10-01   Mean   :25.5   Mean   :59.5   Mean   :1.523  
#>  3rd Qu.:2023-10-01   3rd Qu.:26.5   3rd Qu.:60.5   3rd Qu.:1.648  
#>  Max.   :2023-10-01   Max.   :26.5   Max.   :60.5   Max.   :1.739  

# read multiple files

sUV_vars_OMUVBd_nc4(file.names)
#>  [1] "Date"                  "Longitude"             "Latitude"             
#>  [4] "CloudOpticalThickness" "ErythemalDailyDose"    "ErythemalDoseRate"    
#>  [7] "Irradiance305"         "Irradiance310"         "Irradiance324"        
#> [10] "Irradiance380"         "UVindex"              

sUV_grid_OMUVBd_nc4(file.names)
#>   Longitude Latitude
#> 1      24.5     58.5
#> 2      26.5     60.5
sUV_grid_OMUVBd_nc4(file.names, expand = TRUE)
#>   Longitude Latitude
#> 1      24.5     58.5
#> 2      25.5     58.5
#> 3      26.5     58.5
#> 4      24.5     59.5
#> 5      25.5     59.5
#> 6      26.5     59.5
#> 7      24.5     60.5
#> 8      25.5     60.5
#> 9      26.5     60.5

sUV_date_OMUVBd_nc4(file.names)
#> OMI-Aura_L3-OMUVBd_2023m1001_v003.nc4 OMI-Aura_L3-OMUVBd_2023m1002_v003.nc4 
#>                          "2023-10-01"                          "2023-10-02" 
#> OMI-Aura_L3-OMUVBd_2023m1003_v003.nc4 
#>                          "2023-10-03" 
sUV_date_OMUVBd_nc4(file.names, use.names = FALSE)
#> [1] "2023-10-01" "2023-10-02" "2023-10-03"

summer_3days_spain.tb <- sUV_read_OMUVBd_nc4(file.names)
dim(summer_3days_spain.tb)
#> [1] 27 11
summary(summer_3days_spain.tb)
#>       Date              Longitude       Latitude    CloudOpticalThickness
#>  Min.   :2023-10-01   Min.   :24.5   Min.   :58.5   Min.   : 0.5107      
#>  1st Qu.:2023-10-01   1st Qu.:24.5   1st Qu.:58.5   1st Qu.: 1.1440      
#>  Median :2023-10-02   Median :25.5   Median :59.5   Median : 1.6853      
#>  Mean   :2023-10-02   Mean   :25.5   Mean   :59.5   Mean   : 5.8036      
#>  3rd Qu.:2023-10-03   3rd Qu.:26.5   3rd Qu.:60.5   3rd Qu.: 7.5133      
#>  Max.   :2023-10-03   Max.   :26.5   Max.   :60.5   Max.   :28.9309      
#>  ErythemalDailyDose ErythemalDoseRate Irradiance305   Irradiance310   
#>  Min.   :347.0      Min.   :17.82     Min.   :3.471   Min.   : 9.188  
#>  1st Qu.:564.0      1st Qu.:28.88     1st Qu.:5.057   1st Qu.:14.752  
#>  Median :769.5      Median :38.68     Median :5.745   Median :18.863  
#>  Mean   :695.2      Mean   :35.32     Mean   :6.155   Mean   :17.745  
#>  3rd Qu.:836.6      3rd Qu.:42.68     3rd Qu.:7.869   3rd Qu.:21.571  
#>  Max.   :867.6      Max.   :44.34     Max.   :8.442   Max.   :22.666  
#>  Irradiance324    Irradiance380       UVindex      
#>  Min.   : 52.85   Min.   : 95.49   Min.   :0.7085  
#>  1st Qu.: 89.09   1st Qu.:170.28   1st Qu.:1.1526  
#>  Median :131.81   Median :263.52   Median :1.5431  
#>  Mean   :114.22   Mean   :231.07   Mean   :1.4099  
#>  3rd Qu.:135.12   3rd Qu.:278.49   3rd Qu.:1.7008  
#>  Max.   :151.29   Max.   :321.25   Max.   :1.7763