phasorpy 0.3__cp312-cp312-win_arm64.whl → 0.5__cp312-cp312-win_arm64.whl

phasorpy/cluster.py

@@ -0,0 +1,170 @@
+"""Cluster phasor coordinates.
+
+The `phasorpy.cluster` module provides functions to:
+
+- fit elliptic clusters to phasor coordinates using
+  Gaussian Mixture Model (GMM):
+
+  - :py:func:`phasor_cluster_gmm`
+
+"""
+
+from __future__ import annotations
+
+__all__ = ['phasor_cluster_gmm']
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._typing import Any, ArrayLike
+
+import math
+
+import numpy
+from sklearn.mixture import GaussianMixture
+
+
+def phasor_cluster_gmm(
+    real: ArrayLike,
+    imag: ArrayLike,
+    /,
+    *,
+    sigma: float = 2.0,
+    clusters: int = 1,
+    **kwargs: Any,
+) -> tuple[
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+    tuple[float, ...],
+]:
+    """Return elliptic clusters in phasor coordinates using GMM.
+
+    Fit a Gaussian Mixture Model (GMM) to the provided phasor coordinates and
+    extract the parameters of ellipses that represent each cluster according
+    to [1]_.
+
+    Parameters
+    ----------
+    real : array_like
+        Real component of phasor coordinates.
+    imag : array_like
+        Imaginary component of phasor coordinates.
+    sigma: float, default = 2.0
+        Scaling factor for radii of major and minor axes.
+        Defaults to 2, which corresponds to the scaling of eigenvalues for a
+        95% confidence ellipse.
+    clusters : int, optional
+        Number of Gaussian distributions to fit to phasor coordinates.
+        Defaults to 1.
+    **kwargs
+        Additional keyword arguments passed to
+        :py:class:`sklearn.mixture.GaussianMixture`.
+
+        Common options include:
+
+        - covariance_type : {'full', 'tied', 'diag', 'spherical'}
+        - max_iter : int, maximum number of EM iterations
+        - random_state : int, for reproducible results
+
+    Returns
+    -------
+    center_real : tuple of float
+        Real component of ellipse centers.
+    center_imag : tuple of float
+        Imaginary component of ellipse centers.
+    radius_major : tuple of float
+        Major radii of ellipses.
+    radius_minor : tuple of float
+        Minor radii of ellipses.
+    angle : tuple of float
+        Rotation angles of major axes in radians, within range [0, pi].
+
+    Raises
+    ------
+    ValueError
+        If the array shapes of `real` and `imag` do not match.
+        If `clusters` is not a positive integer.
+
+
+    References
+    ----------
+    .. [1] Vallmitjana A, Torrado B, and Gratton E.
+      `Phasor-based image segmentation: machine learning clustering techniques
+      <https://doi.org/10.1364/BOE.422766>`_.
+      *Biomed Opt Express*, 12(6): 3410-3422 (2021).
+
+    Examples
+    --------
+    Recover the clusters from a synthetic distribution of phasor coordinates
+    with two clusters:
+
+    >>> real1, imag1 = numpy.random.multivariate_normal(
+    ...     [0.2, 0.3], [[3e-3, 1e-3], [1e-3, 2e-3]], 100
+    ... ).T
+    >>> real2, imag2 = numpy.random.multivariate_normal(
+    ...     [0.4, 0.5], [[2e-3, -1e-3], [-1e-3, 3e-3]], 100
+    ... ).T
+    >>> real = numpy.concatenate([real1, real2])
+    >>> imag = numpy.concatenate([imag1, imag2])
+    >>> center_real, center_imag, radius_major, radius_minor, angle = (
+    ...     phasor_cluster_gmm(real, imag, clusters=2)
+    ... )
+    >>> centers_real  # doctest: +SKIP
+    (0.2, 0.4)
+
+    """
+    coords = numpy.stack((real, imag), axis=-1).reshape(-1, 2)
+
+    valid_data = ~numpy.isnan(coords).any(axis=1)
+    coords = coords[valid_data]
+
+    kwargs.pop('n_components', None)
+
+    gmm = GaussianMixture(n_components=clusters, **kwargs)
+    gmm.fit(coords)
+
+    center_real = []
+    center_imag = []
+    radius_major = []
+    radius_minor = []
+    angle = []
+
+    for i in range(clusters):
+        center_real.append(float(gmm.means_[i, 0]))
+        center_imag.append(float(gmm.means_[i, 1]))
+
+        if gmm.covariance_type == 'full':
+            cov = gmm.covariances_[i]
+        elif gmm.covariance_type == 'tied':
+            cov = gmm.covariances_
+        elif gmm.covariance_type == 'diag':
+            cov = numpy.diag(gmm.covariances_[i])
+        else:  # 'spherical'
+            cov = numpy.eye(2) * gmm.covariances_[i]
+
+        eigenvalues, eigenvectors = numpy.linalg.eigh(cov[:2, :2])
+
+        idx = eigenvalues.argsort()[::-1]
+        eigenvalues = eigenvalues[idx]
+        eigenvectors = eigenvectors[:, idx]
+
+        major_vector = eigenvectors[:, 0]
+        current_angle = math.atan2(major_vector[1], major_vector[0])
+
+        if current_angle < 0:
+            current_angle += math.pi
+
+        angle.append(float(current_angle))
+
+        radius_major.append(sigma * math.sqrt(2 * eigenvalues[0]))
+        radius_minor.append(sigma * math.sqrt(2 * eigenvalues[1]))
+
+    return (
+        tuple(center_real),
+        tuple(center_imag),
+        tuple(radius_major),
+        tuple(radius_minor),
+        tuple(angle),
+    )

phasorpy/color.py

@@ -19,13 +19,13 @@ def wavelength2rgb(
 ) -> tuple[float, float, float] | NDArray[Any]:
     """Return approximate sRGB color components of visible wavelength(s).
 
-    Wavelength values are clipped to 360..750, rounded, and used to index
-    the :py:attr:`SRGB_SPECTRUM` palette.
+    Wavelengths are clipped to range [360, 750] nm, rounded, and used to
+    index the :py:attr:`SRGB_SPECTRUM` palette.
 
     Parameters
     ----------
     wavelength : array_like
-        Scalar or array of wavelength(s) to convert.
+        Scalar or array of wavelengths in nm.
     dtype : data-type, optional
         Data-type of return value. The default is ``float32``.
 
@@ -33,8 +33,8 @@ def wavelength2rgb(
     -------
     ndarray or tuple
         Approximate sRGB color components of visible wavelength.
-        Floating-point types are in range 0.0 to 1.0.
-        Integer types are scaled to the dtype's maximum value.
+        Floating-point values are in range [0.0, 1.0].
+        Integer values are scaled to the dtype's maximum value.
 
     Examples
     --------
@@ -59,8 +59,7 @@ def wavelength2rgb(
         else:
             rgb = rgb.astype(dtype)
     if astuple:
-        rgb_list = rgb.tolist()
-        return (rgb_list[0], rgb_list[1], rgb_list[2])
+        return tuple(rgb.tolist()[:3])
     return rgb
 
 
@@ -69,7 +68,7 @@ def float2int(
     /,
     dtype: DTypeLike = numpy.uint8,
 ) -> NDArray[Any]:
-    """Return normalized color components as integer type.
+    """Return normalized color components as integers.
 
     Parameters
     ----------
@@ -78,6 +77,11 @@ def float2int(
     dtype : data-type, optional
         Data type of return value. The default is ``uint8``.
 
+    Returns
+    -------
+    ndarray
+        Color components as integers scaled to dtype's range.
+
     Examples
     --------
     >>> float2int([0.0, 0.5, 1.0])
@@ -163,11 +167,11 @@ CATEGORICAL: NDArray[numpy.float32] = numpy.array([
     [0.523809, 0.888889, 0.460317],
     [0.285714, 0.0, 0.238095],
 ], dtype=numpy.float32)
-"""Categorical sRGB color palette inspired by C Glasbey.
+"""Categorical sRGB color palette inspired by C. Glasbey.
 
-The palette contains 64 maximally distinct colours.
+Contains 64 maximally distinct colours for visualization.
 
-Generated with the `glasbey <https://glasbey.readthedocs.io>`_ package::
+Generated using the `glasbey <https://glasbey.readthedocs.io>`_ package::
 
     import glasbey; numpy.array(glasbey.create_palette(64, as_hex=False))
 
@@ -569,11 +573,11 @@ SRGB_SPECTRUM: NDArray[numpy.float32] = numpy.array([
     [0.005006, 0.0, 0.0],
     [0.004664, 0.0, 0.0],
 ], dtype=numpy.float32)
-"""sRGB color components for visible light wavelengths 360-750 nm.
+"""sRGB color components for wavelengths of visible light (360-750 nm).
 
 Based on the CIE 1931 2° Standard Observer.
 
-Generated with the `colour <https://colour.readthedocs.io>`_ package::
+Generated using the `colour <https://colour.readthedocs.io>`_ package::
 
     import colour; colour.plotting.plot_visible_spectrum()
 

phasorpy/components.py

@@ -65,10 +65,10 @@ def two_fractions_from_phasor(
         Real component of phasor coordinates.
     imag : array_like
         Imaginary component of phasor coordinates.
-    components_real: array_like, shape (2,)
-        Real coordinates of the first and second components.
-    components_imag: array_like, shape (2,)
-        Imaginary coordinates of the first and second components.
+    components_real : array_like, shape (2,)
+        Real coordinates of first and second components.
+    components_imag : array_like, shape (2,)
+        Imaginary coordinates of first and second components.
 
     Returns
     -------
@@ -78,7 +78,7 @@ def two_fractions_from_phasor(
     Raises
     ------
     ValueError
-        If the real and/or imaginary coordinates of the known components are
+        If the real or imaginary coordinates of the known components are
         not of size 2.
 
     See Also
@@ -145,13 +145,13 @@ def graphical_component_analysis(
         Real component of phasor coordinates.
     imag : array_like
         Imaginary component of phasor coordinates.
-    components_real: array_like, shape (2,) or (3,)
+    components_real : array_like, shape (2,) or (3,)
         Real coordinates for two or three components.
-    components_imag: array_like, shape (2,) or (3,)
+    components_imag : array_like, shape (2,) or (3,)
         Imaginary coordinates for two or three components.
-    radius: float, optional, default: 0.05
-        Radius of the cursor in phasor coordinates.
-    fractions: array_like or int, optional
+    radius : float, optional, default: 0.05
+        Radius of cursor.
+    fractions : array_like or int, optional
         Number of equidistant fractions, or 1D array of fraction values.
         Fraction values must be in range [0.0, 1.0].
         If an integer, ``numpy.linspace(0.0, 1.0, fractions)`` fraction values
@@ -163,8 +163,8 @@ def graphical_component_analysis(
     Returns
     -------
     counts : tuple of ndarray
-        Counts along each line segment connecting the components, ordered
-        0-1 (2 components) or 0-1, 0-2, 1-2 (3 components).
+        Counts along each line segment connecting components.
+        Ordered 0-1 (2 components) or 0-1, 0-2, 1-2 (3 components).
 
     Raises
     ------
@@ -172,7 +172,7 @@ def graphical_component_analysis(
         The array shapes of `real` and `imag`, or `components_real` and
         `components_imag` do not match.
         The number of components is not 2 or 3.
-        Fraction values are not in range [0.0, 1.0].
+        Fraction values are out of range [0.0, 1.0].
 
     See Also
     --------
@@ -216,7 +216,7 @@ def graphical_component_analysis(
     >>> graphical_component_analysis(
     ...     [0.6, 0.3], [0.35, 0.38], [0.2, 0.9], [0.4, 0.3], fractions=6
     ... )  # doctest: +NUMBER
-    (array([0, 0, 1, 0, 1, 0]),)
+    (array([0, 0, 1, 0, 1, 0], dtype=uint64),)
 
     Count the number of phasors between the combinations of three components:
 
@@ -227,9 +227,9 @@ def graphical_component_analysis(
     ...     [0.0, 0.4, 0.3],
     ...     fractions=6,
     ... )  # doctest: +NUMBER +NORMALIZE_WHITESPACE
-    (array([0, 1, 1, 1, 1, 0]),
-     array([0, 1, 0, 0, 0, 0]),
-     array([0, 1, 2, 0, 0, 0]))
+    (array([0, 1, 1, 1, 1, 0], dtype=uint64),
+     array([0, 1, 0, 0, 0, 0], dtype=uint64),
+     array([0, 1, 2, 0, 0, 0], dtype=uint64))
 
     """
     real = numpy.asarray(real)
