Initial release v1.0.0v1.0.0

Event detection and analysis pipeline for transient events in time-series data.
- Event detection based on SNR thresholds
- Configurable background estimation and noise analysis
- Visualization with scopekit integration
- Chunked processing for large files

1 files changed, 144 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0ff20d5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,144 @@
+# 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.
+
+## Quick Start
+
+The primary entrypoint for analysis is the `transivent.process_file` function. The analysis pipeline is controlled via a configuration dictionary, and the library provides functions to read waveform data from binary files with XML sidecars.
+
+Here is a brief example based on `example.py`:
+
+```python
+from transivent import process_file, get_waveform_params
+
+# 1. Define the analysis configuration
+CONFIG = {
+    "DATA_PATH": "path/to/your/data/",
+    "SMOOTH_WIN_T": 10e-3,
+    "DETECTION_SNR": 3,
+    "MIN_EVENT_KEEP_SNR": 5,
+    "SIGNAL_POLARITY": 1,
+    "CHUNK_SIZE": 1_000_000,  # Set to a value to enable chunking
+    # ... and more
+}
+
+# 2. Define the measurement file
+measurement = {
+    "data": "RefCurve_2025-07-17_0_065114.Wfm.bin",
+}
+
+# 3. Merge configs and get waveform parameters
+config = {**CONFIG, **measurement}
+params = get_waveform_params(
+    config["data"], data_path=config["DATA_PATH"]
+)
+
+# 4. Run the processing pipeline
+process_file(
+    name=config["data"],
+    data_path=config["DATA_PATH"],
+    sampling_interval=params["sampling_interval"],
+    smooth_win_t=config.get("SMOOTH_WIN_T"),
+    detection_snr=config.get("DETECTION_SNR"),
+    min_event_keep_snr=config.get("MIN_EVENT_KEEP_SNR"),
+    signal_polarity=config.get("SIGNAL_POLARITY"),
+    chunk_size=config.get("CHUNK_SIZE"),
+    # ... other parameters
+)
+```
+
+## API Documentation
+
+The public interface of `transivent` is defined in the main `__init__.py` package.
+
+---
+### `analyze_thresholds`
+```python
+def analyze_thresholds(x: np.ndarray, bg_clean: np.ndarray, global_noise: np.float32, detection_snr: float, min_event_keep_snr: float, signal_polarity: int) -> Tuple[np.ndarray, np.ndarray]
+```
+Analyze threshold statistics and create threshold arrays.
+
+### `calculate_initial_background`
+```python
+def calculate_initial_background(t: np.ndarray, x: np.ndarray, smooth_n: int, filter_type: str = "gaussian") -> np.ndarray
+```
+Calculate initial background estimate.
+
+### `calculate_smoothing_parameters`
+```python
+def calculate_smoothing_parameters(sampling_interval: float, smooth_win_t: Optional[float], smooth_win_f: Optional[float], min_event_t: float, detection_snr: float, min_event_keep_snr: float, widen_frac: float, signal_polarity: int) -> Tuple[int, int]
+```
+Calculate smoothing window size and minimum event length in samples.
+
+### `configure_logging`
+```python
+def configure_logging(log_level: str = "INFO") -> None
+```
+Configure loguru logging with specified level.
+
+### `create_oscilloscope_plot`
+```python
+def create_oscilloscope_plot(t: np.ndarray, x: np.ndarray, bg_initial: np.ndarray, bg_clean: np.ndarray, events: np.ndarray, detection_threshold: np.ndarray, keep_threshold: np.ndarray, name: str, detection_snr: float, min_event_keep_snr: float, max_plot_points: int, envelope_mode_limit: float, smooth_n: int, global_noise: Optional[np.float32] = None) -> OscilloscopePlot
+```
+Create oscilloscope plot with all visualization elements.
+
+### `get_final_events`
+```python
+def get_final_events(state: Dict[str, Any]) -> np.ndarray
+```
+Extract and finalise the list of detected events from the state.
+
+### `initialize_state`
+```python
+def initialize_state(config: Dict[str, Any]) -> Dict[str, Any]
+```
+Initialise the state dictionary for processing.
+
+### `process_chunk`
+```python
+def process_chunk(data: Tuple[np.ndarray, np.ndarray], state: Dict[str, Any]) -> Dict[str, Any]
+```
+Process a single data chunk to find events.
+
+### `process_file`
+```python
+def process_file(name: str, sampling_interval: float, data_path: str, smooth_win_t: Optional[float] = None, smooth_win_f: Optional[float] = None, detection_snr: float = 3.0, min_event_keep_snr: float = 6.0, min_event_t: float = 0.75e-6, widen_frac: float = 10.0, signal_polarity: int = -1, max_plot_points: int = 10000, envelope_mode_limit: float = 10e-3, sidecar: Optional[str] = None, crop: Optional[List[int]] = None, yscale_mode: str = "snr", show_plots: bool = True, filter_type: str = "gaussian", filter_order: int = 2, chunk_size: Optional[int] = None) -> None
+```
+Process a single waveform file for event detection.
+
+### `EventPlotter`
+```python
+class EventPlotter:
+    def __init__(self, osc_plot: OscilloscopePlot, events: Optional[np.ndarray] = None, trace_idx: int = 0, bg_clean: Optional[np.ndarray] = None, global_noise: Optional[np.float32] = None, y_scale_mode: str = "raw")
+```
+Provides utility functions for plotting individual events or event grids.
+
+### `detect_events`
+```python
+def detect_events(time: np.ndarray, signal: np.ndarray, bg: np.ndarray, snr_threshold: np.float32 = np.float32(2.0), min_event_len: int = 20, min_event_amp: np.float32 = np.float32(0.0), widen_frac: np.float32 = np.float32(0.5), global_noise: Optional[np.float32] = None, signal_polarity: int = -1) -> Tuple[np.ndarray, np.float32]
+```
+Detect events in signal above background with specified thresholds.
+
+### `merge_overlapping_events`
+```python
+def merge_overlapping_events(events: np.ndarray) -> np.ndarray
+```
+Merge overlapping events.
+
+### `get_waveform_params`
+```python
+def get_waveform_params(bin_filename: str, data_path: Optional[str] = None, sidecar: Optional[str] = None) -> Dict[str, Any]
+```
+Parse XML sidecar file to extract waveform parameters.
+
+### `rd`
+```python
+def rd(filename: str, sampling_interval: Optional[float] = None, data_path: Optional[str] = None, sidecar: Optional[str] = None, crop: Optional[List[int]] = None) -> Tuple[np.ndarray, np.ndarray]
+```
+Read waveform binary file using sidecar XML for parameters.
+
+### `rd_chunked`
+```python
+def rd_chunked(filename: str, chunk_size: int, sampling_interval: Optional[float] = None, data_path: Optional[str] = None, sidecar: Optional[str] = None) -> Generator[Tuple[np.ndarray, np.ndarray], None, None]
+```
+Read waveform binary file in chunks using sidecar XML for parameters. This is a generator function that yields chunks of data.