py-lfkit 0.1.4__py3-none-any.whl

lfkit/corrections/color_anchors.py

@@ -0,0 +1,176 @@
+"""Color-anchor utilities for ``kcorrect``.
+
+Core concept:
+  An "anchor" is defined by a single two-band color constraint:
+
+      color = (band_a - band_b) = color_value
+
+where band_a and band_b are *kcorrect response names* (e.g. "sdss_g0").
+
+This module is intentionally agnostic:
+- no galaxy "types"
+- no "red/blue" naming
+- no survey assumptions beyond optional filter mapping wrappers
+
+What this module does:
+  The goal is simply to obtain a set of kcorrect template coefficients that
+  reproduce a specified two-band color at a given redshift. Since a color only
+  fixes a *flux ratio*, the overall normalization of the SED is arbitrary.
+  To make the problem well defined we choose an arbitrary reference magnitude
+  ("anchor") and construct a minimal synthetic photometry vector consistent
+  with the requested color. Those fluxes are then passed to kcorrect to solve
+  for the template mixture.
+
+Important limitations:
+  The resulting coefficients are **not a unique physical SED fit**. A single
+  color constraint leaves large degeneracies in template space. The anchor
+  normalization is purely a gauge choice, and no attempt is made to infer
+  galaxy type, stellar population parameters, dust, or luminosity evolution.
+  The coefficients are therefore best interpreted as a convenient internal
+  representation for evaluating K(z) curves consistent with the specified
+  color constraint.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from lfkit.utils.units import mag_to_maggies
+
+from .kcorrect_backend import build_kcorrect
+
+__all__ = [
+    "fit_coeffs_from_bandcolor",
+]
+
+# Internal normalization (gauge) used to build a concrete photometry vector
+# from a pure color (flux ratio) constraint.
+_ANCHOR_MAG_DEFAULT = 22.0
+
+
+def fit_coeffs_from_bandcolor(
+    *,
+    color: tuple[str, str],
+    color_value: float,
+    z_phot: float = 0.0,
+    anchor_band: str | None = None,
+    anchor_mag: float = _ANCHOR_MAG_DEFAULT,
+    responses: list[str] | None = None,
+    ivar_level: float = 1e10,
+    response_dir: str | Path | None = None,
+    redshift_range: tuple[float, float] = (0.0, 2.0),
+    nredshift: int = 4000,
+    rescale_maggies: bool = True,
+) -> tuple[np.ndarray, list[str]]:
+    """Fit kcorrect coefficients from a single two-band color constraint.
+
+    This routine constructs the minimal synthetic photometry required to
+    reproduce a given color. Because a color only fixes a flux ratio, the
+    overall normalization is arbitrary; we therefore choose an internal
+    anchor magnitude to define a concrete flux scale. The resulting fluxes
+    are passed to kcorrect to solve for a template mixture whose predicted
+    photometry matches the requested color at the specified redshift.
+
+    Args:
+        color: Tuple (band_a, band_b) meaning color = m_a - m_b.
+               These must be kcorrect response names (file stems).
+        color_value: Target color value in magnitudes.
+        z_phot: Redshift at which to fit the coefficients.
+        anchor_band: Band used to set the arbitrary flux normalization.
+                     If None, defaults to band_b.
+        anchor_mag: Magnitude used to set the arbitrary flux normalization.
+        responses: Optional explicit list of responses to use in the fit.
+                   If None, uses the minimal set {band_a, band_b, anchor_band}.
+        ivar_level: Inverse-variance weight for constrained bands.
+        response_dir: Optional directory containing custom response .dat files.
+        redshift_range: Internal kcorrect lookup redshift range.
+        nredshift: Internal kcorrect lookup grid size.
+        rescale_maggies: If True, rescale synthetic maggies to O(1) to reduce
+                         numerical issues; adjusts ivar accordingly.
+
+    Returns:
+        (coeffs, fit_responses)
+        - coeffs: array (n_templates,)
+        - fit_responses: list of responses actually used in the fit
+    """
+    band_a, band_b = map(str, color)  # color = m_a - m_b
+
+    if anchor_band is None:
+        anchor_band = band_b
+
+    # responses used for fitting
+    if responses is None:
+        fit_responses = list(dict.fromkeys([band_a, band_b, str(anchor_band)]))
+    else:
+        fit_responses = list(map(str, responses))
+        missing = [
+            x for x in (band_a, band_b, str(anchor_band)) if x not in fit_responses
+        ]
+        if missing:
+            raise ValueError(f"responses is missing required bands: {missing}")
+
+    kc = build_kcorrect(
+        responses_in=fit_responses,
+        responses_out=fit_responses,
+        responses_map=fit_responses,
+        response_dir=response_dir,
+        redshift_range=redshift_range,
+        nredshift=nredshift,
+    )
+
+    # anchor magnitude -> anchor flux (maggies)
+    f_anchor = float(mag_to_maggies(anchor_mag))
+    if (not np.isfinite(f_anchor)) or f_anchor <= 0:
+        raise ValueError("anchor_mag must map to positive finite maggies.")
+
+    # color = m_a - m_b => f_a / f_b = 10^(-0.4*color)
+    ratio = 10.0 ** (-0.4 * float(color_value))
+    if (not np.isfinite(ratio)) or ratio <= 0:
+        raise ValueError("color_value must be finite.")
+
+    # choose fluxes consistent with color and anchor band choice
+    if anchor_band == band_a:
+        f_a = f_anchor
+        f_b = f_a / ratio
+    elif anchor_band == band_b:
+        f_b = f_anchor
+        f_a = f_b * ratio
+    else:
+        # If anchor_band is distinct, anchor it and set (a,b) relative in a simple way.
+        f_b = f_anchor
+        f_a = f_b * ratio
+
+    flux_map = {band_a: f_a, band_b: f_b, str(anchor_band): f_anchor}
+
+    maggies = np.full(len(fit_responses), np.nan, dtype=float)
+    ivar = np.zeros(len(fit_responses), dtype=float)
+
+    w = float(ivar_level)
+    for i, band in enumerate(fit_responses):
+        if band in flux_map:
+            maggies[i] = float(flux_map[band])
+            ivar[i] = w
+
+    if rescale_maggies:
+        pos = maggies[np.isfinite(maggies) & (maggies > 0)]
+        scale = float(np.nanmedian(pos)) if pos.size else 1.0
+        if np.isfinite(scale) and scale > 0:
+            maggies = maggies / scale
+            ivar = ivar * (scale**2)
+
+    coeffs = kc.fit_coeffs(redshift=float(z_phot), maggies=maggies, ivar=ivar)
+    coeffs = np.asarray(coeffs, float)
+
+    nt = int(kc.templates.restframe_flux.shape[0])
+    if coeffs.shape != (nt,):
+        raise ValueError(f"fit_coeffs returned shape {coeffs.shape}, expected ({nt},)")
+    if not np.all(np.isfinite(coeffs)):
+        raise ValueError("fit_coeffs returned non-finite coeffs.")
+    if np.any(coeffs < 0):
+        raise ValueError("fit_coeffs returned negative coeffs.")
+    if float(np.sum(coeffs)) <= 0:
+        raise ValueError("fit_coeffs returned coeffs with sum<=0.")
+
+    return coeffs, fit_responses

lfkit/corrections/filters.py

@@ -0,0 +1,185 @@
+"""Filter / response mapping utilities.
+
+LFKit uses a survey-oriented way to specify photometric bands:
+
+    (filterset, band)
+
+Examples:
+    ("sdss", "r")
+    ("hsc", "i")
+    ("decam", "r")
+    ("bessell", "V")
+
+Internally, kcorrect does not work with survey names. Instead it expects
+**response curve identifiers**, which correspond to filter throughput
+files distributed with the package.
+
+This module provides a lightweight mapping between the LFKit public
+notation
+
+    (filterset, band)
+
+and the corresponding kcorrect response names. The mapping can also be
+extended or overridden to support custom filter curves.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+KNOWN_FILTERSETS: tuple[str, ...] = (
+    "sdss",
+    "hsc",
+    "decam",
+    "bessell",
+)
+
+DEFAULT_RESPONSE_MAP: dict[tuple[str, str], str] = {
+    ("sdss", "u"): "sdss_u0",
+    ("sdss", "g"): "sdss_g0",
+    ("sdss", "r"): "sdss_r0",
+    ("sdss", "i"): "sdss_i0",
+    ("sdss", "z"): "sdss_z0",
+    ("decam", "u"): "decam_u",
+    ("decam", "g"): "decam_g",
+    ("decam", "r"): "decam_r",
+    ("decam", "i"): "decam_i",
+    ("decam", "z"): "decam_z",
+    ("decam", "Y"): "decam_Y",
+    ("hsc", "g"): "subaru_suprimecam_g",
+    ("hsc", "r"): "subaru_suprimecam_r",
+    ("hsc", "i"): "subaru_suprimecam_i",
+    ("hsc", "z"): "subaru_suprimecam_z",
+    ("bessell", "U"): "bessell_U",
+    ("bessell", "B"): "bessell_B",
+    ("bessell", "V"): "bessell_V",
+    ("bessell", "R"): "bessell_R",
+    ("bessell", "I"): "bessell_I",
+    ("2mass", "J"): "twomass_J",
+    ("2mass", "H"): "twomass_H",
+    ("2mass", "K"): "twomass_Ks",
+}
+
+
+def normalize_filterset(filterset: str) -> str:
+    """Return the canonical LFKit representation of a filterset name.
+
+    Filterset names are normalized to lowercase and stripped of
+    surrounding whitespace so that user input such as "SDSS", "sdss",
+    or " sdss " all resolve to the same canonical form.
+    """
+    return str(filterset).strip().lower()
+
+
+def normalize_band(band: str) -> str:
+    """Normalize a band label.
+
+    Band names are stripped of surrounding whitespace while preserving
+    their case, since some filter systems distinguish between
+    uppercase and lowercase band identifiers.
+    """
+    return str(band).strip()
+
+
+def make_response_map(
+    *,
+    base: dict[tuple[str, str], str] | None = None,
+    extra: dict[tuple[str, str], str] | None = None,
+) -> dict[tuple[str, str], str]:
+    """Create a response mapping dictionary.
+
+    The returned mapping associates (filterset, band) pairs with
+    kcorrect response identifiers. A custom mapping can be created
+    by starting from a base map and overriding or extending entries
+    with the ``extra`` dictionary.
+    """
+    out = dict(DEFAULT_RESPONSE_MAP if base is None else base)
+    if extra:
+        out.update(extra)
+    return out
+
+
+def resolve_response_name(
+    *,
+    filterset: str,
+    band: str,
+    response_map: dict[tuple[str, str], str] | None = None,
+) -> str:
+    """Resolve a survey band to a kcorrect response identifier.
+
+    Given a (filterset, band) pair, this function returns the
+    corresponding kcorrect response name used to load the filter
+    throughput curve. A custom mapping can be provided to support
+    additional surveys or user-defined filters.
+    """
+    fs = normalize_filterset(filterset)
+    b = normalize_band(band)
+    m = DEFAULT_RESPONSE_MAP if response_map is None else response_map
+
+    key = (fs, b)
+    if key in m:
+        return str(m[key])
+
+    available_for_fs = sorted([bb for (ffs, bb) in m.keys() if ffs == fs])
+    if available_for_fs:
+        raise ValueError(
+            f"No response mapping for (filterset, band)=({fs!r}, {b!r}). "
+            f"Known bands for filterset={fs!r}: {available_for_fs}. "
+            "Provide response_map=... to extend the mapping."
+        )
+
+    known_filtersets = sorted(set(ffs for (ffs, _) in m.keys()))
+    raise ValueError(
+        f"No response mapping for filterset={fs!r}. "
+        f"Known filtersets in mapping: {known_filtersets}. "
+        "Provide response_map=... to extend the mapping."
+    )
+
+
+def list_supported(
+    response_map: dict[tuple[str, str], str] | None = None,
+) -> dict[str, list[str]]:
+    """Return the set of supported bands grouped by filterset.
+
+    The output lists all (filterset, band) combinations available
+    in the current response mapping. This is useful for inspecting
+    which survey filters are currently recognized by LFKit.
+    """
+    m = DEFAULT_RESPONSE_MAP if response_map is None else response_map
+    out: dict[str, list[str]] = {}
+    for (fs, band), _resp in m.items():
+        out.setdefault(fs, []).append(band)
+    for fs in out:
+        out[fs] = sorted(set(out[fs]))
+    return dict(sorted(out.items()))
+
+
+def validate_coverage(
+    *,
+    filterset: str,
+    bands: Iterable[str],
+    response_map: dict[tuple[str, str], str] | None = None,
+) -> None:
+    """Check that a set of bands exists in the response mapping.
+
+    This function verifies that all requested bands are defined for
+    the given filterset in the response mapping. If any band is
+    missing, an informative error is raised listing the supported
+    bands for that filterset.
+    """
+    fs = normalize_filterset(filterset)
+    m = DEFAULT_RESPONSE_MAP if response_map is None else response_map
+
+    missing: list[str] = []
+    for b in bands:
+        key = (fs, normalize_band(b))
+        if key not in m:
+            missing.append(str(b))
+
+    if missing:
+        supported = sorted([bb for (ffs, bb) in m.keys() if ffs == fs])
+        raise ValueError(
+            f"Missing response mappings for filterset={fs!r}: {missing}. "
+            f"Supported bands: {supported}. "
+            "Provide response_map=... to extend."
+        )

