fimx 0.1.0__py3-none-any.whl

fimx/__init__.py

@@ -0,0 +1,22 @@
+"""Functions for Fisher information on labeled xarray matrices."""
+
+from .combination import combine, gaussian_prior
+from .construction import matrix
+from .datasets import dataset
+from .inversion import errors, inv
+from .parameters import expand, fix, marginalize, transform
+from .plotting import plot
+
+__all__ = [
+    "combine",
+    "dataset",
+    "errors",
+    "expand",
+    "fix",
+    "gaussian_prior",
+    "inv",
+    "marginalize",
+    "matrix",
+    "plot",
+    "transform",
+]

fimx/cli.py

@@ -0,0 +1,97 @@
+"""Command-line interface for plotting Fisher forecasts."""
+
+from argparse import ArgumentParser, BooleanOptionalAction
+from collections.abc import Sequence
+from json import loads
+from pathlib import Path
+
+from .io import load_dataset
+from .plotting import plot
+
+
+def _parser() -> ArgumentParser:
+    """Build the command-line argument parser."""
+    parser = ArgumentParser(
+        description="Overlay Fisher forecast Datasets in a corner plot."
+    )
+    parser.add_argument(
+        "--file",
+        dest="files",
+        action="append",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="NetCDF Dataset to plot; repeat to overlay multiple forecasts.",
+    )
+    parser.add_argument(
+        "--figure-file",
+        type=Path,
+        default=Path("plot.png"),
+        metavar="PATH",
+        help="Output figure path (default: plot.png).",
+    )
+    parser.add_argument(
+        "--figure-dpi",
+        type=int,
+        default=150,
+        metavar="DPI",
+        help="Output resolution in dots per inch (default: 150).",
+    )
+    parser.add_argument(
+        "--parameters",
+        nargs="+",
+        metavar="NAME",
+        help="Parameters to include in the plot, in the requested order.",
+    )
+    parser.add_argument(
+        "--filled",
+        action=BooleanOptionalAction,
+        default=True,
+        help="Fill two-dimensional contours (default; use --no-filled for lines).",
+    )
+    parser.add_argument(
+        "--backend",
+        default="getdist",
+        metavar="NAME",
+        help="Plotting backend (default: getdist).",
+    )
+    parser.add_argument(
+        "--backend-kwargs",
+        type=loads,
+        metavar="JSON",
+        help="JSON object of backend-specific plotting options.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Load Fisher forecast files, plot them, and save the figure.
+
+    Parameters
+    ----------
+    argv : sequence of str, optional
+        Arguments to parse. Defaults to the process command line.
+    """
+    parser = _parser()
+    args = parser.parse_args(argv)
+    datasets = {}
+    for path in args.files:
+        label = path.stem
+        if label in datasets:
+            parser.error(
+                f"Input filenames must have unique stems; duplicate {label!r}."
+            )
+        datasets[label] = load_dataset(path)
+
+    figure = plot(
+        datasets,
+        parameters=args.parameters,
+        filled=args.filled,
+        backend=args.backend,
+        backend_kwargs=args.backend_kwargs,
+    )
+    figure.savefig(args.figure_file, dpi=args.figure_dpi)
+
+
+if __name__ == "__main__":
+    main()

fimx/combination.py

@@ -0,0 +1,67 @@
+"""Combination of independent information and Gaussian priors."""
+
+import operator
+from collections.abc import Mapping
+from functools import reduce
+
+import numpy as np
+import xarray as xr
+
+from .construction import _labels, _new_matrix, _real_values, _validate_matrix
+from .parameters import expand
+
+
+def combine(*matrices: xr.DataArray) -> xr.DataArray:
+    """Add independent information over the union of parameter labels.
+
+    Parameters
+    ----------
+    *matrices : xarray.DataArray
+        One or more matrices satisfying the canonical matrix contract.
+
+    Returns
+    -------
+    xarray.DataArray
+        Fresh sum. Keep the first input order and append newly encountered
+        labels in subsequent input order; absent entries contribute zero.
+
+    Raises
+    ------
+    ValueError
+        If no matrices are supplied or any matrix is malformed.
+    """
+    if not matrices:
+        raise ValueError("At least one matrix is required.")
+    labels = [list(_validate_matrix(F)[1]) for F in matrices]
+    union = list(dict.fromkeys(label for group in labels for label in group))
+    total = reduce(operator.add, (expand(F, union) for F in matrices))
+    return _new_matrix(total.values, union)
+
+
+def gaussian_prior(sigmas: Mapping[str, float]) -> xr.DataArray:
+    """Construct independent Gaussian prior information from standard deviations.
+
+    Parameters
+    ----------
+    sigmas : mapping of str to float
+        Nonempty mapping of unique parameter names to finite, positive
+        standard deviations. Mapping order determines matrix order.
+
+    Returns
+    -------
+    xarray.DataArray
+        Fresh diagonal matrix with entries ``1 / sigma**2``.
+
+    Raises
+    ------
+    ValueError
+        If names or standard deviations are invalid, or information cannot
+        be represented as finite float64 values.
+    """
+    labels = _labels(list(sigmas), name="sigmas")
+    deviations = _real_values(list(sigmas.values()))
+    if np.any(deviations <= 0):
+        raise ValueError("Standard deviations must be positive.")
+    with np.errstate(over="ignore", divide="ignore", invalid="ignore"):
+        information = np.square(1 / deviations)
+    return _new_matrix(np.diag(information), labels)

fimx/construction.py

@@ -0,0 +1,100 @@
+"""Construction and shared validation of labeled dense matrices."""
+
+from collections.abc import Sequence
+
+import numpy as np
+import xarray as xr
+from numpy.typing import ArrayLike, NDArray
+
+
+def _labels(parameters: Sequence[str], *, name: str) -> list[str]:
+    """Validate a nonempty sequence of unique string labels."""
+    if isinstance(parameters, str):
+        # A bare string is an invalid label sequence, even for one parameter.
+        raise ValueError(f"{name} must be a sequence of parameter names.")  # noqa: TRY004
+    labels = list(parameters)
+    if not labels or any(not isinstance(label, str) for label in labels):
+        raise ValueError(f"{name} must be a nonempty sequence of unique string labels.")
+    if len(set(labels)) != len(labels):
+        raise ValueError(f"{name} must contain unique string labels.")
+    return labels
+
+
+def _real_values(values: ArrayLike) -> NDArray[np.float64]:
+    """Convert finite, real numeric data to float64."""
+    array = np.asarray(values)
+    if array.dtype.kind not in "iuf":
+        raise ValueError("Values must be real numeric data.")
+    with np.errstate(over="ignore", invalid="ignore"):
+        result = np.asarray(array, dtype=np.float64)
+    if not np.all(np.isfinite(result)):
+        raise ValueError("Values must be finite.")
+    return result
+
+
+def _coordinate_labels(array: xr.DataArray, dimension: str) -> list[str]:
+    """Read an explicit one-dimensional parameter coordinate."""
+    if dimension not in array.coords or array.coords[dimension].dims != (dimension,):
+        raise ValueError(f"An explicit coordinate for {dimension!r} is required.")
+    return _labels(array.coords[dimension].values.tolist(), name=dimension)
+
+
+def _validate_matrix(F: xr.DataArray) -> tuple[xr.DataArray, list[str]]:
+    """Validate a canonical matrix without checking positive definiteness."""
+    if not isinstance(F, xr.DataArray):
+        raise TypeError("Matrix inputs must be xarray.DataArray objects.")
+    if F.dims != ("row", "col"):
+        raise ValueError("Matrix dimensions must be exactly ('row', 'col').")
+    if F.shape[0] == 0 or F.shape[0] != F.shape[1]:
+        raise ValueError("Matrices must be nonempty and square.")
+    parameters = _coordinate_labels(F, "row")
+    if parameters != _coordinate_labels(F, "col"):
+        raise ValueError("Row and column parameter coordinates must match in order.")
+    values = _real_values(F.values)
+    if not np.allclose(values, values.T, rtol=1e-10, atol=1e-12):
+        raise ValueError("Matrices must be symmetric.")
+    return _new_matrix(values, parameters), parameters
+
+
+def _new_matrix(values: ArrayLike, parameters: Sequence[str]) -> xr.DataArray:
+    """Create a fresh matrix with only canonical coordinates."""
+    labels = list(parameters)
+    return xr.DataArray(
+        _real_values(values).copy(),
+        dims=("row", "col"),
+        coords={"row": labels, "col": labels.copy()},
+    )
+
+
+def matrix(values: ArrayLike, parameters: Sequence[str]) -> xr.DataArray:
+    """Construct a labeled, symmetric dense matrix.
+
+    Parameters
+    ----------
+    values : array_like
+        Nonempty square array of finite, real numeric values.
+    parameters : sequence of str
+        Unique parameter names, in matrix order.
+
+    Returns
+    -------
+    xarray.DataArray
+        Fresh float64 matrix with dimensions ``('row', 'col')``.
+
+    Raises
+    ------
+    ValueError
+        If the values or parameter names violate the matrix contract.
+
+    Notes
+    -----
+    Symmetry uses ``rtol=1e-10`` and ``atol=1e-12``. Positive definiteness
+    is checked only by operations requiring a Cholesky solve.
+    """
+    labels = _labels(parameters, name="parameters")
+    array = _real_values(values)
+    if array.ndim != 2 or array.shape != (len(labels), len(labels)):
+        raise ValueError("Values must be square and match the parameter count.")
+    result = _new_matrix(array, labels)
+    _validate_matrix(result)
+    return result

fimx/datasets.py

@@ -0,0 +1,72 @@
+"""Construction of labeled Fisher matrix Datasets with parameter metadata."""
+
+from collections.abc import Hashable, Mapping
+
+import numpy as np
+import xarray as xr
+from numpy.typing import ArrayLike
+
+from .construction import _validate_matrix
+
+
+def dataset(
+    F: xr.DataArray, arrays: Mapping[Hashable, ArrayLike | xr.DataArray]
+) -> xr.Dataset:
+    """Combine a Fisher matrix and arrays on shared parameter coordinates.
+
+    Parameters
+    ----------
+    F : xarray.DataArray
+        Canonical matrix with dimensions ``('row', 'col')``.
+    arrays : mapping of hashable to array_like or xarray.DataArray
+        Additional variables. One-dimensional arrays use ``row``; two-
+        dimensional arrays use ``('row', 'col')``. Plain arrays follow matrix
+        order. DataArray dimensions are renamed by position and indexed axes
+        are aligned by label. Unindexed axes follow matrix order. Names
+        ``fisher``, ``row``, and ``col`` are reserved.
+
+    Returns
+    -------
+    xarray.Dataset
+        Independent variables with shared matrix coordinates. Additional
+        arrays retain their dtypes; positive definiteness is not required.
+
+    Raises
+    ------
+    TypeError
+        If F is not a DataArray or arrays is not a mapping.
+    ValueError
+        If the matrix is invalid, names are reserved, arrays are not one- or
+        two-dimensional, or xarray rejects incompatible sizes or coordinates.
+
+    Notes
+    -----
+    Shape, coordinate, and merge compatibility are checked by xarray.
+    Metadata need not be numeric or finite. Plotting validates fiducials.
+    """
+    fisher, _ = _validate_matrix(F)
+    if not isinstance(arrays, Mapping):
+        raise TypeError("Arrays must be a mapping of names to arrays.")
+    variables: dict[Hashable, xr.DataArray] = {"fisher": fisher}
+    dimensions = {1: ("row",), 2: ("row", "col")}
+    ordered = fisher.sortby(["row", "col"])
+    for name, array in arrays.items():
+        if name in {"fisher", "row", "col"}:
+            raise ValueError(f"Variable name {name!r} is reserved.")
+        variable = (
+            array
+            if isinstance(array, xr.DataArray)
+            else xr.DataArray(np.asarray(array))
+        )
+        if variable.ndim not in dimensions:
+            raise ValueError("Additional arrays must be one- or two-dimensional.")
+        dims = dimensions[variable.ndim]
+        variable = variable.rename(dict(zip(variable.dims, dims, strict=True)))
+        variable = variable.assign_coords(
+            {dim: fisher.coords[dim] for dim in dims if dim not in variable.indexes}
+        )
+        # Exact alignment on sorted coordinates permits reordered labels while
+        # letting xarray reject missing, extra, or duplicate labels and sizes.
+        xr.align(ordered, variable.sortby(list(dims)), join="exact")
+        variables[name] = variable.sel({dim: fisher.coords[dim] for dim in dims})
+    return xr.Dataset(variables).copy(deep=True)

fimx/inversion.py

@@ -0,0 +1,78 @@
+"""Cholesky inversion and marginalized constraints."""
+
+import numpy as np
+import xarray as xr
+from xarray_einstats import linalg
+
+from .construction import _new_matrix, _validate_matrix
+
+
+def _solve(values: xr.DataArray, rhs: xr.DataArray) -> xr.DataArray:
+    """Solve a positive definite system using labeled Cholesky operations."""
+    chol = linalg.cholesky(values, dims=("row", "col"))
+    intermediate = linalg.solve(chol, rhs, dims=("row", "col", "rhs_col"))
+    return linalg.solve(
+        chol.transpose("col", "row"),
+        intermediate,
+        dims=("col", "row", "rhs_col"),
+    ).rename(rhs_col="col")
+
+
+def inv(F: xr.DataArray) -> xr.DataArray:
+    """Return the labeled inverse, or covariance of a Fisher matrix.
+
+    Parameters
+    ----------
+    F : xarray.DataArray
+        Matrix satisfying the canonical matrix contract.
+
+    Returns
+    -------
+    xarray.DataArray
+        Fresh symmetric inverse with the input parameter order.
+
+    Raises
+    ------
+    numpy.linalg.LinAlgError
+        If the matrix is singular or not positive definite.
+    ValueError
+        If the matrix contract is violated.
+    """
+    values, parameters = _validate_matrix(F)
+    rhs = xr.DataArray(
+        np.eye(len(parameters)),
+        dims=("row", "rhs_col"),
+        coords={"row": parameters, "rhs_col": parameters},
+    )
+    covariance = _solve(values, rhs)
+    raw = covariance.values
+    return _new_matrix(raw / 2 + raw.T / 2, parameters)
+
+
+def errors(F: xr.DataArray) -> xr.DataArray:
+    """Return marginalized standard deviations from a Fisher matrix.
+
+    Parameters
+    ----------
+    F : xarray.DataArray
+        Matrix satisfying the canonical matrix contract.
+
+    Returns
+    -------
+    xarray.DataArray
+        Square roots of the covariance diagonal on dimension ``parameter``.
+
+    Raises
+    ------
+    numpy.linalg.LinAlgError
+        If the matrix is singular or not positive definite.
+    ValueError
+        If the matrix contract is violated.
+    """
+    covariance = inv(F)
+    diagonal = linalg.diagonal(covariance, dims=("row", "col"))
+    return xr.DataArray(
+        np.sqrt(diagonal.values),
+        dims=("parameter",),
+        coords={"parameter": covariance.coords["row"].values.copy()},
+    )

fimx/io.py

@@ -0,0 +1,24 @@
+"""NetCDF loading helpers."""
+
+from os import PathLike
+
+import xarray as xr
+
+
+def load_dataset(path: str | PathLike[str]) -> xr.Dataset:
+    """Load a NetCDF Dataset using the optional h5netcdf engine.
+
+    Parameters
+    ----------
+    path : str or os.PathLike
+        Path to a NetCDF file.
+
+    Returns
+    -------
+    xarray.Dataset
+        Loaded Dataset.
+    """
+    return xr.load_dataset(path, engine="h5netcdf")
+
+
+__all__ = ["load_dataset"]

fimx/parameters.py

@@ -0,0 +1,204 @@
+"""Parameter addition, removal and changes of variables."""
+
+from collections.abc import Sequence
+
+import xarray as xr
+from xarray_einstats import linalg
+
+from .construction import (
+    _coordinate_labels,
+    _labels,
+    _new_matrix,
+    _real_values,
+    _validate_matrix,
+)
+from .inversion import _solve
+
+
+def _selection(
+    labels: list[str], parameters: str | Sequence[str]
+) -> tuple[list[int], list[int]]:
+    """Resolve parameter removal while preserving retained input order."""
+    selected = [parameters] if isinstance(parameters, str) else list(parameters)
+    if any(not isinstance(name, str) for name in selected):
+        raise ValueError("Selected parameters must be strings.")
+    if len(set(selected)) != len(selected):
+        raise ValueError("Selected parameters must be unique.")
+    for name in selected:
+        if name not in labels:
+            raise KeyError(name)
+    if len(selected) == len(labels):
+        raise ValueError("Cannot remove all parameters.")
+    removed = set(selected)
+    return (
+        [i for i, name in enumerate(labels) if name not in removed],
+        [i for i, name in enumerate(labels) if name in removed],
+    )
+
+
+def expand(F: xr.DataArray, parameters: Sequence[str]) -> xr.DataArray:
+    """Embed a matrix in a larger parameter set, filling new entries with zeros.
+
+    Parameters
+    ----------
+    F : xarray.DataArray
+        Matrix satisfying the canonical matrix contract.
+    parameters : sequence of str
+        Unique target names, in the desired output order. Must contain every
+        name in ``F``; the order may differ from that of ``F``.
+
+    Returns
+    -------
+    xarray.DataArray
+        Fresh matrix over ``parameters``. Entries involving names absent from
+        ``F`` are zero, so matrices expanded to the same ``parameters`` can be
+        added directly with ``+``.
+
+    Raises
+    ------
+    ValueError
+        If input is malformed, ``parameters`` is invalid, or a name in ``F``
+        is missing from ``parameters``.
+    """
+    values, labels = _validate_matrix(F)
+    target = _labels(parameters, name="parameters")
+    missing = [name for name in labels if name not in target]
+    if missing:
+        raise ValueError(f"parameters is missing names present in F: {missing}.")
+    filled = values.reindex(row=target, col=target, fill_value=0)
+    return _new_matrix(filled.values, target)
+
+
+def fix(F: xr.DataArray, parameters: str | Sequence[str]) -> xr.DataArray:
+    """Fix selected parameters by keeping the remaining principal submatrix.
+
+    Parameters
+    ----------
+    F : xarray.DataArray
+        Matrix satisfying the canonical matrix contract.
+    parameters : str or sequence of str
+        Names to remove. An empty sequence returns a fresh copy.
+
+    Returns
+    -------
+    xarray.DataArray
+        Fresh principal submatrix in retained input order.
+
+    Raises
+    ------
+    KeyError
+        If a selected name is unknown.
+    ValueError
+        If input is malformed, names are duplicated, or all are removed.
+    """
+    values, labels = _validate_matrix(F)
+    keep, _ = _selection(labels, parameters)
+    retained = [labels[i] for i in keep]
+    selected = values.sel(row=retained, col=retained)
+    return _new_matrix(selected.values, retained)
+
+
+def marginalize(F: xr.DataArray, parameters: str | Sequence[str]) -> xr.DataArray:
+    """Remove nuisance parameters through the Schur complement.
+
+    Parameters
+    ----------
+    F : xarray.DataArray
+        Matrix satisfying the canonical matrix contract.
+    parameters : str or sequence of str
+        Names to remove. An empty sequence returns a fresh copy.
+
+    Returns
+    -------
+    xarray.DataArray
+        Fresh marginalized matrix in retained input order.
+
+    Raises
+    ------
+    KeyError
+        If a selected name is unknown.
+    ValueError
+        If input is malformed, names are duplicated, or all are removed.
+    numpy.linalg.LinAlgError
+        If the removed block is singular or not positive definite.
+
+    Notes
+    -----
+    For retained block A, cross block B and removed block D, compute
+    ``A - B @ solve(D, B.T)``. Only D must be positive definite.
+    """
+    values, labels = _validate_matrix(F)
+    keep, drop = _selection(labels, parameters)
+    retained = [labels[i] for i in keep]
+    removed = [labels[i] for i in drop]
+    result = values.sel(row=retained, col=retained)
+    if drop:
+        cross = values.sel(row=retained, col=removed)
+        rhs = cross.transpose("col", "row").rename(row="rhs_col").rename(col="row")
+        solved = _solve(values.sel(row=removed, col=removed), rhs).rename(
+            row="drop_parameter", col="rhs_col"
+        )
+        product = linalg.matmul(
+            cross,
+            solved,
+            dims=(("row", "col"), ("drop_parameter", "rhs_col")),
+        ).rename(rhs_col="col")
+        result = result - product
+    raw = result.values
+    return _new_matrix(raw / 2 + raw.T / 2, retained)
+
+
+def transform(F: xr.DataArray, jacobian: xr.DataArray) -> xr.DataArray:
+    """Change variables using a labeled Jacobian of old with respect to new.
+
+    Parameters
+    ----------
+    F : xarray.DataArray
+        Matrix satisfying the canonical matrix contract.
+    jacobian : xarray.DataArray
+        Finite real array with dimensions ``('old', 'new')``
+        and unique string coordinates. Entries are
+        ``J[i, j] = d theta_i / d phi_j``. Old labels must match all F labels;
+        rows are reordered to F. New labels must be nonempty.
+
+    Returns
+    -------
+    xarray.DataArray
+        Fresh symmetric matrix ``J.T @ F @ J`` in new-parameter order.
+
+    Raises
+    ------
+    ValueError
+        If the matrix or Jacobian contract is violated.
+    TypeError
+        If the Jacobian is not a DataArray.
+    """
+    values, labels = _validate_matrix(F)
+    if not isinstance(jacobian, xr.DataArray):
+        raise TypeError("The Jacobian must be an xarray.DataArray.")
+    if jacobian.dims != ("old", "new"):
+        raise ValueError("Jacobian dimensions must be ('old', 'new').")
+    old = _coordinate_labels(jacobian, "old")
+    new = _coordinate_labels(jacobian, "new")
+    if set(old) != set(labels):
+        raise ValueError(
+            "Jacobian old labels must match the complete matrix parameters."
+        )
+    J = xr.DataArray(
+        _real_values(jacobian.sel(old=labels).values),
+        dims=("old", "new"),
+        coords={"old": labels, "new": new},
+    ).rename(old="col")
+    right = linalg.matmul(values, J, dims=("row", "col", "new"))
+    left = J.transpose("new", "col")
+    right = right.rename(row="old", new="new_right")
+    result = linalg.matmul(
+        left,
+        right,
+        dims=(
+            ("new", "col"),
+            ("old", "new_right"),
+        ),
+    ).rename(new="row", new_right="col")
+    raw = result.values
+    return _new_matrix(raw / 2 + raw.T / 2, new)

fimx/plotting/__init__.py

@@ -0,0 +1,88 @@
+"""Backend selection for Fisher forecast plots."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+import xarray as xr
+
+from .base import PlotBackend
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+
+def _getdist() -> PlotBackend:
+    """Load the optional GetDist implementation."""
+    try:
+        from .getdist import plot
+    except ModuleNotFoundError as exc:
+        if exc.name not in {"getdist", "matplotlib"}:
+            raise
+        raise ImportError(
+            "The GetDist backend requires plotting dependencies. "
+            "Install them with uv add 'fimx[plotting]'."
+        ) from exc
+    return plot
+
+
+_BACKENDS: dict[str, Callable[[], PlotBackend]] = {"getdist": _getdist}
+
+
+def plot(
+    datasets: Mapping[str, xr.Dataset],
+    *,
+    parameters: Sequence[str] | None = None,
+    filled: bool = True,
+    backend: str = "getdist",
+    backend_kwargs: Mapping[str, Any] | None = None,
+) -> Figure:
+    """Plot overlaid marginalized constraints from labeled Fisher forecasts.
+
+    Parameters
+    ----------
+    datasets : mapping of str to xarray.Dataset
+        Nonempty forecast mapping. Keys provide legend labels and overlay
+        order. Each Dataset requires ``fisher`` on ``('row', 'col')`` and
+        finite ``fiducials`` on ``row`` with matching parameter coordinates.
+    parameters : sequence of str, optional
+        Unique parameters present in every forecast, in plotting order.
+        Defaults to their intersection in the first forecast's order.
+        Omitted parameters are marginalized over.
+    filled : bool
+        Whether to fill two-dimensional contours. Default is True.
+    backend : str
+        Backend name. Currently only ``'getdist'`` is supported.
+    backend_kwargs : mapping, optional
+        GetDist ``triangle_plot`` options excluding ``roots``, ``params``,
+        ``legend_labels``, and ``filled``. Native styles and confidence
+        levels apply unless customized.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        Figure for editing or saving; it is not automatically shown or saved.
+
+    Raises
+    ------
+    TypeError
+        If containers have incorrect types or backend options are reserved.
+    ValueError
+        If data are invalid, no parameters are shared, or backend is unknown.
+    KeyError
+        If a requested parameter is unavailable in any forecast.
+    numpy.linalg.LinAlgError
+        If any complete Fisher matrix is singular or not positive definite.
+    ImportError
+        If the selected backend's optional dependencies are unavailable.
+    """
+    if backend not in _BACKENDS:
+        raise ValueError(f"Unknown plotting backend {backend!r}. Available: getdist.")
+    implementation = _BACKENDS[backend]()
+    return implementation(
+        datasets, parameters=parameters, filled=filled, backend_kwargs=backend_kwargs
+    )
+
+
+__all__ = ["plot"]

fimx/plotting/base.py

@@ -0,0 +1,98 @@
+"""Backend protocol and shared preparation for marginalized Gaussian plots."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+import numpy as np
+import xarray as xr
+from numpy.typing import NDArray
+
+from ..construction import _labels, _real_values, _validate_matrix
+from ..inversion import inv
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+
+class PlotBackend(Protocol):
+    """Callable interface implemented by each plotting backend."""
+
+    def __call__(
+        self,
+        datasets: Mapping[str, xr.Dataset],
+        *,
+        parameters: Sequence[str] | None = None,
+        filled: bool = True,
+        backend_kwargs: Mapping[str, Any] | None = None,
+    ) -> Figure:
+        """Return a Figure overlaying the supplied forecasts."""
+        ...
+
+
+@dataclass(frozen=True)
+class _Gaussian:
+    """Prepared marginal distribution for one forecast."""
+
+    label: str
+    mean: NDArray[np.float64]
+    covariance: NDArray[np.float64]
+
+
+def _validate_dataset(forecast: xr.Dataset) -> xr.Dataset:
+    """Validate the Fisher matrix and numeric reference values for plotting."""
+    if not isinstance(forecast, xr.Dataset):
+        raise TypeError("Plot inputs must be xarray.Dataset objects.")
+    if not {"fisher", "fiducials"}.issubset(forecast.data_vars):
+        raise ValueError("Datasets must contain 'fisher' and 'fiducials' variables.")
+    fisher, labels = _validate_matrix(forecast["fisher"])
+    reference = forecast["fiducials"]
+    if reference.dims != ("row",):
+        raise ValueError("Fiducial dimensions must be exactly ('row',).")
+    return xr.Dataset(
+        {
+            "fisher": fisher,
+            "fiducials": xr.DataArray(
+                _real_values(reference.values).copy(),
+                dims="row",
+                coords={"row": labels},
+            ),
+        }
+    )
+
+
+def _prepare(
+    datasets: Mapping[str, xr.Dataset], parameters: Sequence[str] | None
+) -> tuple[list[str], list[_Gaussian]]:
+    """Validate forecasts and select marginalized Gaussian distributions."""
+    if not isinstance(datasets, Mapping):
+        raise TypeError("Plot inputs must be a mapping of labels to Datasets.")
+    if not datasets:
+        raise ValueError("At least one Dataset is required.")
+    if any(not isinstance(label, str) for label in datasets):
+        raise ValueError("Plot labels must be strings.")
+    forecasts = {label: _validate_dataset(ds) for label, ds in datasets.items()}
+    first = next(iter(forecasts.values()))
+    if parameters is None:
+        names = [
+            name
+            for name in first.row.values.tolist()
+            if all(name in ds.row.values for ds in forecasts.values())
+        ]
+        if not names:
+            raise ValueError("Datasets have no shared parameters to plot.")
+    else:
+        names = _labels(parameters, name="parameters")
+        for label, ds in forecasts.items():
+            for name in names:
+                if name not in ds.row.values:
+                    raise KeyError(f"Parameter {name!r} is absent from {label!r}.")
+    distributions = []
+    for label, ds in forecasts.items():
+        covariance = inv(ds["fisher"]).sel(row=names, col=names)
+        distributions.append(
+            _Gaussian(label, ds["fiducials"].sel(row=names).values, covariance.values)
+        )
+    return names, distributions

fimx/plotting/getdist.py

@@ -0,0 +1,68 @@
+"""Analytic Gaussian corner plots using GetDist."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import xarray as xr
+from getdist import plots
+from getdist.gaussian_mixtures import GaussianND
+from matplotlib.figure import Figure
+
+from .base import PlotBackend, _prepare
+
+
+def plot(
+    datasets: Mapping[str, xr.Dataset],
+    *,
+    parameters: Sequence[str] | None = None,
+    filled: bool = True,
+    backend_kwargs: Mapping[str, Any] | None = None,
+) -> Figure:
+    """Overlay marginalized Gaussian forecasts with GetDist.
+
+    Parameters
+    ----------
+    datasets : mapping of str to xarray.Dataset
+        Forecasts containing ``fisher`` and ``fiducials`` variables.
+    parameters : sequence of str, optional
+        Ordered parameter selection; otherwise use the common parameters.
+    filled : bool
+        Whether to fill the two-dimensional contours.
+    backend_kwargs : mapping, optional
+        Additional arguments to GetDist's ``triangle_plot``.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        Figure containing the overlaid forecasts.
+
+    Raises
+    ------
+    TypeError
+        If backend options override arguments controlled by this function.
+    """
+    options = dict(backend_kwargs or {})
+    reserved = {"roots", "params", "legend_labels", "filled"}.intersection(options)
+    if reserved:
+        raise TypeError(
+            f"Backend options cannot override: {', '.join(sorted(reserved))}."
+        )
+    names, distributions = _prepare(datasets, parameters)
+    roots = [
+        GaussianND(item.mean, item.covariance, names=names, label=item.label)
+        for item in distributions
+    ]
+    plotter = plots.get_subplot_plotter()
+    plotter.triangle_plot(
+        roots,
+        params=names,
+        legend_labels=[item.label for item in distributions],
+        filled=filled,
+        **options,
+    )
+    figure = plotter.fig
+    assert figure is not None
+    return figure
+
+
+_backend: PlotBackend = plot

fimx-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: fimx
+Version: 0.1.0
+Summary: Dense Fisher matrix functions on labeled xarray arrays
+Keywords: fisher-matrix,forecasting,cosmology,xarray
+Author: binado
+Author-email: binado <bernardopveronese@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: xarray-einstats>=0.10.0
+Requires-Dist: h5netcdf[h5py] ; extra == 'io'
+Requires-Dist: getdist ; extra == 'plotting'
+Requires-Dist: matplotlib ; extra == 'plotting'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/binado/fimx
+Project-URL: Repository, https://github.com/binado/fimx
+Project-URL: Issues, https://github.com/binado/fimx/issues
+Project-URL: Changelog, https://github.com/binado/fimx/blob/main/CHANGELOG.md
+Provides-Extra: io
+Provides-Extra: plotting
+Description-Content-Type: text/markdown
+
+# fimx
+
+`fimx` provides functions for dense Fisher information matrices stored
+as ordinary `xarray.DataArray` objects. NumPy handles the computation; xarray
+handles labels, metadata containers, and persistence.
+
+```sh
+uv add fimx
+# Optional NetCDF backend:
+uv add 'fimx[io]'
+# Optional Gaussian plotting backend:
+uv add 'fimx[plotting]'
+```
+
+## Quickstart
+
+```python
+from fimx import combine, errors, fix, gaussian_prior, inv, marginalize, matrix
+
+F = matrix([[4, 1], [1, 2]], ["a", "b"])
+fixed = fix(F, "b")  # [[4.0]]: b is held fixed
+reduced = marginalize(F, "b")  # [[3.5]]: uncertainty in b is integrated out
+C = inv(F)  # covariance, with the same row/col labels
+sigma = errors(F)  # sqrt(diag(C)), dimension "parameter"
+
+prior = gaussian_prior({"a": 0.5})  # standard deviation 0.5 -> information 4
+posterior = combine(F, prior)
+```
+
+| Function | Behavior |
+| --- | --- |
+| `matrix(values, parameters)` | Construct and validate a canonical matrix. |
+| `expand(F, parameters)` | Embed in a larger or reordered parameter set, filling with zeros. |
+| `fix(F, parameters)` | Remove names through a principal submatrix. |
+| `marginalize(F, parameters)` | Remove names through the Schur complement. |
+| `inv(F)` | Return the inverse using Cholesky. |
+| `errors(F)` | Return marginalized standard deviations. |
+| `transform(F, jacobian)` | Change variables using `J.T @ F @ J`. |
+| `combine(*matrices)` | Sum independent information over the parameter union. |
+| `gaussian_prior(sigmas)` | Construct diagonal information `1 / sigma**2`. |
+
+## Array contract
+
+- Matrices have dimensions exactly `("row", "col")`, a nonempty square shape,
+  and explicit, identical, ordered coordinates of unique string names.
+  Batches, inferred dimensions, and coordinate repair are unsupported.
+- Values must be real, finite, and symmetric. They are converted to float64.
+- Positive semidefiniteness is not checked, so singular matrices can be built,
+  fixed, transformed, or combined. `inv` and `errors` require positive
+  definite input; `marginalize` only requires the removed block to be.
+- Functions return fresh DataArrays and never mutate their inputs. Attributes,
+  names, and auxiliary coordinates are not preserved.
+- Arrays built directly with xarray work if they meet the contract.
+
+Behavior worth knowing:
+
+- `fix` and `marginalize` accept one name or a sequence and keep the remaining
+  order. Unknown names raise `KeyError`; duplicates or removing every
+  parameter raise `ValueError`.
+- `expand` embeds a matrix in a larger or reordered set of names, filling new
+  entries with zeros. The target must contain every existing name. Matrices
+  expanded to the same names add with plain `+`, whereas `+` on mismatched
+  names silently keeps only the overlap.
+- `combine` keeps the first matrix's order and appends new parameters as they
+  appear. Missing entries contribute zero.
+- `gaussian_prior` takes **standard deviations**, not information values.
+- Failures are explicit: `ValueError` for malformed or non-finite data,
+  `TypeError` for non-DataArray inputs, and `numpy.linalg.LinAlgError` for
+  singular or indefinite matrices. There is no pseudoinverse or regularization.
+
+### Changes of variables
+
+The Jacobian has dimensions `("old", "new")` and orientation
+**`J[i, j] = d theta_i / d phi_j`**, where theta are the old parameters and phi
+the new ones. Every old parameter must appear exactly once (rows are reordered
+to match `F`), and the order of the new parameters sets the output order.
+Rectangular Jacobians are supported.
+
+```python
+import xarray as xr
+from fimx import transform
+
+# theta_a = 2 * phi_x, theta_b = phi_x
+# Rows deliberately appear in reverse order to F.
+J = xr.DataArray(
+    [[1.0], [2.0]],
+    dims=("old", "new"),
+    coords={"old": ["b", "a"], "new": ["x"]},
+)
+G = transform(F, J)  # [[22.0]]
+```
+
+## Plotting
+
+Plotting needs the `plotting` extra (GetDist and Matplotlib, loaded lazily).
+
+### Forecast Datasets
+
+Keep fiducials separate from the Fisher matrix and bundle them with
+`dataset()`. In the mapping of extra variables, 1D arrays use `row` and 2D
+arrays use `(row, col)`; plain arrays follow matrix order and indexed axes are
+aligned by label. Strings, units, and nonfinite metadata are allowed. The names
+`fisher`, `row`, and `col` are reserved.
+
+### Corner plots
+
+```python
+from fimx import dataset, plot
+
+fiducials = xr.DataArray([1.0, 2.0], dims="row", coords={"row": ["a", "b"]})
+survey_a = dataset(F, {"fiducials": fiducials, "units": ["km", "s"]})
+survey_b = dataset(2 * F, {"fiducials": fiducials})
+
+fig = plot({"Survey A": survey_a, "Survey B": survey_b})
+fig.savefig("constraints.pdf")
+
+# Explicit order and GetDist customization:
+fig = plot(
+    {"Survey A": survey_a, "Survey B": survey_b},
+    parameters=["b", "a"],
+    backend="getdist",
+    filled=False,
+    backend_kwargs={"contour_colors": ["C0", "C1"]},
+)
+```
+
+- `plot()` takes a nonempty mapping of labels to Datasets with `fisher` and
+  finite, real `fiducials`. Each forecast is centered on its own fiducials;
+  mapping order sets the overlay order and keys become legend labels.
+- By default, the plot uses the parameters shared by all forecasts, in the
+  first forecast's order. An explicit `parameters` list must be unique and
+  present in every forecast.
+- Each full Fisher matrix is inverted before selecting parameters, so omitted
+  parameters are marginalized and every complete matrix (nuisance blocks
+  included) must be positive definite.
+- The GetDist backend draws analytic Gaussians, with no sampling, and returns
+  a Matplotlib `Figure` without showing or saving it. Filled contours are the
+  default. `backend_kwargs` is forwarded to `triangle_plot`, except `roots`,
+  `params`, `legend_labels`, and `filled`, which `plot()` controls.
+- Additional backends implement `fimx.plotting.base.PlotBackend`.
+
+### Command line
+
+With both extras installed, `fimx-plot` draws a corner plot from NetCDF
+Datasets that contain `fisher` and `fiducials`:
+
+```sh
+uv add 'fimx[io,plotting]'
+fimx-plot --file survey-a.nc --file survey-b.nc \
+    --figure-file constraints.png --figure-dpi 200 \
+    --parameters a b --no-filled --backend getdist \
+    --backend-kwargs '{"contour_colors": ["C0", "C1"]}'
+```
+
+Each file stem becomes a legend label, so stems must be unique. The output
+defaults to `plot.png` at 150 dpi. `--parameters` selects and orders
+parameters, `--no-filled` draws line contours, `--backend` picks a backend, and
+`--backend-kwargs` takes a JSON object. `fimx.io.load_dataset(path)` loads the
+same files from Python.
+
+## Storage
+
+There is no `fimx` file format; use xarray. The `io` extra supplies `h5netcdf`.
+
+```python
+F.to_netcdf("fisher.nc", engine="h5netcdf")
+restored = xr.load_dataarray("fisher.nc", engine="h5netcdf")
+C_restored = inv(restored)
+```
+
+## More
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes. `fimx` is released under
+the MIT license; see [LICENSE](LICENSE).

fimx-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+fimx/__init__.py,sha256=KiZtoATZAuidXk1VQQAPacV3nNdHALf1uWBn8aGMsiI,481
+fimx/cli.py,sha256=W2reMC1rGOlYEGV5MS5T279b90BNmIBb2tsF-r4s7PU,2648
+fimx/combination.py,sha256=7WLjJDR7VnY877vlHTtNR_NSrkpCKHAIvaBzGyf6vFA,2210
+fimx/construction.py,sha256=cHxPac74894ZX9VnGJhh0mdFK590ZhHVZlhbDtxrPTU,3956
+fimx/datasets.py,sha256=cZv-Dtw4MWA0ws16OtJuVHNq9aghcta0Pb0RojyNL7Q,2942
+fimx/inversion.py,sha256=vYXKBtRUxywVmJf800UAerwhJTO-RryPn4ZD3gbl-Nk,2238
+fimx/io.py,sha256=HFQa7B51nvtQ13ajL5MneH3w7G_BeKgUxV4jYmq9jdU,451
+fimx/parameters.py,sha256=hSK5OEqHE01zXisBWkwL_IoEbdmG_6hIuGzxN8C3K7c,6860
+fimx/plotting/__init__.py,sha256=qvb06tjlnwHCeFaRmn0pRhvgNOrJeaZqR1zzgRvo36M,2948
+fimx/plotting/base.py,sha256=FsxKHihDh8qYp9PhbISgGiLf3sgAcioAAjv_68YKd9I,3443
+fimx/plotting/getdist.py,sha256=SOIPWVpYw4yYcBak-3HVYOhs_As1AnSGnvsD_TaV_MU,1979
+fimx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fimx-0.1.0.dist-info/licenses/LICENSE,sha256=wn8ZVTnTDUzM-LNP9CaVo-XYYopba86GYhu3wsSvLy0,1080
+fimx-0.1.0.dist-info/WHEEL,sha256=rp-k_VZaX8oABFEtLwG_Df95p8LSKt9-uPyQ4jKH0P4,81
+fimx-0.1.0.dist-info/entry_points.txt,sha256=vFYzACDdtb0n25NcPbzCxSuKN8hob9zREVyXRf2qEHg,45
+fimx-0.1.0.dist-info/METADATA,sha256=-wwmugUGyFfM3uYZtH6lGQrfg0ciIdn4s3SNtUipBnM,7983
+fimx-0.1.0.dist-info/RECORD,,

fimx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.22
+Root-Is-Purelib: true
+Tag: py3-none-any

fimx-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+fimx-plot = fimx.cli:main
+

fimx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bernardo Porto Veronese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.