merge from main and resolve conflicts

Author: NimaSarajpoor

docstring.py

@@ -17,18 +17,17 @@ def get_docstring_args(fd, file_name, func_name, class_name=None):
             msg += f"class: {class_name}\n"
         msg += f"function/method: {func_name}\n"
         raise RuntimeError(msg)
-    if class_name is None and len(re.findall(r"Returns", docstring)) != 1:
+    if len(re.findall(r"Returns", docstring)) != 1:
         msg = "Missing required 'Returns' section in docstring in \n"
         msg += f"file: {file_name}\n"
+        if class_name is not None:
+            msg += f"class: {class_name}\n"
         msg += f"function/method: {func_name}\n"
         raise RuntimeError(msg)
 
-    if len(re.findall(r"Returns", docstring)) > 0:
-        params_section = re.findall(
-            r"(?<=Parameters)(.*)(?=Returns)", docstring, re.DOTALL
-        )[0]
-    else:
-        params_section = re.findall(r"(?<=Parameters)(.*)", docstring, re.DOTALL)[0]
+    params_section = re.findall(
+        r"(?<=Parameters)(.*)(?=Returns)", docstring, re.DOTALL
+    )[0]
 
     args = re.findall(r"(\w+)\s+\:", params_section)
     args = set([a for a in args if a != "i"])  # `i` should never be a parameter
@@ -43,11 +42,11 @@ def get_signature_args(fd):
     return set([a.arg for a in fd.args.args if a.arg != "self"])
 
 
-def check_args(docstring_args, signature_args, file_name, func_name, class_name=None):
+def check_args(doc_args, sig_args, file_name, func_name, class_name=None):
     """
     Compare docstring arguments and signature argments
     """
-    diff_args = signature_args.difference(docstring_args)
+    diff_args = sig_args.difference(doc_args)
     if len(diff_args) > 0:
         msg = "Found one or more arguments/parameters with missing docstring in \n"
         msg += f"file: {file_name}\n"
