distance_localization

Distance-based localization implementation.

DistanceLocalization

Bases: LocalizationBase

Distance-based localization strategy for sparse mask projection.

Follows the same init/call pattern as AutoAdaptiveLocalization: - All configuration is parsed and stored at __init__ time. - __call__ assembles and returns the sparse localization operator.

Parameters:

Name	Type	Description	Default
info	dict or list	Localization configuration. Must contain: field: [nz, nx, ny] grid dimensions. actnum: path to .npz file with active-cell mask (optional). taper_func: kernel type -- "gc", "fb", or "region" (default: "region"). Plus one of: - a .csv key or comma-separated inline rows specifying entries, or - a .pkl / .p key pointing to a pre-built entries dict.	required
data	DataFrame	Observed data with time indices as rows and data types as columns.	None
parameters	list of str	State parameter names used as defaults in __call__.	None
ensemble_size	int	Ensemble size; used by the Furrer-Bengtsson kernel.	None
prior_info	dict	Per-parameter prior information (nx, ny, nz). Used to build zero masks for unconfigured parameters.	None

__call__(curr_data=None, curr_time=None, curr_param=None)

Build the sparse localization operator for the current assimilation step.

Parameters:

Name	Type	Description	Default
curr_data	list of str	Data types to include. Defaults to self.data_types.	None
curr_time	list	Time indices to include. Defaults to self.data_indices.	None
curr_param	list of str	State parameters to update. Defaults to self.parameters.	None

Returns:

Type	Description
scipy.sparse matrix, shape (n_active_cells, n_obs)	Sparse localization operator.

__init__(info, data=None, parameters=None, ensemble_size=None, prior_info=None)

Initialize the DistanceLocalization instance.

Spatial localization entries — one per (data_type, time, parameter) combination — are supplied either via an external CSV file or as comma-separated inline rows embedded in the info dict key. All info keys map directly to the [dataassim.localization] table in a TOML config file.

Parameters:

Name	Type	Description	Default
info	dict or list	Localization configuration. Recognised keys: field : list of int, required Grid dimensions [nz, nx, ny]. Used to size the spatial kernel arrays and to lay out the flattened cell vectors. actnum : str, optional Path to a .npz file whose first array is a boolean mask of active cells. When supplied, only active cells appear in the output localization operator. Default: None. taper_func : {"gc", "fb", "region"}, optional Spatial kernel applied at each observation location: - ``"gc"`` — **Gaspari-Cohn** fifth-order piecewise polynomial. Compact support extends to ``2 × radius`` grid cells. Values lie in [0, 1] with a smooth, differentiable profile. The standard choice for distance-based localization in geoscience DA. - ``"fb"`` — **Furrer-Bengtsson** ensemble-size-aware taper. Weights are scaled by ensemble size *Ne* so that larger ensembles produce sharper localization. Values lie in [0, Ne/(Ne+2)]. Pass ``ensemble_size`` to control *Ne* (default 50). - ``"region"`` — Binary point kernel: weight 1 at the single nearest cell, 0 everywhere else. Equivalent to assigning one observation to exactly one grid cell. Default: ``"region"``. entries : str, list, or dict, optional Localization entries configuration. Three formats are supported: - **str**: Path to a CSV file containing one entry per line (see *CSV row format* in Notes). - **list**: List of entry dicts or CSV row strings. Dicts must contain ``"taper"``, ``"x"``, ``"y"``, ``"radius"``, ``"data_type"``, ``"time"``, ``"param"`` (plus optional ``"z"``, ``"z_range"``, ``"aniso"``, ``"rotation"``). Wildcard ``"*"`` can be used to expand entries across all known values for that field. - **dict**: Pre-built ``{(data_type, time, param): LocalizationEntry}`` dict (rarely used; prefer the other formats).	required
data	DataFrame	Observed data whose index contains the assimilation time steps (must match the time field in each CSV row) and whose columns are the data-type names (e.g. "WOPR PRO1"). Required for __call__ to produce output.	None
parameters	list of str	Ordered list of state parameter names (e.g. ["permx", "poro"]). Determines which parameters receive a localization mask and the stacking order in the output.	None
ensemble_size	int	Ensemble size Ne. Only affects the Furrer-Bengtsson kernel (taper_func = "fb"). Default: None ("fb" falls back to Ne = 50).	None
prior_info	dict	Per-parameter grid sizes. Required only when a parameter appears in parameters but has no localization entry in the CSV; such parameters receive an all-zero weight column whose length is taken from this dict:: {"poro": {"nx": 20, "ny": 20, "nz": 1}}	None

Notes

CSV row format

Each entry is a single space-separated line with 11 fields (or 12 if the data-type name contains a space)::

