dapper.Domain¶

class dapper.Domain(name, mode, provided, support, cells, topounits=None, topounits_dim_name='topounit', topounits_id_col='topounit_id', topounits_gid_col='gid', met_support=None, topo_support=None, domain_nc=None, path_out=None, run_group=None)[source]¶

Bases: object

Canonical spatial object passed through the dapper pipeline.

Geometry views:

provided: exactly what the user supplied (provenance/plotting)
support : what sampling SHOULD use (may be simplified/processed later)
cells : what ELM RUNS on (site points now; per-cell geometries for cellset)

Prepared sampling views (set during the relevant pipeline step; not on init):

met_support
topo_support

Mode:

sites : one set of outputs per row (exporters loop internally)
cellset : one set of outputs total, including all rows

Parameters:

name (str)
mode (DomainMode)
provided (gpd.GeoDataFrame)
support (gpd.GeoDataFrame)
cells (gpd.GeoDataFrame)
topounits (gpd.GeoDataFrame | None)
topounits_dim_name (str)
topounits_id_col (str)
topounits_gid_col (str)
met_support (Optional[gpd.GeoDataFrame])
topo_support (Optional[gpd.GeoDataFrame])
domain_nc (Optional[Path])
path_out (Optional[Path])
run_group (Optional[str])

__init__(name, mode, provided, support, cells, topounits=None, topounits_dim_name='topounit', topounits_id_col='topounit_id', topounits_gid_col='gid', met_support=None, topo_support=None, domain_nc=None, path_out=None, run_group=None)¶

Parameters:

name (str)
mode (DomainMode)
provided (gpd.GeoDataFrame)
support (gpd.GeoDataFrame)
cells (gpd.GeoDataFrame)
topounits (gpd.GeoDataFrame | None)
topounits_dim_name (str)
topounits_id_col (str)
topounits_gid_col (str)
met_support (Optional[gpd.GeoDataFrame])
topo_support (Optional[gpd.GeoDataFrame])
domain_nc (Optional[Path])
path_out (Optional[Path])
run_group (Optional[str])

Return type:

None

Methods

