lfkit.api.corrections module#

Unified k- and e-correction interface.

This module is the user-facing entry point for LFKit photometric corrections. It provides a small, stable API for evaluating:

k(z) bandpass (k-) correction e(z) luminosity evolution (e-) correction ke(z) combined correction, ke(z) = k(z) + e(z)

Design goals#

  • Keep the runtime API minimal and stable: k(z), e(z), ke(z)

  • Make backend choices explicit and composable:

    • k(z) backend: “poggianti” or “kcorrect”

    • e(z) backend: “none” or “poggianti”

  • Use astronomy-friendly inputs at the public boundary:

    • filterset: “sdss”, “hsc”, “decam”, “bessell”, …

    • band: “r”, “i”, “V”, …

    • Poggianti uses a typed table key (gal_type)

    • kcorrect uses an SED mixture specified by a color anchor

Reality check about kcorrect#

kcorrect returns k(z) for a chosen SED mixture and filter response. It does not encode physical luminosity evolution by itself. If you want e(z), you supply a separate evolution model (for example from Poggianti tabulations), and LFKit combines them consistently.

Sign convention#

Absolute magnitude is defined as:

M = m - DM(z) - k(z) + e(z)

With this convention, if galaxies were brighter in the past, then e(z) is typically negative for z > z_piv in pivoted evolution models.

Notes on filter names and kcorrect responses#

In LFKit the public choice of a band is expressed as (filterset, band). kcorrect internally uses response curve identifiers (file stems). LFKit maps:

(filterset, band) -> response_name

You can override or extend this mapping via response_map when working with custom surveys or custom filter curves.

class lfkit.api.corrections.Corrections(k_func, e_func=None, *, meta=None)[source]#

Bases: object

Evaluator for k(z), e(z), and ke(z).

This object wraps callables representing the k-correction and the luminosity evolution correction and provides a consistent interface for evaluating:

k(z) e(z) ke(z) = k(z) + e(z)

Instances are typically created through the class constructors Corrections.poggianti or Corrections.kcorrect.

Parameters:

  • k_func (Callable[[ArrayLike], ArrayLike]) – Callable returning k(z).

  • e_func (Callable[[ArrayLike], ArrayLike] | None) – Optional callable returning e(z). If None, e(z)=0.

  • meta (dict[str, object] | None) – Optional metadata dictionary describing the backend configuration.

e(z)[source]#

Evaluate the luminosity evolution correction.

Parameters:

z (object) – Scalar or array-like redshift.

Returns:

NumPy array containing e(z). If no evolution model is attached, zeros are returned.

Return type:

ndarray

k(z)[source]#

Evaluate the k-correction.

Parameters:

z (object) – Scalar or array-like redshift.

Returns:

NumPy array containing k(z).

Return type:

ndarray

classmethod kcorrect(*, z_grid=None, response_out, color, color_value, z_phot=0.0, anchor_band=None, anchor_mag=22.0, band_shift=None, response_dir=None, redshift_range=(0.0, 2.0), nredshift=4000, ivar_level=10000000000.0, anchor_z0=True, method='pchip', extrapolate=True)[source]#

Construct k(z) using the kcorrect SED template model.

The spectral energy distribution (SED) is constrained by a two-band color. The color fixes a flux ratio between two bands, which determines a mixture of kcorrect templates consistent with that constraint. The resulting template mixture is then used to evaluate k(z) for the requested output response.

Parameters:

  • z_grid (object | None) – Redshift grid used to compute the k(z) curve. If None, a default grid spanning redshift_range is used.

  • response_out (str) – kcorrect response name for which k(z) is evaluated.

  • color (tuple[str, str]) – Two-band color constraint (band_a, band_b).

  • color_value (float) – Target color value in magnitudes.

  • z_phot (float) – Redshift at which the color constraint is applied.

  • anchor_band (str | None) – Band used to set the arbitrary flux normalization.

  • anchor_mag (float) – Magnitude used to set the arbitrary flux normalization.

  • band_shift (float | None) – Optional kcorrect band shift parameter.

  • response_dir (str | Path | None) – Directory containing custom response curves.

  • redshift_range (tuple[float, float]) – Internal redshift range used by kcorrect.

  • nredshift (int) – Internal redshift grid size used by kcorrect.

  • ivar_level (float) – Weight assigned to constrained photometric bands.

  • anchor_z0 (bool) – Whether to normalize so that k(z=0)=0.

  • method (str) – Interpolation method used to construct k(z).

  • extrapolate (bool) – Whether to allow extrapolation outside the computed redshift range.

Returns:

Corrections instance evaluating k(z). In this configuration e(z) = 0.

Return type:

Corrections

ke(z)[source]#

Evaluate the combined correction ke(z).

Parameters:

z (object) – Scalar or array-like redshift.

Returns:

NumPy array containing ke(z) = k(z) + e(z).

Return type:

ndarray

classmethod poggianti(*, band, gal_type, cosmo=None, original_z_for_e=True, method='pchip', extrapolate=True, e_model='poggianti')[source]#

Construct corrections from Poggianti (1997) tabulated models.

Parameters:

  • band (str) – Poggianti band identifier (e.g. “V”, “B”).

  • gal_type (str) – Galaxy spectral type in the Poggianti tables (e.g. “E”, “Sc”).

  • cosmo – Optional cosmology object used for lookback-time calculations in the evolution correction.

  • original_z_for_e (bool) – Whether the evolution correction is evaluated on the original Poggianti redshift grid.

  • method (str) – Interpolation method for the tabulated curves.

  • extrapolate (bool) – Whether to allow extrapolation outside the tabulated redshift range.

  • e_model (str) – Evolution backend (“poggianti” or “none”).

Returns:

Corrections instance capable of evaluating k(z), e(z), and ke(z).

Raises:

ValueError – If an unsupported evolution model is requested.

Return type:

Corrections