% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ncdf.R
\name{read_ncdf}
\alias{read_ncdf}
\title{Read NetCDF into stars object}
\usage{
read_ncdf(
  .x,
  ...,
  var = NULL,
  ncsub = NULL,
  curvilinear = character(0),
  eps = sqrt(.Machine$double.eps),
  ignore_bounds = FALSE,
  make_time = TRUE,
  make_units = TRUE,
  proxy = NULL,
  downsample = 0
)
}
\arguments{
\item{.x}{NetCDF file or source as a character vector or an nc_proxy object.}

\item{...}{ignored}

\item{var}{variable name or names (they must be on matching grids)}

\item{ncsub}{matrix of start, count columns (see Details)}

\item{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.}

\item{eps}{numeric; dimension value increases are considered identical when they differ less than \code{eps}}

\item{ignore_bounds}{logical; should bounds values for dimensions, if present, be ignored?}

\item{make_time}{if \code{TRUE} (the default), an attempt is made to provide
a CFTime class for any "time" dimension.}

\item{make_units}{if \code{TRUE} (the default), an attempt is made to set the units property of each variable}

\item{proxy}{logical; if \code{TRUE}, an object of class \code{stars_proxy} is read which contains array
metadata only; if \code{FALSE} the full array data is read in memory. If not set, defaults to \code{TRUE}
when the number of cells to be read is larger than \code{options(stars.n_proxy)}, or to 1e8 if that option was not set.}

\item{downsample}{integer; number of cells to omit between samples along each dimension. 
e.g. \code{c(1,1,2)} would return every other cell in x and y and every third cell
in the third dimension (z or t). If 0, no downsampling is applied. Note that this transformation
is applied AFTER NetCDF data are read using st_downsample. As such, if proxy=TRUE, this 
option is ignored.}
}
\description{
Read data from a file (or source) using the NetCDF library directly.
}
\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 \code{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.

Any time dimension in the source is captured in a 'CFTime' object, unless the
\code{make_time} argument is false. In that case, the numeric offsets 
representing time are returned instead.


If \code{var} is not set the first set of variables on a shared grid is used.

\code{start} and \code{count} columns of ncsub must correspond to the variable dimension (nrows)
and be valid index using \code{\link[RNetCDF]{var.get.nc}} convention (start is 1-based). If the count value
is \code{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")
if (require(ncmeta, quietly = TRUE)) {
 read_ncdf(f)
 read_ncdf(f, var = c("anom"))
 read_ncdf(f, ncsub = cbind(start = c(1, 1, 1, 1), count = c(10, 12, 1, 1)))
}

\donttest{
if (require(ncmeta, quietly = TRUE)) {
 #' 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)
}

##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)))
}
if (require(dplyr, quietly = TRUE)) {
  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)
}
} # donttest
}
