med64 0.0.2

Headless MED64 electrophysiology toolkit: .modat I/O, spike/burst analysis, assays, spike-rate maps, and CSV/HTML/SVG/HDF5 export
Documentation
//! Namespaced analysis entry points for the `burst_pipeline` facade.
//!
//! Thin wrappers around existing `crate::analysis` APIs so callers can use a
//! stable surface without duplicating algorithms.

use std::path::{Path, PathBuf};

use crate::analysis::{
    compute_asdr, compute_burst_result_table, detect_multi_channel_bursts,
    detect_single_channel_bursts, run_analysis, run_dose_series_report,
    write_native_analysis_log_with_options, AnalysisOptions, AnalysisReport, AsdrTrace,
    BurstResultTable, DoseSeriesReport, MultiChannelBurst, MultiChannelBurstOptions,
    NativeLogOptions, ResultTableOptions, SingleChannelBurst, SingleChannelBurstOptions,
    SpikeTrain,
};
use crate::error::Result;
use crate::export::{
    write_burst_detector_bundle_with_options, write_create_image_package_with_options,
    BurstDetectorBundleOptions, CreateImagePackageOptions,
};

#[cfg(feature = "histograms")]
use crate::analysis::{amplitude_histogram, isi_histogram, Histogram, HistogramOptions};
#[cfg(feature = "correlation")]
use crate::analysis::{
    burst_onset_correlogram, synchrony_index, BurstOnsetCorrelogram, ChannelSynchrony,
    CorrelationOptions,
};

/// Options for a full `burst_pipeline` pipeline run.
#[derive(Debug, Clone)]
pub struct BurstPipelineOptions {
    pub analysis: AnalysisOptions,
}

impl Default for BurstPipelineOptions {
    fn default() -> Self {
        Self { analysis: AnalysisOptions::reference() }
    }
}

/// Report alias kept for API clarity; currently wraps the full [`AnalysisReport`].
#[derive(Debug, Clone)]
pub struct BurstPipelineReport {
    pub analysis: AnalysisReport,
}

impl BurstPipelineReport {
    pub fn into_analysis(self) -> AnalysisReport {
        self.analysis
    }
}

/// Full analysis pipeline on a recording
/// (filter → spikes → single/multi bursts → ASDR → BOTCC → hist → result table).
pub fn run_burst_pipeline(
    path: impl AsRef<Path>,
    options: &BurstPipelineOptions,
) -> Result<AnalysisReport> {
    run_analysis(path, &options.analysis)
}

/// Detect spikes via the full analysis pipeline and return the spike train.
pub fn burst_pipeline_detect_spikes(
    path: impl AsRef<Path>,
    opts: &BurstPipelineOptions,
) -> Result<SpikeTrain> {
    Ok(run_burst_pipeline(path, opts)?.spikes)
}

/// Single-channel burst detection (`burst_pipeline` entry point).
pub fn burst_pipeline_single_channel_bursts(
    train: &SpikeTrain,
    opts: &SingleChannelBurstOptions,
) -> Vec<SingleChannelBurst> {
    detect_single_channel_bursts(train, opts)
}

/// Multi-channel bursts; `asdr` supplies duration when points are present.
pub fn burst_pipeline_multi_channel_bursts(
    train: &SpikeTrain,
    asdr: &AsdrTrace,
    opts: &MultiChannelBurstOptions,
) -> Vec<MultiChannelBurst> {
    let duration_ms = asdr
        .points
        .last()
        .map(|p| p.time_ms + opts.bin_width_ms)
        .filter(|d| *d > 0.0)
        .unwrap_or_else(|| {
            train.spikes.iter().map(|s| s.within_trace_time_ms).fold(0.0_f64, f64::max)
        });
    detect_multi_channel_bursts(train, duration_ms, opts)
}

/// Array spike detection rate (ASDR) + multi-channel bursts.
pub fn burst_pipeline_asdr(
    train: &SpikeTrain,
    trace_duration_ms: f64,
    opts: &MultiChannelBurstOptions,
) -> AsdrTrace {
    compute_asdr(train, trace_duration_ms, opts)
}

/// Burst-onset time cross-correlogram (BOTCC).
#[cfg(feature = "correlation")]
pub fn burst_pipeline_botcc(
    single_bursts: &[SingleChannelBurst],
    opts: &CorrelationOptions,
) -> BurstOnsetCorrelogram {
    burst_onset_correlogram(single_bursts, opts)
}

/// Pairwise synchrony index from single-channel bursts.
#[cfg(feature = "correlation")]
pub fn burst_pipeline_synchrony(
    single_bursts: &[SingleChannelBurst],
    opts: &CorrelationOptions,
) -> Vec<ChannelSynchrony> {
    synchrony_index(single_bursts, opts)
}

#[cfg(feature = "histograms")]
pub fn burst_pipeline_isi_histogram(train: &SpikeTrain, opts: &HistogramOptions) -> Histogram {
    isi_histogram(train, opts)
}

#[cfg(feature = "histograms")]
pub fn burst_pipeline_amplitude_histogram(
    train: &SpikeTrain,
    opts: &HistogramOptions,
) -> Histogram {
    amplitude_histogram(train, opts)
}

pub fn burst_pipeline_result_table(
    report: &AnalysisReport,
    opts: &ResultTableOptions,
) -> BurstResultTable {
    compute_burst_result_table(report, opts)
}

pub fn burst_pipeline_dose_series(
    dir: impl AsRef<Path>,
    opts: &AnalysisOptions,
) -> Result<DoseSeriesReport> {
    run_dose_series_report(dir, opts)
}

pub fn burst_pipeline_create_image(
    report: &AnalysisReport,
    dir: impl AsRef<Path>,
    stem: &str,
    opts: &CreateImagePackageOptions,
) -> Result<Vec<PathBuf>> {
    write_create_image_package_with_options(report, dir, stem, opts)
}

pub fn burst_pipeline_export_bundle(
    report: &AnalysisReport,
    dir: impl AsRef<Path>,
    opts: &BurstDetectorBundleOptions,
) -> Result<Vec<PathBuf>> {
    write_burst_detector_bundle_with_options(report, dir, opts)
}

pub fn burst_pipeline_native_log(
    report: &AnalysisReport,
    dir: impl AsRef<Path>,
    opts: &NativeLogOptions,
) -> Result<()> {
    write_native_analysis_log_with_options(report, &AnalysisOptions::reference(), dir, opts)?;
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::analysis::{MultiChannelBurstOptions, SingleChannelBurstOptions, SpikeTrain};

    #[test]
    fn burst_pipeline_wrappers_empty_train() {
        let train = SpikeTrain::default();
        let single =
            burst_pipeline_single_channel_bursts(&train, &SingleChannelBurstOptions::default());
        assert!(single.is_empty());
        let asdr = burst_pipeline_asdr(&train, 1000.0, &MultiChannelBurstOptions::default());
        assert!(asdr.bursts.is_empty());
        let multi = burst_pipeline_multi_channel_bursts(
            &train,
            &asdr,
            &MultiChannelBurstOptions::default(),
        );
        assert!(multi.is_empty());
    }
}