xrspatial.templates.from_template#

xrspatial.templates.from_template(name, resolution=None, *, preserve=None, backend='numpy', fill=nan, chunks='auto')[source]#

Create an empty DataArray for a common study area.

The returned raster is NaN-filled and obeys the xarray-spatial array contract: a 2-D ['y', 'x'] grid with pixel-center 1-D coordinates (north-up, descending y) and res/crs attributes. It covers the study area’s rectangular bounding box and is meant as a starting canvas.

The requested resolution is honored exactly. The study-area box is rarely a whole number of cells wide, so the far edges (right, top) are nudged out by up to half a cell to land on an exact multiple of the cell size, anchoring the lower-left corner. attrs['res'] therefore matches the resolution you pass.

Parameters:

  • name (str) – A curated region name (case-insensitive), e.g. 'conus', 'nyc', 'europe', 'world'; a world-city name (case-insensitive), e.g. 'london', 'tokyo', 'sao_paulo'; or an ISO-3166 / GADM alpha-3 country code, e.g. 'USA', 'FRA', 'JPN'. Curated regions and cities come back in a projected CRS (cities in their UTM zone); country codes come back in EPSG:4326. Where two cities share a name the larger keeps the bare name and the others take a _<iso2> suffix (e.g. 'hyderabad' vs 'hyderabad_pk').

  • resolution (float or tuple of float, optional) – Cell size in the template’s CRS units (metres for projected regions, degrees for country codes). A scalar gives square cells; a (res_x, res_y) tuple sets each axis. Defaults to a per-template value so a bare from_template('conus') works.

  • preserve ({'area', 'shape'}, optional) – Reproject the template into an EPSG-coded projection chosen for the property it preserves, instead of the template’s default CRS. 'area' gives an equal-area projection (a curated national/continental code such as EPSG:5070, or EPSG:8857 Equal Earth where none is curated). 'shape' gives a conformal projection: the centroid’s UTM zone (UPS at the poles). When set, resolution is in metres and attrs['crs'] is the chosen EPSG int. Requires pyproj.

  • backend (str, default='numpy') – Array backend: 'numpy', 'dask+numpy' (alias 'dask'), 'cupy', or 'dask+cupy'.

  • fill (float, default=numpy.nan) – Value the grid is filled with. The dtype is always float32.

  • chunks (int, str, or tuple, default='auto') – Dask chunk specification; only used by the dask backends.

Returns:

template – Empty 2-D raster with dims=('y', 'x') and pixel-center coordinates. attrs carries res and crs plus the CF Conventions grid-mapping keys grid_mapping_name (the projection token, e.g. 'albers_conical_equal_area') and crs_wkt (full WKT, which carries the human-readable CRS name). The x / y coordinates follow CF axis conventions: units 'm' with standard_name 'projection_x_coordinate' / 'projection_y_coordinate' for projected templates, or 'degrees_east' / 'degrees_north' with standard_name 'longitude' / 'latitude' for EPSG:4326. The grid-mapping keys require pyproj; without it they are omitted (the default, dependency-free path), and grid_mapping_name is also omitted for projections CF does not define (e.g. Equal Earth), leaving crs_wkt alone. These keys sit directly on attrs (the library’s flat CRS convention), not on a separate CF grid-mapping variable, so a strict CF reader will not auto-detect them as a grid mapping.

Return type:

xarray.DataArray

Examples

>>> from xrspatial import from_template
>>> agg = from_template("conus")            # Albers, default 5 km cells
>>> agg.attrs["crs"]
5070
>>> agg = from_template("conus", resolution=1000)   # 1 km cells
>>> agg = from_template("FRA")              # France bbox in EPSG:4326
>>> agg.attrs["crs"]
4326
>>> from_template("london").attrs["crs"]    # greater London, UTM 30N
32630
>>> from_template("FRA", preserve="shape").attrs["crs"]   # UTM 31N
32631
>>> from_template("FRA", preserve="area").attrs["crs"]    # Equal Earth
8857