apbase.mapping

Primary automatic map-generation API.

Use apbase.mapping.Map as the main entry point when you want APbase to choose the interpolation strategy automatically. It runs filtering, boundary/grid generation, one shared variogram fit, IDW-vs-kriging cross-validation, model selection by validation error, and final interpolation. Use apbase.mapping.create_map() when a functional one-shot call is more convenient.

Each public callable below documents its inputs, defaults, return value, and usage examples from the source docstring.

apbase.mapping.create_map(x, y, z, *, resolution, filter=True, bounds=None, geographic_mode=None, power=2.0, max_neighbors=40, min_neighbors=3, max_cv_points=500, seed=None, filter_kwargs=None)

Functional shortcut for the automatic Map pipeline.

Filters, cross-validates, and interpolates x, y, z into a map. Picks IDW or ordinary kriging automatically via select_best_model() on the leave-one-out results from cross_validate(), then interpolates onto a regular grid built from bounds (or a concave hull inferred from x/y when omitted).

By default (geographic_mode=None), x/y are checked automatically (apbase.common.coordinates.guess_xy_coordinate_system()): already projected/metric input is used as-is, with no CRS conversion – the same behavior as before. Geographic (lon/lat) input is detected and handled automatically instead: it – and bounds, when given – is converted to metric coordinates internally (apbase.common.coordinates.prepare_metric_xy(), which itself auto-picks "local" vs "utm" from the input’s own extent against apbase.config["local_mode_extent_km_ceiling"]) before the pipeline runs, and result.x/result.y are converted back to the original input metric automatically; you never call prepare_metric_xy/restore_original_xy yourself. Passing geographic_mode="local" or "utm" explicitly forces that projection instead of auto-picking it (still only applied to input actually detected as geographic).

Parameters:

  • x (ArrayLike) – One-dimensional source coordinates and values.

  • y (ArrayLike) – One-dimensional source coordinates and values.

  • z (ArrayLike) – One-dimensional source coordinates and values.

  • resolution (float) – Output grid spacing. In the metric unit of x/y when they are not geographic; in meters (real UTM or the spherical local approximation) when geographic input is detected, whether geographic_mode was left at None (auto-picked) or set explicitly.

  • filter (bool) – Whether to run SpatialFilter on the source data before cross-validating and interpolating.

  • bounds (Bounds | None) – Optional interpolation domain: a Shapely geometry, a WKT string, or WKB bytes, in the same unit as x/y (before any geographic conversion). When omitted, a concave hull is inferred from the (filtered) source points.

  • geographic_mode (str | None) – None (default): auto-detect, as described above – geographic input auto-picks "local" or "utm"; already-metric input is unaffected. "local" or "utm": force that projection for detected geographic input, using the same semantics as apbase.common.coordinates.prepare_metric_xy()’s geographic_mode. "local" is always compatible with MapResult.to_raster(); "utm"’s inverse reprojection is non-linear and can break exact grid regularity for non-trivial extents – see MapResult.to_raster().

  • power (float) – IDW distance exponent, used only if IDW is selected.

  • max_neighbors (int) – Neighbor bounds shared by cross-validation and the final IDW/kriging fit.

  • min_neighbors (int) – Neighbor bounds shared by cross-validation and the final IDW/kriging fit.

  • max_cv_points (int) – Forwarded to cross_validate().

  • seed (int | None) – Forwarded to cross_validate().

  • filter_kwargs (dict[str, Any] | None) – Extra keyword arguments forwarded to SpatialFilter (ignored when filter=False).

Returns:

Compact map output plus cross-validation and filtering diagnostics.

Return type:

MapResult

Examples

>>> result = create_map(x, y, z, resolution=10.0)
>>> result.method
'kriging'
class apbase.mapping.Map(x=None, y=None, z=None, *, resolution, filter=True, bounds=None, geographic_mode=None, power=2.0, max_neighbors=40, min_neighbors=3, max_cv_points=500, seed=None, filter_kwargs=None)

Bases: object

Primary automatic map builder.

Map is the recommended high-level entry point for production map generation. It filters source data, builds the target grid, fits one shared variogram, cross-validates IDW against ordinary kriging, selects the statistically better method, and interpolates the final map.

Configure it once and call it with source data:

builder = Map(resolution=10.0, bounds=boundary)
result = builder(x, y, z)

The same configured instance can be reused across datasets:

