muse 0.2.0__py3-none-any.whl

muse/__init__.py

@@ -0,0 +1,17 @@
+"""
+====
+muse
+====
+
+A Python library focused on interfacing with data (real or synthetic) for
+NASA's Medium-Class Explorers (MIDEX) Multi-slit Solar Explorer (MUSE).
+
+* `Homepage <https://muse.lmsal.com/>`__
+* `NASA Homepage <https://science.nasa.gov/mission/muse/>`__
+* `Documentation <https://muse-lmsal.readthedocs.io/>`__
+
+"""
+
+from .version import version as __version__
+
+__all__ = ["__version__"]

muse/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = 'gc9eabe1e2'

muse/conftest.py

@@ -0,0 +1,26 @@
+import pytest
+
+from muse.tests.helpers import fake_response, fake_vdem, fake_vdem_offgrid
+from muse.transforms.transforms import reshape_x_to_slit_step
+
+
+@pytest.fixture(scope="session")
+def response():
+    return fake_response()
+
+
+@pytest.fixture
+def raster(vdem):
+    # Function-scoped: tests del attrs on the result, which must not leak across tests.
+    # nslits=35, nraster=11 are the defaults, so the recorded HISTORY string is unchanged.
+    return reshape_x_to_slit_step(vdem)
+
+
+@pytest.fixture(scope="session")
+def vdem():
+    return fake_vdem()
+
+
+@pytest.fixture(scope="session")
+def vdem_offgrid():
+    return fake_vdem_offgrid()

muse/data/README.rst

@@ -0,0 +1,6 @@
+Data directory
+==============
+
+This directory contains data files included with the package source
+code distribution. Note that this is intended only for relatively small files
+- large files should be externally hosted and downloaded as needed.

muse/data/__init__.py

