apbase.filtering

High-level spatial filtering API.

class apbase.filtering.FilterStatistics(pct_diff, local_z, local_prob)

Bases: NamedTuple

Per-point local filtering statistics.

Variables:

  • pct_diff (numpy.ndarray) – Local percent-difference statistic per original input row.

  • local_z (numpy.ndarray) – Local z-score per original input row.

  • local_prob (numpy.ndarray) – Local probability statistic per original input row.

Parameters:

  • pct_diff (ndarray)

  • local_z (ndarray)

  • local_prob (ndarray)

pct_diff: ndarray

Alias for field number 0

local_z: ndarray

Alias for field number 1

local_prob: ndarray

Alias for field number 2

class apbase.filtering.SpatialFilter(*, radius=None, filter_level='light', apply_global_iqr=True, max_neighbors=120, candidate_fraction=1.0, cell_factor=3, global_iqr_whisker=3.0, dedup_radius=0.0, dedup_z_tol=0.0)

Bases: object

Filter projected spatial samples with global IQR and local z-statistics.

Removes invalid rows, optionally removes global IQR outliers, and applies a local native filter using spatial neighborhoods. Coordinates are not projected internally; pass projected/metric coordinates when radius is metric.

Parameters:

  • radius (float | None) – Local search radius. Defaults to range / 3 from a fitted variogram.

  • filter_level (str) – Strictness, loosest to strictest: "light", "moderate", "strict", or "aggressive".

  • apply_global_iqr (bool) – Whether to remove global IQR outliers before local filtering.

  • max_neighbors (int) – Maximum local neighbors per source point. 0 uses every neighbor within radius, uncapped.

  • candidate_fraction (float) – Fraction (0, 1] of in-radius candidates considered for the local sample.

  • cell_factor (int) – Spatial grid factor used by the local kernel.

  • global_iqr_whisker (float) – IQR whisker for the optional global filter; lower removes more points. Ignored when apply_global_iqr=False.

  • dedup_radius (float) – Distance below which two points are treated as spatial duplicates and collapsed to one representative. 0.0 (default) disables this.

  • dedup_z_tol (float) – Extra value-closeness gate combined with dedup_radius: points only merge if also within this value difference. 0.0 (default) means proximity alone is sufficient.

Examples

>>> import numpy as np
>>> from apbase.filtering import SpatialFilter
>>> x = np.ascontiguousarray([0.0, 10.0, 0.0, 10.0])
>>> y = np.ascontiguousarray([0.0, 0.0, 10.0, 10.0])
>>> z = np.ascontiguousarray([5.0, 7.0, 8.0, 10.0])
>>> filt = SpatialFilter(radius=20.0, apply_global_iqr=False).fit(x, y, z)
>>> x_keep, y_keep, z_keep = filt.filter()
property radius: float | None

Local search radius.

Returns:

Explicit radius, or None to derive it from a fitted variogram.

Return type:

float or None

property filter_level: str

Filtering strictness.

Returns:

One of "light", "moderate", "strict", or "aggressive".

Return type:

str

property apply_global_iqr: bool

Whether global IQR outliers are removed before local filtering.

Returns:

True when global IQR filtering is enabled.

Return type:

bool

property max_neighbors: int

Maximum local neighbors used per source point.

Returns:

Local-neighborhood cap. 0 means every in-radius neighbor.

Return type:

int

property candidate_fraction: float

Fraction of in-radius candidates sampled locally.

Returns:

Candidate sampling fraction in (0, 1].

Return type:

float

property cell_factor: int

Spatial grid factor used by the native local kernel.

Returns:

Positive spatial-grid factor.

Return type:

int

property global_iqr_whisker: float

IQR whisker used by the optional global filter.

Returns:

Non-negative IQR whisker.

Return type:

float

property dedup_radius: float

Spatial duplicate-collapse radius.

Returns:

Non-negative distance threshold. 0.0 disables spatial duplicate collapse.

Return type:

float

property dedup_z_tol: float

Value-closeness gate paired with dedup_radius.

Returns:

Non-negative value threshold.

Return type:

float

property n_threads: int

Explicit OpenMP thread count passed to native routines.

Resolved live from apbase.config["n_threads"] (see the class docstring) on every access – not cached at construction time.

Returns:

Current OpenMP thread count.

Return type:

int

classmethod from_data(x, y, z, **kwargs)

Create and fit a spatial filter.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

  • **kwargs – Keyword arguments forwarded to SpatialFilter.

Returns:

Fitted spatial filter.

Return type:

SpatialFilter

property is_fitted: bool

Whether source data and filtering outputs are available.

Returns:

True after fit() succeeds.

Return type:

bool

property model_params: dict[str, float | int | str]

Readable parameters for the variogram used by the default radius.

Returns:

Variogram parameters used to derive the implicit radius.

Return type:

dict

Raises:

ValueError – If the filter is not fitted or was fitted with an explicit radius.

property statistics: FilterStatistics

Local percent difference, z-score, and probability arrays.

Returns:

Copies of the per-input-row local filtering diagnostics.

Return type:

FilterStatistics

fit(x, y, z)

Run global and local filtering for source samples.

Parameters:

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

  • y (ArrayLike) – One-dimensional source y coordinates. Must have the same length as x.

  • z (ArrayLike) – One-dimensional source values. Must have the same length as x and y.

Returns:

The fitted filter. Use mask(), filter(), or statistics to read results.

Return type:

SpatialFilter

Raises:

  • ValueError – If input arrays have inconsistent size, no finite rows, no rows after global filtering, or invalid radius.

  • NativeExecutionError – If a native filtering kernel reports a failure status.

Examples

>>> filt = SpatialFilter(radius=30.0, apply_global_iqr=False)
>>> filt.fit(x, y, z)
>>> keep = filt.mask()
mask()

Return the boolean keep mask for the fitted source arrays.

Returns:

Boolean array aligned with the original input rows. True means the row survived finite, global, and local filtering.

Return type:

numpy.ndarray

filter()

Return filtered x, y, and z arrays.

Returns:

Source coordinates and values where the keep mask is True.

Return type:

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

Examples

>>> x_keep, y_keep, z_keep = filt.filter()
fit_mask(x, y, z)

Fit the filter and return the boolean keep mask.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

Returns:

Boolean keep mask aligned with the original input rows.

Return type:

numpy.ndarray

fit_filter(x, y, z)

Fit the filter and return filtered source arrays.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

Returns:

Filtered source coordinates and values.

Return type:

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