From 0fd50a04e5ad83b3e28649cba2b7d34903979eda Mon Sep 17 00:00:00 2001 From: mgerbino Date: Fri, 28 Jul 2023 16:03:20 +0200 Subject: [PATCH] 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 Co-authored-by: Ian Harrison --- docs/bandpass.rst | 2 +- docs/bias.rst | 2 +- docs/ccl.rst | 2 +- docs/clusters.rst | 36 ++++++++++++ docs/cosmopower.rst | 2 +- docs/crosscorrelation.rst | 31 ++++++++++ docs/foreground.rst | 2 +- docs/index.rst | 6 +- docs/lensing.rst | 22 ++++++++ docs/mflike.rst | 2 +- docs/utils.rst | 2 +- docs/xcorr.rst | 18 ++++++ setup.cfg | 2 +- soliket/__init__.py | 12 +--- soliket/clusters/clusters.py | 35 +++++++++++- soliket/clusters/massfunc.py | 25 +++++++-- soliket/clusters/survey.py | 9 +++ soliket/clusters/sz_utils.py | 9 +++ soliket/clusters/tinker.py | 7 +++ .../CrossCorrelationLikelihood.yaml | 0 soliket/cross_correlation/__init__.py | 1 + .../cross_correlation.py | 17 ++++-- soliket/lensing/lensing.py | 56 +++++++++++++++++++ soliket/xcorr/limber.py | 7 +++ soliket/xcorr/xcorr.py | 14 ++--- 25 files changed, 285 insertions(+), 36 deletions(-) create mode 100644 docs/clusters.rst create mode 100644 docs/crosscorrelation.rst create mode 100644 docs/lensing.rst create mode 100644 docs/xcorr.rst rename soliket/{ => cross_correlation}/CrossCorrelationLikelihood.yaml (100%) create mode 100644 soliket/cross_correlation/__init__.py rename soliket/{ => cross_correlation}/cross_correlation.py (94%) diff --git a/docs/bandpass.rst b/docs/bandpass.rst index 68cf98e1..747f04dd 100644 --- 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 index 46b26704..baf3ae85 100644 --- 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 index 6bfd8003..be31e32f 100644 --- 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 new file mode 100644 index 00000000..92046322 --- /dev/null +++ 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 index ea66e118..6c29e80d 100644 --- 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 new file mode 100644 index 00000000..5dd562fd --- /dev/null +++ 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 index f3b9d8e2..cb793701 100644 --- 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 index 5a17e712..b5103268 100644 --- 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 new file mode 100644 index 00000000..76e07b8f --- /dev/null +++ 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: \ No newline at end of file diff --git a/docs/mflike.rst b/docs/mflike.rst index 1b21d718..bebea98c 100644 --- 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 index 8564a54c..64726e8a 100644 --- 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 new file mode 100644 index 00000000..7d1a81b0 --- /dev/null +++ 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 index 1d10caa4..c7003678 100644 --- 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 index ead5c120..69770a4b 100644 --- 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 \ No newline at end of file diff --git a/soliket/clusters/clusters.py b/soliket/clusters/clusters.py index f4718a8e..3035bca1 100644 --- 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 + `_ +.. [2] Tinker et al, Astrophys. J. 688, 2, 709 (2008) `arXiv: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 index c1b408be..d5293523 100644 --- 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 index a9d0e472..daf3875e 100644 --- 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 index 138ac315..5dbbf3b4 100644 --- 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 `_) 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 index 389f187d..2bc9efc2 100644 --- 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 b/soliket/cross_correlation/CrossCorrelationLikelihood.yaml similarity index 100% rename from soliket/CrossCorrelationLikelihood.yaml rename to soliket/cross_correlation/CrossCorrelationLikelihood.yaml diff --git a/soliket/cross_correlation/__init__.py b/soliket/cross_correlation/__init__.py new file mode 100644 index 00000000..5983588e --- /dev/null +++ b/soliket/cross_correlation/__init__.py @@ -0,0 +1 @@ +from .cross_correlation import CrossCorrelationLikelihood, GalaxyKappaLikelihood, ShearKappaLikelihood # noqa: F401, E501 \ No newline at end of file diff --git a/soliket/cross_correlation.py b/soliket/cross_correlation/cross_correlation.py similarity index 94% rename from soliket/cross_correlation.py rename to soliket/cross_correlation/cross_correlation.py index 8b43f5b4..cdbde250 100644 --- a/soliket/cross_correlation.py +++ b/soliket/cross_correlation/cross_correlation.py @@ -1,12 +1,12 @@ """ -Simple likelihood for CMB-galaxy cross-correlations using the cobaya -CCL module. +:Synopsis: Likelihood for cross-correlation of CMB lensing with Large Scale Structure +data. Makes use of the cobaya CCL module for handling tracers and Limber integration. -First version by Pablo Lemos +:Authors: Pablo Lemos, Ian Harrison. """ import numpy as np -from .gaussian import GaussianData, GaussianLikelihood +from ..gaussian import GaussianData, GaussianLikelihood import pyccl as ccl from cobaya.log import LoggedError @@ -14,6 +14,9 @@ class CrossCorrelationLikelihood(GaussianLikelihood): + r""" + Generic likelihood for cross-correlations of CCL tracer objects. + """ def initialize(self): if self.datapath is None: @@ -91,6 +94,9 @@ def logp(self, **params_values): class GalaxyKappaLikelihood(CrossCorrelationLikelihood): + r""" + Likelihood for cross-correlations of galaxy and CMB lensing data. + """ def _get_theory(self, **params_values): cosmo = self.provider.get_CCL()["cosmo"] @@ -113,6 +119,9 @@ def _get_theory(self, **params_values): class ShearKappaLikelihood(CrossCorrelationLikelihood): + r""" + Likelihood for cross-correlations of galaxy weak lensing shear and CMB lensing data. + """ def _get_theory(self, **params_values): diff --git a/soliket/lensing/lensing.py b/soliket/lensing/lensing.py index 58dda549..a283764e 100644 --- a/soliket/lensing/lensing.py +++ b/soliket/lensing/lensing.py @@ -1,3 +1,16 @@ +r""" +.. module:: lensing + +:Synopsis: Gaussian Likelihood for CMB Lensing for Simons Observatory +:Authors: Frank Qu, Mat Madhavacheril. + +This is a simple likelihood which inherits from generic binned power spectrum (PS) +likelihood. It comes in two forms: the full ``LensingLikelihood`` which requires +(automated) downloading of external data and a more lightweight ``LensingLiteLikelihood`` +which is less accurate (and should only be used for testing) but does not require the +data download. +""" + import os from pkg_resources import resource_filename @@ -12,6 +25,26 @@ class LensingLikelihood(BinnedPSLikelihood, InstallableLikelihood): + r""" + The full ``LensingLikelihood`` makes use of a *fiducial* lensing power spectrum which + is calculated at a hard-coded set of fiducial cosmological parameters. This fiducial + spectrum is combined with noise power spectra correction terms + (:math:`N_0` and :math:`N_1` terms calculated using + `this code `_) + appropriate for SO accounting for known biases in + the lensing estimators. These correction terms are then combined with the power + spectrum calculated at each Monte Carlo step. For more details on the calculation of + the corrected power spectrum see e.g. Section 5.9 and Appendix E of + `Qu et al (2023) `_. + + Noise power spectra are downloaded as part of the ``LensingLikelihood`` installation. + This is an `Installable Likelihood + `_ + with necessary data files stored on NERSC. You can install these data files either by + running ``cobaya-install`` on the yaml file specifying your run, or letting the + Likelihood install itself at run time. Please see the cobaya documentation for more + information about installable likelihoods. + """ _url = "https://portal.nersc.gov/project/act/jia_qu/lensing_like/likelihood.tar.gz" install_options = {"download_url": _url} data_folder = "LensingLikelihood/" @@ -100,7 +133,12 @@ def initialize(self): super().initialize() def _get_fiducial_Cls(self): + """ + Obtain a set of fiducial ``Cls`` from theory provider (e.g. ``camb``). + Fiducial ``Cls`` are used to compute correction terms for the theory vector. + :return: Fiducial ``Cls`` + """ info_fiducial = { "params": self.fiducial_params, "likelihood": {"soliket.utils.OneWithCls": {"lmax": self.theory_lmax}}, @@ -113,6 +151,11 @@ def _get_fiducial_Cls(self): return Cls def get_requirements(self): + """ + Set ``lmax`` for theory ``Cls`` + + :return: Dictionary ``Cl`` of lmax for each spectrum type. + """ return { "Cl": { "pp": self.theory_lmax, @@ -148,6 +191,13 @@ def _get_binning_matrix(self): return binning_matrix def _get_theory(self, **params_values): + """ + Generate binned theory vector of :math:`\kappa \kappa` with correction terms. + + :param params_values: Dictionary of cosmological parameters. + + :return: Array ``Clkk``. + """ cl = self.provider.get_Cl(ell_factor=False) Cl_theo = cl["pp"][0: self.lmax] @@ -184,6 +234,12 @@ def _get_theory(self, **params_values): class LensingLiteLikelihood(BinnedPSLikelihood): + """ + Lite version of Lensing Likelihood for quick tests, which does not make any of the + bias corrections requiring fiducial spectra calculations or downloads of external + data. Simply a Gaussian likelihood between a provided binned ``pp`` data vector + and covariance matrix, and the appropriate theory vector. + """ kind: str = "pp" lmax: int = 3000 datapath: str = resource_filename("soliket", "lensing/data/binnedauto.txt") diff --git a/soliket/xcorr/limber.py b/soliket/xcorr/limber.py index 153f263d..bf49fbd4 100644 --- a/soliket/xcorr/limber.py +++ b/soliket/xcorr/limber.py @@ -1,3 +1,10 @@ +""" +.. module:: limber + +Used internally by the xcorr likelihood to compute angular power spectra of different +probes under the Limber approximation. +""" + import numpy as np import pdb from ..constants import C_HMPC diff --git a/soliket/xcorr/xcorr.py b/soliket/xcorr/xcorr.py index 6c918ad9..acbbb588 100644 --- a/soliket/xcorr/xcorr.py +++ b/soliket/xcorr/xcorr.py @@ -1,4 +1,10 @@ r""" Likelihood for cross-correlation of CMB lensing and galaxy clustering probes. +Based on the original xcorr code [1]_ used in Krolewski et al (2021) [2]_. + + References + ---------- + .. [1] https://github.com/simonsobs/xcorr + .. [2] Krolewski, Ferraro and White, 2021, arXiv:2105.03421 """ @@ -16,8 +22,6 @@ class XcorrLikelihood(GaussianLikelihood): '''Cross-correlation Likelihood for CMB lensing and galaxy clustering probes. - Based on the original xcorr code [1]_ used in [2]_. - Accepts data files containing the two spectra from either text files or a sacc file. Parameters @@ -55,12 +59,6 @@ class XcorrLikelihood(GaussianLikelihood): s1 : float Magnification bias slope for the galaxy sample. - - References - ---------- - .. [1] https://github.com/simonsobs/xcorr - .. [2] Krolewski, Ferraro and White, 2021, arXiv:2105.03421 - ''' def initialize(self):