pygaborstm 0.1.0__tar.gz

pygaborstm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johns Hopkins University - Laboratory for Computational Audio Perception
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygaborstm-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: pygaborstm
+Version: 0.1.0
+Summary: Rate-Scale-Frequency (RSF) representations from audio via bio-inspired auditory spectrograms and 2D Gabor filterbanks.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,speech,auditory-model,spectro-temporal-modulation,gabor-filterbank,cochlear-model,rate-scale-frequency,signal-processing
+Author: Johns Hopkins University - Laboratory for Computational Audio Perception
+Requires-Python: >=3.11
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Provides-Extra: cuda12
+Provides-Extra: cuda13
+Provides-Extra: viz
+Requires-Dist: cupy-cuda12x (>=13.0,<15.0) ; (sys_platform != "darwin") and (extra == "cuda12")
+Requires-Dist: cupy-cuda13x (>=14.0.1,<15.0) ; (sys_platform != "darwin") and (extra == "cuda13")
+Requires-Dist: matplotlib (>=3.10,<4.0) ; extra == "viz"
+Requires-Dist: numpy (>=2.3.3,<3.0.0)
+Requires-Dist: psutil (>=5.9)
+Requires-Dist: scipy (>=1.16.2,<2.0.0)
+Requires-Dist: seaborn (>=0.13,<0.14) ; extra == "viz"
+Project-URL: Documentation, https://pygaborstm.readthedocs.io/
+Project-URL: Homepage, https://github.com/JHU-LCAP/PyGaborSTM
+Project-URL: Issues, https://github.com/JHU-LCAP/PyGaborSTM/issues
+Project-URL: Repository, https://github.com/JHU-LCAP/PyGaborSTM
+Description-Content-Type: text/markdown
+
+# PyGaborSTM
+
+[![PyPI](https://img.shields.io/pypi/v/pygaborstm)](https://pypi.org/project/pygaborstm/)
+[![Python](https://img.shields.io/pypi/pyversions/pygaborstm)](https://pypi.org/project/pygaborstm/)
+[![CI](https://github.com/JHU-LCAP/PyGaborSTM/actions/workflows/ci.yml/badge.svg)](https://github.com/JHU-LCAP/PyGaborSTM/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/pygaborstm/badge/?version=latest)](https://pygaborstm.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+PyGaborSTM is a Python library for extracting Rate-Scale-Frequency (RSF) representations from audio signals using bio-inspired auditory spectrograms and 2D Gabor filterbanks. Documentation can be found [here](https://pygaborstm.readthedocs.io/en/latest/).
+
+The project is `PyGaborSTM`; the package you install and import is lowercase
+`pygaborstm`.
+
+> **Status:** 0.1.0, a first public release. The API may still change in
+> backwards-incompatible ways before 1.0.
+
+## Installation
+
+```bash
+pip install pygaborstm
+```
+
+This is the CPU install and works on macOS, Linux and Windows. It pulls only
+NumPy, SciPy and psutil.
+
+Plotting (`pygaborstm.plot` and `pygaborstm.analysis`) needs matplotlib, which
+is an extra so the core install stays small:
+
+```bash
+pip install 'pygaborstm[viz]'
+```
+
+### GPU (optional, NVIDIA only)
+Pick the extra matching your CUDA version, which `nvidia-smi` reports:
+
+```bash
+pip install 'pygaborstm[cuda12]'   # CUDA 12.x
+pip install 'pygaborstm[cuda13]'   # CUDA 13.x
+```
+
+Install only one: both provide the `cupy` module. CuPy has no macOS wheels, so
+on macOS these extras install nothing and the library runs on CPU.
+
+Then set `use_gpu=True`:
+
+```python
+model = stm.PyGaborSTM(stm.Config(use_gpu=True))
+```
+
+If CuPy is missing or no CUDA device is present, the library warns and falls
+back to NumPy rather than failing. Check what it actually resolved with
+`model.device.on_gpu`.
+
+### From source
+```bash
+git clone https://github.com/JHU-LCAP/PyGaborSTM.git
+cd PyGaborSTM
+poetry install
+```
+
+### Depending on unreleased work
+
+Nothing is published between releases. To build against `main`, pin a commit:
+
+```toml
+# your pyproject.toml
+pygaborstm = { git = "https://github.com/JHU-LCAP/PyGaborSTM.git", rev = "<sha>" }
+```
+
+Between releases the version reads `X.Y.Z.dev0` for every commit, so it tells
+you which release is being worked toward, not which commit you have. The commit
+is recorded by pip at install time and read back with:
+
+```python
+>>> import pygaborstm as stm
+>>> stm.build_info()
+{'version': '0.2.0.dev0', 'source': 'git', 'commit': 'a1b2c3d...', 'url': '...'}
+```
+
+This works even if you pinned a branch: pip records the commit it resolved.
+An install from PyPI reports `source: 'index'` and no commit, because there the
+version identifies the build.
+
+To see what a pinned commit contains relative to the last release:
+
+```bash
+git log --oneline v0.1.0..<sha>
+```
+
+### CUDA Toolkit
+The CuPy wheels bundle the CUDA runtime, so a separate toolkit install is only
+needed if you want `nvcc` and the profiling tools.
+
+Get it from https://developer.nvidia.com/cuda-toolkit, then add to your shell
+profile:
+
+```bash
+export PATH=/usr/local/cuda/bin:$PATH
+export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
+```
+
+## Quick Start
+```python
+import pygaborstm as stm
+
+# Create model (CPU)
+model = stm.PyGaborSTM()
+
+# Create model (GPU)
+model = stm.PyGaborSTM(config=stm.Config(use_gpu=True))
+
+# Compute spectrogram and RSF
+spec = model.spectrogram(audio)
+rsf = model.rsf(spec)
+
+# Visualization
+stm.plot.plt_spectrogram(spec)
+stm.plot.plt_rsf(rsf)
+stm.plot.plt_rsf(rsf, fold=True)  # Symmetric folding
+```
+
+See `notebooks/example_usage.ipynb` for more examples.
+
+### Notebooks and their audio
+
+The notebooks are not self-contained: `data/` and `notebooks/assets/` are
+gitignored, so the audio they read is absent from a fresh clone.
+
+- `chi2005_validation.ipynb` regenerates most of its own stimuli, so it runs
+  after executing its generation cell.
+- `example_usage.ipynb` and `benchmark.ipynb` need audio you supply; point them
+  at any mono file.
+- `chi99_validation.ipynb` and `mvripfft_validation.ipynb` need the ripple set,
+  which `notebooks/nb_utils/audio_generator.py:generate_ripple_set` produces.
+  Note the default rates there are narrower than the set `chi99_validation`
+  expects, so it reproduces the method rather than the exact figure.
+
+## Configuration
+```python
+config = stm.Config(
+    # General
+    use_gpu=False,          # Enable GPU acceleration
+    sample_rate=16000,      # Audio sample rate
+    
+    # Spectrogram
+    n_filters=128,          # Number of frequency channels
+    f_min=180.0,            # Minimum frequency (Hz)
+    octaves=5.3,            # Frequency range in octaves
+    
+    # RSF / Gabor
+    resolution="low",       # "low", "medium", "high", "ultra", "max", "overkill"
+)
+```
+
+## Directory Structure
+```
+PyGaborSTM/
+├── pygaborstm/
+│   ├── __init__.py      # Public API
+│   ├── config.py        # Config dataclass
+│   ├── structs.py       # Spectrogram, RSF dataclasses
+│   ├── spectrogram.py   # AuditorySpectrogram
+│   ├── gabor.py         # GaborFilterbank
+│   ├── core.py          # PyGaborSTM class
+│   ├── plot.py          # Plotting functions (needs [viz])
+│   ├── analysis.py      # MTF analysis helpers (needs [viz])
+│   ├── backend.py       # Device resolution, NumPy/CuPy switching
+│   ├── _optional.py     # Optional-dependency errors
+│   └── gammatone_kernel.py  # Custom CUDA SOS kernel
+├── notebooks/
+└── tests/
+```
+
+## Development
+```bash
+poetry install                      # Install all dependencies
+poetry run jupyter notebook         # Run notebooks
+poetry run pytest -m "not gpu"      # Run all tests excluding GPU kernel tests (used in CI/CD)
+poetry run pytest -v                # Run all tests including GPU kernel tests
+poetry run ruff check --fix .       # lint and fix
+poetry run ruff format .            # format code
+```
+
+### Serve Docs locally
+```bash
+poetry run mkdocs serve
+```
+
+Note: Please lint and format before pushing, as CI will fail otherwise.
+
+### Jupyter Kernel
+Ensure your notebook uses the correct Poetry environment:
+```bash
+# Check Poetry env path
+poetry env info --path
+
+# Register kernel (if needed)
+poetry run python -m ipykernel install --user --name pygaborstm
+```
+
+## Citing
+
+If you use PyGaborSTM in published work, please cite the software (see
+`CITATION.cff`, or the "Cite this repository" button on GitHub) along with the
+papers it implements.
+
+## References
+- Chi, T., Ru, P., & Shamma, S. A. (2005). Multiresolution spectrotemporal analysis of complex sounds. *The Journal of the Acoustical Society of America*, 118(2), 887-906. [doi:10.1121/1.1945807](https://doi.org/10.1121/1.1945807)
+
+  The auditory spectrogram model implemented here.
+
+- Bellur, A., & Elhilali, M. (2017). Feedback-driven sensory mapping adaptation for robust speech activity detection. *IEEE/ACM Transactions on Audio, Speech, and Language Processing*, 25(3), 481-492. [doi:10.1109/TASLP.2016.2639322](https://doi.org/10.1109/TASLP.2016.2639322)
+
+  The Gabor filterbank formulation used for the RSF stage.
+

pygaborstm-0.1.0/README.md

@@ -0,0 +1,214 @@
+# PyGaborSTM
+
+[![PyPI](https://img.shields.io/pypi/v/pygaborstm)](https://pypi.org/project/pygaborstm/)
+[![Python](https://img.shields.io/pypi/pyversions/pygaborstm)](https://pypi.org/project/pygaborstm/)
+[![CI](https://github.com/JHU-LCAP/PyGaborSTM/actions/workflows/ci.yml/badge.svg)](https://github.com/JHU-LCAP/PyGaborSTM/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/pygaborstm/badge/?version=latest)](https://pygaborstm.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+PyGaborSTM is a Python library for extracting Rate-Scale-Frequency (RSF) representations from audio signals using bio-inspired auditory spectrograms and 2D Gabor filterbanks. Documentation can be found [here](https://pygaborstm.readthedocs.io/en/latest/).
+
+The project is `PyGaborSTM`; the package you install and import is lowercase
+`pygaborstm`.
+
+> **Status:** 0.1.0, a first public release. The API may still change in
+> backwards-incompatible ways before 1.0.
+
+## Installation
+
+```bash
+pip install pygaborstm
+```
+
+This is the CPU install and works on macOS, Linux and Windows. It pulls only
+NumPy, SciPy and psutil.
+
+Plotting (`pygaborstm.plot` and `pygaborstm.analysis`) needs matplotlib, which
+is an extra so the core install stays small:
+
+```bash
+pip install 'pygaborstm[viz]'
+```
+
+### GPU (optional, NVIDIA only)
+Pick the extra matching your CUDA version, which `nvidia-smi` reports:
+
+```bash
+pip install 'pygaborstm[cuda12]'   # CUDA 12.x
+pip install 'pygaborstm[cuda13]'   # CUDA 13.x
+```
+
+Install only one: both provide the `cupy` module. CuPy has no macOS wheels, so
+on macOS these extras install nothing and the library runs on CPU.
+
+Then set `use_gpu=True`:
+
+```python
+model = stm.PyGaborSTM(stm.Config(use_gpu=True))
+```
+
+If CuPy is missing or no CUDA device is present, the library warns and falls
+back to NumPy rather than failing. Check what it actually resolved with
+`model.device.on_gpu`.
+
+### From source
+```bash
+git clone https://github.com/JHU-LCAP/PyGaborSTM.git
+cd PyGaborSTM
+poetry install
+```
+
+### Depending on unreleased work
+
+Nothing is published between releases. To build against `main`, pin a commit:
+
+```toml
+# your pyproject.toml
+pygaborstm = { git = "https://github.com/JHU-LCAP/PyGaborSTM.git", rev = "<sha>" }
+```
+
+Between releases the version reads `X.Y.Z.dev0` for every commit, so it tells
+you which release is being worked toward, not which commit you have. The commit
+is recorded by pip at install time and read back with:
+
+```python
+>>> import pygaborstm as stm
+>>> stm.build_info()
+{'version': '0.2.0.dev0', 'source': 'git', 'commit': 'a1b2c3d...', 'url': '...'}
+```
+
+This works even if you pinned a branch: pip records the commit it resolved.
+An install from PyPI reports `source: 'index'` and no commit, because there the
+version identifies the build.
+
+To see what a pinned commit contains relative to the last release:
+
+```bash
+git log --oneline v0.1.0..<sha>
+```
+
+### CUDA Toolkit
+The CuPy wheels bundle the CUDA runtime, so a separate toolkit install is only
+needed if you want `nvcc` and the profiling tools.
+
+Get it from https://developer.nvidia.com/cuda-toolkit, then add to your shell
+profile:
+
+```bash
+export PATH=/usr/local/cuda/bin:$PATH
+export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
+```
+
+## Quick Start
+```python
+import pygaborstm as stm
+
+# Create model (CPU)
+model = stm.PyGaborSTM()
+
+# Create model (GPU)
+model = stm.PyGaborSTM(config=stm.Config(use_gpu=True))
+
+# Compute spectrogram and RSF
+spec = model.spectrogram(audio)
+rsf = model.rsf(spec)
+
+# Visualization
+stm.plot.plt_spectrogram(spec)
+stm.plot.plt_rsf(rsf)
+stm.plot.plt_rsf(rsf, fold=True)  # Symmetric folding
+```
+
+See `notebooks/example_usage.ipynb` for more examples.
+
+### Notebooks and their audio
+
+The notebooks are not self-contained: `data/` and `notebooks/assets/` are
+gitignored, so the audio they read is absent from a fresh clone.
+
+- `chi2005_validation.ipynb` regenerates most of its own stimuli, so it runs
+  after executing its generation cell.
+- `example_usage.ipynb` and `benchmark.ipynb` need audio you supply; point them
+  at any mono file.
+- `chi99_validation.ipynb` and `mvripfft_validation.ipynb` need the ripple set,
+  which `notebooks/nb_utils/audio_generator.py:generate_ripple_set` produces.
+  Note the default rates there are narrower than the set `chi99_validation`
+  expects, so it reproduces the method rather than the exact figure.
+
+## Configuration
+```python
+config = stm.Config(
+    # General
+    use_gpu=False,          # Enable GPU acceleration
+    sample_rate=16000,      # Audio sample rate
+    
+    # Spectrogram
+    n_filters=128,          # Number of frequency channels
+    f_min=180.0,            # Minimum frequency (Hz)
+    octaves=5.3,            # Frequency range in octaves
+    
+    # RSF / Gabor
+    resolution="low",       # "low", "medium", "high", "ultra", "max", "overkill"
+)
+```
+
+## Directory Structure
+```
+PyGaborSTM/
+├── pygaborstm/
+│   ├── __init__.py      # Public API
+│   ├── config.py        # Config dataclass
+│   ├── structs.py       # Spectrogram, RSF dataclasses
+│   ├── spectrogram.py   # AuditorySpectrogram
+│   ├── gabor.py         # GaborFilterbank
+│   ├── core.py          # PyGaborSTM class
+│   ├── plot.py          # Plotting functions (needs [viz])
+│   ├── analysis.py      # MTF analysis helpers (needs [viz])
+│   ├── backend.py       # Device resolution, NumPy/CuPy switching
+│   ├── _optional.py     # Optional-dependency errors
+│   └── gammatone_kernel.py  # Custom CUDA SOS kernel
+├── notebooks/
+└── tests/
+```
+
+## Development
+```bash
+poetry install                      # Install all dependencies
+poetry run jupyter notebook         # Run notebooks
+poetry run pytest -m "not gpu"      # Run all tests excluding GPU kernel tests (used in CI/CD)
+poetry run pytest -v                # Run all tests including GPU kernel tests
+poetry run ruff check --fix .       # lint and fix
+poetry run ruff format .            # format code
+```
+
+### Serve Docs locally
+```bash
+poetry run mkdocs serve
+```
+
+Note: Please lint and format before pushing, as CI will fail otherwise.
+
+### Jupyter Kernel
+Ensure your notebook uses the correct Poetry environment:
+```bash
+# Check Poetry env path
+poetry env info --path
+
+# Register kernel (if needed)
+poetry run python -m ipykernel install --user --name pygaborstm
+```
+
+## Citing
+
+If you use PyGaborSTM in published work, please cite the software (see
+`CITATION.cff`, or the "Cite this repository" button on GitHub) along with the
+papers it implements.
+
+## References
+- Chi, T., Ru, P., & Shamma, S. A. (2005). Multiresolution spectrotemporal analysis of complex sounds. *The Journal of the Acoustical Society of America*, 118(2), 887-906. [doi:10.1121/1.1945807](https://doi.org/10.1121/1.1945807)
+
+  The auditory spectrogram model implemented here.
+
+- Bellur, A., & Elhilali, M. (2017). Feedback-driven sensory mapping adaptation for robust speech activity detection. *IEEE/ACM Transactions on Audio, Speech, and Language Processing*, 25(3), 481-492. [doi:10.1109/TASLP.2016.2639322](https://doi.org/10.1109/TASLP.2016.2639322)
+
+  The Gabor filterbank formulation used for the RSF stage.

pygaborstm-0.1.0/pygaborstm/__init__.py

@@ -0,0 +1,214 @@
+"""PyGaborSTM: spectro-temporal modulation analysis.
+
+Extracts Rate-Scale-Frequency (RSF) representations from audio via a
+bio-inspired auditory spectrogram followed by a 2D Gabor filterbank,
+following Chi, Ru & Shamma (2005) and Bellur & Elhilali (2017).
+
+Public API
+----------
+PyGaborSTM
+    Main user-facing class. Use :meth:`PyGaborSTM.compute` for the full
+    pipeline, or :meth:`PyGaborSTM.spectrogram` and
+    :meth:`PyGaborSTM.rsf` for the individual stages.
+Config
+    Configuration dataclass for all pipeline parameters.
+Spectrogram, RSF
+    Output dataclasses returned by the corresponding stages.
+structs
+    Namespaced submodule of the output dataclasses.
+plot, analysis
+    Namespaced submodules, imported on first attribute access. They need
+    the plotting extra::
+
+        pip install 'pygaborstm[viz]'
+
+    Importing :mod:`pygaborstm` itself never imports matplotlib.
+
+Examples
+--------
+>>> import pygaborstm as stm
+>>> model = stm.PyGaborSTM(config=stm.Config(use_gpu=True))
+>>> spec = model.spectrogram(audio)
+>>> rsf = model.rsf(spec)
+>>> stm.plot.plt_spectrogram(spec)   # needs pygaborstm[viz]
+>>> stm.plot.plt_rsf(rsf)
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+from . import structs
+from ._optional import VIZ_MODULES, missing_extra_message
+from .config import Config
+from .core import PyGaborSTM
+from .structs import RSF, Spectrogram
+
+# Resolved by type checkers and IDEs without importing matplotlib at runtime.
+if TYPE_CHECKING:
+    # Redundant aliases mark these as re-exports; they are public but kept out
+    # of __all__ so star-import does not require the viz extra.
+    from . import analysis as analysis
+    from . import plot as plot
+
+try:
+    __version__ = _dist_version("pygaborstm")
+except PackageNotFoundError:  # source tree that was never installed
+    __version__ = "0.0.0.dev0"
+
+
+def build_info() -> dict[str, str | None]:
+    """Where this installation came from.
+
+    Between releases the version alone does not identify a build, since every
+    commit reports the same ``X.Y.Z.dev0``. This reads the record pip writes at
+    install time (PEP 610 ``direct_url.json``) to recover the exact commit.
+
+    Returns
+    -------
+    dict
+        ``version`` always. ``source`` is one of ``"git"``, ``"vcs"``,
+        ``"archive"``, ``"local"``, ``"editable"``, ``"index"`` or
+        ``"unknown"``. ``commit`` is the resolved sha for a git install and
+        None otherwise; ``url`` is the origin when one was recorded.
+
+    Examples
+    --------
+    >>> import pygaborstm as stm
+    >>> stm.build_info()["commit"]
+    'a1b2c3d4e5f6...'
+
+    Notes
+    -----
+    A git install records the commit pip actually resolved, so pinning a branch
+    still yields a concrete sha. Released installs from an index carry no such
+    record: there the version is the identifier.
+
+    This never raises. Anything it cannot establish is reported as
+    ``"unknown"`` rather than guessed, because a confident wrong answer about
+    provenance is worse than admitting ignorance.
+    """
+    info: dict[str, str | None] = {
+        "version": __version__,
+        "source": "unknown",
+        "commit": None,
+        "url": None,
+    }
+    try:
+        return _provenance(info)
+    except Exception:  # pragma: no cover - diagnostics must never break import
+        return info
+
+
+def _record_describes_this_import(dist) -> bool:
+    """True if ``dist``'s files are the ones that actually got imported."""
+    from pathlib import Path
+
+    try:
+        located = dist.locate_file("pygaborstm/__init__.py")
+        if located is None:
+            return False
+        return Path(located).resolve() == Path(__file__).resolve()
+    except Exception:
+        return False
+
+
+def _provenance(info: dict[str, str | None]) -> dict[str, str | None]:
+    """Fill in ``info`` from the installed distribution's PEP 610 record."""
+    import json
+    from importlib.metadata import PackageNotFoundError, distribution
+
+    try:
+        dist = distribution("pygaborstm")
+    except (PackageNotFoundError, ValueError):
+        # A source tree that was never installed. Not an index install.
+        return info
+
+    raw = dist.read_text("direct_url.json")
+    if raw is None:
+        # Installed, but with no direct URL recorded: came from an index.
+        info["source"] = "index"
+        return info
+
+    try:
+        record = json.loads(raw)
+    except ValueError:
+        return info
+    if not isinstance(record, dict):
+        return info
+
+    url = record.get("url")
+    info["url"] = url if isinstance(url, str) else None
+
+    vcs_info = record.get("vcs_info")
+    dir_info = record.get("dir_info")
+    if isinstance(vcs_info, dict):
+        # PEP 610 allows hg, bzr and svn too; only git carries a sha we can
+        # hand back as a commit.
+        if vcs_info.get("vcs") == "git":
+            commit = vcs_info.get("commit_id")
+            info["source"] = "git"
+            info["commit"] = commit if isinstance(commit, str) else None
+            if not _record_describes_this_import(dist):
+                # Metadata lookup returns the first match on sys.path, which
+                # need not be the copy that got imported. A commit from some
+                # other installation is worse than no commit at all.
+                info["source"] = "unknown"
+                info["commit"] = None
+        else:
+            info["source"] = "vcs"
+    elif isinstance(dir_info, dict):
+        info["source"] = "editable" if dir_info.get("editable") else "local"
+    elif isinstance(record.get("archive_info"), dict):
+        info["source"] = "archive"
+    return info
+
+
+#: Submodules imported on first attribute access (PEP 562), so that
+#: `import pygaborstm` costs numpy and scipy and nothing else.
+_LAZY_SUBMODULES = frozenset({"plot", "analysis"})
+
+__all__ = [  # noqa: RUF022 - grouped by meaning, not alphabetised
+    # Main class
+    "PyGaborSTM",
+    # Config
+    "Config",
+    # Data structures
+    "Spectrogram",
+    "RSF",
+    # Namespaced modules. plot and analysis are deliberately absent: they
+    # are reachable as attributes, but listing them here would make
+    # `from pygaborstm import *` require the viz extra.
+    "structs",
+    # Metadata
+    "__version__",
+    "build_info",
+]
+
+
+def __getattr__(name: str) -> ModuleType:
+    if name not in _LAZY_SUBMODULES:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        module = import_module(f".{name}", __name__)
+    except ImportError as exc:
+        # Only translate a missing optional dependency. A genuine ImportError
+        # from inside plot.py or analysis.py must surface unchanged.
+        missing = (exc.name or "").split(".")[0]
+        if missing not in VIZ_MODULES:
+            raise
+        raise ImportError(
+            missing_extra_message(missing, extra="viz", feature=f"pygaborstm.{name}")
+        ) from exc
+    globals()[name] = module
+    return module
+
+
+def __dir__() -> list[str]:
+    # _LAZY_SUBMODULES explicitly: they are public and should be discoverable
+    # before they have been touched, even though they are not in __all__.
+    return sorted(set(globals()) | set(__all__) | _LAZY_SUBMODULES)