derivkit.forecasting.expansions module¶

Provides tools for facilitating experimental forecasts.

The user must specify the observables, fiducial values and covariance matrix at which the derivative should be evaluated. Derivatives of the first order are Fisher derivatives. Derivatives of second order are evaluated using the derivative approximation for likelihoods (DALI) technique as described in https://doi.org/10.1103/PhysRevD.107.103506.

More details about available options can be found in the documentation of the methods.

Bases: object

Provides tools for facilitating experimental forecasts.

function¶: The scalar or vector-valued function to differentiate. It should accept a list or array of parameter values as input and return either a scalar or a np.ndarray of observable values.

theta0¶: The point(s) at which the derivative is evaluated. A 1D array or list of parameter values matching the expected input of the function.

cov¶: The covariance matrix of the observables. Should be a square matrix with shape (n_observables, n_observables), where n_observables is the number of observables returned by the function.

n_parameters¶: The number of elements of theta0.

n_observables¶: The number of cosmic observables. Determined from the dimension of cov.

Initialises the class.

Parameters:

function – The scalar or vector-valued function to differentiate. It should accept a list or array of parameter values as input and return either a scalar or a np.ndarray of observable values.
theta0 – The points at which the derivative is evaluated. A 1D array or list of parameter values matching the expected input of the function.
cov – The covariance matrix of the observables. Should be a square matrix with shape (n_observables, n_observables), where n_observables is the number of observables returned by the function.

Raises:

ValueError – raised if cov is not a square numpy array.

build_delta_nu(data_with: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]], data_without: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]], *, dtype: type | ~numpy.dtype = <class 'float'>) → ndarray[tuple[Any, ...], dtype[floating]]¶

Compute the difference between two data vectors.

This function is typically used for Fisher-bias estimates, taking two data vectors— one with a systematic included and one without—and returning their difference as a 1D array that matches the expected number of observables in this instance. It works with both 1D inputs and 2D arrays (for example, correlation × ell) and flattens 2D arrays using NumPy’s row-major (“C”) order, our standard convention throughout the package.

We standardize on row-major (“C”) flattening of 2D arrays, where the last axis varies fastest. The user must ensure that any data vectors and associated covariances are constructed with the same convention for consistent results.

Parameters:

data_with – Data vector that includes the systematic effect. Can be 1D or 2D. If 1D, it must follow the NumPy’s row-major (“C”) flattening convention used throughout the package.
data_without – Reference data vector without the systematic. Can be 1D or 2D. If 1D, it must follow the NumPy’s row-major (“C”) flattening convention used throughout the package.
dtype – Data type of the output array (defaults to float).

Returns:

A 1D NumPy array of length self.n_observables representing the data mismatch (delta_nu = data_with − data_without).

Raises:

ValueError – If input shapes differ, inputs are not 1D/2D, or the flattened length does not match self.n_observables.
FloatingPointError – If non-finite values are detected in the result.

build_fisher_bias(fisher_matrix: ndarray[tuple[Any, ...], dtype[floating]], delta_nu: ndarray[tuple[Any, ...], dtype[floating]], n_workers: int = 1, method: str | None = None, dk_kwargs: dict | None = None, rcond: float = 1e-12) → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]¶

Estimate parameter bias using the stored model, expansion point, and covariance.

This method quantifies how differences between two data sets (for example, a fiducial prediction and one affected by a systematic) propagate into parameter biases when interpreted through a Fisher forecast. It evaluates the model response internally and uses it, together with the stored covariance and provided Fisher matrix, to estimate both the bias vector and the resulting shift in parameter values. For more information, see https://arxiv.org/abs/0710.5171.

Parameters:

fisher_matrix – Square matrix describing information about the parameters. Its shape must be (p, p), where p is the number of parameters.
delta_nu – Difference between two data vectors (for example, with and without a systematic). Accepts a 1D array of length n or a 2D array that will be flattened in row-major order (“C”) to length n, where n is the number of observables. If supplied as a 1D array, it must already follow the same row-major (“C”) flattening convention used throughout the package.
n_workers – Number of workers used by the internal derivative routine when forming the Jacobian.
method – Method name or alias (e.g., “adaptive”, “finite”). If None, the DerivativeKit default (“adaptive”) is used.
dk_kwargs – Additional keyword arguments passed to DerivativeKit.differentiate.
rcond – Regularization cutoff for pseudoinverse. Default is 1e-12.

Returns:

bias_vec: parameter-space bias vector.
delta_theta: estimated parameter shifts.

Return type:

A tuple (bias_vec, delta_theta) where both entries are 1D arrays of length p

Raises:

ValueError – If input shapes are inconsistent with the stored model, covariance, or the Fisher matrix dimensions.
FloatingPointError – If the difference vector contains NaNs.

get_forecast_tensors(forecast_order: int = 1, method: str | None = None, n_workers: int = 1, dk_kwargs: dict | None = None) → ndarray[tuple[Any, ...], dtype[float64]] | Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]¶

Returns a set of tensors according to the requested order of the forecast.

Parameters:

forecast_order –
The requested order D of the forecast:
- D = 1 returns a Fisher matrix.
- D = 2 returns the 3-d and 4-d tensors required for the doublet-DALI approximation.
- D = 3 would be the triplet-DALI approximation.
Currently only D = 1, 2 are supported.
method – Method name or alias (e.g., “adaptive”, “finite”). If None, the DerivativeKit default (“adaptive”) is used.
n_workers – Number of workers for per-parameter parallelization/threads. Default 1 (serial). Inner batch evaluation is kept serial to avoid nested pools.
dk_kwargs – Additional keyword arguments passed to DerivativeKit.differentiate.

Returns:

Fisher matrix of shape (P, P). If D = 2: tuple (G, H) with shapes (P, P, P) and (P, P, P, P).

Return type:

If D = 1

Raises:

ValueError – If forecast_order is not 1 or 2.

Warns:

RuntimeWarning – If cov is not symmetric (proceeds as-is, no symmetrization), is ill-conditioned (large condition number), or inversion falls back to the pseudoinverse.

derivkit.forecasting.expansions.mixed_partial_path(y: float, *, function: Callable, theta0: ndarray, i: int, j: int, method: str | None, dk_kwargs: dict | None = None) → ndarray¶

Compute a first derivative while temporarily fixing another parameter.

This helper builds a single-argument path where parameter j is set to the provided value and all other parameters are held at the expansion point. Along that path it evaluates the first derivative of the model with respect to parameter i. It is used to construct mixed second derivatives without nested function definitions.

Parameters:

y – Value to assign to parameter j along the evaluation path.
function – Model function that returns a vector of observables given a parameter vector.
theta0 – Parameter vector at the expansion point.
i – Index of the parameter to differentiate with respect to.
j – Index of the parameter that is temporarily set to y.
method – Derivative method to use, such as “adaptive” or “finite”. If None, the DerivativeKit default is used.
dk_kwargs – Extra keyword arguments forwarded to DerivativeKit.differentiate.

Returns:

A one-dimensional array with the first derivative of each observable with respect to parameter i evaluated at the path where parameter j equals y.