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
//! Connectivity package — Network Connectivity Graph
//! (detect → timestamp CSV → connection map → gap histogram).

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

use serde::{Deserialize, Serialize};

use crate::analysis::{run_analysis, AnalysisOptions, AnalysisReport};
use crate::error::{Med64Error, Result};
use crate::toolkit::connection_map::{
    connection_map, write_connection_map_package, ConnectionMapOptions,
};
use crate::toolkit::connectivity::ConnectivityOptions;
use crate::toolkit::pdm_detector::{
    write_pdm_timestamp_package, PdmDetectorOptions, PdmTimestampMode, PdmTimestampVariant,
};

#[derive(Debug, Clone)]
pub struct ConnectivityPackageOptions {
    pub analysis: AnalysisOptions,
    pub timestamps: PdmDetectorOptions,
    pub connectivity: ConnectivityOptions,
    pub connection_map: ConnectionMapOptions,
    /// Gap-histogram bin width (ms) for `Timestampcount`-style export.
    pub gap_bin_ms: f64,
    pub gap_start_ms: Option<f64>,
    pub gap_end_ms: Option<f64>,
    pub name: String,
}

impl Default for ConnectivityPackageOptions {
    fn default() -> Self {
        Self {
            analysis: AnalysisOptions { max_blocks: Some(10), ..AnalysisOptions::default() },
            timestamps: PdmDetectorOptions {
                mode: PdmTimestampMode::All,
                variant: PdmTimestampVariant::Modat,
                name: "Timestamp".into(),
                ..PdmDetectorOptions::default()
            },
            connectivity: ConnectivityOptions::default(),
            connection_map: ConnectionMapOptions::default(),
            gap_bin_ms: 1.0,
            gap_start_ms: None,
            gap_end_ms: None,
            name: "connectivity".into(),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GapHistBin {
    pub bin_start_ms: f64,
    pub bin_end_ms: f64,
    pub cluster_id: u32,
    pub count: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConnectivityPackageReport {
    pub path: PathBuf,
    pub spike_count: usize,
    pub edge_count: usize,
    pub outputs: Vec<PathBuf>,
}

/// Build gap histogram of consecutive within-channel ISIs (`Timestampcount` style).
pub fn gap_histogram_from_report(
    report: &AnalysisReport,
    bin_ms: f64,
    start_ms: Option<f64>,
    end_ms: Option<f64>,
) -> Vec<GapHistBin> {
    let bin = bin_ms.max(1e-9);
    let mut gaps: Vec<f64> = Vec::new();
    let by = report.spikes.by_channel();
    for (_ch, spikes) in by {
        let mut times: Vec<f64> = spikes
            .iter()
            .map(|s| s.within_session_time_ms)
            .filter(|&t| {
                start_ms.map(|a| t >= a).unwrap_or(true) && end_ms.map(|b| t <= b).unwrap_or(true)
            })
            .collect();
        times.sort_by(|a, b| a.partial_cmp(b).unwrap());
        for w in times.windows(2) {
            let gap = w[1] - w[0];
            if gap > 0.0 {
                gaps.push(gap);
            }
        }
    }
    if gaps.is_empty() {
        return Vec::new();
    }
    let max_gap = gaps.iter().copied().fold(0.0_f64, f64::max);
    let n_bins = ((max_gap / bin).floor() as usize) + 1;
    let mut counts = vec![0u64; n_bins];
    for g in gaps {
        let idx = (g / bin).floor() as usize;
        if idx < counts.len() {
            counts[idx] += 1;
        }
    }
    counts
        .into_iter()
        .enumerate()
        .filter(|(_, c)| *c > 0)
        .map(|(i, count)| GapHistBin {
            bin_start_ms: i as f64 * bin,
            bin_end_ms: (i + 1) as f64 * bin,
            cluster_id: 0,
            count,
        })
        .collect()
}

pub fn write_gap_histogram_csv(bins: &[GapHistBin], path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut out = String::from("bin_start_ms,bin_end_ms,cluster_id,count\n");
    for b in bins {
        out.push_str(&format!(
            "{:.6},{:.6},{},{}\n",
            b.bin_start_ms, b.bin_end_ms, b.cluster_id, b.count
        ));
    }
    std::fs::write(path, out)
        .map_err(|source| Med64Error::WriteIo { path: path.to_path_buf(), source })
}

pub fn run_connectivity_package(
    path: impl AsRef<Path>,
    out_dir: impl AsRef<Path>,
    options: &ConnectivityPackageOptions,
) -> Result<ConnectivityPackageReport> {
    let path = path.as_ref();
    let dir = out_dir.as_ref();
    std::fs::create_dir_all(dir)
        .map_err(|source| Med64Error::WriteIo { path: dir.to_path_buf(), source })?;

    let report = run_analysis(path, &options.analysis)?;

    let mut ts_opts = options.timestamps.clone();
    ts_opts.analysis = options.analysis.clone();
    let mut outputs = write_pdm_timestamp_package(&report, dir, &ts_opts)?;

    let mut cmap_opts = options.connection_map.clone();
    cmap_opts.connectivity = options.connectivity.clone();
    let cmap = connection_map(&report.spikes, &cmap_opts);
    let cmap_outs = write_connection_map_package(&cmap, &cmap_opts, dir)?;
    outputs.extend(cmap_outs);

    let gaps = gap_histogram_from_report(
        &report,
        options.gap_bin_ms,
        options.gap_start_ms,
        options.gap_end_ms,
    );
    let gap_path = dir.join("gap_histogram.csv");
    write_gap_histogram_csv(&gaps, &gap_path)?;
    outputs.push(gap_path);

    let manifest = dir.join("connectivity_manifest.json");
    let body = serde_json::json!({
        "source": path.display().to_string(),
        "name": options.name,
        "spike_count": report.spikes.spikes.len(),
        "edge_count": cmap.edges.len(),
        "gap_bins": gaps.len(),
        "files": outputs.iter().map(|p| p.display().to_string()).collect::<Vec<_>>(),
    });
    std::fs::write(&manifest, serde_json::to_string_pretty(&body).unwrap())
        .map_err(|source| Med64Error::WriteIo { path: manifest.clone(), source })?;
    outputs.push(manifest);

    Ok(ConnectivityPackageReport {
        path: path.to_path_buf(),
        spike_count: report.spikes.spikes.len(),
        edge_count: cmap.edges.len(),
        outputs,
    })
}