@@ -0,0 +1,106 @@
+"""
+Helpers for downloading the example data used by the documentation gallery.
+"""
+
+import os
+from pathlib import Path
+
+__all__ = ["fetch_example_data"]
+
+_SAMPLE_DATA_URL = "https://github.com/LM-SAL/muse-sample-data/releases/download/v1/"
+
+#: File name -> (download URL, SHA-256 hash, cache subdirectory).
+_REGISTRY = {
+    "muse_example_vdem.zarr": (
+        f"{_SAMPLE_DATA_URL}muse_example_vdem.zarr.tar.gz",
+        "sha256:9736243c13be83b62986095f2cdfc9884c9eae941ff0498c2c2d37551b079c50",
+        "muse_example_vdem",
+    ),
+    "aia_chianti_line_list_94_Fe_sun_coronal_2021_chianti.nc": (
+        f"{_SAMPLE_DATA_URL}aia_chianti_line_list_94_Fe_sun_coronal_2021_chianti.nc",
+        "sha256:f76fe28b1325e809ea4ec61ba916af447826220f436464f1b39d5000af12274e",
+        "chianti_line_lists",
+    ),
+    "eis_chianti_line_list_195_FeXII_sun_coronal_2021_chianti.nc": (
+        f"{_SAMPLE_DATA_URL}eis_chianti_line_list_195_FeXII_sun_coronal_2021_chianti.nc",
+        "sha256:47d046bcfd2c8f4a6ca6417e5a3a26d0ce49abb5a4d3389720dd579a736c35b9",
+        "chianti_line_lists",
+    ),
+    "eis_chianti_line_list_174_175_FeX_sun_coronal_2021_chianti_density.nc": (
+        f"{_SAMPLE_DATA_URL}eis_chianti_line_list_174_175_FeX_sun_coronal_2021_chianti_density.nc",
+        "sha256:c5ee652cee96c1224c338a526fedea631d85fe2bb37499c2ab6254991d9e081c",
+        "chianti_line_lists",
+    ),
+    "muse_sg_response_108_FeXIX108.355_FeXXI108.117_sun_coronal_2021_chianti_effarea.zarr": (
+        f"{_SAMPLE_DATA_URL}muse_sg_response_108_FeXIX108.355_FeXXI108.117_sun_coronal_2021_chianti_effarea.zarr.tar.gz",
+        "sha256:dccba701ae6bbf9043d2d1a29ed6794dc3e88c00c6f757efecb3be2ce6cf10c9",
+        "synthesis_tutorial",
+    ),
+    "muse_sg_response_171_FeIX171.073_sun_coronal_2021_chianti_effarea.zarr": (
+        f"{_SAMPLE_DATA_URL}muse_sg_response_171_FeIX171.073_sun_coronal_2021_chianti_effarea.zarr.tar.gz",
+        "sha256:d93ae1eae64de9d1e33964c3a834374fae2af0d04d5a5378c487cf7379de5e16",
+        "synthesis_tutorial",
+    ),
+    "muse_sg_response_284_FeXV284.163_sun_coronal_2021_chianti_effarea.zarr": (
+        f"{_SAMPLE_DATA_URL}muse_sg_response_284_FeXV284.163_sun_coronal_2021_chianti_effarea.zarr.tar.gz",
+        "sha256:79b58e21d44aa0b92250fad69a90c095d687d4cc72078c80e0cdbe178e1aea98",
+        "synthesis_tutorial",
+    ),
+    "EIS_EffArea_B.005": (
+        "https://hesperia.gsfc.nasa.gov/ssw/hinode/eis/response/EIS_EffArea_B.005",
+        "sha256:b56e5c2873b10bdc9bd31d0f342e5ecc0491ff752ece5807f1d8de2f94d15d64",
+        "eis_calibration",
+    ),
+    "muse_synthetic_spectra.nc": (
+        f"{_SAMPLE_DATA_URL}muse_synthetic_spectra.nc",
+        "sha256:9b9ca430c298a719f7d0b0cb8ff66aa6c9b8d9c91299799d6d506a8d4cd79f58",
+        "synthesis_tutorial",
+    ),
+}
+
+
+def fetch_example_data(name):
+    """
+    Download and cache one of the example data files used by the documentation gallery.
+
+    A VDEM or synthetic spectrum already present in the synthesis-tutorial
+    output directory (``MUSE_SYNTHESIS_TUTORIAL_OUTPUT_DIR``, defaulting to
+    ``examples/synthesis_tutorial/artifacts``) is returned without downloading.
+    Every other file comes from the published copy.
+
+    Parameters
+    ----------
+    name : `str`
+        Name of the file to fetch, e.g. ``"muse_example_vdem.zarr"``.
+
+    Returns
+    -------
+    `pathlib.Path`
+        Path to the local copy of the file.
+    """
+    if name not in _REGISTRY:
+        msg = f"{name!r} is not a known example data file, expected one of: {sorted(_REGISTRY)}"
+        raise ValueError(msg)
+    if name in {"muse_example_vdem.zarr", "muse_synthetic_spectra.nc"}:
+        local_dir = Path(os.environ.get("MUSE_SYNTHESIS_TUTORIAL_OUTPUT_DIR", "examples/synthesis_tutorial/artifacts"))
+        local_path = local_dir / name
+        if local_path.exists():
+            return local_path
+    try:
+        import pooch
+    except ImportError:
+        msg = "pooch is required to download the example data, install it with `pip install pooch`"
+        raise ImportError(msg) from None
+    url, known_hash, subdir = _REGISTRY[name]
+    cache = Path(pooch.os_cache("muse"))
+    if name.endswith(".zarr"):
+        # Zarr stores are directories, published as tarballs; retrieve extracts once.
+        pooch.retrieve(
+            url,
+            known_hash=known_hash,
+            fname=f"{name}.tar.gz",
+            path=cache,
+            processor=pooch.Untar(extract_dir=subdir),
+        )
+        return cache / subdir / name
+    return Path(pooch.retrieve(url, known_hash=known_hash, fname=name, path=cache / subdir))

muse/data/tests/test_data.py

