py-lfkit 0.3.0__tar.gz → 0.5.0__tar.gz

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-lfkit
-Version: 0.3.0
+Version: 0.5.0
 Summary: Luminosity functions and photometric corrections toolkit.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/docs/about/photometry_overview.rst

@@ -202,7 +202,7 @@ Here:
 - :math:`\alpha` is the faint-end slope,
 - :math:`x` is the luminosity ratio :math:`L/L_\star` written in magnitude form.
 
-The parameter :math:`M_\star` marks the transition between the power-law part of
+The parameter :math:`M_\star` marks the transition between the power law part of
 the luminosity function and the exponential bright-end cutoff. The parameter
 :math:`\alpha` controls how rapidly the abundance rises toward fainter
 magnitudes. More negative values of :math:`\alpha` produce a steeper faint end.

py_lfkit-0.5.0/docs/api/index.rst

@@ -0,0 +1,8 @@
+API reference
+=============
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   lfkit

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/docs/examples/conditional_luminosity_function.rst

@@ -25,7 +25,7 @@ mass, or another quantity.
 
 LFKit exposes conditional luminosity functions through
 :class:`lfkit.ConditionalLuminosityFunction`. Each constructor returns a
-luminosity-function object that can be evaluated with
+luminosity function object that can be evaluated with
 ``lf.phi`` and integrated through the usual ``lf.integrals`` namespace.
 
 The examples below use redshift as the conditioning variable because this is
@@ -127,7 +127,7 @@ population evolves.
 Conditional Schechter surface
 -----------------------------
 
-The same conditional Schechter model can be evaluated over the full
+The same conditional luminosity function model can be evaluated over the full
 magnitude-redshift plane rather than at a few selected redshifts.
 
 The filled colour scale shows :math:`\log_{10}\Phi(M \mid z)`. The contours
@@ -387,10 +387,12 @@ The model therefore changes both in amplitude and in shape.
        cmap_range=(0.0, 0.2),
    )
 
-   lf = ConditionalLuminosityFunction.schechter(
+   lf = ConditionalLuminosityFunction.double_schechter(
        phi_star=lambda z: 1.2e-3 * (1.0 + z) ** 0.5,
        m_star=lambda z: -20.3 - 0.5 * (z - 0.1),
        alpha=lambda z: -1.15 - 0.10 * z,
+       beta=lambda z: -0.45 - 0.05 * z,
+       m_transition=lambda z: -19.0 - 0.3 * (z - 0.1),
    )
 
    fig, ax = plt.subplots(figsize=(7.0, 5.0))
@@ -423,7 +425,7 @@ It is useful to compare the component shapes at fixed condition before combining
 them into more complicated models. This separates differences in functional
 form from differences caused by redshift or halo-mass evolution.
 
-The standard Schechter form has a power-law faint end and an exponential
+The standard Schechter form has a power law faint end and an exponential
 bright-end cutoff. The modified Schechter component has a broader bright-end
 shape. The lognormal component is localized around a characteristic luminosity.
 Together, these examples show the kinds of galaxy populations each component is

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/docs/examples/lf_models/composite_models.rst

@@ -5,7 +5,7 @@
 |lfkitlogo| Composite models
 =============================
 
-Composite models combine multiple luminosity-function components. They are
+Composite models combine multiple luminosity function components. They are
 useful when a population is better described as a mixture rather than by one
 single analytic shape.
 
@@ -83,7 +83,7 @@ function with a suppressed bright end.
 Luminosity cutoff modifier
 --------------------------
 
-A luminosity cutoff can be applied to an existing luminosity-function object.
+A luminosity cutoff can be applied to an existing luminosity function object.
 This keeps the base model unchanged and returns a new object whose
 :meth:`lfkit.LuminosityFunction.phi` values are multiplied by a bright-end
 cutoff.

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/docs/examples/lf_models/power_law_models.rst

@@ -13,7 +13,7 @@ a Schechter-like exponential cutoff.
 Single power law
 ----------------
 
-The single power-law model has one slope. In magnitude space, this gives a
+The single power law model has one slope. In magnitude space, this gives a
 straight-line trend when shown on a logarithmic :math:`\Phi(M)` axis.
 
 .. plot::
@@ -58,7 +58,7 @@ straight-line trend when shown on a logarithmic :math:`\Phi(M)` axis.
        r"$\Phi(M)$ [$\mathrm{Mpc}^{-3}\,\mathrm{mag}^{-1}$]",
        fontsize=LABEL_SIZE,
    )