result_a = builder.fit_generate(x_a, y_a, z_a)
result_b = builder(x_b, y_b, z_b)

For one-shot functional usage, call create_map().

Parameters:

  • x (array_like or None, default None) – Optional source coordinates and values. When x is supplied, all three must be supplied and the map is generated during construction.

  • y (array_like or None, default None) – Optional source coordinates and values. When x is supplied, all three must be supplied and the map is generated during construction.

  • z (array_like or None, default None) – Optional source coordinates and values. When x is supplied, all three must be supplied and the map is generated during construction.

  • resolution (float) – Output grid spacing.

  • filter (bool, default True) – Whether to apply SpatialFilter.

  • bounds (geometry, str, bytes, or None, default None) – Optional Shapely geometry, WKT, or WKB interpolation domain.

  • geographic_mode ({"local", "utm"} or None, default None) – Geographic projection mode passed through to create_map().

  • power (float, default 2.0) – IDW distance exponent.

  • max_neighbors (int) – Neighbor bounds shared by cross-validation and final interpolation.

  • min_neighbors (int) – Neighbor bounds shared by cross-validation and final interpolation.

  • max_cv_points (int, default 500) – Maximum leave-one-out samples used by cross-validation.

  • seed (int or None, default None) – Random seed for cross-validation sampling and model selection.

  • filter_kwargs (dict or None, default None) – Extra keyword arguments forwarded to SpatialFilter.

resolution
filter
bounds
geographic_mode
power
max_neighbors
min_neighbors
max_cv_points
seed
filter_kwargs
result: MapResult | None
fit_generate(x, y, z)

Run the full pipeline and store the generated map.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

Returns:

Generated map result, also stored on result.

Return type:

MapResult

class apbase.mapping.MapResult(x, y, z, method, cross_validation, radius, resolution, n_source_points, filter_statistics, coordinate_transform)

Bases: object

Result of automatic map generation.

x, y, z are a compact point list – one row per target point inside the boundary, no padding for cells outside it. Call to_raster()/to_array3d() to materialize a padded rectangular array, only when one is actually needed.

Variables:

  • z (x, y,) – Compact target coordinates and interpolated values.

  • method ({"idw", "kriging"}) – Interpolation method selected by cross-validation.

  • cross_validation (CrossValidationResult) – Leave-one-out diagnostics used for method selection.

  • radius (float) – Local search radius used by the final interpolation.

  • resolution (float) – Output grid spacing.

  • n_source_points (int) – Number of source points used after finite filtering and optional spatial filtering.

  • filter_statistics (FilterStatistics or None) – Local filtering diagnostics, or None when filtering was disabled.

  • coordinate_transform (CoordinateTransform or None) – Transform used to recover output coordinates in the original input coordinate system.

Parameters:

  • x (ndarray)

  • y (ndarray)

  • z (ndarray)

  • method (Literal['idw', 'kriging'])

  • cross_validation (CrossValidationResult)

  • radius (float)

  • resolution (float)

  • n_source_points (int)

  • filter_statistics (FilterStatistics | None)

  • coordinate_transform (CoordinateTransform | None)

x: ndarray
y: ndarray
z: ndarray
method: Literal['idw', 'kriging']
cross_validation: CrossValidationResult
radius: float
resolution: float
n_source_points: int
filter_statistics: FilterStatistics | None
coordinate_transform: CoordinateTransform | None
to_raster()

Reconstruct (X, Y, Z) as (ny, nx) arrays, NaN outside the boundary.

X/Y hold the real input coordinates (same unit as the source x/y/bounds), not a rebased 0..nx/0..ny index.

When coordinate_transform.geographic_mode == "utm" (i.e. the map was built with geographic_mode="utm" from detected geographic input), the inverse UTM->lon/lat reprojection is non-linear, so a grid that is exactly regular internally may no longer be exactly regular in lon/lat – this can raise ValueError for non-trivial extents. geographic_mode="local" uses a fixed affine transform instead and is always safe for to_raster/to_array3d.

Returns:

Rectangular X, Y, and Z arrays. Masked-out cells are NaN.

Return type:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Raises:

ValueError – If compact points cannot be represented as a regular masked grid.

to_array3d()

Stack to_raster() into a single (ny, nx, 3) array.

Returns:

Rectangular array whose last axis stores X, Y, and Z.

Return type:

numpy.ndarray