lfkit/corrections/kcorrect_backend.py

@@ -0,0 +1,149 @@
+"""``kcorrect`` backend construction utilities.
+
+This module provides a small wrapper around ``kcorrect.Kcorrect`` that
+standardizes how LFKit creates and reuses backend instances.
+
+A kcorrect backend depends on the set of input responses, output responses,
+and the redshift grid used internally by the solver. Constructing this object
+can be relatively expensive, so LFKit builds and caches instances associated
+with a specific response configuration.
+
+The wrapper also ensures that requested filter response names exist before
+initializing the backend and allows optional use of custom response
+directories when supported by the installed kcorrect version.
+"""
+
+from __future__ import annotations
+
+import inspect
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import kcorrect.kcorrect as kk
+
+from .responses import require_responses
+
+
+def _kc_cache_key(
+    *,
+    responses_in: tuple[str, ...],
+    responses_out: tuple[str, ...],
+    responses_map: tuple[str, ...],
+    response_dir: str | Path | None,
+    redshift_range: tuple[float, float],
+    nredshift: int,
+    abcorrect: bool,
+) -> tuple:
+    """Build a normalized cache key for a kcorrect backend configuration.
+
+    The key uniquely identifies a backend setup based on the requested
+    filter responses, redshift grid configuration, and optional response
+    directory. This normalized representation allows identical backend
+    configurations to reuse the same cached ``kcorrect.Kcorrect`` instance.
+    """
+    if response_dir is None:
+        rdir_key = "__AUTO__"
+    else:
+        rdir_key = str(Path(response_dir).resolve())
+
+    return (
+        responses_in,
+        responses_out,
+        responses_map,
+        rdir_key,
+        (float(redshift_range[0]), float(redshift_range[1])),
+        int(nredshift),
+        bool(abcorrect),
+    )
+
+
+@lru_cache(maxsize=8)
+def _build_kcorrect_cached(key: tuple) -> kk.Kcorrect:
+    """Construct and cache a ``kcorrect.Kcorrect`` backend instance.
+
+    The input key encodes the response configuration and solver settings.
+    For each unique configuration the corresponding backend is created
+    once and stored in the cache, allowing repeated k(z) evaluations to
+    reuse the same initialized solver.
+    """
+    (
+        responses_in,
+        responses_out,
+        responses_map,
+        rdir_key,
+        redshift_range,
+        nredshift,
+        abcorrect,
+    ) = key
+
+    response_dir: Path | None
+    if rdir_key == "__AUTO__":
+        response_dir = None
+    else:
+        response_dir = Path(rdir_key)
+
+    # validate response names exist
+    require_responses(list(responses_in), response_dir)
+    require_responses(list(responses_out), response_dir)
+    require_responses(list(responses_map), response_dir)
+
+    kwargs: dict[str, Any] = dict(
+        responses=list(responses_in),
+        responses_out=list(responses_out),
+        responses_map=list(responses_map),
+        redshift_range=[float(redshift_range[0]), float(redshift_range[1])],
+        nredshift=int(nredshift),
+        abcorrect=bool(abcorrect),
+    )
+
+    if response_dir is not None:
+        sig = inspect.signature(kk.Kcorrect)
+        if "response_dir" in sig.parameters:
+            kwargs["response_dir"] = str(response_dir)
+        else:
+            raise TypeError(
+                "This kcorrect version does not support response_dir=... in kk.Kcorrect(...). "
+                "To use custom filters, install a kcorrect build that supports response_dir, "
+                "or place your *.dat filter files into kcorrect’s packaged response directory."
+            )
+
+    return kk.Kcorrect(**kwargs)
+
+
+def build_kcorrect(
+    *,
+    responses_in: list[str],
+    responses_out: list[str] | None = None,
+    responses_map: list[str] | None = None,
+    response_dir: str | Path | None = None,
+    redshift_range: tuple[float, float] = (0.0, 2.0),
+    nredshift: int = 4000,
+    abcorrect: bool = False,
+) -> kk.Kcorrect:
+    """Create a kcorrect backend configured for a specific response setup.
+
+    This function returns a ``kcorrect.Kcorrect`` instance configured with the
+    requested input and output filter responses. The backend defines the template
+    set and internal redshift grid used to evaluate k-corrections.
+
+    Backend objects are cached so that repeated calls with the same configuration
+    reuse the existing instance rather than rebuilding the solver each time. This
+    keeps repeated k(z) evaluations fast while ensuring that the requested filter
+    responses are validated before use.
+    """
+    if responses_out is None:
+        responses_out = responses_in
+    if responses_map is None:
+        responses_map = responses_in
+
+    key = _kc_cache_key(
+        responses_in=tuple(map(str, responses_in)),
+        responses_out=tuple(map(str, responses_out)),
+        responses_map=tuple(map(str, responses_map)),
+        response_dir=response_dir,
+        redshift_range=(float(redshift_range[0]), float(redshift_range[1])),
+        nredshift=int(nredshift),
+        abcorrect=bool(abcorrect),
+    )
+    return _build_kcorrect_cached(key)

