senselab

Build codecov Ruff

PyPI Python Version License

pages

Welcome to senselab! This is a Python package for streamlining the processing and analysis of behavioral data, such as voice and speech patterns, with robust and reproducible methodologies.

Why should I use senselab?

  • Modular Design: Easily integrate or use standalone transformations for flexible data manipulation.
  • Pre-built Pipelines: Access pre-configured pipelines to reduce setup time and effort.
  • Reproducibility: Ensure consistent and verifiable results with fixed seeds and version-controlled steps.
  • Easy Integration: Seamlessly fit into existing workflows with minimal configuration.
  • Extensible: Modify and contribute custom transformations and pipelines to meet specific research needs.
  • Comprehensive Documentation: Detailed guides, examples, and documentation for all features and modules.
  • Performance Optimized: Efficiently process large datasets with optimized code and algorithms.
  • Interactive Examples: Jupyter notebooks provide practical examples for deriving insights from real-world datasets.

Caution:: this package is still under development and may change rapidly over the next few weeks.

⚠️ System Requirements

  1. If on macOS, this package requires an ARM64 architecture due to PyTorch 2.2.2+ dropping support for x86-64 on macOS.

    ❌ Unsupported systems include:

    • macOS (Intel x86-64)
    • Other platforms where dependencies are unavailable

    To check your system compatibility, please run this command:

    python -c "import platform; print(platform.machine())"

    If the output is:

    • arm64 → ✅ Your system is compatible.
    • x86_64 → ❌ Your system is not supported.

    If you attempt to install this package on an unsupported system, the installation or execution will fail.

  2. FFmpeg is required by some audio and video dependencies (e.g., torchaudio). Please make sure you have FFmpeg properly installed on your machine before installing and using senselab (see here for detailed platform-dependent instructions).

  3. CUDA libraries matching the CUDA version expected by the PyTorch wheels (e.g., the latest pytorch 2.7 expects cuda-12.6). To install those with conda, please do:

    • conda config --add channels nvidia
    • conda install -y nvidia/label/cuda-12.6.3::cuda-libraries-dev

Installation

Install this package via:

pip install 'senselab[all]'

Or get the newest development version via:

pip install git+https://github.com/sensein/senselab.git

If you want to install only audio dependencies, you do:

pip install 'senselab[audio]'

To install audio and articulatory dependencies, you do:

pip install 'senselab[audio,articulatory]'

To install video and text extras, please do:

pip install 'senselab[video,text]'

Quick start

from senselab.audio.data_structures import Audio
from senselab.audio.tasks.preprocessing import resample_audios

audio = Audio(filepath='path_to_audio_file.wav')

print("The original audio has a sampling rate of {} Hz.".format(audio.sampling_rate))
[audio] = resample_audios([audio], resample_rate=16000)
print("The resampled audio has a sampling rate of {} Hz.".format(audio.sampling_rate))

For more detailed information, check out our Getting Started Tutorial.

Contributing

We welcome contributions from the community! Before getting started, please review our CONTRIBUTING.md.

Acknowledgments

senselab is mostly supported by the following organizations and initiatives:

  • McGovern Institute ICON Fellowship
  • NIH Bridge2AI Precision Public Health (OT2OD032720)
  • Child Mind Institute
  • ReadNet Project
  • Chris and Lann Woehrle Psychiatric Fund
 1""".. include:: ../../README.md"""  # noqa: D415
 2
 3import asyncio
 4import platform
 5from multiprocessing import set_start_method
 6
 7import nest_asyncio
 8
 9# Raise error on incompatible macOS architecture
10if platform.system() == "Darwin" and platform.machine() != "arm64":
11    raise RuntimeError(
12        "Error: This package requires an ARM64 architecture on macOS "
13        "since PyTorch 2.2.2+ does not support x86-64 on macOS."
14    )
15
16
17# Conditionally apply nest_asyncio to avoid uvloop conflict
18def safe_apply_nest_asyncio() -> None:
19    """Apply nest_asyncio to avoid uvloop conflict."""
20    try:
21        loop = asyncio.get_event_loop()
22        if "uvloop" not in str(type(loop)):
23            nest_asyncio.apply()
24    except Exception as e:
25        print(f"nest_asyncio not applied: {e}")
26
27
28safe_apply_nest_asyncio()
29
30from senselab.utils.data_structures.pydra_helpers import *  # NOQA
31
32# Ensure multiprocessing start method is 'spawn'
33try:
34    set_start_method("spawn", force=True)
35except RuntimeError:
36    pass  # Method already set
def safe_apply_nest_asyncio() -> None: 
19def safe_apply_nest_asyncio() -> None:
20    """Apply nest_asyncio to avoid uvloop conflict."""
21    try:
22        loop = asyncio.get_event_loop()
23        if "uvloop" not in str(type(loop)):
24            nest_asyncio.apply()
25    except Exception as e:
26        print(f"nest_asyncio not applied: {e}")

Apply nest_asyncio to avoid uvloop conflict.