@@ -0,0 +1,25 @@
+import pytest
+
+from muse.data import _REGISTRY, fetch_example_data
+
+
+def test_unknown_name_raises():
+    with pytest.raises(ValueError, match="not a known example data file"):
+        fetch_example_data("nope.nc")
+
+
+def test_registry_entries_well_formed():
+    for url, known_hash, subdir in _REGISTRY.values():
+        assert url.startswith("https://")
+        assert known_hash.startswith("sha256:")
+        assert len(known_hash) == len("sha256:") + 64
+        assert subdir
+
+
+@pytest.mark.parametrize("name", ["muse_example_vdem.zarr", "muse_synthetic_spectra.nc"])
+def test_local_tutorial_output_wins(name, tmp_path, monkeypatch):
+    monkeypatch.setenv("MUSE_SYNTHESIS_TUTORIAL_OUTPUT_DIR", str(tmp_path))
+    local_path = tmp_path / name
+    local_path.touch()
+
+    assert fetch_example_data(name) == local_path

muse/instrument/__init__.py

@@ -0,0 +1,24 @@
+from muse.instrument.linelist import create_chianti_line_list
+from muse.instrument.migration import migrate_response
+from muse.instrument.radiometry import transform_response_units
+from muse.instrument.response import map_response_to_ci_detector, map_response_to_sg_detector
+from muse.instrument.response_io import (
+    align_response_and_vdem,
+    load_and_concat_responses,
+    read_response,
+    save_response,
+)
+from muse.instrument.spectral import create_spectral_response
+
+__all__ = [
+    "align_response_and_vdem",
+    "create_chianti_line_list",
+    "create_spectral_response",
+    "load_and_concat_responses",
+    "map_response_to_ci_detector",
+    "map_response_to_sg_detector",
+    "migrate_response",
+    "read_response",
+    "save_response",
+    "transform_response_units",
+]

muse/instrument/linelist.py

