Adding documentation and Examples to the repo [version:1.0.4]

.github/workflows/build_check.yml

@@ -215,3 +215,17 @@ jobs:
           use_oidc: false
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+  doc-valid:
+    name: Documentation build
+    runs-on: ubuntu-latest
+    needs: quick-validation
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install doc dependencies
+        run: pip install -r docs/requirements.txt numpy scipy
+      - name: Build the docs
+        run: make -C docs/ html

.gitignore

@@ -12,4 +12,12 @@ lsstdesc_crow.egg-info/
 .vscode/
 
 # hypothesis
-.hypothesis/
+.hypothesis/
+
+
+# Documentation
+docs/api/
+docs/api.rst
+docs/index.rst
+docs/compiled-examples/
+docs/_build/

README.md

@@ -1,2 +1,86 @@
 # CROW
 **C**luster **R**econstruction of **O**bservables **W**orkbench: **CROW**
+
+The LSST-DESC Cluster Reconstruction of Observables Workbench (CROW) code is a DESC tool consisting of a Python library for predicting galaxy cluster observabless.
+
+## Table of contents
+1. [Installing CROW](#installing)
+2. [Using CROW](#using)
+3. [Contributing to CROW](#contributing)
+5. [Contact](#contact)
+
+# Installing Crow <a name="installing"></a>
+
+Crow can be installed with `pip` or `conda`.
+
+For a `pip` installation, run:
+
+```bash
+    pip install lsstdesc-crow
+```
+
+For a `conda` installation, run:
+
+```bash
+    conda install -c conda-forge lsstdesc-crow
+```
+After, to use is in your code, just do 
+
+```bash
+import crow
+```
+
+## Requirements <a name="requirements"></a>
+
+Crow requires Python version 3.11 or later.
+
+### Dependencies <a name="dependencies"></a>
+
+Crow has the following dependencies:
+
+- [NumPy](https://www.numpy.org/) (v2 or later)
+- [SciPy](https://scipy.org/) (v1.12 or later)
+- [Pyccl](https://ccl.readthedocs.io/en/latest/index.html)
+- [CLMM](https://lsstdesc.org/CLMM/)
+- [NumCosmo](https://numcosmo.readthedocs.io/en/latest/)
+
+# Using Crow <a name="using"></a>
+
+This code has been released by DESC, although it is still under active
+development. You are welcome to re-use the code, which is open source and available under
+terms consistent with our
+[LICENSE](https://github.com/LSSTDESC/crow/blob/main/LICENSE) ([BSD
+3-Clause](https://opensource.org/licenses/BSD-3-Clause)).
+
+Example usage can be found in the `notebooks` folder.
+
+**DESC Projects**: External contributors and DESC members wishing to
+use Crow for DESC projects should consult with the DESC Clusters analysis
+working group (CL WG) conveners, ideally before the work has started, but
+definitely before any publication or posting of the work to the arXiv.
+
+**Non-DESC Projects by DESC members**: If you are in the DESC
+community, but planning to use Crow in a non-DESC project, it would be
+good practice to contact the CL WG co-conveners and/or the Crow
+Team leads as well (see Contact section).  A desired outcome would be for your
+non-DESC project concept and progress to be presented to the working group,
+so working group members can help co-identify tools and/or ongoing development
+that might mutually benefit your non-DESC project and ongoing DESC projects.
+
+**External Projects by Non-DESC members**: If you are not from the DESC
+community, you are also welcome to contact Crow Team leads to introduce
+your project and share feedback.
+
+
+# Contributing to Crow <a name="contributing"></a>
+
+You are welcome to contribute to the code. To do so, please make sure
+you use `isort` and `black` on your code and assure you provide unit tests.
+
+# Contact <a name="contact"></a>
+
+If you have comments, questions, or feedback, please contact the current leads
+ of the LSST DESC Crow Team: Michel Aguena
+(m-aguena, aguena@inaf.it) and Eduardo Barroso (eduardojsbarroso,
+barroso@lapp.in2p3.fr)
+

codecov.yml

@@ -0,0 +1,12 @@
+coverage:
+  status:
+    project:
+      default:
+        threshold: 1%    # allow up to 1% drop without failing
+    patch:
+      default:
+        target: auto     # compare patch coverage to base, not project total
+        threshold: 1%
+
+ignore:
+  - "docs/**"

crow/__init__.py

@@ -8,4 +8,4 @@
 from .recipes.binned_grid import GridBinnedClusterRecipe
 from .recipes.binned_parent import BinnedClusterRecipe
 
-__version__ = "1.0.3"
+__version__ = "1.0.4"

crow/cluster_modules/__init__.py

@@ -0,0 +1,30 @@
+"""Cluster modules package.
+
+Keep this module lightweight: do not import the submodules or classes eagerly
+here because several submodules import the top-level ``crow`` package and that
+can produce circular imports when the top-level ``crow.__init__`` imports
+things from ``cluster_modules``.
+
+To import classes or modules use the explicit submodule path, for example::
+
+    from crow.cluster_modules.abundance import ClusterAbundance
+    from crow.cluster_modules.shear_profile import ClusterShearProfile
+
+Sphinx/apidoc will still find and document the submodules even if they are not
+imported here; this file only needs to exist so Python treats the directory as
+a package.
+"""
+
+# Expose the expected subpackage/module names for convenience. Do NOT import
+# the modules at package import time to avoid circular import problems.
+__all__ = [
+    "abundance",
+    "completeness_models",
+    "kernel",
+    "parameters",
+    "purity_models",
+    "_clmm_patches",
+    "shear_profile",
+    "shear_profile_parallel",
+    "mass_proxy",
+]

crow/cluster_modules/abundance.py

@@ -21,6 +21,18 @@ class ClusterAbundance:
     an area on the sky, a halo mass function, as well as multiple kernels, where
     each kernel represents a different distribution involved in the final cluster
     abundance integrand.
+
+    Attributes
+    ----------
+    cosmo : pyccl.cosmology.Cosmology or None
+        Cosmology object used for predictions. Set via the `cosmo` property.
+    halo_mass_function : callable
+        Halo mass function object compatible with PyCCL's MassFunc interface.
+    parameters : Parameters
+        Container for optional model parameters.
+    _hmf_cache : dict
+        Cache for previously computed halo mass function evaluations keyed by
+        (log_mass, scale_factor).
     """
 
     @property
@@ -47,9 +59,28 @@ def __init__(
     def comoving_volume(
         self, z: npt.NDArray[np.float64], sky_area: float = 0
     ) -> npt.NDArray[np.float64]:
-        """The differential comoving volume given area sky_area at redshift z.
-
-        :param sky_area: The area of the survey on the sky in square degrees.
+        """Differential comoving volume for a given sky area.
+
+        Parameters
+        ----------
+        z : array_like
+            Redshift or array of redshifts at which to compute the differential
+            comoving volume (dV/dz per steradian).
+        sky_area : float, optional
+            Survey area in square degrees. Default 0 returns per-steradian volume.
+
+        Returns
+        -------
+        numpy.ndarray
+            Differential comoving volume (same shape as `z`) multiplied by the
+            survey area (converted to steradians). Units: [Mpc/h]^3 (consistent
+            with the internal PyCCL conventions used here).
+
+        Notes
+        -----
+        This uses PyCCL background helpers to evaluate the angular diameter
+        distance and h(z) factor. If `sky_area` is zero the returned array is
+        the per-steradian dV/dz.
         """
         assert self.cosmo is not None
         scale_factor = 1.0 / (1.0 + z)
@@ -73,7 +104,26 @@ def mass_function(
         log_mass: npt.NDArray[np.float64],
         z: npt.NDArray[np.float64],
     ) -> npt.NDArray[np.float64]:
-        """The mass function at z and mass."""
+        """Evaluate the halo mass function at given log-mass and redshift.
+
+        Parameters
+        ----------
+        log_mass : array_like
+            Array of log10 halo masses (M_sun).
+        z : array_like
+            Array of redshifts matching `log_mass`.
+
+        Returns
+        -------
+        numpy.ndarray
+            Array with mass function values (dn/dlnM or as provided by the
+            configured `halo_mass_function`) evaluated at each (mass, z).
+
+        Notes
+        -----
+        Results are cached in `_hmf_cache` keyed by (log_mass, scale_factor)
+        to avoid repeated expensive evaluations for identical inputs.
+        """
         scale_factor = 1.0 / (1.0 + z)
         return_vals = []