@@ -305,7 +305,7 @@ def graphical_component_analysis(
                         components_imag[3 - i - j],  # c_imag
                         radius,
                     )
-                fraction_counts = numpy.sum(mask)
+                fraction_counts = numpy.sum(mask, dtype=numpy.uint64)
                 component_counts.append(fraction_counts)
 
             counts.append(numpy.asarray(component_counts))

phasorpy/conftest.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+__all__: list[str] = []
+
 import math
 from typing import TYPE_CHECKING
 

phasorpy/cursors.py

@@ -291,15 +291,15 @@ def mask_from_polar_cursor(
     imag : array_like
         Imaginary component of phasor coordinates.
     phase_min : array_like, shape (n,)
-        Minimum of angular range of cursors in radians.
-        Values should be between -pi and pi.
+        Lower bound of angular range of cursors in radians.
+        Values should be in range [-pi, pi].
     phase_max : array_like, shape (n,)
-        Maximum of angular range of cursors in radians.
-        Values should be between -pi and pi.
+        Upper bound of angular range of cursors in radians.
+        Values should be in range [-pi, pi].
     modulation_min : array_like, shape (n,)
-        Minimum of radial range of cursors.
+        Lower bound of radial range of cursors.
     modulation_max : array_like, shape (n,)
-        Maximum of radial range of cursors.
+        Upper bound of radial range of cursors.
 
     Returns
     -------
@@ -362,7 +362,7 @@ def mask_from_polar_cursor(
             f'{phase_min.ndim=}, {phase_max.ndim=}, '
             f'{modulation_min.ndim=}, or {modulation_max.ndim=} > 1'
         )
-    # TODO: check if angles are between -pi and pi
+    # TODO: check if angles are in range [-pi and pi]
 
     moveaxis = False
     if real.ndim > 0 and (
@@ -406,7 +406,7 @@ def pseudo_color(
         Maximum value to normalize `intensity`.
         If None, the maximum value of `intensity` is used.
     colors : array_like, optional, shape (N, 3)
-        Colors assigned to each cursor.
+        RGB colors assigned to each cursor.
         The last dimension contains the normalized RGB floating point values.
         The default is :py:data:`phasorpy.color.CATEGORICAL`.
 
@@ -463,7 +463,7 @@ def pseudo_color(
     shape = numpy.asarray(masks[0]).shape
 
     if intensity is not None:
-        # normalize intensity to range 0..1
+        # normalize intensity to range [0, 1]
         intensity = numpy.array(
             intensity, dtype=numpy.float32, ndmin=1, copy=True
         )

phasorpy/datasets.py

@@ -14,8 +14,11 @@ Datasets from the following repositories are available:
   <https://github.com/zoccoler/napari-flim-phasor-plotter/tree/0.0.6/src/napari_flim_phasor_plotter/data>`_
 - `Phasor-based multi-harmonic unmixing for in-vivo hyperspectral imaging
   <https://zenodo.org/records/13625087>`_
+  (`second record <https://zenodo.org/records/14860228>`_)
 - `Convallaria slice acquired with time-resolved 2-photon microscope
   <https://zenodo.org/records/14026720>`_
+- `Convallaria FLIM dataset in FLIM LABS JSON format
+  <https://zenodo.org/records/15007900>`_
 
 The implementation is based on the `Pooch <https://www.fatiando.org/pooch>`_
 library.
@@ -266,14 +269,15 @@ ZENODO_13625087 = pooch.create(
     base_url=(
         'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_13625087'
         # if DATA_ON_GITHUB
-        # else 'doi:10.1088/2050-6120/ac9ae9'
+        # else 'doi:10.1088/2050-6120/ac9ae9'  # TODO: not working with Pooch
     ),
     env=ENV,
     registry={
-        '33_Hoechst_Golgi_Mito_Lyso_CellMAsk_404_488_561_633_SP.lsm': (
-            'sha256:'
-            '68fcefcad4e750e9ec7068820e455258c986f6a9b724e66744a28bbbb689f986'
-        ),
+        # part of ZENODO_14860228
+        # '33_Hoechst_Golgi_Mito_Lyso_CellMAsk_404_488_561_633_SP.lsm': (
+        #    'sha256:'
+        #    '68fcefcad4e750e9ec7068820e455258c986f6a9b724e66744a28bbbb689f986'
+        # ),
         '34_Hoechst_Golgi_Mito_Lyso_CellMAsk_404_488_561_633_SP.lsm': (
             'sha256:'
             '5c0b7d76c274fd64891fca2507013b7c8c9979d8131ce282fac55fd24fbb38bd'
@@ -289,9 +293,65 @@ ZENODO_13625087 = pooch.create(
     },
 )
 
+ZENODO_14860228 = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_14860228'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.14860228'
+    ),
+    env=ENV,
+    registry={
+        '38_Hoechst_Golgi_Mito_Lyso_CellMAsk_404_488_561_633_SP.lsm': (
+            'sha256:'
+            '092ac050edf55e26dcda8cba10122408c6f1b81d19accf07214385d6eebfcf3e'
+        ),
+        'spectral cell mask.lsm': (
+            'sha256:'
+            'c4c2c567bd99ef4930d7278794d4e3daebaad0375c0852a5ab86a2ea056f4fe3'
+        ),
+        'spectral golgi.lsm': (
+            'sha256:'
+            'd0a5079d9ed18b1248434f3f6d4b2b240fb034891121262cfe9dfec64d8429cd'
+        ),
+        'spectral hoehst.lsm': (
+            'sha256:'
+            '3ee44a7f9f125698bb5e34746d9723669f67c520ffbf21244757d7fc25dbbb88'
+        ),
+        'spectral lyso tracker green.lsm': (
+            'sha256:'
+            '0964448649e2c73a57f5ca0c705c86511fb4625c0a2af0d7850dfa39698fcbb9'
+        ),
+        'spectral mito tracker.lsm': (
+            'sha256:'
+            '99b9892b247256ebf8a9917c662bc7bb66a8daf3b5db950fbbb191de0cd35b37'
+        ),
+    },
+)
+
+ZENODO_14976703 = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_14976703'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.14976703'
+    ),
+    env=ENV,
+    registry={
+        'Convalaria_LambdaScan.lif': (
+            'sha256:'
+            '27f1282cf02f87e11f8c7d3064066a4517ad4c9c769c796b32e459774f18c62a'
+        ),
+    },
+)
+
 CONVALLARIA_FBD = pooch.create(
     path=pooch.os_cache('phasorpy'),
-    base_url='doi:10.5281/zenodo.14026719',
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/zenodo_14026720'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.14026719'
+    ),
     env=ENV,
     registry={
         'Convallaria_$EI0S.fbd': (
@@ -305,6 +365,99 @@ CONVALLARIA_FBD = pooch.create(
     },
 )
 
+FLIMLABS = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/flimlabs'
+        if DATA_ON_GITHUB
+        else 'doi:10.5281/zenodo.15007900'
+    ),
+    env=ENV,
+    registry={
+        'Convallaria_m2_1740751781_phasor_ch1.json': (
+            'sha256:'
+            'a8bf0179f352ab2c6c78d0bd399545ab1fb6d5537f23dc06e5f12a7ef5af6615'
+        ),
+        'Convallaria_m2_1740751781_phasor_ch1.json.zip': (
+            'sha256:'
+            '9c5691f55e85778717ace13607d573bcd00c29e357e063c8db4f173340f72984'
+        ),
+        'Fluorescein_Calibration_m2_1740751189_imaging.json': (
+            'sha256:'
+            'aeebb074dbea6bff7578f409c7622b2f7f173bb23e5475d1436adedca7fc2eed'
+        ),
+        'Fluorescein_Calibration_m2_1740751189_imaging.json.zip': (
+            'sha256:'
+            '32960bc1dec85fd16ffc7dd74a3cd63041fb3b69054ee6582f913129b0847086'
+        ),
+        'Fluorescein_Calibration_m2_1740751189_imaging_calibration.json': (
+            'sha256:'
+            '7fd1b9749789bd139c132602a771a127ea0c76f403d1750e9636cd657cce017a'
+        ),
+    },
+)
+
+FIGSHARE_22336594 = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/figshare_22336594'
+        if DATA_ON_GITHUB
+        else 'doi:10.6084/m9.figshare.22336594.v1'
+    ),
+    env=ENV,
+    registry={
+        'FLIM_testdata.lif': (
+            'sha256:'
+            '902d8fa6cd39da7cf062b32d43aab518fa2a851eab72b4bd8b8eca1bad591850'
+        ),
+    },
+)
+
+FIGSHARE_22336594_EXPORTED = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url=(
+        'https://github.com/phasorpy/phasorpy-data/raw/main/figshare_22336594'
+    ),
+    env=ENV,
+    registry={
+        'FLIM_testdata.lif.ptu': (
+            'sha256:'
+            'c85792b25d0b274f1484e490c99aa19052ab8e48e4e5022aabb1f218cd1123b6'
+        ),
+        'FLIM_testdata.lif.ptu.zip': (
+            'sha256:'
+            'c5134c470f6a3e5cb21eabd538cbd5061d9911dad96d58e3a4040cfddadaef33'
+        ),
+        'FLIM_testdata.xlef': (
+            'sha256:'
+            '7860ef0847dc9f5534895a9c11b979bb446f67382b577fe63fb166e281e5dc5e'
+        ),
+        'FLIM_testdata.xlef.zip': (
+            'sha256:'
+            'ad0ad6389f38dcba6f9809b54934ef3f19da975d9dabeb4c3a248692b959b9cf'
+        ),
+        'FLIM_testdata.lif.filtered.ptu': (
+            'sha256:'
+            'a00b84f626a39e79263322c60ae50b64163b36bb977ecc4dc54619097ba7f5b7'
+        ),
+        'FLIM_testdata.lif.filtered.ptu.zip': (
+            'sha256:'
+            '717366b231213bfd6e295c3efb7bf1bcd90e720eb28aab3223376087172e93e5'
+        ),
+    },
+)
+
+MISC = pooch.create(
+    path=pooch.os_cache('phasorpy'),
+    base_url='https://github.com/phasorpy/phasorpy-data/raw/main/misc',
+    env=ENV,
+    registry={
+        'NADHandSHG.ifli': (
+            'sha256:'
+            'dfa65952850b8a222258776a8a14eb1ab7e70ff5f62b58aa2214797c5921b4a3'
+        ),
+    },
+)
 
 REPOSITORIES: dict[str, pooch.Pooch] = {
     'tests': TESTS,
@@ -312,7 +465,13 @@ REPOSITORIES: dict[str, pooch.Pooch] = {
     'flute': FLUTE,
     'napari-flim-phasor-plotter': NAPARI_FLIM_PHASOR_PLOTTER,
     'zenodo-13625087': ZENODO_13625087,
+    'zenodo-14860228': ZENODO_14860228,
+    'zenodo-14976703': ZENODO_14976703,
     'convallaria-fbd': CONVALLARIA_FBD,
+    'flimlabs': FLIMLABS,
+    'figshare_22336594': FIGSHARE_22336594,
+    'figshare_22336594_exported': FIGSHARE_22336594_EXPORTED,
+    'misc': MISC,
 }
 """Pooch repositories."""
 
@@ -325,19 +484,19 @@ def fetch(
 ) -> Any:  # str | tuple[str, ...]
     """Return absolute path(s) to sample file(s) in local storage.
 
-    The files are downloaded from a remote repository if they do not already
-    exist in the local storage.
+    The files are downloaded from a remote repository if not present in local
+    storage.
 
     Parameters
     ----------
-    *args: str or iterable of str, optional
+    *args : str or iterable of str, optional
         Name(s) of file(s) or repositories to fetch from local storage.
         If omitted, return files in all repositories.
     extract_dir : str or None, optional
         Path, relative to cache location, where ZIP files will be unpacked.
     return_scalar : bool, optional
         If true (default), return single path as string, else tuple of string.
-    **kwargs : optional
+    **kwargs
         Additional arguments passed to ``pooch.fetch()``.
         For example, ``progressbar=True``.