@@ -0,0 +1,361 @@
+"""
+CHIANTI line lists with contribution functions (GOFNT).
+"""
+
+import os
+import re
+import warnings
+from types import ModuleType
+from numbers import Real
+from pathlib import Path
+from importlib import reload
+
+import numpy as np
+import xarray as xr
+
+import astropy.units as u
+
+from muse.utils.utils import add_history
+
+__all__ = ["create_chianti_line_list"]
+
+
+def create_chianti_line_list(
+    temperature: xr.DataArray,
+    density: xr.DataArray | None = None,
+    pressure: xr.DataArray | None = None,
+    abundance: str | None = None,
+    wavelength_range: u.Quantity | None = None,
+    minimum_abundance: float | None = None,
+    element_list: list[str] | None = None,
+    ion_list: list[str] | None = None,
+) -> xr.Dataset:
+    """
+    Generate a line list with contribution functions using ChiantiPy.
+
+    Parameters
+    ----------
+    temperature : `xarray.DataArray`
+        Temperature array with an `astropy.units.Quantity` payload convertible
+        to K and a ``logT`` dimension.
+    density : `xarray.DataArray`, optional
+        Electron density array with an `astropy.units.Quantity` payload
+        convertible to cm^-3. Mutually exclusive with ``pressure``. The output
+        carries this grid on a ``logD`` dimension whose coordinate is
+        ``log10(density)``.
+    pressure : `xarray.DataArray`, optional
+        Electron pressure array with an `astropy.units.Quantity` payload
+        convertible to K cm^-3. Mutually exclusive with ``density``.
+    abundance : `str`, optional
+        CHIANTI abundance name, e.g. ``"sun_coronal_2021_chianti"``. If not
+        given, ChiantiPy's configured default applies
+        (``sun_photospheric_2021_asplund`` unless a ``chiantirc`` file overrides
+        it); the resolved name is recorded in the ``abundance`` attribute.
+    wavelength_range : `astropy.units.Quantity`
+        Two-element wavelength range convertible to Angstroms.
+    minimum_abundance : `float`, optional
+        Finite positive minimum elemental abundance to keep. Mutually exclusive
+        with ``element_list`` and ``ion_list``.
+    element_list : `list` of `str`, optional
+        CHIANTI element symbols to include, such as ``"fe"`` and ``"o"``.
+        Mutually exclusive with ``ion_list`` and ``minimum_abundance``.
+    ion_list : `list` of `str`, optional
+        CHIANTI ion names to include, such as ``"fe_9"``. Mutually exclusive
+        with ``element_list`` and ``minimum_abundance``.
+
+    Returns
+    -------
+    `xarray.Dataset`
+        Line list with contribution functions and per-transition metadata.
+
+    Notes
+    -----
+    The ``XUVTOP`` environment variable must point to a local CHIANTI database.
+    ChiantiPy's ``gui`` default is forced off for headless batch jobs.
+    """
+    temperature, plasma_grid, wavelength_range = _validate_line_list_inputs(
+        temperature, density, pressure, wavelength_range
+    )
+    minimum_abundance, element_list, ion_list = _validate_species_selection(minimum_abundance, element_list, ion_list)
+
+    chiantipy_version, ch = _initialize_chianti()
+
+    if density is not None:
+        plasma_grid = plasma_grid.rename({plasma_grid.dims[0]: "logD"})
+        temperature_bc, density_bc = xr.broadcast(temperature, plasma_grid)
+        extra_coord_name = "logD"
+        extra_coord = np.log10(plasma_grid.data)
+    else:
+        density_bc = plasma_grid / temperature
+        temperature_bc = temperature.broadcast_like(density_bc)
+        extra_coord_name = plasma_grid.dims[0]
+        extra_coord = plasma_grid.data
+    temperature_flat = temperature_bc.data.reshape(-1)
+    density_flat = density_bc.data.reshape(-1)
+
+    chianti_kwargs = {
+        "em": 1.0,
+        "abundance": abundance,
+        "allLines": True,
+        "keepIons": True,
+        "minAbund": minimum_abundance,
+        "ionList": ion_list,
+        "elementList": element_list,
+    }
+    # ChiantiPy cannot descale collision strengths for 1-element arrays; hand it scalars.
+    chianti_temperature = temperature_flat.item() if temperature_flat.size == 1 else temperature_flat
+    chianti_density = density_flat.item() if density_flat.size == 1 else density_flat
+    bunch = ch.bunch(chianti_temperature, chianti_density, wavelength_range, **chianti_kwargs)
+    abundance = getattr(bunch, "AbundanceName", abundance)
+    if abundance is not None:
+        abundance = Path(abundance).stem
+
+    line_list = _chianti_bunch_to_dataset(
+        bunch,
+        temperature=temperature,
+        temperature_bc=temperature_bc,
+        extra_coords={extra_coord_name: extra_coord},
+        wavelength_range=wavelength_range,
+        chiantipy_version=chiantipy_version,
+    )
+    if line_list.sizes["trans_index"] == 0:
+        msg = "CHIANTI returned no lines; check wavelength_range and the species selection"
+        raise ValueError(msg)
+    add_history(line_list, locals(), create_chianti_line_list)
+    return line_list
+
+
+def _initialize_chianti() -> tuple[str, ModuleType]:
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", RuntimeWarning)
+        try:
+            import ChiantiPy  # noqa: PLC0415
+        except ImportError:
+            msg = "ChiantiPy is required for this function, install it with `pip install muse[chianti]`"
+            raise ImportError(msg) from None
+
+    xuvtop = os.environ.get("XUVTOP")
+    if xuvtop is None:
+        msg = (
+            "The XUVTOP environment variable is not set; ChiantiPy cannot locate the CHIANTI database. "
+            "Point it at a local copy of the database, e.g. `export XUVTOP=/path/to/chianti/dbase` "
+            "(available from https://www.chiantidatabase.org)."
+        )
+        raise OSError(msg)
+
+    with warnings.catch_warnings():
+        # Without a chiantirc file, ChiantiPy evaluates os.path.isfile(False)
+        # at import, which raises a RuntimeWarning on Python >= 3.14.
+        warnings.simplefilter("ignore", RuntimeWarning)
+        # ChiantiPy imports its optional ipyparallel implementation from core.
+        warnings.filterwarnings(
+            "ignore",
+            message=r"ipyparallel not found\.",
+            category=UserWarning,
+            module=r"ChiantiPy\.core\.IpyMspectrum",
+        )
+        import ChiantiPy.tools.data as chdata  # noqa: PLC0415
+
+        if not hasattr(chdata, "Defaults") or getattr(chdata, "Xuvtop", None) != xuvtop:
+            chdata = reload(chdata)
+        import ChiantiPy.core as ch  # noqa: PLC0415
+
+    if not hasattr(chdata, "Defaults"):
+        msg = f"ChiantiPy could not initialize the CHIANTI database at {xuvtop}"
+        raise OSError(msg)
+
+    chdata.Defaults["gui"] = False
+    return ChiantiPy.__version__, ch
+
+
+def _chianti_bunch_to_dataset(
+    bunch,
+    *,
+    temperature: xr.DataArray,
+    temperature_bc: xr.DataArray,
+    extra_coords: dict[str, np.ndarray],
+    wavelength_range: tuple[float, float],
+    chiantipy_version: str,
+) -> xr.Dataset:
+    if getattr(bunch, "Intensity", None) is None or len(bunch.Intensity["wvl"]) == 0:
+        msg = "CHIANTI returned no lines; check wavelength_range and the species selection"
+        raise ValueError(msg)
+
+    import ChiantiPy.tools.io as chio  # noqa: PLC0415
+
+    ion_names = bunch.Intensity["ionS"]
+    name_info = {
+        ion: {"spectroscopic": bunch.IonInstances[ion].Spectroscopic, "Z": bunch.IonInstances[ion].Z}
+        for ion in np.unique(ion_names)
+    }
+    per_transition = {
+        "ion_name": ion_names,
+        "wavelength": bunch.Intensity["wvl"],
+        "lower_level_label": bunch.Intensity["pretty1"],
+        "upper_level_label": bunch.Intensity["pretty2"],
+        "lower_level_index": bunch.Intensity["lvl1"],
+        "upper_level_index": bunch.Intensity["lvl2"],
+        "spectroscopic_name": np.array([name_info[ion]["spectroscopic"] for ion in ion_names]),
+        "atomic_number": np.array([name_info[ion]["Z"] for ion in ion_names]),
+        "observed": bunch.Intensity["obs"] == "Y",
+    }
+    line_list = xr.Dataset({name: ("trans_index", values) for name, values in per_transition.items()})
+
+    gofnt_values = bunch.Intensity["intensity"].reshape((*temperature_bc.data.shape, -1))
+    line_list["gofnt"] = xr.DataArray(
+        gofnt_values,
+        dims=(*temperature_bc.dims, "trans_index"),
+        coords={"logT": np.log10(temperature), **extra_coords},
+    )
+    line_list["logT_peak"] = np.log10(temperature[{"logT": line_list.gofnt.argmax(dim="logT")}])
+    line_list["full_name"] = (
+        line_list.spectroscopic_name.astype(object) + " " + line_list.wavelength.astype(str).astype(object)
+    )
+
+    line_list.attrs["Chiantipy"] = chiantipy_version
+    line_list.attrs["Chianti"] = chio.versionRead()
+    line_list.wavelength.attrs["units"] = str(u.AA)
+    line_list.gofnt.attrs["units"] = "erg cm3 / (s sr)"
+    line_list.logT.attrs["units"] = str(u.dex(u.K))
+    if "logD" in line_list.coords:
+        line_list.logD.attrs["units"] = str(u.dex(u.cm**-3))
+
+    in_range = (line_list.wavelength >= wavelength_range[0]) & (line_list.wavelength <= wavelength_range[1])
+    return line_list.isel(trans_index=in_range)
+
+
+def _validate_line_list_inputs(
+    temperature: xr.DataArray,
+    density: xr.DataArray | None,
+    pressure: xr.DataArray | None,
+    wavelength_range: u.Quantity | None,
+) -> tuple[xr.DataArray, xr.DataArray, tuple[float, float]]:
+    if density is None and pressure is None:
+        msg = "Specify density or pressure"
+        raise ValueError(msg)
+    if density is not None and pressure is not None:
+        msg = "density and pressure are mutually exclusive"
+        raise ValueError(msg)
+
+    temperature = _validate_positive_data_array(temperature, "temperature", u.K, dimension="logT")
+    if density is not None:
+        name = "density"
+        plasma_grid = _validate_positive_data_array(density, name, u.cm**-3)
+    else:
+        name = "pressure"
+        plasma_grid = _validate_positive_data_array(pressure, name, u.K / u.cm**3)
+    if plasma_grid.dims[0] in ("logT", "trans_index"):
+        msg = f"{name} dimension must not be named {plasma_grid.dims[0]!r}"
+        raise ValueError(msg)
+
+    return temperature, plasma_grid, _validate_wavelength_range(wavelength_range)
+
+
+def _validate_wavelength_range(wavelength_range: u.Quantity | None) -> tuple[float, float]:
+    if not isinstance(wavelength_range, u.Quantity):
+        msg = "wavelength_range must be an astropy.units.Quantity convertible to Angstrom"
+        raise TypeError(msg)
+    try:
+        values = np.asarray(wavelength_range.to_value(u.AA), dtype=float)
+    except u.UnitConversionError as exc:
+        msg = "wavelength_range units must be convertible to Angstrom"
+        raise ValueError(msg) from exc
+    if values.shape != (2,):
+        msg = "wavelength_range must contain exactly two values"
+        raise ValueError(msg)
+    if not np.all(np.isfinite(values)):
+        msg = "wavelength_range must contain only finite values"
+        raise ValueError(msg)
+    lower, upper = values
+    if lower >= upper:
+        msg = "wavelength_range must be in increasing order"
+        raise ValueError(msg)
+    return float(lower), float(upper)
+
+
+def _validate_positive_data_array(
+    values: xr.DataArray, name: str, unit: u.UnitBase, *, dimension: str | None = None
+) -> xr.DataArray:
+    if not isinstance(values, xr.DataArray):
+        msg = f"{name} must be an xarray.DataArray"
+        raise TypeError(msg)
+    expected_dims = (dimension,) if dimension is not None else None
+    if (expected_dims is not None and values.dims != expected_dims) or (expected_dims is None and values.ndim != 1):
+        qualifier = f"one-dimensional {dimension}" if dimension is not None else "one-dimensional"
+        msg = f"{name} must be a {qualifier} array"
+        raise ValueError(msg)
+    if values.size == 0:
+        msg = f"{name} must not be empty"
+        raise ValueError(msg)
+    if not isinstance(values.data, u.Quantity):
+        msg = f"{name} data must be an astropy.units.Quantity convertible to {unit}"
+        raise TypeError(msg)
+    try:
+        data = values.data.to_value(unit)
+    except u.UnitConversionError as exc:
+        msg = f"{name} units must be convertible to {unit}"
+        raise ValueError(msg) from exc
+    if not np.all(np.isfinite(data)):
+        msg = f"{name} must contain only finite values"
+        raise ValueError(msg)
+    if np.any(data <= 0):
+        msg = f"{name} must contain only positive values"
+        raise ValueError(msg)
+    return values.copy(data=data)
+
+
+def _normalize_species_names(values: list[str] | tuple[str, ...], name: str, pattern: str) -> list[str]:
+    if isinstance(values, str) or not isinstance(values, list | tuple):
+        msg = f"{name} must be a list of strings"
+        raise TypeError(msg)
+    if not values or any(not isinstance(value, str) or not value.strip() for value in values):
+        msg = f"{name} must contain unique, non-empty strings"
+        raise ValueError(msg)
+    normalized = [value.strip().lower() for value in values]
+    if len(set(normalized)) != len(normalized):
+        msg = f"{name} must contain unique, non-empty strings"
+        raise ValueError(msg)
+    normalized.sort()
+    invalid = [value for value in normalized if re.fullmatch(pattern, value) is None]
+    if invalid:
+        msg = f"invalid {name}: {', '.join(invalid)}"
+        raise ValueError(msg)
+    return normalized
+
+
+def _validate_species_selection(
+    minimum_abundance: float | None, element_list: list[str] | None, ion_list: list[str] | None
+) -> tuple[float | None, list[str] | None, list[str] | None]:
+    """
+    Require exactly one species selection and normalize it.
+
+    Returns the ``(minimum_abundance, element_list, ion_list)`` triple with the two
+    unselected entries set to `None`.
+    """
+    given = [
+        name
+        for name, value in (
+            ("minimum_abundance", minimum_abundance),
+            ("element_list", element_list),
+            ("ion_list", ion_list),
+        )
+        if value is not None
+    ]
+    if not given:
+        msg = "Specify minimum_abundance, element_list, or ion_list"
+        raise ValueError(msg)
+    if len(given) > 1:
+        msg = f"{', '.join(given)} are mutually exclusive; give only one"
+        raise ValueError(msg)
+    if element_list is not None:
+        return None, _normalize_species_names(element_list, "element_list", r"[a-z]{1,2}"), None
+    if ion_list is not None:
+        return None, None, _normalize_species_names(ion_list, "ion_list", r"[a-z]{1,2}_[1-9][0-9]*d?")
+    if isinstance(minimum_abundance, bool) or not isinstance(minimum_abundance, Real):
+        msg = "minimum_abundance must be a real number"
+        raise TypeError(msg)
+    minimum_abundance = float(minimum_abundance)
+    if not np.isfinite(minimum_abundance) or minimum_abundance <= 0:
+        msg = "minimum_abundance must be finite and positive"
+        raise ValueError(msg)
+    return minimum_abundance, None, None

