Add missing likelihood documentation (#137)

* added documentation for lensing lkl * added documentation for cluster lkl * added xcorr to documentation * expanded docs for lensing likelihoods * tidied cluster likelihood docs * tidying of xcorr docs * added crosscorrelation likelihood docs * added crosscorrelation as module * remove .DS * promoted crosscxorrelation to full module * added missing init * added missing rst * added descriptive toc parentheses --------- Co-authored-by: Martina Gerbino <[email protected]> Co-authored-by: Ian Harrison <[email protected]>
simonsobs · Oct 4, 2023 · e60c56d · e60c56d
1 parent d970b20
commit e60c56d
Show file tree

Hide file tree

Showing 25 changed files with 285 additions and 36 deletions.
diff --git a/docs/bandpass.rst b/docs/bandpass.rst
@@ -1,4 +1,4 @@
-Bandpass
+Bandpass (CMB)
 ========
 
 Bandpass computation

diff --git a/docs/bias.rst b/docs/bias.rst
@@ -1,4 +1,4 @@
-Bias
+Bias (Galaxy Bias)
 ====
 
 .. automodule:: soliket.bias

diff --git a/docs/ccl.rst b/docs/ccl.rst
@@ -1,4 +1,4 @@
-The Core Cosmology Library (CCL) Calculator
+Core Cosmology Library (CCL) Calculator
 ===========================================
 
 .. automodule:: soliket.ccl

diff --git a/docs/clusters.rst b/docs/clusters.rst
@@ -0,0 +1,36 @@
+Clusters (Galaxy Clusters)
+======
+
+.. automodule:: soliket.clusters.clusters
+
+Cluster Likelihood
+--------------------------
+
+.. autoclass:: soliket.clusters.ClusterLikelihood
+    :exclude-members: initialize
+    :members:
+    :private-members:
+    :show-inheritance:
+
+Halo Mass Function
+------------------------------------------
+
+.. automodule:: soliket.clusters.massfunc
+
+
+Survey
+------------------------------------------
+
+.. automodule:: soliket.clusters.survey
+
+
+SZ Utils
+------------------------------------------
+
+.. automodule:: soliket.clusters.sz_utils
+
+Tinker
+------------------------------------------
+
+.. automodule:: soliket.clusters.tinker
+
diff --git a/docs/cosmopower.rst b/docs/cosmopower.rst
@@ -1,4 +1,4 @@
-Cosmopower
+Cosmopower (Boltzmann Emulator)
 ==========
 
 .. automodule:: soliket.cosmopower

diff --git a/docs/crosscorrelation.rst b/docs/crosscorrelation.rst
@@ -0,0 +1,31 @@
+CrossCorrelation
+======
+
+.. automodule:: soliket.cross_correlation
+
+CrossCorrelation Likelihood
+--------------------------
+
+.. autoclass:: soliket.cross_correlation.CrossCorrelationLikelihood
+    :exclude-members: initialize
+    :members:
+    :private-members:
+    :show-inheritance:
+
+GalaxyKappa Likelihood
+--------------------------
+
+.. autoclass:: soliket.cross_correlation.GalaxyKappaLikelihood
+    :exclude-members: initialize
+    :members:
+    :private-members:
+    :show-inheritance:
+
+ShearKappa Likelihood
+--------------------------
+
+.. autoclass:: soliket.cross_correlation.ShearKappaLikelihood
+    :exclude-members: initialize
+    :members:
+    :private-members:
+    :show-inheritance:
diff --git a/docs/foreground.rst b/docs/foreground.rst
@@ -1,4 +1,4 @@
-Foreground
+Foreground (CMB)
 ==========
 
 Foreground computation

diff --git a/docs/index.rst b/docs/index.rst
@@ -30,17 +30,21 @@ The pages here describe how to install and run SOLikeT, and document the functio
    :caption: Theory codes
    :maxdepth: 1
 
-   bias
    ccl
    cosmopower
    bandpass
    foreground
+   bias
 
 .. toctree::
    :caption: Likelihood codes
    :maxdepth: 1
 
    mflike
+   lensing
+   clusters
+   xcorr
+   crosscorrelation
 
 .. toctree::
    :caption: Miscellaneous

diff --git a/docs/lensing.rst b/docs/lensing.rst
@@ -0,0 +1,22 @@
+Lensing (CMB Lensing)
+======
+
+.. automodule:: soliket.lensing.lensing
+
+Lensing Likelihood
+--------------------------
+
+.. autoclass:: soliket.lensing.LensingLikelihood
+    :exclude-members: initialize
+    :members:
+    :private-members:
+    :show-inheritance:
+
+LensingLite Likelihood
+--------------------------
+
+.. autoclass:: soliket.lensing.LensingLiteLikelihood
+    :exclude-members: initialize
+    :members:
+    :private-members:
+    :show-inheritance:
diff --git a/docs/mflike.rst b/docs/mflike.rst
@@ -1,4 +1,4 @@
-MFLike
+MFLike (Primary CMB)
 ======
 
 .. automodule:: soliket.mflike.mflike

diff --git a/docs/utils.rst b/docs/utils.rst
@@ -1,4 +1,4 @@
-Utils
+Utilities
 ==================
 
 .. automodule:: soliket.utils

diff --git a/docs/xcorr.rst b/docs/xcorr.rst
@@ -0,0 +1,18 @@
+XCorr (Cross-correlation)
+======
+
+.. automodule:: soliket.xcorr.xcorr
+
+Cross-correlation Likelihood
+--------------------------
+
+.. autoclass:: soliket.xcorr.XcorrLikelihood
+    :exclude-members: initialize
+    :members:
+    :private-members:
+    :show-inheritance:
+
+Limber Calculator
+------------------------------------------
+
+.. automodule:: soliket.xcorr.limber
diff --git a/setup.cfg b/setup.cfg
@@ -27,7 +27,7 @@ install_requires =
     syslibrary
 
 [options.package_data]
-soliket = *.yaml,*.bibtex,clusters/data/*,clusters/data/selFn_equD56/*,lensing/data/*.txt,lensing/data/*.fits,mflike/*.yaml,tests/*.yaml,data/xcorr_simulated/*.txt,data/CosmoPower/CP_paper/CMB/*.pkl,tests/data/test_bandpass/*
+soliket = *.yaml,*.bibtex,clusters/data/*,clusters/data/selFn_equD56/*,lensing/data/*.txt,lensing/data/*.fits,mflike/*.yaml,tests/*.yaml,data/xcorr_simulated/*.txt,data/CosmoPower/CP_paper/CMB/*.pkl,tests/data/test_bandpass/*,cross_correlation/*.yaml
 testpaths = "soliket"
 text_file_format = rst
 

diff --git a/soliket/__init__.py b/soliket/__init__.py
@@ -4,21 +4,15 @@
 from .ps import PSLikelihood, BinnedPSLikelihood  # noqa: F401
 from .mflike import MFLike  # noqa: F401
 from .mflike import TheoryForge_MFLike
+from .cross_correlation import GalaxyKappaLikelihood, ShearKappaLikelihood  # noqa: F401, E501
 from .xcorr import XcorrLikelihood  # noqa: F401
 from .foreground import Foreground
 from .bandpass import BandPass
 from .cosmopower import CosmoPower, CosmoPowerDerived
+from .ccl import CCL  # noqa: F401
 
 try:
     from .clusters import ClusterLikelihood  # noqa: F401
 except ImportError:
     print('Skipping cluster likelihood (is pyCCL installed?)')
-    pass
-
-try:
-    import pyccl as ccl  # noqa: F401
-    from .ccl import CCL  # noqa: F401
-    from .cross_correlation import GalaxyKappaLikelihood, ShearKappaLikelihood  # noqa: F401, E501
-except ImportError:
-    print('Skipping CCL module as pyCCL is not installed')
-    pass
+    pass
diff --git a/soliket/clusters/clusters.py b/soliket/clusters/clusters.py
@@ -1,5 +1,21 @@
 """
-requires extra: astlib
+.. module:: clusters
+
+:Synopsis: Poisson likelihood for SZ clusters for Simons Osbervatory 
+:Authors: Nick Battaglia, Eunseong Lee
+
+Likelihood for unbinned tSZ galaxy cluster number counts. Currently under development and
+should be used only with caution and advice. Uses the SZ scaling relations from 
+Hasselfield et al (2013) [1]_ to compare observed number of :math:`y`-map detections 
+with the prediction from a Tinker [2]_ Halo Mass Function.
+
+References
+----------
+.. [1] Hasselfield et al, JCAP 07, 008 (2013) `arXiv:1301.0816 
+                                                <https://arxiv.org/abs/1301.0816>`_
+.. [2] Tinker et al, Astrophys. J. 688, 2, 709 (2008) `arXiv:0803.2706 
+                                                    <https://arxiv.org/abs/0803.2706>`_
+
 """
 import numpy as np
 import pandas as pd
@@ -21,6 +37,9 @@ class SZModel:
 
 
 class ClusterLikelihood(PoissonLikelihood):
+    """
+    Poisson Likelihood for un-binned :math:`y`-map galaxy cluster counts.
+    """
     name = "Clusters"
     columns = ["tsz_signal", "z", "tsz_signal_err"]
     data_path = resource_filename("soliket", "clusters/data/selFn_equD56")
@@ -37,6 +56,12 @@ def initialize(self):
         super().initialize()
 
     def get_requirements(self):
+        """
+        This likelihood require :math:`P(k,z)`, :math:`H(z)`, :math:`d_A(z)`, 
+        :math:`r(z)` (co-moving radial distance) from Theory codes.
+
+        :return: Dictionary of requirements 
+        """
         return {
             "Pk_interpolator": {
                 "z": self.zarr,
@@ -142,6 +167,10 @@ def _get_param_vals(self, **kwargs):
         return param_vals
 
     def _get_rate_fn(self, **kwargs):
+        """
+        Calculates the observed rate of clusters from the provided catalogue, which is
+        then compared directly to the predicted rate at the current parameter values.
+        """
         HMF = self._get_HMF()
         param_vals = self._get_param_vals(**kwargs)
 
@@ -170,7 +199,6 @@ def Prob_per_cluster(z, tsz_signal, tsz_signal_err):
         # Implement a function that returns a rate function (function of (tsz_signal, z))
 
     def _get_dVdz(self):
-        """dV/dzdOmega"""
         DA_z = self.theory.get_angular_diameter_distance(self.zarr)
 
         dV_dz = (
@@ -183,6 +211,9 @@ def _get_dVdz(self):
         return dV_dz
 
     def _get_n_expected(self, **kwargs):
+        """
+        Calculates expected number of clusters at the current parameter values.
+        """
         # def Ntot_survey(self,int_HMF,fsky,Ythresh,param_vals):
 
         HMF = self._get_HMF()

diff --git a/soliket/clusters/massfunc.py b/soliket/clusters/massfunc.py
@@ -1,3 +1,11 @@
+"""
+.. module:: massfunction
+
+The ``HMF`` class build the halo mass function internally required for the cluster 
+likelihood. Calculates the Halo Mass Function as in Tinker et al (2008) [2]_ .
+
+"""
+
 import numpy as np
 from scipy.interpolate import RegularGridInterpolator
 from .tinker import dn_dlogM
@@ -7,6 +15,9 @@
 
 
 class HMF:
+    """
+    Build halo mass function
+    """
     def __init__(self, om, Ez, pk=None, kh=None, zarr=None):
 
         # Initialize redshift and mass ranges
@@ -39,12 +50,16 @@ def __init__(self, om, Ez, pk=None, kh=None, zarr=None):
             # self.kh, self.pk = self._pk(self.zarr)
 
     def rhoc(self):
-        # critical density as a function of z
+        """
+        Critical density as a function of z
+        """
         ans = self.rho_crit0H100 * self.E_z ** 2.
         return ans
 
     def rhom(self):
-        # mean matter density as a function of z
+        """
+        Mean matter density as a function of z
+        """
         ans = self.rhoc0om * (1.0 + self.zarr) ** 3
         return ans
 
@@ -55,7 +70,9 @@ def critdensThreshold(self, deltac):
     def dn_dM(self, M, delta):
         """
         dN/dmdV Mass Function
-        M here is in MDeltam but we can convert
+
+        :param M: Mass in MDeltam, but we can convert
+        :param delta: Threshold for critical density
         """
         delts = self.critdensThreshold(delta)
         dn_dlnm = dn_dlogM(M, self.zarr, self.rhoc0om, delts, self.kh, self.pk,
@@ -65,7 +82,7 @@ def dn_dM(self, M, delta):
 
     def inter_dndmLogm(self, delta, M=None):
         """
-        interpolating over M and z for faster calculations
+        Interpolating over M and z for faster calculations
         """
         if M is None:
             M = self.M

diff --git a/soliket/clusters/survey.py b/soliket/clusters/survey.py
@@ -1,3 +1,12 @@
+"""
+.. module:: survey
+
+This module contains useful functions to internally required by the cluster likelihood to 
+navigate cluster catalogues. The ``SurveyData`` class contains information about the 
+specific survey.
+
+"""
+
 import os
 import numpy as np
 

diff --git a/soliket/clusters/sz_utils.py b/soliket/clusters/sz_utils.py
@@ -1,3 +1,12 @@
+"""
+.. module:: szutils
+
+Contains functions (many inherited from the 
+`nemo <https://nemo-sz.readthedocs.io/en/latest/>`_) code) which are used internally by 
+the cluster likelihood to convert between observed tSZ signal and cluster mass.
+
+"""
+
 import numpy as np
 from scipy import interpolate
 # from astropy.cosmology import FlatLambdaCDM

diff --git a/soliket/clusters/tinker.py b/soliket/clusters/tinker.py
@@ -1,3 +1,10 @@
+"""
+.. module:: tinker
+
+Parameters and functions used internally by the cluster likelihood for the Tinker profile.
+
+"""
+
 from builtins import zip
 import numpy as np
 from scipy.interpolate import InterpolatedUnivariateSpline as iuSpline

diff --git a/soliket/CrossCorrelationLikelihood.yaml → ...rrelation/CrossCorrelationLikelihood.yaml b/soliket/CrossCorrelationLikelihood.yaml → ...rrelation/CrossCorrelationLikelihood.yaml
diff --git a/soliket/cross_correlation/__init__.py b/soliket/cross_correlation/__init__.py
@@ -0,0 +1 @@
+from .cross_correlation import CrossCorrelationLikelihood, GalaxyKappaLikelihood, ShearKappaLikelihood   # noqa: F401, E501