transivent

transivent is a Python library for detecting and analysing transient events (~spikes) in time-series data. It provides a flexible and configurable pipeline for processing waveform data, identifying events based on signal-to-noise ratio, and visualizing the results. The library is designed to handle large files efficiently through chunked processing.

Additionally, transivent includes tools for diffusion analysis of detected events, including Mean Square Displacement (MSD) calculation, autocorrelation analysis, and statistical visualization.

Brutalist Philosophy: Simple, composable building blocks. Use detect() for custom data or detect_from_wfm() for Wfm files. All underlying components are available for advanced users. No unnecessary abstractions.

Quick Start

For Custom Time-Series Data

import numpy as np
from transivent import detect

# Load your data (CSV, NumPy, HDF5, etc.)
t = np.linspace(0, 1, 100000)  # Time in seconds
x = np.random.randn(100000) * 0.1  # Signal

# Detect events
results = detect(
    t, x,
    name="My Data",
    detection_snr=3.0,
    signal_polarity=-1,  # -1 for negative spikes, +1 for positive
)

# Access results
events = results["events"]
print(f"Found {len(events)} events")

For Wfm Files (proprietary format with XML sidecar)

from transivent import detect_from_wfm

# Detect events in Wfm file
results = detect_from_wfm(
    name="data.Wfm.bin",
    sampling_interval=5e-7,  # seconds
    data_path="/path/to/data/",
    target_sampling_interval=5e-6,  # Optional: downsample to 200 kHz
    detection_snr=3.0,
)

New in v2.1.0: Use target_sampling_interval to downsample oversampled data before detection. This improves SNR and processing speed for high-frequency data.

events = results["events"] print(f"Found {len(events)} events")

## Advanced Usage

For advanced workflows, individual building blocks are available in submodules. The `detect()` function internally uses these components:

```python
from transivent.analysis import (
    calculate_initial_background,
    calculate_clean_background,
    detect_initial_events,
    detect_final_events,
    estimate_noise,
)

# Use these functions to build custom pipelines

For diffusion analysis:

from transivent.diffusion import (
    extract_event_waveforms,
    calculate_msd_parallel,
    calculate_acf,
    fit_diffusion_linear,
)

# After detecting events with detect()...
results = detect(t, x)
events = results["events"]
bg_clean = results["bg_clean"]

waveforms = extract_event_waveforms(t, x, events, bg_clean=bg_clean)
# ... continue with diffusion analysis

Public API

The main entry points are detect() and detect_from_wfm(). For full API documentation, consult the docstrings in the source code or the type hints in src/transivent/__init__.py.

Building blocks and advanced functions are available in submodules: - transivent.analysis - Background estimation, noise analysis, event detection - transivent.event_detector - Low-level detection algorithms
- transivent.diffusion - Diffusion analysis tools (optional) - transivent.io - File I/O utilities

Examples

The repository includes several example scripts demonstrating different use cases:

• example_quick_start.py - Quick introduction to both detect() and detect_from_wfm()
• example.py - Complete workflow for processing Wfm files with XML sidecars
• example_custom_data.py - Demonstrates using transivent with any time-series data (CSV, NumPy arrays, etc.)
• example_diffusion.py - Complete diffusion analysis workflow with visualization

Each example is self-contained and can be run directly to see the library in action.

Migration from v1.0.0

If you're upgrading from v1.0.0, here's how to update your code:

v1.0.0 → v2.0.0 Mapping

Old:

from transivent import process_file

process_file(
    name="data.Wfm.bin",
    sampling_interval=5e-7,
    data_path="/path/to/data/",
    detection_snr=3.0,
    show_plots=True,
)

New:

from transivent import detect_from_wfm

results = detect_from_wfm(
    name="data.Wfm.bin",
    sampling_interval=5e-7,
    data_path="/path/to/data/",
    detection_snr=3.0,
    save_plots=True,
)

events = results["events"]  # Now you get results back!

Key Changes

Building Blocks

If you were using internal functions like calculate_initial_background, they're still available but now in submodules:

# Old (no longer in main API)
from transivent import calculate_initial_background

# New
from transivent.analysis import calculate_initial_background