lfkit/corrections/kcorrect_from_color.py

@@ -0,0 +1,111 @@
+"""kcorrect k(z) evaluation from a single color anchor.
+
+This module provides a minimal path from a **two-band color constraint**
+to a k(z) curve. The idea is straightforward: a rest-frame color fixes a
+flux ratio between two bands, which constrains the mixture of kcorrect
+SED templates. Once the corresponding template coefficients are obtained,
+kcorrect can be evaluated across redshift to produce the resulting k(z).
+
+Only a single color constraint is used. No galaxy types or population
+labels are introduced, and no attempt is made to infer a physical galaxy
+classification. The color simply defines a template mixture that is
+consistent with the specified flux ratio, which is then used to evaluate
+k(z) for the requested output response band.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from .color_anchors import fit_coeffs_from_bandcolor
+from .kcorrect_backend import build_kcorrect
+
+__all__ = [
+    "kcorrect_from_bandcolor",
+]
+
+# Internal normalization used to construct a concrete photometry vector
+# for the fitter. This is a gauge choice in one-color mode.
+_ANCHOR_MAG_DEFAULT = 22.0
+
+
+def kcorrect_from_bandcolor(
+    *,
+    z: np.ndarray,
+    response_out: str,
+    color: tuple[str, str],
+    color_value: float,
+    z_phot: float = 0.0,
+    anchor_band: str | None = None,
+    anchor_mag: float = _ANCHOR_MAG_DEFAULT,
+    band_shift: float | None = None,
+    response_dir: str | Path | None = None,
+    redshift_range: tuple[float, float] = (0.0, 2.0),
+    nredshift: int = 4000,
+    ivar_level: float = 1e10,
+    anchor_z0: bool = True,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compute k(z) for a single output response from a two-band color.
+
+    This routine converts a color constraint into kcorrect template
+    coefficients and evaluates the resulting k(z) curve on the supplied
+    redshift grid. The color defines the relative flux between two bands,
+    which constrains the template mixture used by kcorrect.
+
+    Because a color only fixes a flux ratio, the overall normalization of
+    the spectrum is arbitrary. An internal anchor magnitude is therefore
+    used to define a concrete photometry vector for the fit. The resulting
+    coefficients should be interpreted as a convenient representation of
+    an SED consistent with the specified color rather than a unique
+    physical galaxy model.
+    """
+    z = np.asarray(z, float)
+    if z.ndim != 1 or z.size < 2 or np.any(~np.isfinite(z)):
+        raise ValueError("z must be a finite 1D array with >=2 points.")
+
+    coeffs, _fit_responses = fit_coeffs_from_bandcolor(
+        color=color,
+        color_value=float(color_value),
+        z_phot=float(z_phot),
+        anchor_band=anchor_band,
+        anchor_mag=float(anchor_mag),
+        responses=None,
+        ivar_level=float(ivar_level),
+        response_dir=response_dir,
+        redshift_range=redshift_range,
+        nredshift=int(nredshift),
+        rescale_maggies=True,
+    )
+
+    kc = build_kcorrect(
+        responses_in=[str(response_out)],
+        responses_out=[str(response_out)],
+        responses_map=[str(response_out)],
+        response_dir=response_dir,
+        redshift_range=redshift_range,
+        nredshift=nredshift,
+    )
+
+    K = np.full_like(z, np.nan, dtype=float)
+    for i, zi in enumerate(z):
+        if band_shift is None:
+            kval = kc.kcorrect(redshift=float(zi), coeffs=coeffs)
+        else:
+            kval = kc.kcorrect(
+                redshift=float(zi), coeffs=coeffs, band_shift=float(band_shift)
+            )
+        K[i] = float(np.asarray(kval, float)[0])
+
+    ok = np.isfinite(K)
+    if np.count_nonzero(ok) < 2:
+        raise ValueError(
+            f"Too few finite K(z) points for response_out={response_out!r}."
+        )
+
+    if anchor_z0:
+        i0 = int(np.where(ok)[0][0])
+        K[ok] = K[ok] - K[i0]
+
+    return z[ok], K[ok]