auto_ada_loc

Adaptive localization implementation.

AutoAdaptiveLocalization

Bases: LocalizationBase

Adaptive localization strategy and engine implementation.

__call__(X, Y, parameters=None, prior_info=None)

Calculate truncated cross-covariance matrix.

Parameters:

Name	Type	Description	Default
X	(ndarray, shape(nx, ne))	State perturbation ensemble.	required
Y	(ndarray, shape(ny, ne))	Projected predicted data ensemble.	required
parameters	list[str]	Ordered list of parameters corresponding to blocks in X.	None
prior_info	dict	Prior information for each parameter. If provided, prior_info[param]["active"] specifies the number of active variables associated with the parameter.	None

Returns:

Type	Description
(ndarray, shape(nx, ny))	Tapered matrix containing the tapering coefficients for the cross-covariance between X and Y.

__init__(info, rng=None)

Initialize the AutoAdaptiveLocalization instance.

All configuration is supplied through the info dictionary, which maps directly to a [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. For a 3-D reservoir use [nz, nx, ny]; for a 2-D field [nx, ny] is sufficient. Only the product (total cell count) is used by this class. actnum : str, optional Path to a .npz file whose first array is a boolean mask of active cells. When supplied, only active cells are counted toward default_num_active. Default: None (all cells are considered active). threshold : {"adaptive", "fixed", "universal"}, optional Method used to compute the correlation threshold below which a correlation is deemed indistinguishable from sampling noise: - ``"adaptive"`` — threshold = ``cutoff * sigma``, where *sigma* is estimated column-wise from shuffled correlations via the MAD estimator. The ``cutoff`` parameter controls how many noise standard deviations to use as the cut-off. - ``"fixed"`` — threshold equals ``cutoff`` directly; no noise estimation is performed. Use when you want a deterministic, reproducible cut-off independent of the ensemble. - ``"universal"`` — threshold = ``sqrt(2 * log(N)) * sigma``; adapts automatically to ensemble size without requiring ``cutoff`` to be tuned. Default: ``"adaptive"``. cutoff : float, optional Threshold value or noise multiplier (interpretation depends on threshold). Larger values suppress more correlations. Default: 0.3. type : {"hard", "soft", "sigm"}, optional Tapering strategy applied once the threshold is known: - ``"hard"`` — binary mask: 1 where |r| ≥ threshold, 0 elsewhere. Sharp cut-off, computationally efficient. - ``"soft"`` — smooth rational-function taper that transitions gradually around the threshold. Avoids discontinuities in the localization operator. - ``"sigm"`` — sigmoid-based taper; similar smoothness to ``"soft"`` but with a different shape near the transition. Default: ``"hard"``.	required

Examples:

Minimal TOML block inside [dataassim] using fixed thresholding:

[dataassim.localization]
name       = "autoadaloc"
field      = [1, 20, 20]   # [nz, nx, ny]
threshold  = "fixed"
cutoff     = 0.4
type       = "hard"

Noise-adaptive thresholding with a smooth taper:

[dataassim.localization]
name       = "autoadaloc"
field      = [2, 30, 40]   # two-layer, 30×40 lateral grid
actnum     = "active_cells.npz"
threshold  = "universal"   # adapts to ensemble size automatically
type       = "soft"

Large state vector — skip forming the full cross-covariance:

[dataassim.localization]
name       = "autoadaloc"
field      = [5, 100, 100]
threshold  = "fixed"
cutoff     = 0.3
type       = "hard"

corr_matrix(X, Y, eps=1e-06)

Compute the correlation matrix between two ensemble matrices X and Y.

Parameters:

Name	Type	Description	Default
X	(ndarray, shape(nx, ne))		required
Y	(ndarray, shape(ny, ne))		required
eps	float	Small value to avoid division by zero when computing standard deviations.	1e-6

Returns:

Name	Type	Description
corr	(ndarray, shape(nx, ny))	The correlation matrix between X and Y.

rational_function(distance, length_scale)

Piecewise rational taper of distance at length_scale: 1 inside the scale, decaying to 0 at twice the scale.

rational_function_sigmoid(distance, length_scale)

A steep sigmoid taper switching at length_scale.

tapering_function(corr_values, corr_values_shuffled)

Compute tapering coefficients from sample correlations.

The tapering coefficients are used to suppress correlations that are indistinguishable from noise. A noise level is estimated for each observation variable from the corresponding shuffled correlations using the median absolute deviation (MAD),

sigma = median(|r_shuffled|) / 0.6745

which provides a robust estimate of the standard deviation under the assumption of Gaussian noise.

Depending on the localization settings, the correlation threshold is computed using one of the following methods:

• "adaptive" (default): threshold = cutoff * sigma
• "fixed": threshold = cutoff
• "universal": threshold = sqrt(2 log(N)) * sigma

Tapering can then be applied using one of three strategies:

• "hard" (default): correlations above the threshold are assigned a taper value of 1, otherwise 0.
• "soft": smooth tapering based on rational_function.
• "sigm": sigmoid-based tapering using rational_function_sigmoid.

Parameters:

Name	Type	Description	Default
corr_values	ndarray of shape (nx, ny)	Sample correlation matrix.	required
corr_values_shuffled	ndarray of shape (nx, ny)	Correlation matrix computed from shuffled or randomized ensembles. Used to estimate the noise level of the correlations.	required

Returns:

Type	Description
ndarray of shape (nx, ny)	Tapering coefficients in the interval [0, 1]. These coefficients can be applied element-wise to the correlation matrix to reduce the influence of correlations attributed to sampling noise.