PyCosmoMMF 0.6.0__tar.gz → 1.0.1__tar.gz

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycosmommf
-Version: 0.6.0
+Version: 1.0.1
 Summary: A package for identifying structures in the cosmic web.
 Project-URL: Homepage, https://github.com/James11222/pycosmommf
 Project-URL: Bug Tracker, https://github.com/James11222/pycosmommf/issues
@@ -64,6 +64,7 @@ Description-Content-Type: text/markdown
 
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
+[![DOI](https://zenodo.org/badge/770792459.svg)](https://doi.org/10.5281/zenodo.14876495)
 
 [![codecov](https://codecov.io/gh/James11222/PyCosmoMMF/graph/badge.svg?token=UCHHHXEV2D)](https://codecov.io/gh/James11222/PyCosmoMMF)
 [![PyPI version][pypi-version]][pypi-link]

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/README.md

@@ -2,6 +2,7 @@
 
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
+[![DOI](https://zenodo.org/badge/770792459.svg)](https://doi.org/10.5281/zenodo.14876495)
 
 [![codecov](https://codecov.io/gh/James11222/PyCosmoMMF/graph/badge.svg?token=UCHHHXEV2D)](https://codecov.io/gh/James11222/PyCosmoMMF)
 [![PyPI version][pypi-version]][pypi-link]

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/docs/basic_usage.md

@@ -46,7 +46,7 @@ density_field = np.load("path/to/density_field.npy")
 Rs = [sqrt(2) ** n for n in range(10)]  # smoothing scales
 
 max_signatures = PyCosmoMMF.maximum_signature(
-    Rs, density_field, alg="NEXUSPLUS"
+    Rs, density_field, algorithm="NEXUSPLUS"
 )  # compute maximum signatures
 ```
 
@@ -67,18 +67,13 @@ output of this can be seen below
 
 We then have the option of running the tagging scheme a few different ways. The
 first important argument in `calc_structure_bools()` besides the `density_field`
-and the `max_signatures` arrays is the `verbose_flag`. When
-
-set to `True` the code gives a lot more information and provides a few plots.
-This is best turned on when
-
-debugging the code. When `verbose_flag` is turned on there are 4 additional
-outputs to the `calc_structure_bools()`
-
-function: `S_fil, dM2_fil, S_wall, dM2_wall` which can be used to make the mass
-change curves for filaments and
-
-walls.
+and the `max_signatures` arrays is the `verbose_flag`. When set to `True` the
+code gives a lot more information and provides a few plots. This is best turned
+on when debugging the code. When `verbose_flag` is turned on there is an
+additional output to the `calc_structure_bools()` function: `summary_data` which
+is a dictionary containing all the relevant extra information one might need. It
+can be used to make the mass change curves for filaments and walls. Consult the
+API Docs tab for a detailed summary of what is inside `summary_data`.
 
 **_Verbose Flag On:_**
 
@@ -86,8 +81,8 @@ walls.
 verbose_flag = True  # or False
 
 
-clusbool, filbool, wallbool, voidbool, S_fil, dM2_fil, S_wall, dM2_wall = (
-    PyCosmoMMF.calc_structure_bools(density_field, max_signatures, verbose_flag)
+clusbool, filbool, wallbool, voidbool, summary_data = PyCosmoMMF.calc_structure_bools(
+    density_field, max_signatures, verbose_flag
 )  # tag structures
 ```
 
@@ -125,11 +120,13 @@ clusbool, filbool, wallbool, voidbool = PyCosmoMMF.calc_structure_bools(
 ```
 
 Another important optional argument in the `calc_structure_bools()` function is
-`Δ`. The default value is `Δ = 370` as used in
+`overdensity_threshold`. The default value is `overdensity_threshold = 370` as
+used in
 [Cautun et al. 2013](https://academic.oup.com/mnras/article/429/2/1286/1038906)
-but other values can be 200 or 500 corresponding to `R_200` or `R_500`. `Δ` is
-the overdensity parameter, when clusters achieve a density greater than this
-value, they are thought to be virialized/collapsed.
+but other values can be 200 or 500 corresponding to `R_200` or `R_500`.
+`overdensity_threshold` is the overdensity parameter Δ, when clusters achieve an
+average overdensity greater than this value, they are thought to be
+virialized/collapsed.
 
 The boolean filters for each structure type produced by `calc_structure_bools()`
 can be used to tag structures within a density field, the results of this can be

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/pyproject.toml

@@ -124,6 +124,7 @@ ignore = [
   "PLR09",    # Too many <...>
   "PLR2004",  # Magic value used in comparison
   "ISC001",   # Conflicts with formatter
+  "RUF001",   # allow usage of `ρ` symbol in docstrings
 ]
 isort.required-imports = ["from __future__ import annotations"]
 

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/src/pycosmommf/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.6.0'
-__version_tuple__ = version_tuple = (0, 6, 0)
+__version__ = version = '1.0.1'
+__version_tuple__ = version_tuple = (1, 0, 1)

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/src/pycosmommf/filter.py

@@ -8,19 +8,19 @@ jit_compiler = nb.njit(parallel=True, fastmath=True)
 
 def wavevectors3D(dims, box_size=(2 * np.pi, 2 * np.pi, 2 * np.pi)):
     """
-    Returns the wavevectors for a 3D grid of dimensions `dims` and box size `box_size`.
-
-    Parameters
-    ----------
-    dims : tuple
-        The dimensions of the grid.
-    box_size : tuple
-        The size of the box in each dimension.
-
-    Returns
-    -------
-    kx, ky, kz : tuple
-        The wavevectors in each dimension.
+    Returns the wavevectors for a 3D grid of dimensions ``dims`` and box size ``box_size``.
+
+    Args:
+        dims (:obj:`tuple`):
+            The dimensions of the grid ``(nx, ny, nz)``.
+        box_size (:obj:`tuple`, optional):
+            The size of the box in each dimension ``(Lx, Ly, Lz)``. Defaults to ``(2π, 2π, 2π)``.
+
+    Returns:
+        (tuple): a tuple containing:
+            - **kx** (:obj:`np.ndarray`): The wavevector in the x-direction.
+            - **ky** (:obj:`np.ndarray`): The wavevector in the y-direction.
+            - **kz** (:obj:`np.ndarray`): The wavevector in the z-direction.
     """
     sample_rate = 2 * np.pi * (np.array(dims) / box_size)
     kx = (np.fft.fftfreq(dims[0], 1 / sample_rate[0]) * (2 * np.pi / dims[0])).astype(
@@ -40,17 +40,14 @@ def kspace_gaussian_filter(R_S, kv):  # pragma: no cover
     """
     create a Gaussian filter in k-space.
 
-    Parameters
-    ----------
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    filter_k : array
-        The filter in k-space.
+    Args:
+        R_S (:obj:`float`):
+            The smoothing scale.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension, each a ``1D float np.ndarray``.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The filter in k-space.
     """
     kx, ky, kz = kv
     nx, ny, nz = len(kx), len(ky), len(kz)
@@ -69,17 +66,14 @@ def kspace_top_hat_filter(R_S, kv):  # pragma: no cover
     """
     create a top-hat filter in k-space.
 
-    Parameters
-    ----------
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    filter_k : array
-        The filter in k-space.
+    Args:
+        R_S (:obj:`float`):
+            The smoothing scale.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The filter in k-space.
     """
 
     kx, ky, kz = kv
@@ -106,19 +100,16 @@ def smooth_top_hat(f, R_S, kv):
     """
     apply a top-hat filter to a field f.
 
-    Parameters
-    ----------
-    f : array
-        The field to be smoothed.
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    f_Rn : array
-        The smoothed field.
+    Args:
+        f (:obj:`3D float np.ndarray`):
+            The field to be smoothed.
+        R_S (:obj:`float`):
+            The smoothing scale in units of voxels.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The smoothed field.
     """
     GF = kspace_top_hat_filter(R_S, kv)
     f_Rn = np.real(np.fft.ifftn(GF * np.fft.fftn(f)))
@@ -130,19 +121,16 @@ def smooth_gauss(f, R_S, kv):
     """
     apply a Gaussian filter to a field f.
 
-    Parameters
-    ----------
-    f : array
-        The field to be smoothed.
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    f_Rn : array
-        The smoothed field.
+    Args:
+        f (:obj:`3D float np.ndarray`):
+            The field to be smoothed.
+        R_S (:obj:`float`):
+            The smoothing scale in units of voxels.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The smoothed field.
     """
     GF = kspace_gaussian_filter(R_S, kv)
     f_Rn = np.real(np.fft.ifftn(GF * np.fft.fftn(f)))
@@ -154,19 +142,16 @@ def smooth_loggauss(f, R_S, kv):
     """
     apply a Gaussian filter to the log of a field f.
 
-    Parameters
-    ----------
-    f : array
-        The field to be smoothed.
-    R_S : float
-        The smoothing scale.
-    kv : tuple
-        The wavevectors in each dimension.
-
-    Returns
-    -------
-    f_Rn : array
-        The smoothed field.
+    Args:
+        f (:obj:`3D float np.ndarray`):
+            The field to be smoothed.
+        R_S (:obj:`float`):
+            The smoothing scale in units of voxels.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The smoothed field.
     """
     # Get filter in Fourier space
     GF = kspace_gaussian_filter(R_S, kv)

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/src/pycosmommf/hessian.py

@@ -10,19 +10,17 @@ def fast_hessian_from_smoothed(f_Rn, R_S, kv):
     """
     Compute the hessian matrix of the smoothed field f_Rn.
 
-    Parameters
-    ----------
-    f_Rn : 3D array
-        The smoothed field.
-    R_S : float
-        The smoothing scale.
-    kv : 3D array
-        The wavevectors.
-
-    Returns
-    -------
-    hessian : 3D array
-        The hessian matrix.
+    Args:
+        f_Rn (:obj:`3D float np.ndarray`):
+            The smoothed field in real space.
+        R_S (:obj:`float`):
+            The smoothing scale in units of voxels.
+        kv (:obj:`tuple`):
+            The wavevectors in each dimension.
+
+    Returns:
+        (:obj:`4D float np.ndarray`): The hessian matrix of the smoothed field.
+        The shape is ``(nx, ny, nz, 6)``, where ``nx, ny, nz`` are the dimensions of ``f_Rn``.
     """
 
     f_Rn_hat = np.fft.fftn(f_Rn)

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/src/pycosmommf/signatures.py

@@ -14,15 +14,15 @@ def signatures_from_hessian(hessian):  # pragma: no cover
     """
     Function to calculate the signatures from a given hessian.
 
-    Parameters
-    ----------
-    hessian : 4D array
-        The hessian matrix.
-
-    Returns
-    -------
-    sigs : 4D array
-        The signatures.
+    Args:
+        hessian (:obj:`4D float np.ndarray`):
+            The hessian matrix of the smoothed field, with shape ``(nx, ny, nz, 6)``.
+
+    Returns:
+        (:obj:`4D float np.ndarray`): The signatures array with shape ``(nx, ny, nz, 3)``. Each signature corresponds to a different type of structure:
+            - ``sigs[..., 0]``: Cluster signature
+            - ``sigs[..., 1]``: Filament signature
+            - ``sigs[..., 2]``: Wall signature
     """
 
     hsize = hessian.shape[:3]
@@ -78,35 +78,34 @@ def signatures_from_hessian(hessian):  # pragma: no cover
     return sigs
 
 
-def maximum_signature(Rs, field, alg="NEXUSPLUS", eps=1e-8):
+def maximum_signature(Rs, density_cube, algorithm="NEXUSPLUS", eps=1e-8):
     """
     Compute the maximum signatures across all scales Rs.
 
-    Parameters
-    ----------
-    Rs : array
-        The scales.
-    field : 3D array
-        The field.
-    alg : string, optional
-        The algorithm to use. Can be either 'NEXUS' or 'NEXUSPLUS'.
-        Default is 'NEXUSPLUS'.
-    eps : float, optional
-        A small number to avoid division by zero errors and whatnot. Default is 1e-8.
-
-    Returns
-    -------
-    sigmax : 4D array
-        The maximum signatures.
+    Args:
+        Rs (:obj:`list` of :obj:`float`):
+            List of smoothing scales in units of voxels.
+        density_cube (:obj:`3D float np.ndarray`):
+            The 3D density field to analyze.
+        algorithm (:obj:`str`, optional):
+            The algorithm to use for smoothing. Can be either "NEXUS" or "NEXUSPLUS". Defaults to "NEXUSPLUS".
+        eps (:obj:`float`, optional):
+            Small value to avoid division by zero. Defaults to ``1e-8``.
+
+    Returns:
+        (:obj:`4D float np.ndarray`):
+            An array of signatures with shape ``(nx, ny, nz, 3)``, where ``nx, ny, nz`` are the dimensions of the input ``density_cube``.
+            The last dimension contains the signatures for clusters, filaments, and walls respectively.
     """
-    if alg not in ["NEXUS", "NEXUSPLUS"]:  # pragma: no cover
-        msg = "alg must be either 'NEXUS' or 'NEXUSPLUS'"
+
+    if algorithm not in ["NEXUS", "NEXUSPLUS"]:  # pragma: no cover
+        msg = "algorithm must be either 'NEXUS' or 'NEXUSPLUS'"
         raise ValueError(msg)
 
-    nx, ny, nz = field.shape
+    nx, ny, nz = density_cube.shape
 
     # Make sure the field has no 0 values
-    field = field + eps
+    density_cube = density_cube + eps
 
     # Calculate wave vectors for our field
     wave_vecs = wavevectors3D((nx, ny, nz))
@@ -125,10 +124,10 @@ def maximum_signature(Rs, field, alg="NEXUSPLUS", eps=1e-8):
                         )
 
     for R in Rs:
-        if alg == "NEXUS":
-            f_Rn = smooth_gauss(field, R, wave_vecs)
-        elif alg == "NEXUSPLUS":
-            f_Rn = smooth_loggauss(field, R, wave_vecs)
+        if algorithm == "NEXUS":
+            f_Rn = smooth_gauss(density_cube, R, wave_vecs)
+        elif algorithm == "NEXUSPLUS":
+            f_Rn = smooth_loggauss(density_cube, R, wave_vecs)
 
         H_Rn = fast_hessian_from_smoothed(f_Rn, R, wave_vecs)
 

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/src/pycosmommf/tagging.py

@@ -7,30 +7,30 @@ import skimage.measure
 jit_compiler = nb.njit(parallel=True, fastmath=True)
 
 
-def make_the_clusbool(delta, max_sigs, Δ):  # pragma: no cover
+def make_the_clusbool(delta, max_sigs, overdensity_threshold):  # pragma: no cover
     """
-    make_the_clusbool() - Documentation
-
-    A function that creates a Boolean Filter which selects only
+    A function that creates a bool Filter which selects only
     the clusters in a given cosmological δ field. This function accomplishes
     this by finding a threshold value for 𝒮_cluster by looking at the
     change in virialization fraction as a function of 𝒮_cluster.
 
-    Arguments:
-    ----------------
-    delta - [3D Float Array] - delta refers to the δ field.
-    max_sigs - [4D Float Array] - the maximum signatures array from CosmoMMF.maximum_signature()
-    verbose - [Boolean] - a flag to allow the function to be more helpful and verbose.
-    Δ - [Int] - The overdensity parameter threshold for determining virialization. This
-    parameter comes from a paper by Gunn & Gott on spherical collapse. Commonly
-    used values that are physically motivated can be 370, 200, or 500 (for R_200 or R_500).
+    Args:
+        delta (:obj:`3D float np.ndarray`):
+            delta refers to the (δ = ρ / <ρ> - 1) field, this is NOT the (δ + 1 = ρ / <ρ>) field.
+        max_sigs (:obj:`4D float np.ndarray`):
+            the maximum signatures array from the ``maximum_signature()`` function.
+        verbose_flag (:obj:`bool`):
+            a flag to allow the function to be more helpful and verbose.
+        overdensity_threshold (:obj:`float`):
+            The overdensity parameter threshold for determining virialization. Commonly used values
+            that are physically motivated can be 370, 200, or 500.
 
     Returns:
-    ----------------
-    clusbool - [3D Boolean Array] - a boolean filter that selects only the clusters in a given cosmological δ field.
-    S_th - [Float] - the threshold value for 𝒮_cluster.
-    signature_thresholds - [1D Float Array] - an array of threshold values for 𝒮_cluster.
-    virialized_fractions - [1D Float Array] - an array of virialized fractions as a function of 𝒮_cluster.
+        (tuple): a tuple containing:
+            - **clusbool** (:obj:`3D bool np.ndarray`): a boolean filter that selects only the clusters in a given cosmological δ field.
+            - **S_th** (:obj:`float`): the threshold value for 𝒮_cluster.
+            - **signature_thresholds** (:obj:`1D float np.ndarray`): an array of threshold values for 𝒮_cluster.
+            - **virialized_fractions** (:obj:`1D float np.ndarray`): an array of virialized fractions as a function of 𝒮_cluster.
     """
 
     signature_thresholds = np.geomspace(0.1, 30, 10)  # hard coded for now
@@ -65,9 +65,9 @@ def make_the_clusbool(delta, max_sigs, Δ):  # pragma: no cover
         )  # an array where 0 is background and 1, 2, 3, ... are the clumps
         averaged_overdensity_per_clump = calc_virialized_fraction(clumps)
 
-        virialized_fractions[i] = np.sum(averaged_overdensity_per_clump > Δ) / np.max(
-            clumps
-        )
+        virialized_fractions[i] = np.sum(
+            averaged_overdensity_per_clump > overdensity_threshold
+        ) / np.max(clumps)
 
     S_th = signature_thresholds[np.abs(virialized_fractions - 0.5).argmin()]
     clusbool = max_sigs[:, :, :, 0] > S_th
@@ -79,17 +79,20 @@ def calc_mass_change(sig_vec, density_vec, Smin, Smax):
     """
     Calculate the mass change curve for a given structure type.
 
-    Arguments:
-    -----------
-        sig_vec - [1D Float Array] - the signature values for a given structure type
-        density_vec - [1D Float Array] - the density values for a given structure type
-        Smin - [Float] - the minimum signature value
-        Smax - [Float] - the maximum signature value
+    Args:
+        sig_vec (:obj:`1D float np.ndarray`):
+            the signature values for a given structure type
+        density_vec (:obj:`1D float np.ndarray`):
+            the density values for a given structure type
+        Smin (:obj:`float`):
+            the minimum signature value
+        Smax (:obj:`float`):
+            the maximum signature value
 
     Returns:
-    -----------
-        S - [1D Float Array] - the signature values
-        ΔM_2 - [1D Float Array] - the mass change curve
+        (tuple): a tuple containing:
+            - **S** (:obj:`1D float np.ndarray`): the signature values
+            - **ΔΜ_2** (:obj:`1D float np.ndarray`): the mass change curve
     """
     # Initialize our arrays
     log10S = np.arange(Smin, Smax + 0.1, 0.1)
@@ -111,48 +114,75 @@ def calc_mass_change(sig_vec, density_vec, Smin, Smax):
 
 
 def calc_structure_bools(
-    density_cube, max_sigs, verbose, clusbool=None, Smin=-3, Smax=2, Δ=370
+    density_cube,
+    max_sigs,
+    verbose_flag,
+    clusbool=None,
+    Smin=-3,
+    Smax=2,
+    overdensity_threshold=370,
 ):
     """
     Calculate the boolean filters for clusters, filaments, walls, and voids.
 
-    Arguments:
-    -----------
-        density_cube - [3D Float Array] - the δ+1 density_cube
-        max_sigs - [4D Float Array] - the maximum signatures array from CosmoMMF.maximum_signature()
-        verbose - [Boolean] - a flag to allow the function to be more helpful and verbose.
-        clusbool - [3D Boolean Array] - the cluster boolean filter
-        Smin - [Float] - the minimum signature value
-        Smax - [Float] - the maximum signature value
-        Δ - [Int] - the overdensity parameter threshold for determining virialization
+    Args:
+        density_cube (:obj:`3D float np.ndarray`):
+            the (δ+1 = ρ/<ρ>) ``density_cube``, this is NOT (δ = ρ/<ρ> - 1).
+        max_sigs (:obj:`4D float np.ndarray`):
+            the maximum signatures array from CosmoMMF.maximum_signature()
+        verbose_flag (:obj:`bool`) :
+            a flag to allow the function to be more helpful and verbose.
+        clusbool (:obj:`bool np.ndarray`, optional):
+            the cluster boolean filter
+        Smin (:obj:`float`, optional):
+            the minimum signature value
+        Smax (:obj:`float`, optional):
+            the maximum signature value
+        overdensity_threshold (:obj:`int`, optional):
+            the overdensity parameter threshold for determining virialization
 
     Returns:
-    -----------
-        clusbool - [3D Boolean Array] - the cluster boolean filter
-        filbool - [3D Boolean Array] - the filament boolean filter
-        wallbool - [3D Boolean Array] - the wall boolean filter
-        voidbool - [3D Boolean Array] - the void boolean filter
-
-        VERBOSE ONLY:
-            summary_data - [Dict] - a dictionary containing the following keys:
-                S_clus - [1D Float Array] - the signature values for clusters
-                f_vir_clus - [1D Float Array] - the virialization fraction for clusters
-                S_fil - [1D Float Array] - the signature values for filaments
-                dM2_fil - [1D Float Array] - the mass change curve for filaments
-                S_wall - [1D Float Array] - the signature values for walls
-                dM2_wall - [1D Float Array] - the mass change curve for walls
-
+        (tuple): a tuple containing:
+            - **clusbool** (:obj:`3D bool np.ndarray`): the cluster boolean filter
+            - **filbool** (:obj:`3D bool np.ndarray`): the filament boolean filter
+            - **wallbool** (:obj:`3D bool np.ndarray`): the wall boolean filter
+            - **voidbool** (:obj:`3D bool np.ndarray`): the void boolean filter
+            - **summary_data** (:obj:`dict`): a dictionary returned only when ``verbose_flag = True``, it contains the following keys:
+                - **S_clus** (:obj:`1D float np.ndarray`): the signature values for clusters
+                - **f_vir_clus** (:obj:`1D float np.ndarray`): the virialization fraction for clusters
+                - **S_fil** (:obj:`1D float np.ndarray`): the signature values for filaments
+                - **dM2_fil** (:obj:`1D float np.ndarray`): the mass change curve for filaments
+                - **S_fil_thresh** (:obj:`float`): the threshold value for filaments
+                - **S_wall** (:obj:`1D float np.ndarray`): the signature values for walls
+                - **dM2_wall** (:obj:`1D float np.ndarray`): the mass change curve for walls
+                - **S_wall_thresh** (:obj:`float`): the threshold value for walls
+                - **mass_fractions** (:obj:`1D float np.ndarray`): a list of mass fractions for clusters, filaments, walls, and voids
+                - **volume_fractions** (:obj:`1D float np.ndarray`): a list of volume fractions for clusters, filaments, walls, and voids
     """
 
     N_cells = np.prod(density_cube.shape)
 
+    # Check if the input density_cube is actually δ
+    if np.isclose(np.abs(np.mean(density_cube)), 0, atol=1e-3):
+        msg = "make sure that you are not inputing the overdensity field δ = ρ/<ρ> - 1, but rather δ + 1 = ρ/<ρ>."
+        raise ValueError(msg)
+
+    # Check if the input density_cube is actually δ + 1 = ρ/<ρ> or just ρ
+    if np.mean(density_cube) > 1.0:
+        # If the mean is greater than 1, we assume it is simply ρ, but we want to transform to δ + 1 = ρ/<ρ>
+        if verbose_flag:  # pragma: no cover
+            print(
+                "Input density_cube is in density units, transforming to δ + 1 = ρ/<ρ>."
+            )
+        density_cube /= np.mean(density_cube)  # normalize to mean = 1
+
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-    #                 Step 1. Create Cluster Boolean Filter
+    #                 Step 1. Create Cluster bool Filter
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
     if clusbool is None:  # pragma: no cover
         clusbool, cluster_thresh, S_clus, f_vir_clus = make_the_clusbool(
-            density_cube - 1.0, max_sigs, Δ
+            density_cube - 1.0, max_sigs, overdensity_threshold
         )
     else:
         cluster_thresh = None
@@ -160,7 +190,7 @@ def calc_structure_bools(
         f_vir_clus = None
 
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-    #                 Step 2. Create Filament Boolean Filter
+    #                 Step 2. Create Filament bool Filter
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
     # we create 3 N^3 arrays with the signature corresponding to each structure
@@ -181,7 +211,7 @@ def calc_structure_bools(
     filbool = (max_sigs[:, :, :, 1] > filament_thresh) & (~clusbool)
 
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-    #                   Step 3. Create Wall Boolean Filter
+    #                   Step 3. Create Wall bool Filter
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
     # Isolate Valid Walls (not clusters or filaments)
@@ -196,14 +226,14 @@ def calc_structure_bools(
     wallbool = (max_sigs[:, :, :, 2] > wall_thresh) & ~(filbool | clusbool)
 
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-    #                   Step 4. Create Void Boolean Filter
+    #                   Step 4. Create Void bool Filter
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
     voidbool = (clusbool + filbool + wallbool) == 0
 
-    if verbose:
+    if verbose_flag:
         print("---------------------------------------")
-        print("     Cluster Boolean Filter Report    ")
+        print("     Cluster bool Filter Report    ")
         print("---------------------------------------\n")
 
         volume_fraction_clus = np.sum(clusbool) / N_cells
@@ -215,7 +245,7 @@ def calc_structure_bools(
         print("")
 
         print("---------------------------------------")
-        print("     Filament Boolean Filter Report    ")
+        print("     Filament bool Filter Report    ")
         print("---------------------------------------\n")
 
         volume_fraction_fil = np.sum(filbool) / N_cells
@@ -227,7 +257,7 @@ def calc_structure_bools(
         print("")
 
         print("---------------------------------------")
-        print("       Wall Boolean Filter Report      ")
+        print("       Wall bool Filter Report      ")
         print("---------------------------------------\n")
 
         volume_fraction_wall = np.sum(wallbool) / N_cells
@@ -239,7 +269,7 @@ def calc_structure_bools(
         print("")
 
         print("---------------------------------------")
-        print("       Void Boolean Filter Report      ")
+        print("       Void bool Filter Report      ")
         print("---------------------------------------\n")
 
         volume_fraction_void = np.sum(voidbool) / N_cells

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/src/pycosmommf/utils.py

@@ -6,6 +6,15 @@ import numpy as np
 def shrink(data, new_size):
     """
     A simple function to shrink a 3D array by summing over blocks of new_size.
+
+    Args:
+        data (:obj:`3D float np.ndarray`):
+            The input 3D array to be shrunk.
+        new_size (:obj:`int`):
+            The new size for each dimension after shrinking.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): The shrunk 3D array.
     """
     xs = new_size
     ys = new_size
@@ -23,20 +32,36 @@ def shrink(data, new_size):
 def wall(n):
     """
     Builds a wall out of an nxnxn array. All values in the wall
-    are set to 1. Other points are set to 0.
+    are set to 10. Other points are set to 0.
+
+    Args:
+        n (:obj:`int`):
+            The size of the 3D array to create.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): An nxnxn array with a wall in the center.
     """
     array = np.zeros((n, n, n))
     array[:, :, :] = 0.1
     index = n // 2
-    array[index, :, :] = 1
+    array[index, :, :] = 10.0
     return array
 
 
 def cylinder(n, r):
     """
     Returns an nxnxn array with a cylinder in the center with
-    radius r. All points within the radius are set to 1, the rest
+    radius r. All points within the radius are set to 10, the rest
     are set to 0.
+
+    Args:
+        n (:obj:`int`):
+            The size of the 3D array to create.
+        r (:obj:`int`):
+            The radius of the cylinder.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): An nxnxn array with a cylinder in the center.
     """
     array = np.zeros((n, n, n), dtype=np.float64)
     array[:, :, :] = 0.1
@@ -44,15 +69,24 @@ def cylinder(n, r):
         for y in range(n):
             for z in range(n):
                 if (x - (n // 2)) ** 2 + (y - (n // 2)) ** 2 < r**2:
-                    array[x, y, z] = 1
+                    array[x, y, z] = 10.0
     return array
 
 
 def sphere(n, r):
     """
     Returns an nxnxn array with a sphere in the center with
-    radius r. All points within the radius are set to 1, the rest
+    radius r. All points within the radius are set to 10, the rest
     are set to 0.
+
+    Args:
+        n (:obj:`int`):
+            The size of the 3D array to create.
+        r (:obj:`int`):
+            The radius of the sphere.
+
+    Returns:
+        (:obj:`3D float np.ndarray`): An nxnxn array with a sphere in the center.
     """
     array = np.zeros((n, n, n), dtype=np.float64)
     array[:, :, :] = 0.1
@@ -62,5 +96,5 @@ def sphere(n, r):
                 if (x - (n // 2)) ** 2 + (y - (n // 2)) ** 2 + (
                     z - (n // 2)
                 ) ** 2 < r**2:
-                    array[x, y, z] = 1
+                    array[x, y, z] = 10.0
     return array

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/tests/test_integration.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import numpy as np
+import pytest
 
 import pycosmommf as m
 
@@ -15,28 +16,28 @@ test_field = (
 def test_maximum_signature():
     Rs = [np.sqrt(2) ** n for n in range(5)]
     field = test_field
-    sigs = m.maximum_signature(Rs, field, alg="NEXUSPLUS")
+    sigs = m.maximum_signature(Rs, field, algorithm="NEXUSPLUS")
     assert sigs.shape == (32, 32, 32, 3)
 
-    sigs = m.maximum_signature(Rs, field, alg="NEXUS")
+    sigs = m.maximum_signature(Rs, field, algorithm="NEXUS")
     assert sigs.shape == (32, 32, 32, 3)
 
 
 def test_calc_structure_bools():
     Rs = [np.sqrt(2) ** n for n in range(5)]
     field = test_field
-    sigs = m.maximum_signature(Rs, field, alg="NEXUS")
+    sigs = m.maximum_signature(Rs, field, algorithm="NEXUS")
     clusbool = (
         np.roll(m.sphere(32, 2), -10, axis=0) + np.roll(m.sphere(32, 2), 10, axis=0)
     ) >= 1
     clusbool, filbool, wallbool, voidbool, summary_stats = m.calc_structure_bools(
         field,
         max_sigs=sigs,
-        verbose=True,
+        verbose_flag=True,
         clusbool=clusbool,
         Smin=-3,
         Smax=2,
-        Δ=370,
+        overdensity_threshold=370,
     )
     assert clusbool.shape == (32, 32, 32)
     assert filbool.shape == (32, 32, 32)
@@ -47,13 +48,26 @@ def test_calc_structure_bools():
     clusbool, filbool, wallbool, voidbool = m.calc_structure_bools(
         field,
         max_sigs=sigs,
-        verbose=False,
+        verbose_flag=False,
         clusbool=clusbool,
         Smin=-3,
         Smax=2,
-        Δ=370,
+        overdensity_threshold=370,
     )
     assert clusbool.shape == (32, 32, 32)
     assert filbool.shape == (32, 32, 32)
     assert wallbool.shape == (32, 32, 32)
     assert voidbool.shape == (32, 32, 32)
+
+    delta = field / np.mean(field) - 1.0
+
+    with pytest.raises(ValueError):  # noqa: PT011
+        clusbool, filbool, wallbool, voidbool = m.calc_structure_bools(
+            density_cube=delta,
+            max_sigs=sigs,
+            verbose_flag=False,
+            clusbool=clusbool,
+            Smin=-3,
+            Smax=2,
+            overdensity_threshold=370,
+        )

{pycosmommf-0.6.0 → pycosmommf-1.0.1}/docs/api/pycosmommf.rst

@@ -3,8 +3,8 @@ pycosmommf package
 
 .. automodule:: pycosmommf
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members:
 
 Submodules
 ----------
@@ -14,37 +14,37 @@ pycosmommf.filter module
 
 .. automodule:: pycosmommf.filter
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members:
 
 pycosmommf.hessian module
 -------------------------
 
 .. automodule:: pycosmommf.hessian
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members:
 
 pycosmommf.signatures module
 ----------------------------
 
 .. automodule:: pycosmommf.signatures
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members:
 
 pycosmommf.tagging module
 -------------------------
 
 .. automodule:: pycosmommf.tagging
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members:
 
 pycosmommf.utils module
 -----------------------
 
 .. automodule:: pycosmommf.utils
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members: