dapper.topounit package

Submodules

dapper.topounit.topomake module

Topographic unit generation utilities.

dapper.topounit.topomake.add_topounit_image_samples(topounits_gdf, sampling_specs, default_scale=None, ensure_pixel_centers=True, verbose=False)

Attach additional sampled properties from arbitrary GEE images to each topounit.

Parameters:

• topounits_gdf (GeoDataFrame) – Output from make_topounits(return_as=’gdf’). Must contain ‘band_name’.

• sampling_specs (list[dict]) –

  Each dict describes one sampled variable with keys:

  • ’image’ : ee.Image or image ID string

  • ’band’ : optional band name (if omitted, image must be single-band)

  • ’reducer’ : str {‘mean’,’min’,’max’,’std’} or ee.Reducer

  • ’out_name’: name of the column to add

  • ’scale’ : optional scale [m]; overrides default_scale

• default_scale (float, optional) – Default scale [m] for specs that do not define ‘scale’. If None, uses topounits_gdf[‘analysis_scale_m’].iloc[0] if present; otherwise the nominal scale of each image.

• ensure_pixel_centers (bool, default True) – If True, guard against polygons with no pixel centers.

• verbose (bool, default False) – Print which variables were attached.

Returns:

Copy of topounits_gdf with new columns added.

Return type:

GeoDataFrame

dapper.topounit.topomake.build_bins_for_source(source_id, image, region, binning_spec, analysis_scale, aspect_ranges_default=None)

Produces a list of bin definitions for a source. Numeric sources (elev, hand): [{‘id’, ‘low’, ‘high’, ‘label’, ‘method’, ‘units’}] Aspect (circular): [{‘id’,’start’,’end’,’wrap’,’label’,’method’,’units’}]

dapper.topounit.topomake.build_source(source_id, feature, desired_scale_hint, binning_spec, dem_source='arcticdem', verbose=False)

Returns (single-band ee.Image renamed to ‘v’, native_scale_m, meta dict).

Built-in source_ids:

• ‘elev’ : ArcticDEM elevation (meters)

• ‘hand’ : multi-scale HAND auto-selection (meters)

• ‘aspect’ : Aspect (degrees) derived from DEM

• ‘cti’ : Compound Topographic Index (dimensionless), mosaicked & scaled

Custom image:

If binning[source_id] contains key ‘image’, that value MUST be a single-band ee.Image (already mosaicked/selected/masked as needed). We validate single-band and use it. If the image advertises a degree-based/undefined native scale (~111,319 m), we coerce the native scale to desired_scale_hint (if provided) or 90 m to avoid over-clamping.

dapper.topounit.topomake.choose_hand_image(desired_scale=None, hand_edges=None, verbose=False)

Auto-select among available HAND products based on a desired scale (m) and/or fixed edges. If edges extend >100 m, prefer *_1000 variants. Returns (hand_image_single_band, native_scale_m).

dapper.topounit.topomake.make_topounits(aoi, sources=None, binning=None, combine='cartesian', combine_order=None, max_topounits=256, dem_source='arcticdem', return_as='gdf', export_scale='native', asset_name='topounits', asset_ftype='GeoJSON', min_patch_pixels=None, target_pixels_per_topounit=500, target_scale=None, verbose=False)

SINGLE-AOI topounit builder.

aoi can be:

• Domain (must have exactly 1 geometry in domain.support / domain.gdf)

• shapely geometry

• ee.Geometry / ee.Feature / ee.FeatureCollection

• str (GEE FeatureCollection asset id)

If sources is None, sources = list(binning.keys()) (dict insertion order).

dapper.topounit.topomake.make_topounits_for_domain(domain, *, sources, binning, 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)

Compute topounits per-domain-geometry and attach them to the Domain.

• For domain.mode == ‘sites’: this computes per-run (each run is 1 geom) and returns a Domain with a concatenated topounits table; iter_runs() can later subset by gid.

• For domain.mode == ‘cellset’: loops over each cell geometry and computes topounits for each gid separately (can be slow for large N).

Returns:

domain with domain.topounits populated (expects Domain.with_topounits exists).

Return type:

Domain

Parameters:

• domain (Domain)

• allow_slow_ncells (int)

dapper.topounit.topoplot module

Plotting utilities for topounits and domains.

dapper.topounit.topoplot.plot_interactive(gdf, tiles='CartoDB positron', tooltip_cols=('legend_label', 'area_km2', 'band_name', 'analysis_scale_m'), style_kwds=None)

Interactive Folium map. Returns a folium.Map.

Parameters:

• gdf (geopandas.GeoDataFrame)

• tiles (str)

dapper.topounit.topoplot.plot_static(gdf, basemap='positron', figsize=(10, 10), alpha=0.6, edgecolor='black', linewidth=0.7, legend=True, cmap=None, ax=None)

Static plot with contextily basemap. basemap options: ‘positron’, ‘dark’, ‘osm’, ‘terrain’, ‘satellite’ If ax is provided, draw into that axes (and do not create a new figure).

Parameters:

• gdf (geopandas.GeoDataFrame)

• basemap (str)

• alpha (float)

• edgecolor (str)

• linewidth (float)

• legend (bool)

dapper.topounit.topoplot.prepare_for_plot(gdf, area_epsg=3857, area_col='area_km2', ndigits_numeric=0, order=None)

Return type:

GeoDataFrame

Parameters:

• gdf (geopandas.GeoDataFrame)

• area_epsg (int)

• area_col (str)

• ndigits_numeric (int)

• order (list[str] | None)

Returns a copy with:

• legend_label: pretty combined label for legend/coloring

• area_km2: polygon area (in km²) computed in a projected CRS (default EPSG:3857)

Module contents

dapper module: topounit.__init__.