Read NetCDF into stars object

Source: R/ncdf.R

Read data from a file (or source) using the NetCDF library directly.

read_ncdf(
  .x,
  ...,
  var = NULL,
  ncsub = NULL,
  curvilinear = character(0),
  eps = 1e-12,
  ignore_bounds = FALSE,
  make_time = TRUE,
  make_units = TRUE
)

Arguments

.x

NetCDF file or source
...

ignored
var

variable name or names (they must be on matching grids)
ncsub

matrix of start, count columns (see Details)
curvilinear

length two character named vector with names of variables holding longitude and latitude values for all raster cells. `stars` attempts to figure out appropriate curvilinear coordinates if they are not supplied.
eps

numeric; dimension value increases are considered identical when they differ less than eps
ignore_bounds

logical; should bounds values for dimensions, if present, be ignored?
make_time

if TRUE (the default), an atttempt is made to provide a date-time class from the "time" variable
make_units

if TRUE (the default), an attempt is made to set the units property of each variable

Details

The following logic is applied to coordinates. If any coordinate axes have regularly spaced coordinate variables they are reduced to the offset/delta form with 'affine = c(0, 0)', otherwise the values of the coordinates are stored and used to define a rectilinear grid.

If the data has two or more dimensions and the first two are regular they are nominated as the 'raster' for plotting.

If the curvilinear argument is used it specifies the 2D arrays containing coordinate values for the first two dimensions of the data read. It is currently assumed that the coordinates are 2D and that they relate to the first two dimensions in that order.

If var is not set the first set of variables on a shared grid is used.

start and count columns of ncsub must correspond to the variable dimemsion (nrows) and be valid index using var.get.nc convention (start is 1-based). If the count value is NA then all steps are included. Axis order must match that of the variable/s being read.

Examples

f <- system.file("nc/reduced.nc", package = "stars")
read_ncdf(f)

#> no 'var' specified, using sst, anom, err, ice
#> other available variables:
#>  lon, lat, zlev, time
#> No projection information found in nc file. 
#>  Coordinate variable units found to be degrees, 
#>  assuming WGS84 Lat/Lon.
#> stars object with 4 dimensions and 4 attributes
#> attribute(s):
#>     sst [°C]       anom [°C]         err [°C]     ice [percent]  
#>  Min.   :-1.80   Min.   :-7.950   Min.   :0.110   Min.   :0.010  
#>  1st Qu.:-0.03   1st Qu.:-0.580   1st Qu.:0.160   1st Qu.:0.470  
#>  Median :13.65   Median :-0.080   Median :0.270   Median :0.920  
#>  Mean   :12.99   Mean   :-0.185   Mean   :0.263   Mean   :0.718  
#>  3rd Qu.:24.81   3rd Qu.: 0.210   3rd Qu.:0.320   3rd Qu.:0.960  
#>  Max.   :32.97   Max.   : 2.990   Max.   :0.840   Max.   :1.000  
#>  NA's   :4448    NA's   :4449     NA's   :4448    NA's   :13266  
#> dimension(s):
#>      from  to offset delta  refsys point         values x/y
#> lon     1 180     -1     2  WGS 84    NA           NULL [x]
#> lat     1  90    -90     2  WGS 84    NA           NULL [y]
#> zlev    1   1     NA    NA      NA    NA              0    
#> time    1   1     NA    NA POSIXct    NA 1981-12-31 UTC    
read_ncdf(f, var = c("anom"))

#> No projection information found in nc file. 
#>  Coordinate variable units found to be degrees, 
#>  assuming WGS84 Lat/Lon.
#> stars object with 4 dimensions and 1 attribute
#> attribute(s):
#>    anom [°C]     
#>  Min.   :-7.950  
#>  1st Qu.:-0.580  
#>  Median :-0.080  
#>  Mean   :-0.185  
#>  3rd Qu.: 0.210  
#>  Max.   : 2.990  
#>  NA's   :4449    
#> dimension(s):
#>      from  to offset delta  refsys point         values x/y
#> lon     1 180     -1     2  WGS 84    NA           NULL [x]
#> lat     1  90    -90     2  WGS 84    NA           NULL [y]
#> zlev    1   1     NA    NA      NA    NA              0    
#> time    1   1     NA    NA POSIXct    NA 1981-12-31 UTC    
read_ncdf(f, ncsub = cbind(start = c(1, 1, 1, 1), count = c(10, 12, 1, 1)))

#> no 'var' specified, using sst, anom, err, ice
#> other available variables:
#>  lon, lat, zlev, time
#> No projection information found in nc file. 
#>  Coordinate variable units found to be degrees, 
#>  assuming WGS84 Lat/Lon.
#> stars object with 4 dimensions and 4 attributes
#> attribute(s):
#>     sst [°C]        anom [°C]           err [°C]     ice [percent]   
#>  Min.   :-1.390   Min.   :-1.07000   Min.   :0.300   Min.   :0.0100  
#>  1st Qu.:-0.720   1st Qu.:-0.36250   1st Qu.:0.300   1st Qu.:0.1100  
#>  Median :-0.515   Median : 0.19500   Median :0.300   Median :0.1700  
#>  Mean   :-0.534   Mean   : 0.05867   Mean   :0.303   Mean   :0.2094  
#>  3rd Qu.:-0.275   3rd Qu.: 0.55500   3rd Qu.:0.300   3rd Qu.:0.2550  
#>  Max.   : 0.030   Max.   : 0.92000   Max.   :0.320   Max.   :0.5200  
#>  NA's   :90       NA's   :90         NA's   :90      NA's   :104     
#> dimension(s):
#>      from to offset delta  refsys point         values x/y
#> lon     1 10     -1     2  WGS 84    NA           NULL [x]
#> lat     1 12    -90     2  WGS 84    NA           NULL [y]
#> zlev    1  1     NA    NA      NA    NA              0    
#> time    1  1     NA    NA POSIXct    NA 1981-12-31 UTC    


#' precipitation data in a curvilinear NetCDF
prec_file = system.file("nc/test_stageiv_xyt.nc", package = "stars")
prec = read_ncdf(prec_file, curvilinear = c("lon", "lat"), ignore_bounds = TRUE)

#> no 'var' specified, using Total_precipitation_surface_1_Hour_Accumulation
#> other available variables:
#>  time_bounds, lon, lat, time
#> No projection information found in nc file. 
#>  Coordinate variable units found to be degrees, 
#>  assuming WGS84 Lat/Lon.

##plot(prec) ## gives error about unique breaks
## remove NAs, zeros, and give a large number
## of breaks (used for validating in detail)
qu_0_omit = function(x, ..., n = 22) {
  x = units::drop_units(na.omit(x))
  c(0, quantile(x[x > 0], seq(0, 1, length.out = n)))
}
library(dplyr)
prec_slice = slice(prec, index = 17, along = "time")
plot(prec_slice, border = NA, breaks = qu_0_omit(prec_slice[[1]]), reset = FALSE)

nc = sf::read_sf(system.file("gpkg/nc.gpkg", package = "sf"), "nc.gpkg")
plot(st_geometry(nc), add = TRUE, reset = FALSE, col = NA)