derivkit.forecasting.fisher module#

Fisher forecasting utilities.

derivkit.forecasting.fisher.build_delta_nu(cov: ArrayLike, *, data_biased: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]], data_unbiased: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]], dtype: DTypeLike = <class 'numpy.float64'>) → ndarray[tuple[Any, ...], dtype[floating]]#

Computes the difference between two data vectors.

This helper is used in Fisher-bias calculations and any other workflow where two data vectors are compared: it takes a pair of vectors (for example, a version with a systematic and one without) and returns their difference as a 1D array whose length matches the number of observables implied by cov. It works with both 1D inputs and 2D arrays (for example, correlation-by-ell) and flattens 2D inputs using NumPy’s row-major (“C”) order, which is the standard convention throughout the DerivKit package.

Parameters:

  • 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.

  • data_biased – 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_unbiased – 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 – NumPy dtype for the output array (defaults to np.float64, i.e. NumPy’s default floating type).

Returns:

A 1D NumPy array of length n_observables representing the mismatch between the two input data vectors. This is simply the element-wise difference between the input with systematic and the input without systematic, flattened if necessary to match the expected observable ordering.

Raises:

  • ValueError – If input shapes differ, inputs are not 1D/2D, or the flattened length does not match n_observables.

  • FloatingPointError – If non-finite values are detected in the result.

derivkit.forecasting.fisher.build_fisher_bias(function: Callable[[ArrayLike], float | ndarray[tuple[Any, ...], dtype[floating]]], theta0: ArrayLike, cov: ArrayLike, *, fisher_matrix: ndarray[tuple[Any, ...], dtype[floating]], delta_nu: ndarray[tuple[Any, ...], dtype[floating]], n_workers: int = 1, method: str | None = None, rcond: float = 1e-12, **dk_kwargs: Any) → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]#

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

This function takes a model, an expansion point, a covariance matrix, a Fisher matrix, and a data-vector difference delta_nu and maps that difference into parameter space. A common use case is the classic “Fisher bias” setup, where one asks how a systematic-induced change in the data would shift inferred parameters.

Internally, the function evaluates the model response at the expansion point and uses the covariance and Fisher matrix to compute both the parameter-space bias vector and the corresponding shifts. See https://arxiv.org/abs/0710.5171 for details.

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 – 1D array-like of fiducial parameters (single expansion point). This helper currently assumes a single expansion point; if you need multiple expansion points with different covariances, call this function in a loop or work directly with derivkit.forecast_kit.ForecastKit.

  • cov – The covariance matrix of the observables. Must be a square matrix with shape (n_observables, n_observables), where n_observables is the number of observables returned by the function.

  • 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 a biased and an unbiased data vector, for example \(\\Delta\nu = \nu_{\\mathrm{with\\,sys}} - \nu_{\\mathrm{without\\,sys}}\). 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 derivkit.derivative_kit.DerivativeKit default ("adaptive") is used.

  • rcond – Regularization cutoff for pseudoinverse. Default is 1e-12.

  • **dk_kwargs – Additional keyword arguments passed to derivkit.derivative_kit.DerivativeKit.differentiate().

Returns:

A tuple (bias_vec, delta_theta) of 1D arrays with length p, where bias_vec is the parameter-space bias vector and delta_theta are the corresponding parameter shifts.

Raises:

  • ValueError – If input shapes are inconsistent with the stored model, covariance, or the Fisher matrix dimensions.

  • FloatingPointError – If the difference vector contains at least one NaN.

derivkit.forecasting.fisher.build_fisher_matrix(function: Callable[[ArrayLike], float | ndarray[tuple[Any, ...], dtype[floating]]], theta0: ArrayLike, cov: ArrayLike, *, method: str | None = None, n_workers: int = 1, **dk_kwargs: Any) → ndarray[tuple[Any, ...], dtype[floating]]#

Computes the Fisher information matrix for a given model and covariance.

Parameters:

  • function – The scalar or vector-valued model function. It should accept a 1D array-like of parameter values and return either a scalar or an array of observables.

  • theta0 – 1D array-like of fiducial parameters (single expansion point). This helper currently assumes a single expansion point; if you need multiple expansion points with different covariances, call this function in a loop or work directly with derivkit.forecast_kit.ForecastKit.

  • cov – Covariance matrix of the observables. Must be square with shape (n_observables, n_observables).

  • method – Derivative method name or alias (e.g., "adaptive", "finite"). If None, the derivkit.derivative_kit.DerivativeKit default is used.

  • n_workers – Number of workers for per-parameter parallelisation. Default is 1 (serial).

  • **dk_kwargs – Additional keyword arguments forwarded to derivkit.derivative_kit.DerivativeKit.differentiate().

Returns:

Fisher matrix with shape (n_parameters, n_parameters).