Exactly one of dsn, builder, object must be supplied.
Usage
# S4 method for class 'XarrayDriver'
dbConnect(
drv,
dsn = NULL,
...,
open = "open_dataset",
builder = NULL,
object = NULL
)Arguments
- drv
result of
xarray()- dsn
character string openable by xarray
- ...
keyword arguments passed to the xarray open function
- open
name of the xarray open function, default "open_dataset"
- builder
function taking the xarray module, returning a Dataset
- object
an existing Python xarray object to adopt
Details
dsn: a string that xarray can open. Passed toxr.<open>(dsn, ...)whereopenis"open_dataset"by default (also useful:"open_zarr", which defaults to dask, so passchunks = reticulate::py_none()for the lazy path;"open_mfdataset", which needs dask,reticulate::py_require("dask"); and"open_datatree"). Extra named arguments in...are passed through as Python keyword arguments, e.g.engine = "h5netcdf",decode_times = TRUE, orchunks = reticulate::dict()(Pythonchunks={}: dask at the storage chunking; an Rlist()would become a Python list).engine = "gdalxarray"opens anything GDAL reads (it needs the GDAL Python bindings; see xrdbi-package). It uses GDAL's multidimensional API by default;multidim = FALSEuses the classic raster API, where a GeoTIFF or COG becomes one variable,band_data, over (band, y, x).builder: an R function of one argument (the xarray module, not converted) returning a Dataset. Use this when construction needs more than a single open call, e.g. virtualizarr or icechunk session setup.object: an existing reticulate Python object (an xarray Dataset), adopted as-is. Handy when the object was built interactively withreticulate::py_run_string()or in a repl.
The connection holds a reference to the Python object. Opening reads metadata; data are read when a result is fetched (see XarrayResult for statements that compute).
See also
XarrayConnection for what a connection offers; XarrayResult to query it with Python statements; tbl() to query it with dplyr verbs; the Python requirements in xrdbi-package for the engines a source needs.
Examples
if (FALSE) { # \dontrun{
## needs a Python environment with xarray (see ?xrdbi)
f <- system.file("extdata/autotest/trmm.nc", package = "xrdbi")
con <- dbConnect(xarray(), f)
## anything that takes more than one call
con <- dbConnect(xarray(), builder = function(xr) {
xr$open_dataset(f)$rename(list(pcp = "precip"))
})
dbListTables(con)
## many files as one dataset (open_mfdataset needs dask)
reticulate::py_require("dask")
files <- c(f, f) # e.g. a daily series of files on one grid
con <- dbConnect(xarray(), builder = function(xr) {
xr$open_mfdataset(files, combine = "nested", concat_dim = "run")
})
## an object already built in the session
reticulate::py_run_string("import xarray; myds = xarray.Dataset()")
con <- dbConnect(xarray(), object = reticulate::py_eval("myds", convert = FALSE))
} # }