Skip to content

Commit

Permalink
gh-346: enforce NumPy docstrings + use static typing in docs (#347)
Browse files Browse the repository at this point in the history 
Closes #346. Working towards #188.

The main changes here have been:
- Remove all types in the docstrings in favour of proper static typing
(being added in #308)
- Switch from `numpydoc` to `sphinx.ext.napolean` due to
numpy/numpydoc#196

Have had to change the references to `[1]` rather than `[1]_` due to
this bug, sphinx-doc/sphinx#9689. Hopefully
this can be fixed in the future.

Example:
`glass.lensing.from_convergence`
<img width="781" alt="image"
src="https://github.com/user-attachments/assets/9b6fd087-686a-4a5c-a77a-f8a3ec9fc3e2">

Raised #350, #351.
  • Loading branch information
@paddyroddy
paddyroddy authored Oct 14, 2024
1 parent 28d5fb8 commit 41c4266
Show file tree
Hide file tree
Showing 12 changed files with 310 additions and 329 deletions.
17 changes: 7 additions & 10 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,12 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"numpydoc",
"sphinx.ext.intersphinx",
"sphinxcontrib.katex",
"matplotlib.sphinxext.plot_directive",
"nbsphinx",
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
"sphinxcontrib.katex",
]

# Add any paths that contain templates here, relative to this directory.
Expand All @@ -42,7 +42,7 @@

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "furo"
Expand All @@ -69,15 +69,12 @@

# -- autodoc -----------------------------------------------------------------

autodoc_typehints = "none"
autodoc_typehints = "description"


# -- numpydoc ----------------------------------------------------------------
# -- napoleon ----------------------------------------------------------------

# Whether to create a Sphinx table of contents for the lists of class methods
# and attributes. If a table of contents is made, Sphinx expects each entry to
# have a separate page.
numpydoc_class_members_toctree = False
napoleon_google_docstring = False


# -- plot_directive ----------------------------------------------------------
Expand Down
2 changes: 1 addition & 1 deletion glass/core/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@
The :mod:`glass.core` module contains core functionality for developing
GLASS modules.
""" # noqa: D205, D400, D415
""" # noqa: D205, D400
6 changes: 3 additions & 3 deletions glass/core/algorithm.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,13 @@ def nnls(
"""
Compute a non-negative least squares solution.
Implementation of the algorithm due to [1]_ as described in [2]_.
Implementation of the algorithm due to [1] as described in [2].
References
----------
.. [1] Lawson, C. L. and Hanson, R. J. (1995), Solving Least Squares
* [1] Lawson, C. L. and Hanson, R. J. (1995), Solving Least Squares
Problems. doi: 10.1137/1.9781611971217
.. [2] Bro, R. and De Jong, S. (1997), A fast
* [2] Bro, R. and De Jong, S. (1997), A fast
non-negativity-constrained least squares algorithm. J.
Chemometrics, 11, 393-401.
Expand Down
50 changes: 22 additions & 28 deletions glass/fields.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
.. currentmodule:: glass
The following functions provide functionality for simulating random
fields on the sphere. This is done in the form of HEALPix maps.
fields on the sphere. This is done in the form of HEALPix maps.
Functions
---------
Expand All @@ -22,7 +22,7 @@
.. autofunction:: getcl
""" # noqa: D205, D400, D415
""" # noqa: D205, D400

from __future__ import annotations

Expand Down Expand Up @@ -163,7 +163,7 @@ def gaussian_gls(
Depending on the given arguments, this truncates the angular power spectra
to ``lmax``, removes all but ``ncorr`` correlations between fields, and
applies the HEALPix pixel window function of the given ``nside``. If no
applies the HEALPix pixel window function of the given ``nside``. If no
arguments are given, no action is performed.
"""
Expand Down Expand Up @@ -221,7 +221,7 @@ def generate_gaussian(
``nside``.
The optional argument ``ncorr`` can be used to artificially limit now many
realised fields are correlated. This saves memory, as only `ncorr` previous
realised fields are correlated. This saves memory, as only `ncorr` previous
fields need to be kept.
The ``gls`` array must contain the auto-correlation of each new field
Expand Down Expand Up @@ -329,18 +329,15 @@ def getcl(cls, i, j, lmax=None):
Parameters
----------
cls : list of array_like
cls:
List of angular power spectra in *GLASS* ordering.
i, j : int
Combination of indices to return.
lmax : int, optional
i:
Indices to return.
j:
Indices to return.
lmax:
Truncate the returned spectrum at this mode number.
Returns
-------
cl : array_like
The angular power spectrum for indices *i* and *j*.
"""
if j > i:
i, j = j, i
Expand All @@ -360,28 +357,25 @@ def effective_cls(
Compute effective angular power spectra from weights.
Computes a linear combination of the angular power spectra *cls*
using the factors provided by *weights1* and *weights2*. Additional
using the factors provided by *weights1* and *weights2*. Additional
axes in *weights1* and *weights2* produce arrays of spectra.
Returns a dictionary of effective angular power spectra, where keys
correspond to the leading axes of *weights1* and *weights2*.
Parameters
----------
cls : (N,) list of array_like
cls:
Angular matter power spectra to combine, in *GLASS* ordering.
weights1 : (N, \\*M1) array_like
Weight factors for spectra. The first axis must be equal to the
number of fields.
weights2 : (N, \\*M2) array_like, optional
Second set of weights. If not given, *weights1* is used.
lmax : int, optional
Truncate the angular power spectra at this mode number. If not
weights1:
Weight factors for spectra. The first axis must be equal to
the number of fields.
weights2:
Second set of weights. If not given, *weights1* is used.
lmax:
Truncate the angular power spectra at this mode number. If not
given, the longest input in *cls* will be used.
Returns
-------
cls : (\\*M1, \\*M2, LMAX+1) array_like
Dictionary of effective angular power spectra, where keys
correspond to the leading axes of *weights1* and *weights2*.
"""
from itertools import combinations_with_replacement, product

Expand Down
111 changes: 55 additions & 56 deletions glass/galaxies.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
.. autofunction:: galaxy_shear
.. autofunction:: gaussian_phz
""" # noqa: D205, D400, D415
""" # noqa: D205, D400

from __future__ import annotations

Expand Down Expand Up @@ -45,20 +45,17 @@ def redshifts(
This function samples *n* redshifts from a distribution that follows
the given radial window function *w*.
Returns random redshifts following the radial window function.
Parameters
----------
n : int or array_like
Number of redshifts to sample. If an array is given, the
n:
Number of redshifts to sample. If an array is given, the
results are concatenated.
w : :class:`~glass.RadialWindow`
w:
Radial window function.
rng : :class:`~numpy.random.Generator`, optional
Random number generator. If not given, a default RNG is used.
Returns
-------
z : array_like
Random redshifts following the radial window function.
rng:
Random number generator. If not given, a default RNG is used.
"""
return redshifts_from_nz(n, w.za, w.wa, rng=rng, warn=False)
Expand All @@ -77,31 +74,31 @@ def redshifts_from_nz(
The function supports sampling from multiple populations of
redshifts if *count* is an array or if there are additional axes in
the *z* or *nz* arrays. In this case, the shape of *count* and the
the *z* or *nz* arrays. In this case, the shape of *count* and the
leading dimensions of *z* and *nz* are broadcast to a common shape,
and redshifts are sampled independently for each extra dimension.
The results are concatenated into a flat array.
Returns redshifts sampled from the given source distribution. For
inputs with extra dimensions, returns a flattened 1-D array of
samples from all populations.
Parameters
----------
count : int or array_like
Number of redshifts to sample. If an array is given, its shape
count:
Number of redshifts to sample. If an array is given, its shape
is broadcast against the leading axes of *z* and *nz*.
z, nz : array_like
Source distribution. Leading axes are broadcast against the
z:
Source distribution. Leading axes are broadcast against the
shape of *count*.
rng : :class:`~numpy.random.Generator`, optional
Random number generator. If not given, a default RNG is used.
warn : bool
nz:
Source distribution. Leading axes are broadcast against the
shape of *count*.
rng:
Random number generator. If not given, a default RNG is used.
warn:
Throw relevant warnings.
Returns
-------
redshifts : array_like
Redshifts sampled from the given source distribution. For
inputs with extra dimensions, returns a flattened 1-D array of
samples from all populations.
"""
if warn:
warnings.warn(
Expand Down Expand Up @@ -158,22 +155,26 @@ def galaxy_shear( # noqa: PLR0913
Takes lensing maps for convergence and shear and produces a lensed
ellipticity (shear) for each intrinsic galaxy ellipticity.
Returns an array of complex-valued observed galaxy shears
(lensed ellipticities).
Parameters
----------
lon, lat : array_like
Arrays for galaxy longitudes and latitudes.
eps : array_like
lon:
Array for galaxy longitudes.
lat:
Array for galaxy latitudes.
eps:
Array of galaxy :term:`ellipticity`.
kappa, gamma1, gamma2 : array_like
HEALPix maps for convergence and two components of shear.
reduced_shear : bool, optional
If ``False``, galaxy shears are not reduced by the convergence.
Default is ``True``.
Returns
-------
she : array_like
Array of complex-valued observed galaxy shears (lensed ellipticities).
kappa:
HEALPix map for convergence.
gamma1:
HEALPix maps for a component of shear.
gamma2:
HEALPix maps for a component of shear.
reduced_shear:
If ``False``, galaxy shears are not reduced
by the convergence. Default is ``True``.
"""
nside = healpix.npix2nside(np.broadcast(kappa, gamma1, gamma2).shape[-1])
Expand Down Expand Up @@ -218,40 +219,38 @@ def gaussian_phz(
A simple toy model of photometric redshift errors that assumes a
Gaussian error with redshift-dependent standard deviation
:math:`\sigma(z) = (1 + z) \sigma_0` [1]_.
:math:`\sigma(z) = (1 + z) \sigma_0` [1].
Returns photometric redshifts assuming Gaussian errors, of the same
shape as *z*.
Parameters
----------
z : array_like
z:
True redshifts.
sigma_0 : float or array_like
sigma_0:
Redshift error in the tomographic binning at zero redshift.
lower, upper : float or array_like, optional
lower:
Bounds for the returned photometric redshifts.
rng : :class:`~numpy.random.Generator`, optional
Random number generator. If not given, a default RNG is used.
Returns
-------
phz : array_like
Photometric redshifts assuming Gaussian errors, of the same
shape as *z*.
upper:
Bounds for the returned photometric redshifts.
rng:
Random number generator. If not given, a default RNG is used.
Warnings
--------
The *lower* and *upper* bounds are implemented using plain rejection
sampling from the non-truncated normal distribution. If bounds are
sampling from the non-truncated normal distribution. If bounds are
used, they should always contain significant probability mass.
See Also
--------
glass.tomo_nz_gausserr :
Create tomographic redshift distributions assuming the same
model.
glass.tomo_nz_gausserr:
Create tomographic redshift distributions assuming the same model.
References
----------
.. [1] Amara A., Réfrégier A., 2007, MNRAS, 381, 1018.
* [1] Amara A., Réfrégier A., 2007, MNRAS, 381, 1018.
doi:10.1111/j.1365-2966.2007.12271.x
Examples
Expand Down
Loading

0 comments on commit 41c4266

Please sign in to comment.