1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
# 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/",
detection_snr=3.0,
)
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
```
|