-   ax.set_title("Single power-law luminosity functions", fontsize=TITLE_SIZE)
+   ax.set_title("Single power law luminosity functions", fontsize=TITLE_SIZE)
    ax.tick_params(axis="both", labelsize=TICK_SIZE)
    ax.legend(frameon=True, fontsize=LEGEND_SIZE, loc="best")
    plt.tight_layout()
@@ -148,7 +148,7 @@ and faint sides need different behaviour without using a Schechter cutoff.
 Log-normalized power law
 ------------------------
 
-The log-normalized power-law model is the same power-law shape, but the
+The log-normalized power law model is the same power law shape, but the
 normalization is supplied as ``log_phi_star``. This is convenient for fitting
 or sampling applications where the normalization is naturally varied in
 logarithmic space.
@@ -199,7 +199,7 @@ logarithmic space.
        r"$\Phi(M)$ [$\mathrm{Mpc}^{-3}\,\mathrm{mag}^{-1}$]",
        fontsize=LABEL_SIZE,
    )
-   ax.set_title("Log-normalized power-law models", fontsize=TITLE_SIZE)
+   ax.set_title("Log-normalized power law models", fontsize=TITLE_SIZE)
    ax.tick_params(axis="both", labelsize=TICK_SIZE)
    ax.legend(frameon=True, fontsize=LEGEND_SIZE, loc="best")
    plt.tight_layout()

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/docs/examples/lf_models/schechter_models.rst

@@ -5,7 +5,7 @@
 |lfkitlogo| Schechter family models
 ===================================
 
-The Schechter family contains luminosity functions with a power-law faint end
+The Schechter family contains luminosity functions with a power law faint end
 and a bright-end cutoff. These models are commonly used when the abundance of
 faint galaxies rises approximately as a power law, while the most luminous
 galaxies are exponentially rare.

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/pyproject.toml

@@ -120,20 +120,18 @@ commands = [
 ]
 
 [tool.tox.env.docs]
