gdalxarray passes the string you give it to GDAL unchanged, so everything GDAL’s virtual file systems and connection strings can express is available without any code in gdalxarray. This page walks through the common ones using three days of real NOAA OISST v2.1 sea surface temperature kept with this repository, so it runs anywhere.
Data: NOAA 0.25-degree Daily Optimum Interpolation Sea Surface Temperature (OISST), Version 2.1; doi:10.25921/RE9P-PT57; licence: CC0-1.0; days 20250101, 20250102, 20250103. Built by scripts/fixtures/make_oisst.py; details in docs/fixtures/oisst/provenance.json.
| Prefix or syntax | What it does |
|---|---|
/vsicurl/<url> |
HTTP(S) range requests |
/vsis3/<bucket>/<key>, /vsigs/, /vsiaz/ |
object stores (anonymous with AWS_NO_SIGN_REQUEST=YES) |
/vsizip/<zip>/<member> |
a member of a zip, which can itself be remote |
ZARR:"<store>":/<array>[:i:j] |
one array of a Zarr store, optionally a 2D slice of it |
NETCDF:"<file>":<var> |
one variable of a netCDF as a classic raster |
vrt://<path>?<options> |
an inline VRT: resize, subset, assign a CRS, pick bands |
A local directory, the same directory with the explicit ZARR: prefix, and the same store over HTTPS (this repository on GitHub, at the commit that last changed it) all give the same Dataset:
rel = "oisst/oisst.zarr"
addresses = {
"local": data(rel),
"ZARR: local": f'ZARR:"{data(rel)}"',
"ZARR: /vsicurl/": f'ZARR:"{data(rel, remote=True)}"',
}
addresses["ZARR: /vsicurl/"]'ZARR:"/vsicurl/https://raw.githubusercontent.com/hypertidy/gdalxarray/b3f2245ca62573ca5eba60b942404afbfe83f497/docs/fixtures/oisst/oisst.zarr"'opened = {k: xr.open_dataset(v, engine="gdalxarray") for k, v in addresses.items()}
ref = opened["local"]["sst"].isel(time=1).values
{k: bool(np.array_equal(d["sst"].isel(time=1).values, ref, equal_nan=True)) for k, d in opened.items()}{'local': True, 'ZARR: local': True, 'ZARR: /vsicurl/': True}For a remote Zarr the ZARR: prefix is not optional. A web server has no directory listing to sniff, so a bare /vsicurl/.../store.zarr does not identify as anything:
try:
xr.open_dataset(data(rel, remote=True), engine="gdalxarray")
except Exception as e:
print(type(e).__name__, str(e).splitlines()[0][:100])RuntimeError HTTP response code: 404 - Failure writing output to destination, passed 14 returned 0For the same reason, a Zarr v3 store meant to be read over HTTP needs consolidated metadata (a consolidated_metadata entry in its root zarr.json, which xarray writes with to_zarr(..., consolidated=True)). Without it the store still opens, but with no arrays in it, because there is no listing to find them by.
Over /vsicurl/, also set GDAL_DISABLE_READDIR_ON_OPEN=EMPTY_DIR so GDAL does not try to list what is really a web server. This site sets it for every page.
ZARR:"store":/array:i:j fixes the leading dimensions of an array to indices i, j, leaving a 2D raster that classic tools understand. Here sst is (time, zlev, lat, lon), and :2:0 picks the third day:
face = xr.open_dataset(f'ZARR:"{data(rel)}":/sst:2:0', engine="gdalxarray", multidim=False)
face["band_data"].dims, face["band_data"].shape(('band', 'y', 'x'), (1, 720, 1440))The stored values are identical to the multidim read of the same day:
raw_face = xr.open_dataset(f'ZARR:"{data(rel)}":/sst:2:0', engine="gdalxarray",
multidim=False, mask_and_scale=False)["band_data"].values[0]
raw_md = xr.open_dataset(data(rel), engine="gdalxarray",
mask_and_scale=False)["sst"].isel(time=2, zlev=0).values
assert np.array_equal(raw_face, raw_md)
bool(np.array_equal(raw_face, raw_md))Truebut the two models can disagree on the fill value. A Zarr v3 array has two places for one: the Zarr-level fill_value in its metadata, and a CF _FillValue among its attributes. Here is what xarray wrote for sst, OISST’s own packing being int16 with a -999 fill:
meta = data_json(f"{rel}/sst/zarr.json")
{"zarr fill_value": meta["fill_value"], "CF _FillValue": meta["attributes"].get("_FillValue")}{'zarr fill_value': 0, 'CF _FillValue': -999}GDAL reports the Zarr-level value as the band or array nodata; gdalxarray’s multidim path prefers the CF attribute, and the classic path has only GDAL’s band value to go on:
{"classic": face["band_data"].encoding.get("_FillValue"),
"multidim": opened["local"]["sst"].encoding.get("_FillValue")}{'classic': 0.0, 'multidim': -999}So with mask-and-scale decoding on, the classic face masks 0 rather than -999: on this data, land cells (stored as -999) come through as -9.99 degrees, and real water at exactly 0 degrees is masked. Pass mask_and_scale=False and decode yourself, or prefer the multidim read, for stores written this way.
One of the daily OISST netCDF files, exactly as NOAA publishes it, can be opened as a multidimensional dataset, or one variable as a classic raster with NETCDF::
nc = data("oisst/" + data_json("oisst/provenance.json")["sources"][0]["file"])
md = xr.open_dataset(nc, engine="gdalxarray")
cl = xr.open_dataset(f'NETCDF:"{nc}":sst', engine="gdalxarray", multidim=False)
md["sst"].dims, cl["band_data"].dims(('time', 'zlev', 'lat', 'lon'), ('band', 'y', 'x'))The two models differ in one way worth knowing: classic mode presents the raster north-up (GDAL flips a south-up netCDF to give a conventional geotransform), while multidim keeps the storage order.
fig, axs = plt.subplots(1, 2, figsize=(10, 2.8), layout="constrained")
axs[0].imshow(md["sst"].isel(time=0, zlev=0).values, cmap="RdYlBu_r")
axs[0].set_title(f"multidim: lat[0] = {float(md.lat[0])}")
axs[1].imshow(cl["band_data"].isel(band=0).values, cmap="RdYlBu_r")
axs[1].set_title(f"classic: y[0] = {float(cl.y[0])}")
for ax in axs:
ax.set_xticks([]); ax.set_yticks([])
plt.show()
assert np.array_equal(md["sst"].isel(time=0, zlev=0).values[::-1],
cl["band_data"].isel(band=0).values, equal_nan=True)vrt://vrt:// wraps a source in a VRT built from URL-style options, no XML needed. A quarter-size average, and a window by coordinates:
cog = fixture("cog/world-int16-deflate.tif")
full = xr.open_dataset(cog, engine="gdalxarray", multidim=False)
small = xr.open_dataset(f"vrt://{cog}?outsize=25%,25%&r=average", engine="gdalxarray", multidim=False)
win = xr.open_dataset(f"vrt://{cog}?projwin=100,-10,160,-50", engine="gdalxarray", multidim=False)
{k: d["band_data"].shape for k, d in dict(full=full, small=small, window=win).items()}{'full': (1, 360, 720), 'small': (1, 90, 180), 'window': (1, 80, 120)}fig, axs = plt.subplots(1, 3, figsize=(12, 3), layout="constrained",
gridspec_kw=dict(width_ratios=[2, 2, 1]))
for ax, (name, d) in zip(axs, dict(full=full, small=small, window=win).items()):
d["band_data"].isel(band=0).plot(ax=ax, add_colorbar=False, cmap="cividis")
ax.set_title(f"{name} {d['band_data'].shape[1:]}")
plt.show()
The window keeps real coordinates, so it lines up with the full raster:
assert np.array_equal(win["band_data"].values,
full["band_data"].sel(x=win.x, y=win.y, method="nearest").values)/vsizip/ reads a member of a zip without unpacking it, and the zip can be on a server (/vsizip//vsicurl/https://...). Here the zip is built in memory:
buf = io.BytesIO()
with zipfile.ZipFile(buf, "w") as z:
z.write(nc, "day1.nc")
gdal.FileFromMemBuffer("/vsimem/days.zip", buf.getvalue())
zipped = xr.open_dataset("/vsizip//vsimem/days.zip/day1.nc", engine="gdalxarray")
bool(np.array_equal(zipped["sst"].values, md["sst"].values, equal_nan=True))TrueThe OISST gallery page uses the remote form: a zipped multidimensional VRT on GitHub releases describing 45 years of daily files on AWS.