`__init__`(name, mode, provided, support, cells)
`copy`(**updates)	Return a shallow copy of this Domain with updated fields.
`elm_latlon_layout`([decimals, use_lon_0360])	Compute lat/lon axes and a gid -> (iy, ix) index map for ELM-style lat/lon layouts.
`ensure_cells_lon_lat`()	Ensure `cells` contains `lon` and `lat` columns, derived from geometry if needed.
`ensure_output_dirs`(*[, met])	Create output directories implied by this Domain (and its runs, if mode='sites').
`export_domain`(*[, filename, out_dir, ...])	Export ELM domain NetCDF(s) for this Domain.
`export_landuse`(src_path, *[, filename, ...])	Export landuse timeseries NetCDF(s) for this Domain.
`export_met`(src_path, *, adapter[, out_dir, ...])	Export meteorological forcing NetCDF(s) for this Domain.
`export_surface`(src_path, *[, filename, ...])	Export surface NetCDF(s) for this Domain.
`from_elm_domain`(path_nc, *[, name, ...])	Build a Domain from an ELM domain NetCDF.
`from_file`(path, *[, name, layer, id_col, ...])	Load a geospatial file (e.g., GeoPackage, Shapefile) and construct a Domain.
`from_gdf`(gdf, **kwargs)	Alias for `Domain.from_provided()`.
`from_geometry`(geometry, *[, gid, name, ...])	Construct a single-feature Domain from a shapely geometry.
`from_provided`(provided, *[, name, mode, ...])	Construct a Domain from a provided geometry table.
`has_topounits`()	Return True if this Domain has a non-empty topounits table attached.
`iter_runs`()	Yield (run_id, run_domain) where run_domain is always a single-run 'cellset' Domain.
`make_topounits`(*, binning[, sources, ...])	Convenience wrapper that computes topounits for this Domain and returns a new Domain with domain.topounits attached.
`path_domain_nc`([filename, run_id])	Default output path for the domain NetCDF for this Domain (or a specific run_id).
`path_landuse_nc`([filename, run_id])	Default output path for the landuse NetCDF for this Domain (or a specific run_id).
`path_met_dir`([run_id])	Path to the MET output directory for this Domain (or a specific run_id).
`path_surface_nc`([filename, run_id])	Default output path for the surface NetCDF for this Domain (or a specific run_id).
`path_zone_mappings`([filename, run_id])	Default output path for `zone_mappings.txt` (under the MET directory).
`rep_points`(*[, source, step])	Representative points for a given geometry view.
`simplify_support`(tolerance_m, *, step[, ...])	Simplify the support geometry for a step and store it as met_support/topo_support.
`support_for`(*[, step])	Return the geometry set that should be used for the given step.
`to_df_loc`(*[, lon_col, lat_col, weight_col, ...])	Derived location/weight table from cells (internal glue; users shouldn't need to touch).
`topounits_for_gid`(gid)	Return the topounits subset for a single gid (or None if no topounits).
`with_step_support`(step, gdf)	Attach a step-specific support GeoDataFrame (for "met" or "topounits").
`with_topounits`(topounits, *[, id_col, ...])	Attach topounits GeoDataFrame to this Domain.

Attributes

`domain_nc`
`gdf`	Backwards-compat alias for older code.
`gids`	List of `gid` values (as strings) for the current cell table.
`group_name`	Name of the output group directory for this Domain.
`met_dir`	Convenience property for `Domain.path_met_dir()`.
`met_support`
`path_out`
`run_dir`	Directory holding the main run outputs for this Domain instance.
`run_group`
`topo_support`
`topounits`
`topounits_dim_name`
`topounits_gid_col`
`topounits_id_col`
`name`
`mode`
`provided`
`support`
`cells`

cells: gpd.GeoDataFrame¶

copy(**updates)[source]¶

Return a shallow copy of this Domain with updated fields.

Return type:: Domain

domain_nc: Optional[Path] = None¶

elm_latlon_layout(decimals=6, use_lon_0360=True)[source]¶

Compute lat/lon axes and a gid -> (iy, ix) index map for ELM-style lat/lon layouts. Useful mainly when your cells actually lie on a lat/lon lattice (dense or sparse).

Return type:

tuple[ndarray, ndarray, dict[str, tuple[int, int]]]

Parameters:

decimals (int)
use_lon_0360 (bool)

ensure_cells_lon_lat()[source]¶

Ensure cells contains lon and lat columns, derived from geometry if needed.

Return type:: Domain

ensure_output_dirs(*, met=True)[source]¶

Create output directories implied by this Domain (and its runs, if mode=’sites’). Does not write any files.

Return type:: None
Parameters:: met (bool)

export_domain(*, filename='domain.nc', out_dir=None, overwrite=False, append_attrs=None, **kwargs)[source]¶

Export ELM domain NetCDF(s) for this Domain.

Output layout:

mode=’cellset’: <run_dir>/domain.nc
mode=’sites’ : <run_dir>/<gid>/domain.nc

Return type:

dict[str, Path]

Returns:

dict[run_id, output_path]

Parameters:

filename (str)
out_dir (str | Path | None)
overwrite (bool)
append_attrs (dict | None)

export_landuse(src_path, *, filename='landuse_timeseries.nc', out_dir=None, overwrite=False, append_attrs=None, **kwargs)[source]¶

Export landuse timeseries NetCDF(s) for this Domain.

Return type:

dict[str, Path]

Parameters:

src_path (str | Path)
filename (str)
out_dir (str | Path | None)
overwrite (bool)
append_attrs (dict | None)

export_met(src_path, *, adapter, out_dir=None, filename=None, overwrite=False, append_attrs=None, pack_scope=None, **kwargs)[source]¶

Export meteorological forcing NetCDF(s) for this Domain.

Parameters:

src_path (Path-like) – Directory containing input CSV(s) for the adapter.
adapter (object) – Adapter instance implementing the met adapter protocol.
out_dir (Path-like, optional) – Override output root. Defaults to Domain.run_dir.
filename (str, optional) – Optional filename prefix for output NetCDFs. If provided, each var is written to ‘{filename}_{var}.nc’.
overwrite (bool) – If False, raises if MET output(s) already exist.
append_attrs (dict | None)

Return type:

dict[run_id, met_dir]

export_surface(src_path, *, filename='surfdata.nc', out_dir=None, overwrite=False, append_attrs=None, **kwargs)[source]¶

Export surface NetCDF(s) for this Domain.

Return type:

dict[str, Path]

Parameters:

src_path (str | Path)
filename (str)
out_dir (str | Path | None)
overwrite (bool)
append_attrs (dict | None)

classmethod from_elm_domain(path_nc, *, name=None, mask_name='mask', frac_name='frac', frac_threshold=0.0, path_out=None, run_group=None)[source]¶

Build a Domain from an ELM domain NetCDF. This naturally produces a ‘cellset’.

Return type:

Domain

Parameters:

path_nc (str | Path)
name (str | None)
mask_name (str)
frac_name (str)
frac_threshold (float)
path_out (str | Path | None)
run_group (str | None)

classmethod from_file(path, *, name=None, layer=None, id_col='gid', mode=None, cell_kind=None, path_out=None, run_group=None)[source]¶

Load a geospatial file (e.g., GeoPackage, Shapefile) and construct a Domain.

Return type:

Domain

Parameters:

path (str | Path)
name (str | None)
layer (str | None)
id_col (str)
mode (Literal['sites', 'cellset'] | None)
cell_kind (Literal['site_points', 'as_provided'] | None)
path_out (str | Path | None)
run_group (str | None)

classmethod from_gdf(gdf, **kwargs)[source]¶

Alias for Domain.from_provided().

Return type:: Domain
Parameters:: gdf (geopandas.GeoDataFrame | DataFrame)

classmethod from_geometry(geometry, *, gid='site', name='domain', mode='cellset', cell_kind='site_points', path_out=None, run_group=None)[source]¶

Construct a single-feature Domain from a shapely geometry.

Return type:

Domain

Parameters:

geometry (shapely.geometry.base.BaseGeometry)
gid (str)
name (str)
mode (Literal['sites', 'cellset'])
cell_kind (Literal['site_points', 'as_provided'])
path_out (str | Path | None)
run_group (str | None)

classmethod from_provided(provided, *, name='domain', mode=None, id_col='gid', support=None, cells=None, cell_kind=None, domain_nc=None, path_out=None, run_group=None)[source]¶

Construct a Domain from a provided geometry table.

The input can be a GeoDataFrame (preferred) or a DataFrame with a geometry column. Use mode to choose between a single-run cellset or a multi-run sites container. If cells is not provided, cells are derived from the provided/support geometry depending on cell_kind.

Return type:

Domain

Parameters:

provided (geopandas.GeoDataFrame | DataFrame)
name (str)
mode (Literal['sites', 'cellset'] | None)
id_col (str)
support (geopandas.GeoDataFrame | DataFrame | None)
cells (geopandas.GeoDataFrame | DataFrame | None)
cell_kind (Literal['site_points', 'as_provided'] | None)
domain_nc (str | Path | None)
path_out (str | Path | None)
run_group (str | None)

property gdf: geopandas.GeoDataFrame¶

Backwards-compat alias for older code.

Historically dapper exposed a single GeoDataFrame on the domain object (often a df_loc-style table with columns like gid/lon/lat/geometry). The closest equivalent is cells (the run-level geometry table).

property gids: list[str]¶: List of gid values (as strings) for the current cell table.

property group_name: str¶: Name of the output group directory for this Domain.

has_topounits()[source]¶

Return True if this Domain has a non-empty topounits table attached.

Return type:: bool

iter_runs()[source]¶: Yield (run_id, run_domain) where run_domain is always a single-run ‘cellset’ Domain. - mode=’cellset’ -> yields exactly one run (self) - mode=’sites’ -> yields one run per gid (single-row Domains)

make_topounits(*, binning, sources=None, combine='cartesian', combine_order=None, max_topounits=256, dem_source='arcticdem', export_scale='native', min_patch_pixels=None, target_pixels_per_topounit=500, target_scale=None, verbose=False, allow_slow_ncells=25)[source]¶

Convenience wrapper that computes topounits for this Domain and returns a new Domain with domain.topounits attached.

If this Domain has multiple rows (cellset/sites), it computes topounits per-row (per gid) using dapper.topounit.topomake.make_topounits_for_domain.
If this Domain has one row, it still goes through the same path (safe + consistent).

Users should not need to deal with ee.Geometry vs ee.Feature vs FeatureCollection here.

Return type:

Domain

Parameters:

binning (dict)
sources (list[str] | None)
combine (str)
max_topounits (int)
dem_source (str)
export_scale (str)
target_pixels_per_topounit (int)
target_scale (float | None)
verbose (bool)
allow_slow_ncells (int)

property met_dir: Path¶: Convenience property for Domain.path_met_dir().

met_support: Optional[gpd.GeoDataFrame] = None¶

mode: DomainMode¶

name: str¶

path_domain_nc(filename='domain.nc', run_id=None)[source]¶

Default output path for the domain NetCDF for this Domain (or a specific run_id).

Return type:

Path

Parameters:

filename (str)
run_id (str | None)

path_landuse_nc(filename='landuse_timeseries.nc', run_id=None)[source]¶

Default output path for the landuse NetCDF for this Domain (or a specific run_id).

Return type:

Path

Parameters:

filename (str)
run_id (str | None)

path_met_dir(run_id=None)[source]¶

Path to the MET output directory for this Domain (or a specific run_id).

Return type:: Path
Parameters:: run_id (str | None)

path_out: Optional[Path] = None¶

path_surface_nc(filename='surfdata.nc', run_id=None)[source]¶

Default output path for the surface NetCDF for this Domain (or a specific run_id).

Return type:

Path

Parameters:

filename (str)
run_id (str | None)

path_zone_mappings(filename='zone_mappings.txt', run_id=None)[source]¶

Default output path for zone_mappings.txt (under the MET directory).

Return type:

Path

Parameters:

filename (str)
run_id (str | None)

provided: gpd.GeoDataFrame¶

rep_points(*, source='support', step=None)[source]¶

Representative points for a given geometry view. If source=’support’ and step is provided, uses the prepared support for that step.

Return type:

GeoDataFrame

Parameters:

source (Literal['provided', 'support', 'cells'])
step (Literal['met', 'topounits'] | None)

property run_dir: Path¶

Directory holding the main run outputs for this Domain instance.

For top-level cellset or top-level sites container:: path_out/<group_name>
For per-site/per-cellset run domains (created by iter_runs in sites mode):: path_out/<group_name>/<domain.name>

run_group: Optional[str] = None¶

simplify_support(tolerance_m, *, step, preserve_topology=True, equal_area_epsg=6933)[source]¶

Simplify the support geometry for a step and store it as met_support/topo_support. Does NOT modify provided/support/cells.

Return type:

Domain

Parameters:

tolerance_m (float)
step (Literal['met', 'topounits'])
preserve_topology (bool)
equal_area_epsg (int)

support: gpd.GeoDataFrame¶

support_for(*, step=None)[source]¶

Return the geometry set that should be used for the given step. - step=None -> support - step=”met” -> met_support if set else support - step=”topounits” -> topo_support if set else support

Return type:: GeoDataFrame
Parameters:: step (Literal['met', 'topounits'] | None)

to_df_loc(*, lon_col='lon', lat_col='lat', weight_col='weight', frac_col='frac', default_weight=1.0)[source]¶

Derived location/weight table from cells (internal glue; users shouldn’t need to touch).

Return type:

DataFrame

Parameters:

lon_col (str)
lat_col (str)
weight_col (str)
frac_col (str)
default_weight (float)

topo_support: Optional[gpd.GeoDataFrame] = None¶

topounits: gpd.GeoDataFrame | None = None¶

topounits_dim_name: str = 'topounit'¶

topounits_for_gid(gid)[source]¶

Return the topounits subset for a single gid (or None if no topounits).

Parameters:: gid (str)

topounits_gid_col: str = 'gid'¶

topounits_id_col: str = 'topounit_id'¶

with_step_support(step, gdf)[source]¶

Attach a step-specific support GeoDataFrame (for “met” or “topounits”).

Return type:

Domain

Parameters:

step (Literal['met', 'topounits'])
gdf (geopandas.GeoDataFrame)

with_topounits(topounits, *, id_col='band_name', gid_col='gid', dim_name='topounit')[source]¶

Attach topounits GeoDataFrame to this Domain. - Ensures a stable id column name (self.topounits_id_col == ‘topounit_id’) - Ensures gid linkage column exists (self.topounits_gid_col)

Return type:

Domain

Parameters:

topounits (geopandas.GeoDataFrame)
id_col (str)
gid_col (str)
dim_name (str)