-description = "Build docs with Sphinx and doctest"
+description = "Build docs with Sphinx"
 extras = ["docs", "viz"]
 commands = [
   [
-    "sphinx-apidoc",
-    "-d", "2",
-    "-o", "{tox_root}/docs/api",
-    "{tox_root}/src/lfkit",
-    "--separate",
-    "--no-toc",
-    "-f",
+    "rm",
+    "-rf",
+    "{tox_root}/docs/_build",
+    "{tox_root}/docs/api/generated",
   ],
   [
     "sphinx-build",
+    "-E",
     "-c", "{tox_root}/docs",
     "-b", "{posargs:html}",
     "{tox_root}/docs",
@@ -144,27 +142,18 @@ commands = [
 
 [tool.tox.env.do]
 description = "Run doctests + html build and open local docs"
-recreate = true
 extras = ["docs", "viz"]
 allowlist_externals = ["open", "rm"]
 commands = [
   [
     "rm",
     "-rf",
-    "{tox_root}/docs/_build/doctest",
-    "{tox_root}/docs/_build/html",
-  ],
-  [
-    "sphinx-apidoc",
-    "-d", "2",
-    "-o", "{tox_root}/docs/api",
-    "{tox_root}/src/lfkit",
-    "--separate",
-    "--no-toc",
-    "-f",
+    "{tox_root}/docs/_build",
+    "{tox_root}/docs/api/generated",
   ],
   [
     "sphinx-build",
+    "-E",
     "-b", "doctest",
     "{tox_root}/docs",
     "{tox_root}/docs/_build/doctest",
@@ -172,6 +161,7 @@ commands = [
   ],
   [
     "sphinx-build",
+    "-E",
     "-b", "html",
     "{tox_root}/docs",
     "{tox_root}/docs/_build/html",
@@ -183,15 +173,13 @@ commands = [
 [tool.tox.env.docs-releases]
 description = "Build the documentation for lfkit releases using Sphinx"
 extras = ["docs", "viz"]
-allowlist_externals = ["cp"]
+allowlist_externals = ["cp", "rm"]
 commands = [
   [
-    "sphinx-apidoc",
-    "-d", "2",
-    "-o", "{tox_root}/docs/api",
-    "{tox_root}/src/lfkit",
-    "--separate",
-    "-f",
+    "rm",
+    "-rf",
+    "{tox_root}/docs/_build",
+    "{tox_root}/docs/api/generated",
   ],
   [
     "sphinx-multiversion",

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/src/lfkit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
-__commit_id__ = commit_id = 'gd79ca3a8b'
+__commit_id__ = commit_id = 'g8dbb26ee5'

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/src/lfkit/api/_namespaces.py

@@ -1,4 +1,4 @@
-"""User-facing luminosity-function API namespaces."""
+"""User-facing luminosity function API namespaces."""
 
 from __future__ import annotations
 
@@ -14,28 +14,43 @@ from lfkit.photometry import magnitudes as photo_magnitudes
 
 
 class LFIntegralsAPI:
-    """Grouped API for luminosity function integrals."""
+    """Grouped API for luminosity function integrals.
+
+    Args:
+        lf: Luminosity function object whose callable form is used by bound
+            integral methods.
+    """
 
     def __init__(self, lf) -> None:
         self.lf = lf
 
 
 class LFCompletenessAPI:
-    """Grouped API for catalog-completeness calculations."""
+    """Grouped API for catalog completeness calculations.
+
+    Args:
+        lf: Luminosity function object whose callable form is used by bound
+            completeness methods.
+    """
 
     def __init__(self, lf) -> None:
         self.lf = lf
 
 
 class LFRedshiftDensityAPI:
-    """Grouped API for LF-weighted redshift-density calculations."""
+    """Grouped API for luminosity function weighted redshift density calculations.
+
+    Args:
+        lf: Luminosity function object whose callable form is used by bound
+            redshift density methods.
+    """
 
     def __init__(self, lf) -> None:
         self.lf = lf
 
 
 class LFMagnitudesAPI:
-    """Grouped API for apparent- and absolute-magnitude conversions."""
+    """Grouped API for apparent magnitude and absolute magnitude conversions."""
 
 
 class LFLuminositiesAPI:
@@ -76,7 +91,20 @@ def expose_lf_function(
     lf_arg_position: int | None = None,
     lf_arg_name: str | None = None,
 ) -> Callable[..., Any]:
-    """Expose a low-level LF function as a bound API method."""
+    """Expose a low level luminosity function helper as a bound API method.
+
+    Args:
+        function: Low level function to expose as a method.
+        lf_arg_position: Positional index where the luminosity function callable
+            should be inserted. If ``None``, no positional luminosity function
+            argument is inserted.
+        lf_arg_name: Keyword name used to pass the luminosity function callable.
+            If provided, this takes priority over ``lf_arg_position``.
+
+    Returns:
+        Bound method that injects ``self.lf._as_callable()`` before calling
+        ``function``.
+    """
 
     @wraps(function)
     def method(self, *args, **kwargs):
@@ -97,7 +125,14 @@ def expose_lf_function(
 
 
 def _public_functions(module: object) -> dict[str, Callable[..., Any]]:
-    """Return callable public functions declared by a module."""
+    """Return callable public functions declared by a module.
+
+    Args:
+        module: Module object with an optional ``__all__`` declaration.
+
+    Returns:
+        Dictionary mapping public function names to callable objects.
+    """
     return {
         name: getattr(module, name)
         for name in getattr(module, "__all__", [])
@@ -106,13 +141,21 @@ def _public_functions(module: object) -> dict[str, Callable[..., Any]]:
 
 
 def _method_name(module: object, function_name: str) -> str:
-    """Return API method name for a low-level function."""
+    """Return the API method name for a low level function.
+
+    Args:
+        module: Module object that may define ``__api_aliases__``.
+        function_name: Name of the low level function.
+
+    Returns:
+        Public API method name, using ``__api_aliases__`` when available.
+    """
     aliases = getattr(module, "__api_aliases__", {})
     return aliases.get(function_name, function_name)
 
 
 def _attach_api_methods() -> None:
-    """Attach low-level functions to their API namespace classes."""
+    """Attach low level functions to their API namespace classes."""
     for api_cls, spec in _API_NAMESPACES.items():
         module = spec["module"]
         bound_to_lf = spec.get("bound_to_lf", False)

{py_lfkit-0.3.0 → py_lfkit-0.5.0}/src/lfkit/api/conditional_luminosity_function.py

@@ -21,60 +21,61 @@ __all__ = ["ConditionalLuminosityFunction"]
 class ConditionalLuminosityFunction(LuminosityFunction):
     """User-facing wrapper for conditional luminosity function models.
 
-    A conditional luminosity function evaluates ``Phi(M | x)``, where
-    ``M`` is absolute magnitude and ``x`` is an external conditioning
-    variable such as redshift, halo mass, or another model-specific quantity.
+    A conditional luminosity function evaluates ``Phi(M | x_1, x_2, ...)``,
+    where ``M`` is absolute magnitude and the ``x_i`` are external conditioning
+    variables such as redshift, halo mass, environment, richness, stellar mass,
+    or other model-specific quantities.
 
     Instances can be created either with the generic constructor or with
     automatically generated model constructors.
-
-    Examples:
-        >>> clf = ConditionalLuminosityFunction(
-        ...     model="schechter",
-        ...     parameters={"phi_star": 1e-3, "m_star": -20.5, "alpha": -1.1},
-        ... )
-        >>> phi = clf.phi(absolute_mag=-20.0, condition=0.5)
-
-        >>> ConditionalLuminosityFunction.available_models()
     """
 
     def phi(
         self,
         absolute_mag: FloatInput,
-        condition: FloatInput | None = None,
+        *conditions: FloatInput,
     ) -> FloatArray:
         """Evaluate the conditional luminosity function.
 
         Args:
             absolute_mag: Absolute magnitude value or array.
-            condition: Conditioning variable value or array. The meaning of
-                this variable depends on the selected conditional LF model.
+            *conditions: One or more conditioning variable values or arrays. The
+                meaning of each variable depends on the selected conditional
+                luminosity function model.
 
         Returns:
             Conditional luminosity function evaluated at ``absolute_mag`` and
-            ``condition``.
+            the supplied conditioning variables.
 
         Raises:
-            ValueError: If ``condition`` is not provided or the model is not
-                registered as a conditional luminosity function.
+            ValueError: If no conditioning variables are provided, or if the
+                model is not registered as a conditional luminosity function.
         """
         model_spec = get_conditional_lf_model(self.model)
 
-        if condition is None:
+        if not conditions:
             raise ValueError(
-                f"condition is required for conditional luminosity function "
-                f"model '{self.model}'."
+                f"At least one conditioning variable is required for conditional "
+                f"luminosity function model '{self.model}'."
             )
 
+        condition_arrays = tuple(
+            np.asarray(condition_value, dtype=float) for condition_value in conditions
+        )
+
         return model_spec.function(
             np.asarray(absolute_mag, dtype=float),
-            np.asarray(condition, dtype=float),
+            *condition_arrays,
             **self.parameters_dict,
         )
 
     @staticmethod
     def available_models() -> list[str]:
-        """Return conditional luminosity function model names."""
+        """Return registered conditional luminosity function model names.
+
+        Returns:
+            Sorted list of registered conditional luminosity function model names.
+        """
         return sorted(CONDITIONAL_LF_MODELS)
 
 
@@ -83,7 +84,15 @@ def _make_conditional_constructor(
     model_name: str,
     function: Any,
 ):
-    """Create a classmethod constructor from a registered conditional LF model."""
+    """Create a classmethod constructor from a registered conditional model.
+
+    Args:
+        model_name: Name of the registered conditional luminosity function model.
+        function: Registered low level conditional luminosity function callable.
+
+    Returns:
+        Classmethod constructor for ``ConditionalLuminosityFunction``.
+    """
     signature = inspect.signature(function)
 
     @classmethod
@@ -106,22 +115,24 @@ def _make_conditional_constructor(
     constructor.__name__ = model_name
     constructor.__qualname__ = f"ConditionalLuminosityFunction.{model_name}"
     constructor.__doc__ = f"""Create a ``{model_name}`` conditional luminosity function.
-
-The keyword arguments are inferred from the registered low-level model
-function. Required model parameters must be supplied by the user. Optional
-model parameters use their low-level defaults unless explicitly provided.
-
-Args:
-    meta: Optional metadata stored on the luminosity function object.
-    **parameters: Parameters passed to the registered conditional LF model.
-
-Returns:
-    ConditionalLuminosityFunction: Configured conditional luminosity function.
-
-Examples:
-    >>> clf = ConditionalLuminosityFunction.{model_name}(...)
-    >>> phi = clf.phi(absolute_mag=-20.0, condition=0.5)
-"""
+        
+        The keyword arguments are inferred from the registered low level model
+        function. Required model parameters must be supplied by the user. Optional
+        model parameters use their low level defaults unless explicitly provided.
+        
+        Args:
+            meta: Optional metadata stored on the luminosity function object.
+            **parameters: Parameters passed to the registered conditional luminosity
+                function model.
+        
+        Returns:
+            Configured conditional luminosity function.
+        
+        Examples:
+            >>> clf = ConditionalLuminosityFunction.{model_name}(...)
+            >>> phi = clf.phi(-20.0, 0.5)
+            >>> phi = clf.phi(-20.0, halo_mass, redshift)
+        """
 
     return constructor
 
@@ -131,27 +142,40 @@ def _parameters_from_signature(
     signature: inspect.Signature,
     provided: Mapping[str, Any],
 ) -> dict[str, Any]:
-    """Build stored parameters using function defaults plus user values.
+    """Build stored parameters from a function signature and user values.
 
-    Independent variables such as ``absolute_mag`` and ``condition`` are not
-    stored as model parameters. They are supplied later when calling
+    Independent variables such as ``absolute_mag`` and conditioning variables are
+    not stored as model parameters. They are supplied later when calling
     :meth:`ConditionalLuminosityFunction.phi`.
 
     Args:
-        signature: Signature of the registered low-level conditional LF model.
+        signature: Signature of the registered low level conditional luminosity
+            function model.
         provided: User-supplied constructor keyword arguments.
 
     Returns:
-        Dictionary of model parameters to store on the API object.
+        Dictionary of model parameters stored on the API object.
 
     Raises:
         TypeError: If the user provides a keyword that is not accepted by the
-            registered low-level model function.
+            registered low level model function.
     """
     payload: dict[str, Any] = {}
 
+    independent_names = {
+        "absolute_mag",
+        "condition",
+        "conditions",
+        "z",
+        "redshift",
+        "x",
+        "halo_mass",
+        "environment",
+        "galaxy_type",
+    }
+
     for name, parameter in signature.parameters.items():
-        if name in {"absolute_mag", "condition", "z", "redshift", "x"}:
+        if name in independent_names:
             continue
 
         if parameter.kind in {