muse/instrument/migration.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import xarray as xr
+
+from muse.instrument import response_io
+
+__all__ = ["migrate_response"]
+
+
+def migrate_response(source: str | Path, destination: str | Path) -> tuple[str, str]:
+    """
+    Migrate a legacy response to canonical names at a new destination.
+
+    The migrated response is staged beside the destination and becomes visible
+    only after every stored value has been verified against the source.
+
+    Parameters
+    ----------
+    source : `str` or `pathlib.Path`
+        Existing response file or Zarr store.
+    destination : `str` or `pathlib.Path`
+        New ``.zarr`` or NetCDF destination.
+
+    Returns
+    -------
+    before : `str`
+        Human-readable source schema.
+    after : `str`
+        Human-readable migrated schema.
+    """
+    source = Path(source)
+    destination = Path(destination)
+    if not source.exists():
+        msg = f"Response does not exist: {source}"
+        raise ValueError(msg)
+    if destination.exists():
+        msg = f"Refusing to overwrite existing response: {destination}"
+        raise ValueError(msg)
+    if not destination.parent.is_dir():
+        msg = f"Destination directory does not exist: {destination.parent}"
+        raise ValueError(msg)
+
+    with response_io._open_response_file(source, chunked=True) as opened:
+        before = _schema(opened)
+        canonical = response_io._canonicalize_response_names(opened)
+        with TemporaryDirectory(prefix=f".{destination.name}-", dir=destination.parent) as temporary_directory:
+            staged = Path(temporary_directory) / destination.name
+            response_io.save_response(canonical, staged)
+            with response_io._open_response_file(staged, chunked=True) as written:
+                _verify_values(canonical, written)
+                after = _schema(written)
+            if destination.exists():
+                msg = f"Refusing to overwrite existing response: {destination}"
+                raise ValueError(msg)
+            staged.replace(destination)
+    return before, after
+
+
+def _schema(response: xr.Dataset) -> str:
+    dimensions = ", ".join(f"{name}={size}" for name, size in response.sizes.items())
+    data_variables = ", ".join(f"{name}{response[name].dims}" for name in response.data_vars)
+    coordinates = ", ".join(f"{name}{response[name].dims}" for name in response.coords)
+    return f"dimensions: {dimensions}\ndata variables: {data_variables}\ncoordinates: {coordinates}"
+
+
+def _verify_values(expected: xr.Dataset, actual: xr.Dataset) -> None:
+    try:
+        xr.testing.assert_identical(expected, actual)
+    except AssertionError as exc:
+        msg = "Migrated response does not match the canonical source"
+        raise ValueError(msg) from exc