@@ -57,7 +56,7 @@ def check_args(docstring_args, signature_args, file_name, func_name, class_name=
         msg += f"parameter(s): {diff_args}\n"
         raise RuntimeError(msg)
 
-    diff_args = docstring_args.difference(signature_args)
+    diff_args = doc_args.difference(sig_args)
     if len(diff_args) > 0:
         msg = "Found one or more unsupported arguments/parameters with docstring in \n"
         msg += f"file: {file_name}\n"

environment.yml

@@ -29,3 +29,4 @@ dependencies:
   - polars>=1.14.0
   - fftw>=3.3
   - pyfftw>=0.15.0
+  - numba-cuda>=0.24.0

pyproject.toml

@@ -87,8 +87,9 @@ isort = ">=5.11.0"
 polars = ">=1.14.0"
 pip = "*"
 lxml = "*"
-fftw = ">=3.3"
-pyfftw = ">=0.15.0"
+fftw = "*"
+pyfftw = "*"
+numba-cuda = "*"
 # readthedocs
 sphinx = ">=3.5.3"
 pydata-sphinx-theme = "*"
@@ -113,5 +114,5 @@ tbb = ">=2019.5"
 tests = "./test.sh"
 coverage = "./test.sh coverage"
 docs = "cd docs && ./setup.sh"
-black = 'black --exclude=".*\.ipynb" --extend-exclude=".venv|.pixi" --diff ./'
+black = 'black --exclude=".*\.ipynb" --extend-exclude=".venv|.pixi" ./'
 isort = 'isort --profile black --skip .venv --skip .pixi ./'

stumpy/__init__.py

@@ -1,39 +1,63 @@
 import ast
+import importlib
 import os.path
 import pathlib
+import types
 from importlib.metadata import distribution
 from site import getsitepackages
 
 from numba import cuda
 
 from . import cache, config
-from .aamp import aamp  # noqa: F401
-from .aamp_mmotifs import aamp_mmotifs  # noqa: F401
-from .aamp_motifs import aamp_match, aamp_motifs  # noqa: F401
-from .aamp_ostinato import aamp_ostinato, aamp_ostinatoed  # noqa: F401
-from .aamp_stimp import aamp_stimp, aamp_stimped  # noqa: F401
-from .aampdist import aampdist, aampdisted  # noqa: F401
-from .aampdist_snippets import aampdist_snippets  # noqa: F401
-from .aamped import aamped  # noqa: F401
-from .aampi import aampi  # noqa: F401
-from .chains import allc, atsc  # noqa: F401
-from .core import mass  # noqa: F401
-from .floss import floss, fluss  # noqa: F401
-from .maamp import maamp, maamp_mdl, maamp_subspace  # noqa: F401
-from .maamped import maamped  # noqa: F401
-from .mmotifs import mmotifs  # noqa: F401
-from .motifs import match, motifs  # noqa: F401
-from .mpdist import mpdist, mpdisted  # noqa: F401
-from .mstump import mdl, mstump, subspace  # noqa: F401
-from .mstumped import mstumped  # noqa: F401
-from .ostinato import ostinato, ostinatoed  # noqa: F401
-from .scraamp import prescraamp, scraamp  # noqa: F401
-from .scrump import prescrump, scrump  # noqa: F401
-from .snippets import snippets  # noqa: F401
-from .stimp import stimp, stimped  # noqa: F401
-from .stump import stump  # noqa: F401
-from .stumped import stumped  # noqa: F401
-from .stumpi import stumpi  # noqa: F401
+
+# Define which functions belong to which module
+# Key: function name to expose at top level
+# Value: name of the module
+_lazy_imports = {
+    "aamp": "aamp",
+    "aamp_mmotifs": "aamp_mmotifs",
+    "aamp_match": "aamp_motifs",
+    "aamp_motifs": "aamp_motifs",
+    "aamp_ostinato": "aamp_ostinato",
+    "aamp_ostinatoed": "aamp_ostinato",
+    "aamp_stimp": "aamp_stimp",
+    "aamp_stimped": "aamp_stimp",
+    "aampdist": "aampdist",
+    "aampdisted": "aampdist",
+    "aampdist_snippets": "aampdist_snippets",
+    "aamped": "aamped",
+    "aampi": "aampi",
+    "allc": "chains",
+    "atsc": "chains",
+    "mass": "core",
+    "floss": "floss",
+    "fluss": "floss",
+    "maamp": "maamp",
+    "maamp_mdl": "maamp",
+    "maamp_subspace": "maamp",
+    "maamped": "maamped",
+    "mmotifs": "mmotifs",
+    "match": "motifs",
+    "motifs": "motifs",
+    "mpdist": "mpdist",
+    "mpdisted": "mpdist",
+    "mdl": "mstump",
+    "mstump": "mstump",
+    "subspace": "mstump",
+    "mstumped": "mstumped",
+    "ostinato": "ostinato",
+    "ostinatoed": "ostinato",
+    "prescraamp": "scraamp",
+    "scraamp": "scraamp",
+    "prescrump": "scrump",
+    "scrump": "scrump",
+    "snippets": "snippets",
+    "stimp": "stimp",
+    "stimped": "stimp",
+    "stump": "stump",
+    "stumped": "stumped",
+    "stumpi": "stumpi",
+}
 
 # Get the default fastmath flags for all njit functions
 # and update the _STUMPY_DEFAULTS dictionary
@@ -61,14 +85,18 @@ def _get_fastmath_value(module_name, func_name):  # pragma: no cover
     config._STUMPY_DEFAULTS[key] = _get_fastmath_value(module_name, func_name)
 
 if cuda.is_available():
-    from .gpu_aamp import gpu_aamp  # noqa: F401
-    from .gpu_aamp_ostinato import gpu_aamp_ostinato  # noqa: F401
-    from .gpu_aamp_stimp import gpu_aamp_stimp  # noqa: F401
-    from .gpu_aampdist import gpu_aampdist  # noqa: F401
-    from .gpu_mpdist import gpu_mpdist  # noqa: F401
-    from .gpu_ostinato import gpu_ostinato  # noqa: F401
-    from .gpu_stimp import gpu_stimp  # noqa: F401
-    from .gpu_stump import gpu_stump  # noqa: F401
+    _lazy_imports.update(
+        {
+            "gpu_aamp": "gpu_aamp",
+            "gpu_aamp_ostinato": "gpu_aamp_ostinato",
+            "gpu_aamp_stimp": "gpu_aamp_stimp",
+            "gpu_aampdist": "gpu_aampdist",
+            "gpu_mpdist": "gpu_mpdist",
+            "gpu_ostinato": "gpu_ostinato",
+            "gpu_stimp": "gpu_stimp",
+            "gpu_stump": "gpu_stump",
+        }
+    )
 else:  # pragma: no cover
     from . import core
     from .core import _gpu_aamp_driver_not_found as gpu_aamp  # noqa: F401
@@ -220,3 +248,69 @@ def _get_fastmath_value(module_name, func_name):  # pragma: no cover
     __version__ = "Please install this project with setup.py"
 else:  # pragma: no cover
     __version__ = _dist.version
+
+
+# PEP 562: module-level __getattr__ for lazy imports
+def __getattr__(name):  # pragma: no cover
+    if name in _lazy_imports:
+        mod_name = _lazy_imports[name]
+        module = importlib.import_module(f"{__package__}.{mod_name}")
+        # Retrieve the attribute from the loaded module and cache it
+        attr = getattr(module, name)
+        globals()[name] = attr
+        return attr
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# Ensure that if a module was imported during package import
+# (causing the package attribute to point to the module object), we
+# replace that entry with the actual attribute (e.g., function) so that
+# users get the expected callable at `stumpy.aamp` rather than the module.
+for _name, _sub in _lazy_imports.items():  # pragma: no cover
+    val = globals().get(_name)
+    if isinstance(val, types.ModuleType):
+        try:
+            replacement = getattr(val, _name)
+        except AttributeError:
+            # Nothing to do if the module doesn't define the attribute
+            continue
+        globals()[_name] = replacement
+
+
+# Eagerly import exports that would otherwise collide with
+# same-named modules. This keeps lazy imports for most names but
+# ensures that when a top-level exported name exactly matches its
+# module (e.g., `stump` -> `stump.py`), the exported attribute is
+# available immediately so REPL completers prefer the callable/class
+# instead of the module.
+for _name, _sub in _lazy_imports.items():  # pragma: no cover
+    try:
+        if _name == _sub:
+            filepath = pathlib.Path(__file__).parent / f"{_sub}.py"
+            if filepath.exists():
+                module = importlib.import_module(f"{__package__}.{_sub}")
+                try:
+                    globals()[_name] = getattr(module, _name)
+                except AttributeError:
+                    # If the module doesn't define the attribute, keep it lazy
+                    pass
+    except Exception:
+        # Be conservative: don't let eager-import attempts raise during package import
+        pass
+
+
+def __dir__():  # pragma: no cover
+    # Expose lazy names in dir() for discoverability
+    # Also include __all__ so tools that consult it will see the intended
+    # top-level exports (this helps some REPL completers prefer the
+    # callable/class exports over same-named modules).
+    all_names = list(globals().keys()) + list(_lazy_imports.keys())
+    all_names += list(globals().get("__all__", []))
+    return sorted(all_names)
+
+
+# Make the lazy-exported names explicit for tools that respect __all__.
+# This helps REPL tab-completion prefer functions/classes over modules
+# when names collide (e.g., `stumpy.stump` should point to the function
+# rather than the module during completion).
+__all__ = sorted(list(_lazy_imports.keys()))

stumpy/aamp_stimp.py

@@ -189,6 +189,10 @@ def __init__(
             The p-norm to apply for computing the Minkowski distance. Minkowski distance
             is typically used with `p` being 1 or 2, which correspond to the Manhattan
             distance and the Euclidean distance, respectively.
+
+        Returns
+        -------
+        None
         """
         self._T = T.copy()
         self._T_min = np.min(self._T[np.isfinite(self._T)])
@@ -228,6 +232,10 @@ def update(self):
         ----------
         None
 
+        Returns
+        -------
+        None
+
         Notes
         -----
         `DOI: 10.1109/ICBK.2019.00031 \
@@ -290,7 +298,9 @@ def pan(self, threshold=0.2, normalize=True, contrast=True, binary=True, clip=Tr
 
         Returns
         -------
-        None
+        PAN : numpy.ndarray
+            The transformed (i.e., normalized, contrasted, binarized, and repeated)
+            pan matrix profile
         """
         PAN = self._PAN.copy()
         # Retrieve the row indices where the matrix profile was actually computed
@@ -334,6 +344,12 @@ def PAN_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The transformed (i.e., normalized, contrasted, binarized, and repeated) pan
+            matrix profile
         """
         return self.pan().astype(np.float64)
 
@@ -345,6 +361,12 @@ def M_(self):
         Parameters
         ----------
         None
+
+        Returns
+        -------
+        out : numpy.ndarray
+            The full list of (breadth first search (level) ordered) subsequence window
+            sizes
         """
         return self._M.astype(np.int64)
 
@@ -360,7 +382,9 @@ def P_(self):
 
         Returns
         -------
-        None
+        P : list of numpy.ndarray
+            A list of all of the raw (i.e., non-transformed) matrix profiles matrix
+            profile in (breadth first searched (level) ordered)
         """
         P = []
         for i, idx in enumerate(self._bfs_indices):
@@ -491,6 +515,10 @@ def __init__(
             The p-norm to apply for computing the Minkowski distance. Minkowski distance
             is typically used with `p` being 1 or 2, which correspond to the Manhattan
             distance and the Euclidean distance, respectively.
+
+        Returns
+        -------
+        None
         """
         super().__init__(
             T,
@@ -597,6 +625,10 @@ def __init__(
             The p-norm to apply for computing the Minkowski distance. Minkowski distance
             is typically used with `p` being 1 or 2, which correspond to the Manhattan
             distance and the Euclidean distance, respectively.
+
+        Returns
+        -------
+        None
         """
         super().__init__(
             T,