diff --git a/docs/conf.py b/docs/conf.py index 4392b0b6..d42ebc90 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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. @@ -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" @@ -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 ---------------------------------------------------------- diff --git a/glass/core/__init__.py b/glass/core/__init__.py index 0e4bf9d4..9ea756a2 100644 --- a/glass/core/__init__.py +++ b/glass/core/__init__.py @@ -7,4 +7,4 @@ The :mod:`glass.core` module contains core functionality for developing GLASS modules. -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 diff --git a/glass/core/algorithm.py b/glass/core/algorithm.py index 437ce63a..3e4ccbf3 100644 --- a/glass/core/algorithm.py +++ b/glass/core/algorithm.py @@ -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. diff --git a/glass/fields.py b/glass/fields.py index 38258c65..e8f73340 100644 --- a/glass/fields.py +++ b/glass/fields.py @@ -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 --------- @@ -22,7 +22,7 @@ .. autofunction:: getcl -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 from __future__ import annotations @@ -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. """ @@ -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 @@ -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 @@ -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 diff --git a/glass/galaxies.py b/glass/galaxies.py index ab16c0d1..80e693a4 100644 --- a/glass/galaxies.py +++ b/glass/galaxies.py @@ -15,7 +15,7 @@ .. autofunction:: galaxy_shear .. autofunction:: gaussian_phz -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 from __future__ import annotations @@ -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) @@ -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( @@ -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]) @@ -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 diff --git a/glass/lensing.py b/glass/lensing.py index 17d010d8..0a80b78a 100644 --- a/glass/lensing.py +++ b/glass/lensing.py @@ -27,7 +27,7 @@ .. autofunction:: deflect -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 from __future__ import annotations @@ -59,35 +59,34 @@ def from_convergence( # noqa: PLR0913 Compute other weak lensing maps from the convergence. Takes a weak lensing convergence map and returns one or more of - deflection potential, deflection, and shear maps. The maps are + deflection potential, deflection, and shear maps. The maps are computed via spherical harmonic transforms. + Returns the maps of: + + * deflection potential if ``potential`` is true. + * potential (complex) if ``deflection`` is true. + * shear (complex) if ``shear`` is true. + Parameters ---------- - kappa : array_like + kappa: HEALPix map of the convergence field. - lmax : int, optional + lmax: Maximum angular mode number to use in the transform. - potential, deflection, shear : bool, optional + potential: + Which lensing maps to return. + deflection: Which lensing maps to return. - discretized : bool + shear: + Which lensing maps to return. + discretized: Correct the pixel window function in output maps. - Returns - ------- - psi : array_like - Map of the deflection potential. Only returned if ``potential`` - is true. - alpha : array_like - Map of the deflection (complex). Only returned if ``deflection`` - if true. - gamma : array_like - Map of the shear (complex). Only returned if ``shear`` is true. - Notes ----- The weak lensing fields are computed from the convergence or - deflection potential in the following way. [1]_ + deflection potential in the following way. [1] Define the spin-raising and spin-lowering operators of the spin-weighted spherical harmonics as @@ -117,7 +116,7 @@ def from_convergence( # noqa: PLR0913 = -l \, (l+1) \, \psi_{lm} \;. The :term:`deflection` :math:`\alpha` is the gradient of the - deflection potential :math:`\psi`. On the sphere, this is + deflection potential :math:`\psi`. On the sphere, this is .. math:: @@ -126,7 +125,7 @@ def from_convergence( # noqa: PLR0913 The deflection field has spin weight :math:`1` in the HEALPix convention, in order for points to be deflected towards regions of - positive convergence. The modes :math:`\alpha_{lm}` of the + positive convergence. The modes :math:`\alpha_{lm}` of the deflection field are hence .. math:: @@ -143,7 +142,7 @@ def from_convergence( # noqa: PLR0913 = \eth\eth \, \psi = \eth \, \alpha \;, - and thus has spin weight :math:`2`. The shear modes + and thus has spin weight :math:`2`. The shear modes :math:`\gamma_{lm}` are related to the deflection potential modes as .. math:: @@ -153,7 +152,7 @@ def from_convergence( # noqa: PLR0913 References ---------- - .. [1] Tessore N., et al., OJAp, 6, 11 (2023). + * [1] Tessore N., et al., OJAp, 6, 11 (2023). doi:10.21105/astro.2302.01942 """ @@ -391,21 +390,18 @@ def multi_plane_weights( redshift distribution :math:`n(z)` into the lensing efficiency sometimes denoted :math:`g(z)` or :math:`q(z)`. + Returns the relative lensing weight of each shell. + Parameters ---------- - weights : array_like - Relative weight of each shell. The first axis must broadcast + weights: + Relative weight of each shell. The first axis must broadcast against the number of shells, and is normalised internally. - shells : list of :class:`~glass.RadialWindow` + shells: Window functions of the shells. - cosmo : Cosmology + cosmo: Cosmology instance. - Returns - ------- - lensing_weights : array_like - Relative lensing weight of each shell. - """ # ensure shape of weights ends with the number of shells shape = np.shape(weights) @@ -428,19 +424,18 @@ def deflect( Takes an array of :term:`deflection` values and applies them to the given positions. + Returns the longitudes and latitudes after deflection. + Parameters ---------- - lon, lat : array_like - Longitudes and latitudes to be deflected. - alpha : array_like - Deflection values. Must be complex-valued or have a leading + lon: + Longitudes to be deflected. + lat: + Latitudes to be deflected. + alpha: + Deflection values. Must be complex-valued or have a leading axis of size 2 for the real and imaginary component. - Returns - ------- - lon, lat : array_like - Longitudes and latitudes after deflection. - Notes ----- Deflections on the sphere are :term:`defined ` as diff --git a/glass/observations.py b/glass/observations.py index ab712285..7f82abe7 100644 --- a/glass/observations.py +++ b/glass/observations.py @@ -24,7 +24,7 @@ .. autofunction:: vmap_galactic_ecliptic -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 from __future__ import annotations @@ -49,20 +49,21 @@ def vmap_galactic_ecliptic( Visibility map masking galactic and ecliptic plane. This function returns a :term:`visibility map` that blocks out stripes for - the galactic and ecliptic planes. The location of the stripes is set with + the galactic and ecliptic planes. The location of the stripes is set with optional parameters. Parameters ---------- - nside : int + nside: The NSIDE parameter of the resulting HEALPix map. - galactic, ecliptic : (2,) tuple of float - The location of the galactic and ecliptic plane in their respective - coordinate systems. + galactic: + The location of the galactic plane in the respective coordinate system. + ecliptic: + The location of the ecliptic plane in the respective coordinate system. Returns ------- - vis : array_like + vis: A HEALPix :term:`visibility map`. Raises @@ -103,18 +104,18 @@ def gaussian_nz( Parameters ---------- - z : array_like + z: Redshift values of the distribution. - mean : float or array_like + mean: Mean(s) of the redshift distribution. - sigma : float or array_like + sigma: Standard deviation(s) of the redshift distribution. - norm : float or array_like, optional + norm: If given, the normalisation of the distribution. Returns ------- - nz : array_like + nz: Redshift distribution at the given ``z`` values. """ @@ -141,30 +142,30 @@ def smail_nz( r""" Redshift distribution following Smail et al. (1994). - The redshift follows the Smail et al. [1]_ redshift distribution. + The redshift follows the Smail et al. [1] redshift distribution. Parameters ---------- - z : array_like + z: Redshift values of the distribution. - z_mode : float or array_like + z_mode: Mode of the redshift distribution, must be positive. - alpha : float or array_like + alpha: Power law exponent (z/z0)^\alpha, must be positive. - beta : float or array_like + beta: Log-power law exponent exp[-(z/z0)^\beta], must be positive. - norm : float or array_like, optional + norm: If given, the normalisation of the distribution. Returns ------- - pz : array_like + pz: Redshift distribution at the given ``z`` values. Notes ----- The probability distribution function :math:`p(z)` for redshift :math:`z` - is given by Amara & Refregier [2]_ as + is given by Amara & Refregier [2] as .. math:: @@ -175,8 +176,8 @@ def smail_nz( References ---------- - .. [1] Smail I., Ellis R. S., Fitchett M. J., 1994, MNRAS, 270, 245 - .. [2] Amara A., Refregier A., 2007, MNRAS, 381, 1018 + * [1] Smail I., Ellis R. S., Fitchett M. J., 1994, MNRAS, 270, 245 + * [2] Amara A., Refregier A., 2007, MNRAS, 381, 1018 """ z_mode = np.asanyarray(z_mode)[..., np.newaxis] @@ -207,16 +208,18 @@ def fixed_zbins( Parameters ---------- - zmin, zmax : float + zmin: Extent of the redshift binning. - nbins : int, optional - Number of redshift bins. Only one of ``nbins`` and ``dz`` can be given. - dz : float, optional - Size of redshift bin. Only one of ``nbins`` and ``dz`` can be given. + zmax: + Extent of the redshift binning. + nbins: + Number of redshift bins. Only one of ``nbins`` and ``dz`` can be given. + dz: + Size of redshift bin. Only one of ``nbins`` and ``dz`` can be given. Returns ------- - zbins : list of tuple of float + zbins: List of redshift bin edges. """ @@ -244,14 +247,16 @@ def equal_dens_zbins( Parameters ---------- - z, nz : array_like + z: + The source redshift distribution. Must be one-dimensional. + nz: The source redshift distribution. Must be one-dimensional. - nbins : int + nbins: Number of redshift bins. Returns ------- - zbins : list of tuple of float + zbins: List of redshift bin edges. """ @@ -277,36 +282,38 @@ def tomo_nz_gausserr( This function takes a _true_ overall source redshift distribution ``z``, ``nz`` and returns tomographic source redshift distributions for the - tomographic redshift bins given by ``zbins``. It is assumed that sources - are assigned a tomographic redshift bin with a Gaussian error [1]_. The + tomographic redshift bins given by ``zbins``. It is assumed that sources + are assigned a tomographic redshift bin with a Gaussian error [1]. The standard deviation of the Gaussian depends on redshift and is given by ``sigma(z) = sigma_0*(1 + z)``. Parameters ---------- - z, nz : array_like + z: + The true source redshift distribution. Must be one-dimensional. + nz: The true source redshift distribution. Must be one-dimensional. - sigma_0 : float + sigma_0: Redshift error in the tomographic binning at zero redshift. - zbins : list of tuple of float + zbins: List of redshift bin edges. Returns ------- - binned_nz : array_like + binned_nz: Tomographic redshift bins convolved with a gaussian error. Array has a shape (nbins, len(z)) See Also -------- - equal_dens_zbins : + equal_dens_zbins: produce equal density redshift bins - fixed_zbins : + fixed_zbins: produce redshift bins of fixed size 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 """ diff --git a/glass/points.py b/glass/points.py index 3b8dcf10..d9494f31 100644 --- a/glass/points.py +++ b/glass/points.py @@ -27,7 +27,7 @@ .. autofunction:: linear_bias .. autofunction:: loglinear_bias -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 import healpix import numpy as np @@ -47,14 +47,16 @@ def effective_bias(z, bz, w): Parameters ---------- - z, bz : array_like + z: Redshifts and values of the bias function :math:`b(z)`. - w : :class:`~glass.RadialWindow` + bz: + Redshifts and values of the bias function :math:`b(z)`. + w: The radial window function :math:`w(z)`. Returns ------- - beff : array_like + beff: Effective bias parameter for the window. Notes @@ -104,53 +106,52 @@ def positions_from_delta( # noqa: PLR0912, PLR0913, PLR0915 visibility map. If ``remove_monopole`` is set, the monopole of the computed density - contrast is removed. Over the full sky, the mean number density of - the map will then match the given number density exactly. This, + contrast is removed. Over the full sky, the mean number density of + the map will then match the given number density exactly. This, however, means that an effectively different bias model is being used, unless the monopole is already zero in the first place. The function supports multi-dimensional input for the ``ngal``, - ``delta``, ``bias``, and ``vis`` parameters. Extra dimensions are + ``delta``, ``bias``, and ``vis`` parameters. Extra dimensions are broadcast to a common shape, and treated as separate populations of - points. These are then sampled independently, and the results - concatenated into a flat list of longitudes and latitudes. The + points. These are then sampled independently, and the results + concatenated into a flat list of longitudes and latitudes. The number of points per population is returned in ``count`` as an array in the shape of the extra dimensions. Parameters ---------- - ngal : float or array_like + ngal: Number density, expected number of points per arcmin2. - delta : array_like - Map of the input density contrast. This is fed into the bias + delta: + Map of the input density contrast. This is fed into the bias model to produce the density contrast for sampling. - bias : float or array_like, optional + bias: Bias parameter, is passed as an argument to the bias model. - vis : array_like, optional - Visibility map for the observed points. This is multiplied with - the full sky number count map, and must hence be of compatible - shape. - bias_model : str or callable, optional - The bias model to apply. If a string, refers to a function in + vis: + Visibility map for the observed points. This is multiplied with + the full sky number count map, and must hence be of compatible shape. + bias_model: + The bias model to apply. If a string, refers to a function in the :mod:`~glass.points` module, e.g. ``'linear'`` for - :func:`linear_bias()` or ``'loglinear'`` for - :func:`loglinear_bias`. - remove_monopole : bool, optional - If true, the monopole of the density contrast after biasing is - fixed to zero. - batch : int, optional + :func:`linear_bias()` or ``'loglinear'`` for :func:`loglinear_bias`. + remove_monopole: + If true, the monopole of the density contrast + after biasing is fixed to zero. + batch: Maximum number of positions to yield in one batch. - rng : :class:`~numpy.random.Generator`, optional - Random number generator. If not given, a default RNG is used. + rng: + Random number generator. If not given, a default RNG is used. Yields ------ - lon, lat : array_like - Columns of longitudes and latitudes for the sampled points. - count : int or array_like - The number of sampled points. If multiple populations are - sampled, an array of counts in the shape of the extra - dimensions is returned. + lon: + Columns of longitudes for the sampled points. + lat: + Columns of latitudes for the sampled points. + count: + The number of sampled points If multiple populations are sampled, an + array of counts in the shape of the extra dimensions is returned. """ # get default RNG if not given @@ -255,17 +256,19 @@ def uniform_positions(ngal, *, rng=None): Parameters ---------- - ngal : float or array_like + ngal: Number density, expected number of positions per arcmin2. - rng : :class:`~numpy.random.Generator`, optional - Random number generator. If not given, a default RNG will be used. + rng: + Random number generator. If not given, a default RNG will be used. Yields ------ - lon, lat : array_like or list of array_like - Columns of longitudes and latitudes for the sampled points. - count : int or list of ints - The number of sampled points. For array inputs, an array of + lon: + Columns of longitudes for the sampled points. + lat: + Columns of latitudes for the sampled points. + count: + The number of sampled points. For array inputs, an array of counts with the same shape is returned. """ @@ -303,7 +306,7 @@ def position_weights(densities, bias=None): Compute relative weights for angular clustering. Takes an array *densities* of densities in arbitrary units and - returns the relative weight of each shell. If *bias* is given, a + returns the relative weight of each shell. If *bias* is given, a linear bias is applied to each shell. This is the equivalent of computing the product of normalised @@ -312,15 +315,15 @@ def position_weights(densities, bias=None): Parameters ---------- - densities : array_like - Density of points in each shell. The first axis must broadcast + densities: + Density of points in each shell. The first axis must broadcast against the number of shells, and is normalised internally. - bias : array_like, optional + bias: Value or values of the linear bias parameter for each shell. Returns ------- - weights : array_like + weights: Relative weight of each shell for angular clustering. """ diff --git a/glass/shapes.py b/glass/shapes.py index ccd8ce44..f3f2d43e 100644 --- a/glass/shapes.py +++ b/glass/shapes.py @@ -20,7 +20,7 @@ .. autofunction:: triaxial_axis_ratio -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 from __future__ import annotations @@ -41,28 +41,28 @@ def triaxial_axis_ratio(zeta, xi, size=None, *, rng=None): Parameters ---------- - zeta : array_like + zeta: Axis ratio of intermediate and major axis. - xi : array_like + xi: Axis ratio of minor and major axis. - size : tuple of int or None + size: Size of the random draw. If `None` is given, size is inferred from other inputs. - rng : :class:`~numpy.random.Generator`, optional - Random number generator. If not given, a default RNG will be used. + rng: + Random number generator. If not given, a default RNG will be used. Returns ------- - q : array_like + q: Axis ratio of the randomly projected ellipsoid. Notes ----- - See equations (11) and (12) in [1]_ for details. + See equations (11) and (12) in [1] for details. References ---------- - .. [1] Binney J., 1985, MNRAS, 212, 767. doi:10.1093/mnras/212.4.767 + * [1] Binney J., 1985, MNRAS, 212, 767. doi:10.1093/mnras/212.4.767 """ # default RNG if not provided @@ -102,36 +102,36 @@ def ellipticity_ryden04(mu, sigma, gamma, sigma_gamma, size=None, *, rng=None): Ellipticity distribution following Ryden (2004). The ellipticities are sampled by randomly projecting a 3D ellipsoid with - principal axes :math:`A > B > C` [1]_. The distribution of :math:`\log(1 - + principal axes :math:`A > B > C` [1]. The distribution of :math:`\log(1 - B/A)` is normal with mean :math:`\mu` and standard deviation :math:`\sigma`. The distribution of :math:`1 - C/B` is normal with mean :math:`\gamma` and - standard deviation :math:`\sigma_\gamma` [2]_. Both distributions are + standard deviation :math:`\sigma_\gamma` [2]. Both distributions are truncated to produce ratios in the range 0 to 1 using rejection sampling. Parameters ---------- - mu : array_like + mu: Mean of the truncated normal for :math:`\log(1 - B/A)`. - sigma : array_like + sigma: Standard deviation for :math:`\log(1 - B/A)`. - gamma : array_like + gamma: Mean of the truncated normal for :math:`1 - C/B`. - sigma_gamma : array_like + sigma_gamma: Standard deviation for :math:`1 - C/B`. - size : int or tuple of ints or None - Sample size. If ``None``, the size is inferred from the parameters. - rng : :class:`~numpy.random.Generator`, optional - Random number generator. If not given, a default RNG will be used. + size: + Sample size. If ``None``, the size is inferred from the parameters. + rng: + Random number generator. If not given, a default RNG will be used. Returns ------- - eps : array_like + eps: Array of :term:`ellipticity` from projected axis ratios. References ---------- - .. [1] Ryden B. S., 2004, ApJ, 601, 214. - .. [2] Padilla N. D., Strauss M. A., 2008, MNRAS, 388, 1321. + * [1] Ryden B. S., 2004, ApJ, 601, 214. + * [2] Padilla N. D., Strauss M. A., 2008, MNRAS, 388, 1321. """ # default RNG if not provided @@ -180,23 +180,23 @@ def ellipticity_gaussian( Sample Gaussian galaxy ellipticities. The ellipticities are sampled from a normal distribution with - standard deviation ``sigma`` for each component. Samples where the - ellipticity is larger than unity are discarded. Hence, do not use + standard deviation ``sigma`` for each component. Samples where the + ellipticity is larger than unity are discarded. Hence, do not use this function with too large values of ``sigma``, or the sampling will become inefficient. Parameters ---------- - count : int or array_like + count: Number of ellipticities to be sampled. - sigma : array_like + sigma: Standard deviation in each component. - rng : :class:`~numpy.random.Generator`, optional - Random number generator. If not given, a default RNG is used. + rng: + Random number generator. If not given, a default RNG is used. Returns ------- - eps : array_like + eps: Array of galaxy :term:`ellipticity`. """ @@ -241,16 +241,16 @@ def ellipticity_intnorm( Parameters ---------- - count : int | array_like + count: Number of ellipticities to sample. - sigma : array_like + sigma: Standard deviation of the ellipticity in each component. - rng : :class:`~numpy.random.Generator`, optional - Random number generator. If not given, a default RNG is used. + rng: + Random number generator. If not given, a default RNG is used. Returns ------- - eps : array_like + eps: Array of galaxy :term:`ellipticity`. """ diff --git a/glass/shells.py b/glass/shells.py index d1054af4..eb2906a5 100644 --- a/glass/shells.py +++ b/glass/shells.py @@ -40,7 +40,7 @@ .. autofunction:: distance_weight .. autofunction:: volume_weight .. autofunction:: density_weight -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 from __future__ import annotations @@ -107,11 +107,11 @@ class RadialWindow(NamedTuple): Attributes ---------- - za : Sequence[float] + za: Redshift array; the abscissae of the window function. - wa : Sequence[float] + wa: Weight array; the values (ordinates) of the window function. - zeff : float + zeff: Effective redshift of the window. Methods @@ -134,7 +134,7 @@ def tophat_windows( Tophat window functions from the given redshift bin edges. Uses the *N+1* given redshifts as bin edges to construct *N* tophat - window functions. The redshifts of the windows have linear spacing + window functions. The redshifts of the windows have linear spacing approximately equal to ``dz``. An optional weight function :math:`w(z)` can be given using @@ -144,20 +144,16 @@ def tophat_windows( Their effective redshifts are the mean redshifts of the (weighted) tophat bins. + Returns a list of window functions. + Parameters ---------- - zbins : (N+1,) array_like + zbins: Redshift bin edges for the tophat window functions. - dz : float, optional + dz: Approximate spacing of the redshift grid. - weight : callable, optional - If given, a weight function to be applied to the window - functions. - - Returns - ------- - ws : (N,) list of :class:`RadialWindow` - List of window functions. + weight: + If given, a weight function to be applied to the window functions. See Also -------- @@ -193,8 +189,8 @@ def linear_windows( Linear interpolation window functions. Uses the *N+2* given redshifts as nodes to construct *N* triangular - window functions between the first and last node. These correspond - to linear interpolation of radial functions. The redshift spacing + window functions between the first and last node. These correspond + to linear interpolation of radial functions. The redshift spacing of the windows is approximately equal to ``dz``. An optional weight function :math:`w(z)` can be given using @@ -203,20 +199,16 @@ def linear_windows( The resulting windows functions are :class:`RadialWindow` instances. Their effective redshifts correspond to the given nodes. + Returns a list of window functions. + Parameters ---------- - zgrid : (N+2,) array_like + zgrid: Redshift grid for the triangular window functions. - dz : float, optional + dz: Approximate spacing of the redshift grid. - weight : callable, optional - If given, a weight function to be applied to the window - functions. - - Returns - ------- - ws : (N,) list of :class:`RadialWindow` - List of window functions. + weight: + If given, a weight function to be applied to the window functions. See Also -------- @@ -265,20 +257,16 @@ def cubic_windows( The resulting windows functions are :class:`RadialWindow` instances. Their effective redshifts correspond to the given nodes. + Returns a list of window functions. + Parameters ---------- - zgrid : (N+2,) array_like + zgrid: Redshift grid for the cubic spline window functions. - dz : float, optional + dz: Approximate spacing of the redshift grid. - weight : callable, optional - If given, a weight function to be applied to the window - functions. - - Returns - ------- - ws : (N,) list of :class:`RadialWindow` - List of window functions. + weight: + If given, a weight function to be applied to the window functions. See Also -------- @@ -329,18 +317,17 @@ def restrict( the function and window over the support of the window. Intermediate function values are found by linear interpolation + Returns the restricted function + Parameters ---------- - z, f : array_like + z: The function to be restricted. - w : :class:`RadialWindow` + f: + The function to be restricted. + w: The window function for the restriction. - Returns - ------- - zr, fr : array - The restricted function. - """ z_ = np.compress(np.greater(z, w.za[0]) & np.less(z, w.za[-1]), z) zr = np.union1d(w.za, z_) @@ -370,21 +357,22 @@ def partition( The window functions are given by the sequence *shells* of :class:`RadialWindow` or compatible entries. + Returns the weights of the partition, where the leading axis corresponds to + *shells*. + Parameters ---------- - z, fz : array_like - The function to be partitioned. If *f* is multi-dimensional, + z: + The function to be partitioned. If *f* is multi-dimensional, + its last axis must agree with *z*. + fz: + The function to be partitioned. If *f* is multi-dimensional, its last axis must agree with *z*. - shells : sequence of :class:`RadialWindow` + shells: Ordered sequence of window functions for the partition. - method : {"lstsq", "nnls", "restrict"} - Method for the partition. See notes for description. - - Returns - ------- - x : array_like - Weights of the partition, where the leading axis corresponds to - *shells*. + method: + Method for the partition. See notes for description. The + options are "lstsq", "nnls", "restrict". Notes ----- @@ -405,11 +393,11 @@ def partition( \\end{pmatrix} \\;. The redshift grid is the union of the given array *z* and the - redshift arrays of all window functions. Intermediate function + redshift arrays of all window functions. Intermediate function values are found by linear interpolation. When partitioning a density function, it is usually desirable to - keep the normalisation fixed. In that case, the problem can be + keep the normalisation fixed. In that case, the problem can be enhanced with the further constraint that the sum of the solution equals the integral of the target function, @@ -434,19 +422,19 @@ def partition( obtain a solution: If ``method="nnls"`` (the default), obtain a partition from a - non-negative least-squares solution. This will usually match the - shape of the input function closely. The contribution from each + non-negative least-squares solution. This will usually match the + shape of the input function closely. The contribution from each shell is a positive number, which is required to partition e.g. density functions. If ``method="lstsq"``, obtain a partition from an unconstrained - least-squares solution. This will more closely match the shape of + least-squares solution. This will more closely match the shape of the input function, but might lead to shells with negative contributions. If ``method="restrict"``, obtain a partition by integrating the restriction (using :func:`restrict`) of the function :math:`f` to - each window. For overlapping shells, this method might produce + each window. For overlapping shells, this method might produce results which are far from the input function. """ @@ -619,24 +607,22 @@ def combine( The window functions are given by the sequence *shells* of :class:`RadialWindow` or compatible entries. + Returns a linear combination of window functions, evaluated in *z*. + Parameters ---------- - z : array_like + z: Redshifts *z* in which to evaluate the combined function. - weights : array_like + weights: Weights of the linear combination, where the leading axis corresponds to *shells*. - shells : sequence of :class:`RadialWindow` + shells: Ordered sequence of window functions to be combined. - Returns - ------- - fz : array_like - Linear combination of window functions, evaluated in *z*. - See Also -------- - partition : Find weights for a given function. + partition: + Find weights for a given function. """ return sum( diff --git a/glass/user.py b/glass/user.py index 7996e784..cd7d433b 100644 --- a/glass/user.py +++ b/glass/user.py @@ -15,7 +15,7 @@ .. autofunction:: load_cls .. autofunction:: write_catalog -""" # noqa: D205, D400, D415 +""" # noqa: D205, D400 from contextlib import contextmanager diff --git a/pyproject.toml b/pyproject.toml index 24c2cc59..186a467b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,7 +43,6 @@ docs = [ "ipython", "matplotlib", "nbsphinx", - "numpydoc", "sphinx", "sphinxcontrib-katex", ] @@ -172,6 +171,7 @@ lint.select = [ "ALL", ] lint.mccabe.max-complexity = 18 +lint.pydocstyle.convention = "numpy" [tool.tomlsort] all = true