Merge pull request #43 from jlvdb/add-cosmology-docs

Improved the documentation of the cosmological model

docs/source/api.rst

@@ -29,5 +29,6 @@ This API reference manual details the primary functions and object in the
         api/config
         api/correlation
         api/redshifts
+        api/cosmo_coords
         api/utils
         api/options

docs/source/api/cosmo_coords.rst

@@ -0,0 +1,27 @@
+Coordinates & Cosmology
+-----------------------
+
+.. currentmodule:: yaw
+
+There are two utility classes in `yet_another_wizz` that are used to handle
+angular coordinates and distance computations in angular and 3-dimensional
+Euclidean coordintes:
+
+.. autosummary::
+    :toctree: autogen
+
+    AngularCoordinates
+    AngularDistances
+
+
+In many cases, the code needs to convert physical or comoving distances to
+angles at a given redshift. Although the final clustering redshifts should only
+very weakly depend on the exact cosmological model, it is possible to choose the
+cosmology freely. Valid cosmologies must be either `astropy` cosmologies or a
+subclass of :obj:`~yaw.cosmology.CustomCosmology`:
+
+.. autosummary::
+    :toctree: autogen
+
+    cosmology.CustomCosmology
+    cosmology.get_default_cosmology

docs/source/api/utils.rst

@@ -13,17 +13,6 @@ following utility function:
     utils.get_logger
 
 
-There are two utility classes in `yet_another_wizz` that are used to handle
-angular coordinates and distance computations in angular and 3-dimensional
-Euclidean coordintes:
-
-.. autosummary::
-    :toctree: autogen
-
-    AngularCoordinates
-    AngularDistances
-
-
 Additionally, there is a special container with convenience methods that store
 bin intervals:
 

docs/source/user_guide/examples/randoms.rst

@@ -9,6 +9,7 @@ weights, if desired. For example:
 
 .. code-block:: python
 
+    import yaw
     from yaw.randoms import BoxRandoms
 
     generator = BoxRandoms(
@@ -31,6 +32,21 @@ weights, if desired. For example:
         progress=True,  # shows a progress bar, default: False
     )
 
+To inspect the distribution, we need some additional code:
+
+.. code-block:: python
+
+    import numpy as np
+    from matplotlib import pyplot as plt
+
+    # need to iterate over patches and load coordinates manually
+    coords = yaw.AngularCoordinates.from_coords(
+        patch.coords for patch in cat.values()
+    )
+    plt.hist2d(coords.ra, np.sin(coords.dec), bins=90)
+    plt.xlabel(r"$\alpha$")
+    plt.ylabel(r"$\sin{\delta}$")
+
 
 .. figure:: /_static/rand_density.png
     :figwidth: 100%

src/yaw/cosmology.py

@@ -36,13 +36,17 @@
 
 
 class CustomCosmology(ABC):
-    """Meta-class that defines interface for custom cosmologies that are
-    compatible with `yet_another_wizz` code."""
+    """
+    Meta-class that defines the interface for custom cosmologies.
+
+    Custom cosmology must either be an `astropy` cosmological model or must be
+    a subclass of this meta-class to be compatible with `yet_another_wizz`.
+    """
 
     @abstractmethod
     def comoving_distance(self, z: ArrayLike) -> ArrayLike:
         """
-        Compute the comoving distance.
+        Compute the comoving distance at the given redshift.
 
         Args:
             z:
@@ -57,7 +61,7 @@ def comoving_distance(self, z: ArrayLike) -> ArrayLike:
     @abstractmethod
     def angular_diameter_distance(self, z: ArrayLike) -> ArrayLike:
         """
-        Compute the angular diameter distance.
+        Compute the angular diameter distance at the given redshift.
 
         Args:
             z:
@@ -91,6 +95,12 @@ def cosmology_is_equal(cosmo1: TypeCosmology, cosmo2: TypeCosmology) -> bool:
 
 
 def get_default_cosmology() -> FLRW:
+    """
+    Returns the default Planck 2015 cosmology.
+
+    Parameters are from Planck Collaboration (2016) Paper XIII, Table 4
+    (TT, TE, EE + lowP + lensing + ext)
+    """
     return Planck15