taper  x_pos  y_pos  z_pos  radius  z_range  aniso  rotation  data_type  time  param

For two-word data types (e.g. WOPR PRO1) use 12 fields::

taper  x_pos  y_pos  z_pos  radius  z_range  aniso  rotation  word1  word2  time  param

Field descriptions:

• taper — kernel tag: gc, fb, or region.
• x_pos — observation x-cell index on the grid (0-based), along the nx axis.
• y_pos — observation y-cell index on the grid (0-based), along the ny axis.
• z_pos — observation layer index on the grid (0-based).
• radius — kernel half-radius in grid cells. For gc the full support spans 2 × radius cells from the center.
• z_range — ":" to spread the kernel across all nz layers, or an integer to restrict it to that single layer.
• aniso — anisotropy ratio (x-axis scaling factor). Use 1.0 for isotropic kernels; 2.0 compresses the kernel to half-width in the x-direction.
• rotation — clockwise rotation of the kernel in degrees. Use 0.0 for axis-aligned kernels.
• data_type — observation type name, case-insensitive. Must match a column in the data DataFrame.
• time — assimilation time step; must match an index value of the data DataFrame.
• param — state parameter name, case-insensitive. Must appear in the parameters list.

Examples:

TOML config using an external CSV file (recommended for many observation types or time steps):

[dataassim.localization]
name       = "distance_loc"
field      = [1, 20, 20]    # [nz, nx, ny]
taper_func = "gc"
"loc_entries.csv" = true    # key = filename; value is ignored

Example loc_entries.csv (Gaspari-Cohn, isotropic, all layers):

gc 10 10 0  6 : 1.0  0.0  pressure    400.0 permx
gc 10 10 0  6 : 1.0  0.0  pressure    800.0 permx
gc  5 15 0  4 : 1.0  0.0  wopr pro1   400.0 permx
gc  5 15 0  4 : 2.0 30.0  wopr pro1   800.0 permx

TOML config using the Furrer-Bengtsson kernel with active-cell mask and anisotropic entries in the CSV:

[dataassim.localization]
name       = "distance_loc"
field      = [2, 30, 40]    # two-layer, 30×40 lateral grid
taper_func = "fb"
actnum     = "active.npz"
"loc_entries.csv" = true

loc_entries.csv restricting each observation to layer 0 only (z_range = 0) with anisotropic, rotated kernel:

fb  8 12 0 6 0 2.0 45.0 wopr pro1 400.0 permx
fb 15  5 0 8 0 1.0  0.0 wwct pro2 400.0 permx

Python config using the entries key with a list of dicts (modern preferred approach):

info = {
    "field": [1, 20, 20],
    "taper_func": "gc",
    "entries": [
        {
            "taper": "gc",
            "x": 10, "y": 10, "z": 0,
            "radius": 6,
            "z_range": ":",
            "aniso": 1.0, "rotation": 0.0,
            "data_type": "pressure",
            "time": 400.0,
            "param": "permx",
        },
        {
            "taper": "gc",
            "x": 5, "y": 15, "z": 0,
            "radius": 4,
            "z_range": ":",
            "aniso": 1.0, "rotation": 0.0,
            "data_type": "wopr pro1",
            "time": 400.0,
            "param": "permx",
        },
    ]
}

Wildcard expansion in entries (apply one config to all data types):

info = {
    "field": [1, 20, 20],
    "taper_func": "gc",
    "entries": [
        {
            "taper": "gc",
            "x": 10, "y": 10, "z": 0,
            "radius": 6,
            "z_range": ":",
            "aniso": 1.0, "rotation": 0.0,
            "data_type": "*",      # expands to all data types
            "time": "*",           # expands to all times
            "param": "permx",
        },
    ]
}

FurrerBengtssonKernel

Furrer-Bengtsson ensemble-size-aware taper kernel.

build(radius, anisotropy_ratio, rotation_deg, field_shape, ensemble_size=None)

Taper weights around a datum: Furrer-Bengtsson decay over radius cells, adjusted for the ensemble size.

GaspariCohnKernel

Gaspari-Cohn compactly supported smooth taper kernel.

build(radius, anisotropy_ratio, rotation_deg, field_shape, ensemble_size=None)

Taper weights around a datum: smooth Gaspari-Cohn decay over radius cells, stretched by anisotropy_ratio.

LocalizationEntry

Configuration for a single (data_type, time, parameter) localization entry.

RegionKernel

Binary region kernel - full weight (1) everywhere within range.

build(radius=None, anisotropy_ratio=1.0, rotation_deg=0.0, field_shape=None, ensemble_size=None)

Weight 1 everywhere within radius (stretched by anisotropy_ratio), 0 outside.