Fix documentation (#403)

* Adding cluster docstrings.
* Removing unused class.
* Adding doc strings and removing unnecessary complexity from generic.
* Adding docstrings and removing unnecessary pylint command.
* Ignoring requirement that docstring doesnt start with name of the method.
* Fixing all docstrings except source statistic.
* Adding flake8 docstrings to the environment.yml
* Fixing docstrings in examples.
* Fixing docstrings in source.
* Removing unused file.
* Changing flake8-docstrings to be installed thru conda.
* Fix flake8 complaints in documentation

---------

Co-authored-by: Matt Kwiecien <mattkwiecien@gmail.com>
Co-authored-by: Marc Paterno <paterno@fnal.gov>

environment.yml

@@ -13,6 +13,7 @@ dependencies:
   - dill
   - fitsio
   - flake8
+  - flake8-docstrings
   - fuzzywuzzy
   - getdist
   - idna

examples/cluster_number_counts/cluster_redshift_richness.py

@@ -19,6 +19,7 @@
 
 
 def get_cluster_abundance() -> ClusterAbundance:
+    """Creates and returns a ClusterAbundance object."""
     hmf = ccl.halos.MassFuncBocquet16()
     min_mass, max_mass = 13.0, 16.0
     min_z, max_z = 0.2, 0.8
@@ -30,10 +31,7 @@ def get_cluster_abundance() -> ClusterAbundance:
 def build_likelihood(
     build_parameters: NamedParameters,
 ) -> tuple[Likelihood, ModelingTools]:
-    """
-    Here we instantiate the number density (or mass function) object.
-    """
-
+    """Builds the likelihood for Firecrown."""
     # Pull params for the likelihood from build_parameters
     average_on = ClusterProperty.NONE
     if build_parameters.get_bool("use_cluster_counts", True):

examples/cluster_number_counts/compare_integration_methods.py

@@ -16,6 +16,7 @@
 
 
 def get_cosmology() -> pyccl.Cosmology:
+    """Creates and returns a CCL cosmology object."""
     Omega_c = 0.262
     Omega_b = 0.049
     Omega_k = 0.0

examples/cluster_number_counts/generate_rich_mean_mass_sacc_data.py

@@ -25,7 +25,6 @@
 
 def generate_sacc_file() -> Any:
     """Generate a SACC file for cluster number counts."""
-
     H0 = 71.0
     Ob0 = 0.0448
     Odm0 = 0.22

examples/cosmicshear/cosmicshear.py

@@ -1,5 +1,4 @@
-"""Define the likelihood factory function for the cosmic shear example.
-"""
+"""Define the likelihood factory function for the cosmic shear example."""
 
 import os
 

examples/cosmicshear/generate_cosmicshear_data.py

@@ -1,5 +1,4 @@
-""" Generate the cosmicshear.fits file.
-"""
+"""Generate the cosmicshear.fits file."""
 
 import numpy as np
 import sacc

examples/des_y1_3x2pt/des_y1_3x2pt.py

@@ -19,7 +19,6 @@
 # theoretical prediction and are also constructed in the build_likelihood function.
 def build_likelihood(_):
     """Build the DES Y1 3x2pt likelihood."""
-
     # Creates a LAI systematic. This is a systematic that is applied to
     # all weak-lensing probes. The `sacc_tracer` argument is used to identify the
     # section of the SACC file that this systematic will be applied to. In this

examples/des_y1_3x2pt/des_y1_3x2pt_PT.py

@@ -33,8 +33,11 @@
 
 @dataclass
 class CclSetup:
-    """A package of related CCL parameters, to reduce the number of variables
-    used in the :meth:`run_likelihood` method."""
+    """A package of related CCL parameters.
+
+    We use this to reduce the number of variables used in the :meth:`run_likelihood`
+    method.
+    """
 
     a_1: float = 1.0
     a_2: float = 0.5
@@ -47,8 +50,11 @@ class CclSetup:
 
 @dataclass
 class CElls:
-    """A package of related C_ell values, to reduce the number of variables
-    used in the :meth:`run_likelihood` method."""
+    """A package of related C_ell values.
+
+    This is used to reduce the number of variables used in the
+    :meth:`run_likelihood` method.
+    """
 
     GG: np.ndarray
     GI: np.ndarray
@@ -78,7 +84,6 @@ def __init__(self, stat0: TwoPoint, stat2: TwoPoint, stat3: TwoPoint):
 
 def build_likelihood(_) -> tuple[Likelihood, ModelingTools]:
     """Likelihood factory function for DES Y1 3x2pt analysis."""
-
     # Load sacc file
     sacc_data = sacc.Sacc.load_fits(saccfile)
 
@@ -162,10 +167,7 @@ def build_likelihood(_) -> tuple[Likelihood, ModelingTools]:
 
 # We can also run the likelihood directly
 def run_likelihood() -> None:
-    """Produce some plots using the likelihood function built by
-    :meth:`build_likelihood`.
-    """
-
+    """Produce plots using the likelihood function built by :meth:`build_likelihood`."""
     # pylint: enable=import-outside-toplevel
 
     likelihood, tools = build_likelihood(None)

examples/des_y1_3x2pt/des_y1_cosmic_shear_TATT.py

@@ -94,7 +94,6 @@ def define_sources(n_source):
 # We can also run the likelihood directly
 def run_likelihood() -> None:
     """Run the likelihood."""
-
     likelihood, tools = build_likelihood(None)
 
     # Load sacc file

examples/des_y1_3x2pt/des_y1_cosmic_shear_pk_modifier.py

@@ -1,5 +1,7 @@
-"""Example of a Firecrown likelihood using the DES Y1 cosmic shear data with a
-modified matter power spectrum"""
+"""Example of a Firecrown likelihood using the DES Y1 cosmic shear data.
+
+This example also includes a modified matter power spectrum.
+"""
 
 import os
 
@@ -23,8 +25,10 @@
 
 
 class vanDaalen19Baryonfication(PowerspectrumModifier):
-    """A PowerspectrumModifier class that implements the van Daalen et al. 2019
-    baryon model."""
+    """A PowerspectrumModifier class.
+
+    This clas implements the van Daalen et al. 2019 baryon model.
+    """
 
     name: str = "delta_matter_baryons:delta_matter_baryons"
 
@@ -35,6 +39,7 @@ def __init__(self, pk_to_modify: str = "delta_matter:delta_matter"):
         self.f_bar = create()
 
     def compute_p_of_k_z(self, tools: ModelingTools) -> pyccl.Pk2D:
+        """Compute the 3D power spectrum P(k, z)."""
         self.vD19.update_parameters(fbar=self.f_bar)
         return self.vD19.include_baryonic_effects(
             cosmo=tools.get_ccl_cosmology(), pk=tools.get_pk(self.pk_to_modify)
@@ -110,7 +115,6 @@ def define_sources(n_source):
 # We can also run the likelihood directly
 def run_likelihood() -> None:
     """Run the likelihood."""
-
     likelihood, tools = build_likelihood(None)
 
     # Load sacc file

examples/des_y1_3x2pt/generate_des_data.py

@@ -1,4 +1,4 @@
-""" Generate the firecrown input from the DES Y1 3x2pt data products.
+"""Generate the firecrown input from the DES Y1 3x2pt data products.
 
 Before running this script, you must first download the DES Y1 3x2pt data
 products from:

examples/srd_sn/generate_sn_data.py

@@ -1,5 +1,4 @@
-"""Generate SACC data into file srd-y1-converted.sacc.
-"""
+"""Generate SACC data into file srd-y1-converted.sacc."""
 
 import os
 import tarfile
@@ -14,10 +13,9 @@
 
 
 def conversion(hdg):
-    """
-    CODE TO CONVERT THE NEW DESC HUBBLE DIAGRAM FILE STRUCTURE
-    SIMILAR TO COSMOMC STYLED INPUT HUBBLE DIAGRAM
-    FILE STRUCTURE
+    """Code to convert the new DESC Hubble diagram file structure.
+
+    This is similar to cosmomc styled input hubble diagram file structure.
     """
     col = [
         "#name",
@@ -61,8 +59,9 @@ def conversion(hdg):
 
 
 def read_hubble_data(args):
-    """Read the Hubble and covariance data, either from specified files or
-    from the default files.
+    """Read the Hubble and covariance data.
+
+    This is read either from specified files or from the default files.
     """
     if len(args) == 4:
         path = args[1]
@@ -115,8 +114,7 @@ def read_hubble_data(args):
 
 
 def ensure_local_data_files(dirname_year10, url):
-    """Ensure we have the required local data files, downloading them if
-    needed."""
+    """Ensure we have the required local data files, downloading them if needed."""
     if os.path.exists(dirname_year10):
         print("Y10 directory already downloaded")
     else:

examples/srd_sn/sn_srd.py

@@ -1,5 +1,4 @@
-"""Demonstration of the use of the :class:`Supernova` statistics object.
-"""
+"""Demonstration of the use of the :class:`Supernova` statistics object."""
 
 import sacc
 import firecrown.likelihood.gauss_family.statistic.supernova as sn
@@ -8,8 +7,10 @@
 
 
 def build_likelihood(params: NamedParameters):
-    """Build the Firecrown likelihood object. We have no extra tools for this
-    example."""
+    """Build the Firecrown likelihood object.
+
+    We have no extra tools for this example.
+    """
     # Here we instantiate the necessary statistic object to deal with SNIa data.
     snia_stats = sn.Supernova(sacc_tracer="sn_ddf_sample")
 

firecrown/connector/cobaya/ccl.py

@@ -1,8 +1,6 @@
-"""Cobaya CCL Connector
-
+"""Cobaya CCL Connector.
 
 Provide the class CCLConnector, which is an implementation of a Cobaya Theory.
-
 """
 
 from __future__ import annotations
@@ -18,9 +16,7 @@
 
 
 class CCLConnector(Theory):
-    """
-    A class implementing cobaya.theory.Theory.
-    """
+    """A class implementing cobaya.theory.Theory."""
 
     input_style: Optional[str] = None
 
@@ -30,7 +26,6 @@ def initialize(self):
         This is used instead of __init__, to provide default initialization.
         Cobaya does not allow us to override __init__.
         """
-
         assert self.input_style
         self.map = mapping_builder(input_style=self.input_style)
 
@@ -51,7 +46,6 @@ def initialize_with_provider(self, provider):
 
         Sets instance's provided to the given provider.
         """
-
         self.provider = provider
 
     def get_can_provide_params(self):
@@ -83,9 +77,7 @@ def get_requirements(
         Returns a dictionary with keys:
              omk, Pk_grid, comoving_radial_distance, Hubble,
              and with values reflecting the current status of the object.
-
         """
-
         pyccl_calculator_requires = {
             "omk": None,
             "Pk_grid": {"k_max": self.Pk_kmax, "z": self.z_Pk},
@@ -105,7 +97,6 @@ def calculate(
         self, state: dict[str, float], want_derived=True, **params_values
     ) -> None:
         """Calculate the current cosmology, and set state["pyccl"] to the result."""
-
         self.map.set_params_from_camb(**params_values)
 
         pyccl_params_values = self.map.asdict()

firecrown/connector/cobaya/likelihood.py

@@ -1,4 +1,4 @@
-"""Cobaya Likelihood Connector
+"""Cobaya Likelihood Connector.
 
 Module for providing a likelihood for use in Cobaya.
 
@@ -25,8 +25,7 @@ class LikelihoodConnector(Likelihood):
     build_parameters: NamedParameters
 
     def initialize(self):
-        """Initialize the likelihood object by loading its Firecrown
-        configuration."""
+        """Initialize the likelihood object by loading its Firecrown configuration."""
         if not hasattr(self, "build_parameters"):
             build_parameters = NamedParameters()
         else:
@@ -54,7 +53,6 @@ def initialize_with_provider(self, provider) -> None:
 
         Sets instance's provided to the given provider.
         """
-
         self.provider = provider
 
     def get_can_provide_params(self) -> list[str]:

firecrown/connector/cosmosis/likelihood.py

@@ -1,4 +1,4 @@
-"""CosmoSIS Likelihood Connector
+"""CosmoSIS Likelihood Connector.
 
 This module provides the class FirecrownLikelihood, and the hook functions
 for this module to be a CosmoSIS likelihood module.
@@ -22,8 +22,7 @@
 
 
 def extract_section(sample: cosmosis.datablock, section: str) -> NamedParameters:
-    """Extract the all the parameters from the name datablock section into a
-    dictionary."""
+    """Extract all the parameters from the name datablock section into a dictionary."""
     if not sample.has_section(section):
         raise RuntimeError(f"Datablock section `{section}' does not exist.")
     sec_dict = {name: sample[section, name] for _, name in sample.keys(section=section)}
@@ -183,9 +182,11 @@ def execute(self, sample: cosmosis.datablock) -> int:
         return 0
 
     def form_error_message(self, exc: MissingSamplerParameterError) -> str:
-        """Form the error message that will be used to report a missing
-        parameter, when that parameter should have been supplied by the
-        sampler."""
+        """Form the error message that will be used to report a missing parameter.
+
+        This error message will also include when that parameter should have been
+        supplied by the sampler.
+        """
         msg = (
             "A required parameter was not found in any of the "
             "sections searched on DataBlock.\n"
@@ -203,7 +204,6 @@ def form_error_message(self, exc: MissingSamplerParameterError) -> str:
 
     def calculate_firecrown_params(self, sample: cosmosis.datablock) -> ParamsMap:
         """Calculate the ParamsMap for this sample."""
-
         firecrown_params = ParamsMap()
         for section in self.sampling_sections:
             section_params = extract_section(sample, section)
@@ -222,16 +222,21 @@ def calculate_firecrown_params(self, sample: cosmosis.datablock) -> ParamsMap:
 
 
 def setup(config: cosmosis.datablock) -> FirecrownLikelihood:
-    """Setup hook for a CosmoSIS module. Returns an instance of
+    """Setup hook for a CosmoSIS module.
+
+    Returns an instance of
     class FirecrownLikelihood. The same object will be passed to the CosmoSIS
-    execute hook."""
+    execute hook.
+    """
     return FirecrownLikelihood(config)
 
 
 def execute(sample: cosmosis.datablock, instance: FirecrownLikelihood) -> int:
-    """Execute hook for a CosmoSIS module. Return 0 on success. The parameter
-    `sample` represents the current MCMC sample; `instance` is the
-    FirecrownLikelihood object created by `setup`."""
+    """Execute hook for a CosmoSIS module.
+
+    Return 0 on success. The parameter `sample` represents the current MCMC sample;
+    `instance` is the FirecrownLikelihood object created by `setup`.
+    """
     return instance.execute(sample)