lfkit.photometry.catalog_completeness module#

Catalog completeness utilities for luminosity function models.

This module provides helpers for estimating the observed and missing galaxy population implied by a magnitude-limited catalog. These functions are useful for applications that need an out-of-catalog correction, such as galaxy-catalog priors for gravitational-wave cosmology.

The utilities convert an apparent magnitude limit into an absolute magnitude limit and call the generic LF integration helpers to return number densities or fractions.

The core API accepts a luminosity function callable with signature

lf(absolute_mag, z)

where absolute_mag and z are NumPy arrays that can be broadcast together. This keeps the completeness machinery independent of any specific luminosity function parameterization.

lfkit.photometry.catalog_completeness.absolute_magnitude_limit(cosmo_obj, z, *, m_lim, h=None, k_correction=None, e_correction=None)[source]#

Return the absolute magnitude limit of an apparent magnitude catalog cut.

This converts an apparent magnitude limit into the corresponding limiting absolute magnitude at each redshift,

\[M_{\mathrm{lim}}(z) = m_{\mathrm{lim}} - \mu(z) - K(z) + E(z).\]
Parameters:

  • cosmo_obj (Any) – A PyCCL cosmology object.

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • m_lim (float) – Apparent magnitude limit of the catalog.

  • h (float | None) – Optional dimensionless Hubble parameter used in the distance-modulus convention. If not provided, this is read from cosmo_obj["h"].

  • k_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional k-correction term(s).

  • e_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional evolution-correction term(s).

Returns:

NumPy array of limiting absolute magnitudes.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.catalog_completeness.catalog_completeness_fraction(cosmo_obj, z, lf, *, m_lim, m_bright, m_faint, n_m=512, h=None, k_correction=None, e_correction=None)[source]#

Return the LF fraction observable in a magnitude-limited catalog.

This returns

\[f_{\mathrm{obs}}(z) = \frac{n_{\mathrm{obs}}(z)} {n_{\mathrm{obs}}(z) + n_{\mathrm{miss}}(z)}.\]
Parameters:

  • cosmo_obj (Any) – A PyCCL cosmology object.

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_lim (float) – Apparent magnitude limit of the catalog.

  • m_bright (float) – Bright absolute magnitude bound of the LF model.

  • m_faint (float) – Faint absolute magnitude bound of the LF model.

  • n_m (int) – Number of magnitude-grid points used for the integral.

  • h (float | None) – Optional dimensionless Hubble parameter used in the distance-modulus convention.

  • k_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional k-correction term(s).

  • e_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional evolution-correction term(s).

Returns:

NumPy array of catalog completeness fractions.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.catalog_completeness.missing_number_density(cosmo_obj, z, lf, *, m_lim, m_bright, m_faint, n_m=512, h=None, k_correction=None, e_correction=None)[source]#

Return number density missing from a magnitude-limited catalog.

This integrates the luminosity function over galaxies fainter than the catalog limit,

\[n_{\mathrm{miss}}(z) = \int_{\max[M_{\lim}(z), M_{\mathrm{bright}}]}^{M_{\mathrm{faint}}} \phi(M, z) \, dM.\]
Parameters:

  • cosmo_obj (Any) – A PyCCL cosmology object.

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_lim (float) – Apparent magnitude limit of the catalog.

  • m_bright (float) – Bright absolute magnitude bound of the LF model.

  • m_faint (float) – Faint absolute magnitude bound of the LF model.

  • n_m (int) – Number of magnitude-grid points used for the integral.

  • h (float | None) – Optional dimensionless Hubble parameter used in the distance-modulus convention.

  • k_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional k-correction term(s).

  • e_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional evolution-correction term(s).

Returns:

NumPy array of missing number densities.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.catalog_completeness.observed_number_density(cosmo_obj, z, lf, *, m_lim, m_bright, m_faint, n_m=512, h=None, k_correction=None, e_correction=None)[source]#

Return number density observable in a magnitude-limited catalog.

This integrates the luminosity function over galaxies brighter than the catalog limit,

\[n_{\mathrm{obs}}(z) = \int_{M_{\mathrm{bright}}}^{\min[M_{\lim}(z), M_{\mathrm{faint}}]} \phi(M, z) \, dM.\]
Parameters:

  • cosmo_obj (Any) – A PyCCL cosmology object.

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_lim (float) – Apparent magnitude limit of the catalog.

  • m_bright (float) – Bright absolute magnitude bound of the LF model.

  • m_faint (float) – Faint absolute magnitude bound of the LF model.

  • n_m (int) – Number of magnitude-grid points used for the integral.

  • h (float | None) – Optional dimensionless Hubble parameter used in the distance-modulus convention.

  • k_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional k-correction term(s).

  • e_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional evolution-correction term(s).

Returns:

NumPy array of observed number densities.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

lfkit.photometry.catalog_completeness.out_of_catalog_fraction(cosmo_obj, z, lf, *, m_lim, m_bright, m_faint, n_m=512, h=None, k_correction=None, e_correction=None)[source]#

Return the LF fraction missing from a magnitude-limited catalog.

This returns

\[f_{\mathrm{miss}}(z) = 1 - f_{\mathrm{obs}}(z).\]
Parameters:

  • cosmo_obj (Any) – A PyCCL cosmology object.

  • z (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]]) – Redshift value or array-like of redshift values.

  • lf (Callable[[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Luminosity-function callable with signature lf(M, z).

  • m_lim (float) – Apparent magnitude limit of the catalog.

  • m_bright (float) – Bright absolute magnitude bound of the LF model.

  • m_faint (float) – Faint absolute magnitude bound of the LF model.

  • n_m (int) – Number of magnitude-grid points used for the integral.

  • h (float | None) – Optional dimensionless Hubble parameter used in the distance-modulus convention.

  • k_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional k-correction term(s).

  • e_correction (float | Sequence[float] | ndarray[tuple[Any, ...], dtype[float64]] | None) – Optional evolution-correction term(s).

Returns:

NumPy array of out-of-catalog fractions.

Return type:

ndarray[tuple[Any, …], dtype[float64]]