dubfi.core.util

Utility functions for flux inversion problem.

Added in version 0.1.0: (initial release)

Functions

config_overwrite(config, changes)

Overwrite config by given changes, recursively updating dictionaries.

get_b_prior(flux_cat, config) → numpy.ndarray

Construct a priori B matrix from configuration.

get_s_prior(flux_cat, config) → numpy.ndarray

Construct a priori scaling factors from config.

get_prior_cycling(ds, flux_cat, config) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Construct a priori B matrix in cycling step from results of previous cycle.

mix_b(alpha, b1, b2[, sqrt_b1]) → numpy.ndarray

Compute error covariance matrix for alpha * x1 + (1 - alpha) * x2 from error covariance matricess of x1 and x2.

Module Contents

dubfi.core.util.config_overwrite(config: dict, changes: dict)

Overwrite config by given changes, recursively updating dictionaries.

dubfi.core.util.get_b_prior(flux_cat: numpy.ndarray, config: dict) → numpy.ndarray

Construct a priori B matrix from configuration.

Parameters:

  • flux_cat (np.ndarray) – names of flux categories (as used in configuration), result will be aligned to this list.

  • config (dict) – configuration

Returns:

b_prior – prior uncertainty matrix (B)

Return type:

np.ndarray

dubfi.core.util.get_s_prior(flux_cat: numpy.ndarray, config: dict) → numpy.ndarray

Construct a priori scaling factors from config.

dubfi.core.util.get_prior_cycling(ds: xarray.Dataset, flux_cat: numpy.ndarray, config: dict) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Construct a priori B matrix in cycling step from results of previous cycle.

Parameters:

  • ds (xr.Dataset) – output of previous cycle, coordinates must agree with provided coordinates.

  • flux_cat (array) – names of flux categories, result will be aligned to this list.

  • config (dict) – configuration

Returns:

  • s_prior (np.ndarray) – prior scaling factors for simpler Kalman filter, shape (flux_cat,)

  • b_prior (np.ndarray) – error covariance matrix of s_prior, shape (flux_cat, flux_cat)

  • s_prior_norm_pref (np.ndarray) – prior scaling factors for extended inversion, shape (norm_prefactor, flux_cat)

  • b_prior_norm_pref (np.ndarray) – error covariance matrix of s_prior_norm_pref, shape (norm_prefactor, flux_cat, flux_cat)

  • Remarks

  • ——-

  • This function mixes the initial prior and the posterior from a

  • previous inversion step. The posterior uncertainty is optionally

  • inflated before mixing with the initial prior. It assumes that

  • the uncertainties of the initial prior and the posterior are

  • maximally correlated, see mix_b().

  • .. versionadded:: 0.1.1

dubfi.core.util.mix_b(alpha: float, b1: numpy.ndarray, b2: numpy.ndarray, sqrt_b1: numpy.ndarray | None = None) → numpy.ndarray

Compute error covariance matrix for alpha * x1 + (1 - alpha) * x2 from error covariance matricess of x1 and x2.

Consider two vectors x1, x2 with error covariance matrices B1, B2. Denote the covariance matrix of x1, x2 by B12, i.e., using cumulante notation: B1[i,j] = << x1[i] x1[j] >>, B2[i,j] = << x2[i] x2[j] >>, B12[i,j] = << x1[i] x2[j] >>. Then the error covariance matrix of x1 + x2 is Bsum = B1 + B2 + B12 + B12.T.

We assume that B12 = sqrt(B1) sqrt(B2) such that the error covariance matrix of the combined vector (x1, x2) is singular with minimal rank (equal to rank(B1)=rank(B2)). This describes the strongest possible uncertainty correlation between x1 and x2.

The output of this function is therefore (denote a=alpha):

a**2 * B1 + (1-a)**2 * B2 + a*(1-a) * ( sqrt(B1) sqrt(B2) + sqrt(B2) sqrt(B1) )

Note

b1 and b2 must be real-symmetric and positive-semidefinite.

Added in version 0.1.1.