# transivent

<img src="logo.svg" width="120" markdown="1">

`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

```python
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)

```python
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:

```python
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:**
```python
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:**
```python
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

| v1.0.0 | v2.0.0 | Notes |
|--------|--------|-------|
| `process_file()` | `detect_from_wfm()` | For Wfm files only |
| No custom data support | `detect()` | New entry point for any data |
| No return value (void) | Returns dict | All results in one place |
| 37 public functions | 8 public functions | Much simpler API |
| Plot on disk only | Plot in memory + disk | Access via `results["plot"]` |
| Internal functions exposed | Submodules for building blocks | `transivent.analysis`, `transivent.diffusion` |

### Building Blocks

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

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

# New
from transivent.analysis import calculate_initial_background
```