derivkit 1.0.0__py3-none-any.whl

derivkit/forecasting/sampling_utils.py

@@ -0,0 +1,388 @@
+"""Gaussian sampling-kernel helpers derived from a Fisher matrix.
+
+This module implements a Fisher-based Gaussian sampling distribution
+``q`` centered at ``theta0`` with covariance::
+
+    (kernel_scale**2) * pinv(F)
+
+where ``F`` is the Fisher information matrix evaluated at ``theta0``.
+In this approximation, ``F`` is the Hessian of ``-log L`` at ``theta0`` and
+acts as the local inverse covariance.
+
+This kernel is used to generate candidate points and, for importance sampling,
+to evaluate ``log(q)`` when sampling posteriors approximated with Fisher or DALI.
+
+For importance sampling, ``log(q)`` is subtracted from the target log-posterior to form log-weights.
+
+It provides:
+
+- construction of Fisher-based sampling covariances,
+- stabilized Cholesky factorization for near-singular kernels,
+- sampling and log-density evaluation of the kernel,
+- fast bounds rejection masks,
+- MCMC walker initialization under sampler bounds.
+
+These utilities do not depend on a specific sampler implementation.
+They provide kernel draws, log-densities, and bounds filtering that are
+called by the GetDist importance-sampling wrappers and by the emcee walker
+initialization routine.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+from derivkit.utils.linalg import solve_or_pinv
+from derivkit.utils.validate import (
+    validate_fisher_shape,
+    validate_square_matrix,
+)
+
+__all__ = [
+    "kernel_cov_from_fisher",
+    "stabilized_cholesky",
+    "kernel_samples_from_fisher",
+    "apply_parameter_bounds",
+    "log_gaussian_kernel",
+    "init_walkers_from_fisher",
+    "fisher_to_cov",
+]
+
+
+def kernel_cov_from_fisher(
+    fisher: NDArray[np.floating],
+    *,
+    kernel_scale: float,
+) -> NDArray[np.float64]:
+    """Returns the covariance of the Fisher-based Gaussian sampling kernel.
+
+    This is a thin wrapper around
+    :func:`derivkit.forecasting.integrations.sampling_utils.fisher_to_cov` that converts
+    ``fisher`` to a covariance via pseudoinverse and applies the scaling ``kernel_scale^2``.
+
+    The Fisher matrix is treated as the Hessian of ``-log L`` at ``theta0``.
+    In this local approximation it acts as an inverse covariance, and
+    ``kernel_scale`` controls the overall kernel width.
+    A pseudoinverse is used so the covariance is defined even if ``fisher`` is singular.
+
+    Args:
+        fisher: Fisher information matrix with shape ``(p, p)``.
+        kernel_scale: Multiplicative scale factor applied to the covariance.
+            Increasing values widen the kernel; decreasing values narrow it.
+
+    Returns:
+        Kernel covariance matrix with shape ``(p, p)``, equal to
+        ``(kernel_scale^2) * fisher_to_cov(fisher)``.
+
+    Raises:
+        ValueError: If ``fisher`` is not a square 2D array.
+    """
+    kernel_cov = fisher_to_cov(fisher)
+    return (float(kernel_scale) ** 2) * kernel_cov
+
+
+def stabilized_cholesky(cov: NDArray[np.floating]) -> NDArray[np.float64]:
+    """Returns a Cholesky factor of a covariance matrix.
+
+    This function computes a lower-triangular matrix ``L`` such that ``cov`` is
+    approximately ``L @ L.T``, even when ``cov`` is nearly singular or only
+    positive semi-definite.
+
+    Args:
+        cov: Covariance matrix with shape ``(p, p)`` with ``p`` parameters.
+
+    Returns:
+        A lower-triangular Cholesky factor ``L`` of the regularized covariance.
+
+    Raises:
+        ValueError: If ``cov`` is not a square 2D array.
+    """
+    cov_matrix = np.asarray(cov, dtype=float)
+
+    if cov_matrix.ndim != 2 or cov_matrix.shape[0] != cov_matrix.shape[1]:
+        raise ValueError(f"cov must be square 2D, got {cov_matrix.shape}")
+
+    n_params = cov_matrix.shape[0]
+    trace_cov = float(np.trace(cov_matrix))
+    regularization_scale = max(trace_cov, 1.0)
+    jitter = 1e-12 * regularization_scale / max(n_params, 1)
+
+    regularized_cov = cov_matrix + jitter * np.eye(n_params)
+    cholesky_factor = np.linalg.cholesky(regularized_cov)
+    return cholesky_factor
+
+
+def kernel_samples_from_fisher(
+    theta0: NDArray[np.floating],
+    fisher: NDArray[np.floating],
+    *,
+    n_samples: int,
+    kernel_scale: float,
+    seed: int | None,
+) -> NDArray[np.float64]:
+    """Draws samples from a Fisher-based Gaussian sampling kernel.
+
+    Samples are drawn from the Gaussian kernel density ``q(theta)`` with mean
+    ``theta0`` and covariance ``(kernel_scale^2) * pinv(F)``::
+
+        q(theta) = Normal(mean=theta0, cov=(kernel_scale^2) * pinv(F))
+
+    ``F`` is the Fisher information matrix evaluated at ``theta0``.
+    In this approximation, ``F`` acts as an inverse covariance and
+    Normal represents the multivariate normal distribution.
+    A pseudoinverse is used so the covariance is defined even if
+    ``F`` is singular or ill-conditioned.
+
+    Args:
+        theta0: Kernel mean with shape ``(p,)`` with ``p`` parameters.
+        fisher: Fisher information matrix with shape ``(p, p)``.
+        n_samples: Number of samples to draw.
+        kernel_scale: Multiplicative scale applied to the covariance.
+            Increasing values widen the kernel; decreasing values narrow it.
+        seed: Optional random seed for reproducible draws.
+
+    Returns:
+        Array of samples with shape ``(n_samples, p)``.
+    """
+    rng = np.random.default_rng(seed)
+
+    theta0_vec = np.asarray(theta0, dtype=float)
+    fisher_matrix = np.asarray(fisher, dtype=float)
+    validate_fisher_shape(theta0_vec, fisher_matrix)
+
+    kernel_cov = kernel_cov_from_fisher(fisher_matrix, kernel_scale=float(kernel_scale))
+    chol_lower = stabilized_cholesky(kernel_cov)
+
+    n_params = theta0_vec.size
+    standard_normals = rng.standard_normal((int(n_samples), n_params))
+
+    kernel_mean = theta0_vec[None, :]
+    noise = (chol_lower @ standard_normals.T).T
+    return kernel_mean + noise
+
+
+def apply_parameter_bounds(
+    samples: NDArray[np.floating],
+    parameter_bounds: Sequence[tuple[float | None, float | None]] | None,
+) -> NDArray[np.float64]:
+    """Applies per-parameter bounds to a set of samples.
+
+    This function performs a fast, axis-aligned rejection step: any sample with
+    at least one parameter value outside the specified bounds is discarded.
+    It does not evaluate priors or compute weights.
+
+    Args:
+        samples: Sample array with shape ``(n_samples, p)`` with ``p`` parameters.
+        parameter_bounds: Optional sequence of ``(lower, upper)`` bounds, one
+            per parameter. Use ``None`` to indicate an unbounded side
+            (e.g. ``(0.0, None)``). If ``None``, no filtering is applied.
+
+    Returns:
+        Samples satisfying all bounds, with shape ``(n_kept, p)``.
+        ``n_kept`` may be zero.
+
+    Raises:
+        ValueError: If ``parameter_bounds`` is provided but does not have
+            length ``p``.
+    """
+    sample_array = np.asarray(samples, dtype=np.float64)
+
+    if parameter_bounds is None:
+        return sample_array
+
+    n_params = sample_array.shape[1]
+    if len(parameter_bounds) != n_params:
+        raise ValueError(
+            f"parameter_bounds must have length {n_params}; got {len(parameter_bounds)}"
+        )
+
+    keep_mask = np.ones(sample_array.shape[0], dtype=bool)
+    for param_index, (lower, upper) in enumerate(parameter_bounds):
+        if lower is not None:
+            keep_mask &= sample_array[:, param_index] >= lower
+        if upper is not None:
+            keep_mask &= sample_array[:, param_index] <= upper
+
+    return sample_array[keep_mask]
+
+
+def log_gaussian_kernel(
+    samples: NDArray[np.floating],
+    theta0: NDArray[np.floating],
+    fisher: NDArray[np.floating],
+    *,
+    kernel_scale: float,
+) -> NDArray[np.float64]:
+    """Log-density of a Fisher-based Gaussian sampling kernel.
+
+    Defines a Gaussian kernel ``q`` with mean ``theta0`` and covariance
+
+        ``(kernel_scale^2) * pinv(F)``
+
+    where ``F`` is the Fisher information matrix. The covariance is formed with a
+    pseudoinverse (allowing singular or ill-conditioned ``F``). A small diagonal
+    jitter is added before evaluating the log-density so the calculation remains
+    well-defined for near-singular covariances.
+
+    Args:
+        samples: Sample locations with shape ``(n_samples, p)``.
+        theta0: Kernel mean with shape ``(p,)``.
+        fisher: Fisher information matrix with shape ``(p, p)``.
+        kernel_scale: Multiplicative scale applied to the covariance.
+
+    Returns:
+        Log of the kernel probability density ``log(q(theta))``, evaluated at each
+        sample point, with shape ``(n_samples,)``.
+
+    Raises:
+        ValueError: If input shapes are incompatible.
+        RuntimeError: If the jittered covariance is not positive-definite.
+    """
+    theta0_vec = np.asarray(theta0, dtype=float)
+    fisher_matrix = np.asarray(fisher, dtype=float)
+    validate_fisher_shape(theta0_vec, fisher_matrix)
+    sample_array = np.asarray(samples, dtype=np.float64)
+
+    if sample_array.ndim != 2:
+        raise ValueError(
+            "samples must be 2D with shape (n_samples, p); "
+            f"got shape {sample_array.shape}."
+        )
+
+    if sample_array.shape[1] != theta0_vec.size:
+        raise ValueError(
+            f"samples must have p={theta0_vec.size} columns; got {sample_array.shape[1]}."
+        )
+
+    cov_matrix = kernel_cov_from_fisher(fisher_matrix, kernel_scale=float(kernel_scale))
+
+    n_params = theta0_vec.size
+    trace_cov = float(np.trace(cov_matrix))
+    trace_scale = max(trace_cov, 1.0)
+    jitter = 1e-12 * trace_scale / max(n_params, 1)
+    cov_matrix = cov_matrix + jitter * np.eye(n_params)
+
+    sign, logdet = np.linalg.slogdet(cov_matrix)
+    if sign <= 0 or not np.isfinite(logdet):
+        raise RuntimeError("Kernel covariance is not positive-definite after adding jitter.")
+
+    centered = sample_array - theta0_vec[None, :]
+    solved = solve_or_pinv(
+        cov_matrix,
+        centered.T,
+        rcond=1e-12,
+        assume_symmetric=True,
+        warn_context="log_gaussian_kernel",
+    )
+
+    quad_form = np.einsum("ij,ij->j", centered.T, solved)
+    norm_const = n_params * np.log(2.0 * np.pi) + logdet
+    log_gauss_density = -0.5 * (quad_form + norm_const)
+    return log_gauss_density
+
+
+def init_walkers_from_fisher(
+    theta0: NDArray[np.floating],
+    fisher: NDArray[np.floating],
+    *,
+    n_walkers: int,
+    init_scale: float,
+    seed: int | None,
+    sampler_bounds: Sequence[tuple[float | None, float | None]] | None,
+) -> NDArray[np.float64]:
+    """Returns initial MCMC walker positions from a Fisher-based Gaussian sampling kernel.
+
+    Returns an array of walker positions centered at ``theta0`` with scatter set by
+    a Fisher-derived covariance ``(init_scale^2) * pinv(F)``. If ``sampler_bounds``
+    are provided, positions outside the bounds are rejected and additional candidates
+    are generated until ``n_walkers`` positions are collected or a retry limit is reached.
+
+    Args:
+        theta0: Kernel mean with shape ``(p,)`` with ``p`` parameters.
+        fisher: Fisher information matrix with shape ``(p, p)``.
+        n_walkers: Number of walker positions to return.
+        init_scale: Multiplicative scale applied to the kernel covariance.
+        seed: Optional random seed for reproducible initialization.
+        sampler_bounds: Optional per-parameter ``(lower, upper)`` bounds. Use ``None``
+            for an unbounded side.
+
+    Returns:
+        Array of initial positions with shape ``(n_walkers, p)``.
+
+    Raises:
+        ValueError: If ``theta0`` and ``fisher`` have incompatible shapes.
+        ValueError: If ``sampler_bounds`` is provided and does not have length ``p``.
+        RuntimeError: If sufficient in-bounds positions cannot be generated within
+            the retry limit.
+    """
+    theta0 = np.asarray(theta0, float)
+    fisher = np.asarray(fisher, float)
+    validate_fisher_shape(theta0, fisher)
+
+    if sampler_bounds is not None and len(sampler_bounds) != theta0.size:
+        raise ValueError(
+            f"sampler_bounds must have length {theta0.size}; got {len(sampler_bounds)}."
+        )
+
+    if sampler_bounds is None:
+        return kernel_samples_from_fisher(
+            theta0, fisher, n_samples=int(n_walkers), kernel_scale=float(init_scale), seed=seed
+        )
+
+    out: list[np.ndarray] = []
+    need = int(n_walkers)
+    tries = 0
+    while need > 0:
+        tries += 1
+        if tries > 50:
+            raise RuntimeError(
+                "Failed to initialize emcee walkers within sampler_bounds. "
+                "Try increasing init_scale or relaxing sampler_bounds."
+            )
+
+        draw = kernel_samples_from_fisher(
+            theta0,
+            fisher,
+            n_samples=max(need, int(n_walkers)),
+            kernel_scale=float(init_scale),
+            seed=None if seed is None else seed + tries
+        )
+        draw = apply_parameter_bounds(draw, sampler_bounds)
+        # apply_parameter_bounds returns an array with shape (n_kept, p).
+        # If n_kept == 0, all proposed walkers fell outside the sampler bounds,
+        # so we retry with a fresh draw.
+        if draw.shape[0] == 0:
+            continue
+
+        take = min(need, draw.shape[0])
+        out.append(draw[:take])
+        need -= take
+
+    return np.vstack(out)
+
+
+def fisher_to_cov(
+    fisher: NDArray[np.floating],
+    *,
+    rcond: float | None = None
+) -> NDArray[np.float64]:
+    """Converts a Fisher matrix to a covariance matrix using pseudoinverse.
+
+    Args:
+        fisher: Fisher information matrix with shape ``(p, p)``.
+        rcond: Cutoff ratio for small singular values in pseudoinverse.
+            If ``None``, the default from ``np.linalg.pinv`` is used.
+
+    Returns:
+        Covariance matrix with shape ``(p, p)`` given by ``pinv(fisher)``.
+
+    Raises:
+        ValueError: If ``fisher`` is not a square 2D array.
+    """
+    fisher = validate_square_matrix(fisher, name="fisher")
+    if rcond is None:
+        return np.linalg.pinv(fisher, hermitian=True)
+    return np.linalg.pinv(fisher, rcond=rcond, hermitian=True)

derivkit/likelihood_kit.py

@@ -0,0 +1,114 @@
+"""Provides the LikelihoodKit class.
+
+Typical usage examples
+----------------------
+
+>>> import numpy as np
+>>> from derivkit.likelihood_kit import LikelihoodKit
+>>>
+>>> # Gaussian example
+>>> data = np.linspace(-5.0, 5.0, 200)
+>>> theta = np.array([0.0])
+>>> cov = np.array([[1.0]])
+>>> lkit = LikelihoodKit(data=data, model_parameters=theta)
+>>> grid, pdf = lkit.gaussian(cov=cov)
+>>>
+>>> # Poissonian example
+>>> counts = np.array([1, 2, 3, 4])
+>>> mu = np.array([0.5, 1.0, 1.5, 2.0])
+>>> lkit = LikelihoodKit(data=counts, model_parameters=mu)
+>>> reshaped_counts, pmf = lkit.poissonian()
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from derivkit.likelihoods.gaussian import build_gaussian_likelihood
+from derivkit.likelihoods.poisson import build_poissonian_likelihood
+
+
+class LikelihoodKit:
+    """High-level interface for Gaussian and Poissonian likelihoods.
+
+    The class stores ``data`` and ``model_parameters`` and provides
+    methods to evaluate the corresponding likelihoods.
+    """
+    def __init__(
+        self,
+        data: ArrayLike,
+        model_parameters: ArrayLike,
+    ) -> None:
+        """Initialises the likelihoods object.
+
+        Args:
+            data: Observed data values. The expected shape depends on the
+                particular likelihoods. For the Gaussian likelihoods, ``data``
+                is 1D or 2D, where axis 0 represents different samples and
+                axis 1 the values. For the Poissonian likelihoods, ``data`` is
+                reshaped to align with ``model_parameters``.
+            model_parameters: Theoretical model values. For the Gaussian
+                likelihoods, this is a 1D array of parameters used as the mean
+                of the multivariate normal. For the Poissonian likelihoods,
+                this is the expected counts (Poisson means).
+        """
+        self.data = np.asarray(data)
+        self.model_parameters = np.asarray(model_parameters)
+
+    def gaussian(
+        self,
+        cov: ArrayLike,
+        *,
+        return_log: bool = True,
+    ) -> tuple[tuple[NDArray[np.float64], ...], NDArray[np.float64]]:
+        """Evaluates a Gaussian likelihoods for the stored data and parameters.
+
+        Args:
+            cov: Covariance matrix. May be a scalar, a 1D vector of diagonal
+                variances, or a full 2D covariance matrix. It will be
+                symmetrized and normalized internally.
+            return_log: If ``True``, return the log-likelihoods instead of
+                the probability density function.
+
+        Returns:
+            A tuple ``(coordinate_grids, probabilities)`` where:
+
+            * ``coordinate_grids`` is a tuple of 1D arrays giving the
+              evaluation coordinates for each dimension.
+            * ``probabilities`` is an array with the values of the
+              multivariate Gaussian probability density (or log-density)
+              evaluated on the Cartesian product of those coordinates.
+        """
+        return build_gaussian_likelihood(
+            data=self.data,
+            model_parameters=self.model_parameters,
+            cov=cov,
+            return_log=return_log,
+        )
+
+    def poissonian(
+        self,
+        *,
+        return_log: bool = True,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Evaluates a Poissonian likelihoods for the stored data and parameters.
+
+        Args:
+            return_log: If ``True``, return the log-likelihoods instead of
+                the probability mass function.
+
+        Returns:
+            A tuple ``(counts, probabilities)`` where:
+
+            * ``counts`` is the data reshaped to align with the
+              model parameters.
+            * ``probabilities`` is an array of Poisson probabilities
+              (or log-probabilities) computed from ``counts`` and
+              ``model_parameters``.
+        """
+        return build_poissonian_likelihood(
+            data=self.data,
+            model_parameters=self.model_parameters,
+            return_log=return_log,
+        )

derivkit/likelihoods/__init__.py

@@ -0,0 +1 @@
+"""Likelihood utilities."""

derivkit/likelihoods/gaussian.py

@@ -0,0 +1,136 @@
+"""Gaussian likelihoods function module."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.stats import multivariate_normal
+
+from derivkit.utils.linalg import normalize_covariance
+
+__all__ = [
+    "build_gaussian_likelihood",
+]
+
+
+def build_gaussian_likelihood(
+    data: ArrayLike,
+    model_parameters: ArrayLike,
+    cov: ArrayLike,
+    return_log: bool = True,
+    ) -> tuple[tuple[NDArray[np.float64], ...], NDArray[np.float64]]:
+    """Constructs the Gaussian likelihoods function.
+
+    Args:
+        data: a 1D or 2D array representing the given data values. It is
+            expected that axis 0 represents different samples of data while
+            axis 1 represents the data values.
+        model_parameters: a 1D array representing the theoretical values
+            of the model parameters.
+        cov: covariance matrix. May be a scalar, a 1D vector of diagonal variances,
+            or a full 2D covariance matrix. It will be symmetrised and normalized
+            internally to ensure compatibility with the data and model_parameters.
+        return_log: when set to ``True``, return the log-likelihoods instead of
+            the probability density function.
+
+    Returns:
+        A tuple:
+          - coordinate_grids: tuple of 1D arrays giving the evaluation coordinates
+            for each dimension (one array per dimension), ordered consistently with
+            the first axis of ``data``.
+          - probability_density: ndarray with the values of the multivariate
+            Gaussian probability density function evaluated on the Cartesian
+            product of those coordinates.
+
+    Raises:
+        ValueError: raised if
+            - data is not 1D or 2D,
+            - model_parameters is not 1D,
+            - the number of samples in data does not match the number of
+              model parameters,
+            - model_parameters contain non-finite values,
+            - cov cannot be normalized to a valid covariance matrix.
+
+    Examples:
+        A 1D Gaussian likelihoods:
+            >>> import numpy as np
+            >>> import matplotlib.pyplot as plt
+            >>> from derivkit.likelihoods.gaussian import build_gaussian_likelihood
+            >>> data = np.linspace(-10, 10, 100)[np.newaxis, :]
+            >>> model_parameters = np.array([1.0])
+            >>> cov = np.array([[2.0]])
+            >>> x_grid, pdf = build_gaussian_likelihood(data, model_parameters, cov)
+            >>> plt.plot(x_grid[0], pdf[0])  # doctest: +SKIP
+        A 2D Gaussian likelihoods:
+            >>> import numpy as np
+            >>> import matplotlib.pyplot as plt
+            >>> data = np.asarray((np.linspace(-10, 10, 30), np.linspace(3, 6, 30)))
+            >>> model_parameters = np.array([0.0, 4.0])
+            >>> cov = np.array([[1.0, 0.2], [0.2, 0.3]])
+            >>> # Build coordinate arrays and evaluate the probability density on their
+            >>> # Cartesian product. The indexing ensures the coordinate order matches
+            >>> # the order in ``data``.
+            >>> grid, probability_density = build_gaussian_likelihood(data, model_parameters, cov)
+            >>> plt.contour(*grid, probability_density)  # doctest: +SKIP
+    """
+    # The data is expected to be 2D. However, 1D is allowed, since it can be
+    # embedded in a 2D space.
+    _data = np.array(data, dtype=float, copy=True)
+    if not np.isfinite(_data).all():
+        raise ValueError("data contain non-finite values.")
+    if _data.ndim == 1:
+        _data = _data[np.newaxis, :]
+    elif _data.ndim > 2:
+        raise ValueError(f"data must be a 1D or 2D array, but is a {_data.ndim}D array.")
+
+    number_samples = _data.shape[0]
+    model_parameters = np.asarray(model_parameters, dtype=float)
+    if model_parameters.ndim != 1:
+        raise ValueError(
+            "model_parameters must be a 1D array, "
+            f"but is a {model_parameters.ndim}D array."
+        )
+    model_parameters = model_parameters.ravel()
+    if not np.isfinite(model_parameters).all():
+        raise ValueError("model_parameters contain non-finite values.")
+
+    number_model_parameters = model_parameters.size
+    if number_samples != number_model_parameters:
+        raise ValueError(
+            "There must be as many model parameters as there are samples of data. "
+            f"(n_params={number_model_parameters}, n_samples={number_samples})"
+        )
+
+    cov = np.asarray(cov, dtype=float)
+    if not np.isfinite(cov).all():
+        raise ValueError("cov contains non-finite values.")
+    cov_dim = cov.ndim
+    cov_shape = cov.shape
+    is_scalar = cov_dim == 0
+    is_valid_vector = cov_dim == 1 and cov_shape[0] == number_model_parameters
+    is_valid_matrix = (
+            cov_dim == 2
+            and cov_shape[0] == cov_shape[1] == number_model_parameters
+    )
+    if not (is_scalar or is_valid_vector or is_valid_matrix):
+        raise ValueError(
+            "Input cov is not compatible with input model_parameters."
+        )
+
+    sigma = normalize_covariance(
+        (cov+cov.T)/2,
+        n_parameters=number_model_parameters
+    )
+
+    # The data are coordinate vectors, which have to be extended into a
+    # coordinate grid (meshgrid). The grids are then combined to give a
+    # box of coordinates (dstack), which is then sent to the PDF. The
+    # indexing in meshgrid should ensure that the ordering of the grids
+    # corresponds to the ordering of the original data.
+    coordinate_grids = np.meshgrid(*_data, indexing="ij")
+    coordinate_box = np.dstack(coordinate_grids)
+    distribution = multivariate_normal(mean=model_parameters, cov=sigma)
+    probabilities = distribution.logpdf(coordinate_box) \
+        if return_log \
+        else distribution.pdf(coordinate_box)
+    return coordinate_grids, probabilities