use openreadout_core::model::{FileInfo, TraceInfo};
use openreadout_core::reader::Dataset;
use openreadout_core::{Error, Result};
use openreadout_figure::{
Anchor, AxesSpec, Baseline, Domain, Face, Figure, GridLines, LabelPlacer, Layer, Panel, Path,
Rect, Stroke, TextStyle, Theme, format_value,
};
use crate::color::to_hex;
use crate::marks::{self, Col};
use crate::{
DataMark, Frame, FramePanel, Marks, PreviewOutput, PreviewRequest, TracePreview,
TracePreviewChannel, XAxis,
};
const DEFAULT_CHANNELS: usize = 8;
pub const MAX_TRACE_PREVIEW_SAMPLES: u64 = 20_000_000;
const BATCH_VALUES: u64 = 1 << 23;
const MAX_SPIKE_SAMPLES: u64 = 10_000_000;
const PEAK_FAMILIES: [&str; 6] = [
"spectroscopy",
"chromatography",
"mass-spectrometry",
"nmr",
"diffraction",
"epr",
];
fn find_trace(info: &FileInfo, ti: u32) -> Result<TraceInfo> {
info.traces
.iter()
.find(|t| t.index == ti)
.cloned()
.ok_or_else(|| {
if info.traces.is_empty() && !info.images.is_empty() {
Error::unsupported(
"preview",
format!("trace preview of a {} file", info.format.name),
"This file holds images, not traces. Pick image channels with a selection such as `c=0-2` (`select` in MCP, `--select` on the command line) instead of `channels` or `--channel`, which pick trace channels.",
)
} else if info.traces.is_empty() {
Error::unsupported(
"preview",
format!("trace preview of a {} file", info.format.name),
"This file holds no traces; see `openreadout info` for what it contains.",
)
} else {
Error::Usage(format!(
"trace {ti} out of range (file has {} traces)",
info.traces.len()
))
}
})
}
fn x_channel(t: &TraceInfo) -> Option<u32> {
t.extra
.get("axis")
.filter(|a| a.get("irregular").and_then(serde_json::Value::as_bool) == Some(true))
.and_then(|a| a.get("channel"))
.and_then(serde_json::Value::as_u64)
.and_then(|c| u32::try_from(c).ok())
}
fn wants_peaks(info: &FileInfo, ax: &XAxis, marks: Marks) -> bool {
match marks {
Marks::Peaks => true,
Marks::Auto => {
let family = info.format.family.as_str();
match ax.quantity.as_str() {
"time" => family == "chromatography" || family == "mass-spectrometry",
"sample" | "cycle" | "temperature" => false,
_ => PEAK_FAMILIES.contains(&family),
}
}
_ => false,
}
}
pub(crate) fn axis_title(ax: &XAxis) -> String {
let q = ax.quantity.replace('_', " ");
if ax.unit.is_empty() {
q
} else if q == "mz" {
"m/z".into()
} else {
format!("{q} ({})", ax.unit)
}
}
fn channel_title(name: &str, unit: Option<&str>) -> String {
let name: String = name.chars().take(48).collect();
match unit.map(str::trim).filter(|u| !u.is_empty()) {
Some(u) => format!("{name} ({u})"),
None => name,
}
}
pub(crate) fn render(
ds: &mut dyn Dataset,
info: &FileInfo,
req: &PreviewRequest,
out: &mut PreviewOutput,
) -> Result<(Figure, Frame)> {
let ti = req.trace.unwrap_or_else(|| {
info.traces
.iter()
.find(|t| {
t.extra
.get("axis")
.and_then(|a| a.get("unit"))
.and_then(serde_json::Value::as_str)
.is_some_and(|u| u.contains("ppm"))
})
.map_or(0, |t| t.index)
});
let sweep = req.sweep.unwrap_or(0);
let t = find_trace(info, ti)?;
if sweep >= t.sweep_count {
return Err(Error::Usage(format!(
"sweep {sweep} out of range (trace {ti} has {} sweeps, 0..{})",
t.sweep_count, t.sweep_count
)));
}
if t.extra.get("plot").and_then(serde_json::Value::as_str) == Some("overlay") {
return crate::overlay::render(ds, &t, sweep, req, out);
}
let nch = t.channels.len();
if nch == 0 {
return Err(Error::Usage(format!("trace {ti} has no channels")));
}
let xch = x_channel(&t).filter(|c| (*c as usize) < nch && nch > 1);
let real_only = t.extra.get("kind").and_then(serde_json::Value::as_str)
== Some("processed_spectrum")
&& t.channels.iter().any(|c| c.name == "imag");
let channels: Vec<u32> = if req.channels.is_empty() && real_only {
out.notes
.push("showing the real part; channels=[1] shows the imaginary part".into());
vec![0]
} else if req.channels.is_empty() {
let signal: Vec<u32> = (0..nch as u32).filter(|c| xch != Some(*c)).collect();
if signal.len() > DEFAULT_CHANNELS {
out.notes.push(format!(
"showing the first {DEFAULT_CHANNELS} of {nch} channels; pass channels to choose"
));
}
signal.into_iter().take(DEFAULT_CHANNELS).collect()
} else {
for &c in &req.channels {
if c as usize >= nch {
return Err(Error::Usage(format!(
"channel {c} out of range (trace {ti} has {nch} channels)"
)));
}
}
let mut seen = std::collections::HashSet::new();
req.channels
.iter()
.copied()
.filter(|c| seen.insert(*c))
.collect()
};
let sweep_len = openreadout_core::trace::sweep_samples(&t, sweep);
let n = sweep_len.min(MAX_TRACE_PREVIEW_SAMPLES);
let mut ax = x_axis(&t, sweep_len, n);
let theme = crate::theme(req);
let width = req.max_size.max(64);
let ncols = width as usize;
let step = if n > 1 {
(ax.last - ax.first) / (n - 1) as f64
} else {
0.0
};
let mut cols: Vec<Vec<Option<Col>>> = vec![vec![None; ncols]; channels.len()];
let spike_ch: Option<(usize, f64)> = (req.marks == Marks::Spikes)
.then(|| {
channels.iter().enumerate().find_map(|(k, &c)| {
openreadout_signal::ephys::to_mv(t.channels[c as usize].unit.as_deref())
.map(|f| (k, f))
})
})
.flatten();
if req.marks == Marks::Spikes && spike_ch.is_none() {
out.notes.push(
"marks=spikes needs a voltage channel (mV or V); none is drawn, so no spikes were marked".into(),
);
}
let keep_spike = spike_ch.filter(|_| n <= MAX_SPIKE_SAMPLES);
if spike_ch.is_some() && keep_spike.is_none() {
out.notes.push(format!(
"spikes are marked on sweeps of at most {MAX_SPIKE_SAMPLES} samples; use openreadout_ephys_features for longer ones"
));
}
let mut volts: Vec<f64> = Vec::new();
let mut xs: Option<Vec<f64>> = None;
if let Some(xc) = xch {
let tr = openreadout_core::trace::read_channels(ds, ti, sweep, 0, n, &[xc])?;
xs = tr.into_iter().next();
}
if let (Some(v), Some(xc)) = (&xs, xch) {
let first = v.iter().copied().find(|x| x.is_finite());
let last = v.iter().rev().copied().find(|x| x.is_finite());
if let (Some(first), Some(last)) = (first, last) {
let a = t.extra.get("axis");
let txt = |k: &str| {
a.and_then(|a| a.get(k))
.and_then(serde_json::Value::as_str)
.map(str::to_string)
};
let xc_info = &t.channels[xc as usize];
ax = XAxis {
quantity: txt("quantity").unwrap_or_else(|| xc_info.name.clone()),
unit: txt("unit")
.or_else(|| xc_info.unit.clone())
.unwrap_or_default(),
first,
last,
};
}
}
let (x_lo, x_hi) = match &xs {
Some(v) => v
.iter()
.copied()
.filter(|x| x.is_finite())
.fold((f64::INFINITY, f64::NEG_INFINITY), |(a, b), x| {
(a.min(x), b.max(x))
}),
None => (ax.first.min(ax.last), ax.first.max(ax.last)),
};
let first_x = ax.first;
let (x_lo, x_hi) = match req.x_range {
Some([a, b]) => {
let (a, b) = (a.min(b).max(x_lo), a.max(b).min(x_hi));
if b <= a || b.is_nan() || a.is_nan() {
return Err(Error::Usage(format!(
"x_range does not overlap the trace's axis ({} to {})",
fmt_num(x_lo),
fmt_num(x_hi)
)));
}
if ax.last < ax.first {
(ax.first, ax.last) = (b, a);
} else {
(ax.first, ax.last) = (a, b);
}
(a, b)
}
None => (x_lo, x_hi),
};
let col_of = |x: f64| -> usize {
let span = x_hi - x_lo;
let t = if span > 0.0 { (x - x_lo) / span } else { 0.5 };
((t * ncols as f64) as usize).min(ncols - 1)
};
let batch = (BATCH_VALUES / nch as u64).clamp(4096, 1 << 20);
let mut pos = 0u64;
while pos < n {
let want = batch.min(n - pos);
let tr = ds.read_trace(ti, sweep, pos, want)?;
let got = tr.channels.first().map_or(0, Vec::len) as u64;
for (k, &c) in channels.iter().enumerate() {
let data = tr
.channels
.get(c as usize)
.ok_or_else(|| Error::Other(format!("reader returned no channel {c}")))?;
for (i, &v) in data.iter().enumerate() {
let si = pos + i as u64;
if keep_spike.is_some_and(|(sk, _)| sk == k) {
volts.push(v);
}
if !v.is_finite() {
continue;
}
let x = match &xs {
Some(xv) => match xv.get(si as usize) {
Some(&x) if x.is_finite() => x,
_ => continue,
},
None => first_x + step * si as f64,
};
if x < x_lo || x > x_hi {
continue;
}
let slot = &mut cols[k][col_of(x)];
match slot {
None => *slot = Some(Col::new(x, v)),
Some(c) => c.add(x, v),
}
}
}
if got == 0 {
break;
}
pos += got;
}
let drawn = pos.min(n);
if drawn < sweep_len {
out.notes.push(format!(
"drew the first {drawn} of {sweep_len} samples of the sweep"
));
}
let peaks_on = wants_peaks(info, &ax, req.marks);
let nc = channels.len();
let fs = theme.font_size;
let name = t.name.clone().unwrap_or_else(|| format!("trace {ti}"));
let one_title = nc == 1 && t.channels[channels[0] as usize].name == name;
let caption = (t.sweep_count > 1 || !one_title).then(|| {
if t.sweep_count > 1 {
format!("{name} · sweep {sweep} of {}", t.sweep_count)
} else {
name.clone()
}
});
let header = if caption.is_some() {
fs * 1.9
} else {
fs * 0.3
};
let title_h = fs * 1.9;
let gap = fs * 0.9;
let x_axis_h = fs * 3.4;
let w = width as f32;
let max_h = req.max_size as f32;
let panel_h = if nc == 1 {
(w * 0.42).clamp(110.0, 520.0)
} else {
((w * 0.62) / nc as f32).clamp(70.0, 260.0)
};
let fit_h = ((max_h - header - x_axis_h - (title_h + gap) * nc as f32) / nc as f32).max(24.0);
let panel_h = panel_h.min(fit_h);
let height = header + nc as f32 * (title_h + panel_h + gap) - gap + x_axis_h;
let mut fig = Figure::new(w, height.ceil(), Some(theme.paper));
let reversed = ax.last < ax.first;
let x_dom = {
let d = Domain::linear(x_lo, x_hi);
if reversed { d.reversed() } else { d }
};
let y_doms: Vec<Domain> = cols
.iter()
.map(|cs| {
let lo = cs
.iter()
.flatten()
.map(|c| c.min)
.fold(f64::INFINITY, f64::min);
let hi = cs
.iter()
.flatten()
.map(|c| c.max)
.fold(f64::NEG_INFINITY, f64::max);
let mut d = Domain::of([lo, hi], 0.06, openreadout_figure::ScaleKind::Linear);
if peaks_on {
d.hi += (d.hi - d.lo) * 0.12;
}
d
})
.collect();
let probe_specs: Vec<AxesSpec> = (0..nc).map(|_| AxesSpec::default()).collect();
let left_w = y_doms
.iter()
.zip(&probe_specs)
.map(|(d, s)| {
let p = Panel::fit(Rect::new(0.0, 0.0, 400.0, panel_h), x_dom, *d, &theme, s);
p.rect.x
})
.fold(0.0f32, f32::max);
if let Some(c) = &caption {
let cap_style = TextStyle::new(fs, theme.ink).align(Anchor::Start, Baseline::Alphabetic);
fig.group(Layer::Caption, "caption", |fig| {
fig.text(fs * 0.8, fs * 1.4, c, &cap_style);
});
}
let mut report = Vec::new();
let mut panels = Vec::new();
let mut placer = LabelPlacer::new(fig.rect());
let mut data_marks: Vec<DataMark> = Vec::new();
for (k, &c) in channels.iter().enumerate() {
let ch = &t.channels[c as usize];
let top = header + k as f32 * (title_h + panel_h + gap) + title_h;
let last = k + 1 == nc;
let rect = Rect::new(
left_w + fs * 0.8,
top,
w - left_w - fs * 0.8 - fs * 1.6,
panel_h,
);
let panel = Panel::new(rect, x_dom, y_doms[k]);
let spec = AxesSpec {
y_label: Some(channel_title(&ch.name, ch.unit.as_deref())),
x_label: last.then(|| axis_title(&ax)),
show_x: last,
grid: GridLines::Y,
..AxesSpec::default()
};
let (ylo, yhi) = panel.y.domain();
let color = if nc == 1 { theme.ink } else { theme.series(k) };
fig.group(Layer::Panel, &ch.name, |fig| {
if !last {
fig.line(
rect.x,
rect.bottom(),
rect.right(),
rect.bottom(),
Stroke::new(theme.grid, theme.hairline()),
);
}
panel.axes(fig, &theme, &spec);
if ylo < 0.0 && yhi > 0.0 {
panel.rule_y(fig, 0.0, Stroke::new(theme.rule, theme.hairline()));
}
let pts = envelope_points(&cols[k], &panel);
fig.group(Layer::Series, &ch.name, |fig| {
panel.line_px(fig, pts, Stroke::new(color, theme.line_width * 0.85));
});
if peaks_on {
let resolution = (x_hi - x_lo).abs() / f64::from(rect.w.max(1.0));
let dec = marks::decimals_for(resolution);
let min_gap = (fs * 3.5 / (rect.w / ncols as f32).max(0.01)) as usize;
let idx = marks::prominent(&cols[k], marks::MAX_PEAKS, min_gap.max(1), 0.04);
let peaks: Vec<(f64, f64, String)> = idx
.iter()
.filter_map(|&i| cols[k][i])
.map(|c| (c.x_at_max, c.max, marks::peak_label(c.x_at_max, dec)))
.collect();
data_marks.extend(marks::label_peaks(
fig,
&panel,
&theme,
&peaks,
Some(c),
&mut placer,
));
}
if let Some((sk, factor)) = keep_spike
&& sk == k
{
data_marks.extend(spikes(
fig,
&panel,
&theme,
&volts,
factor,
&t,
sweep,
&ax,
c,
&mut out.notes,
));
}
});
report.push(TracePreviewChannel {
index: c,
name: ch.name.clone(),
unit: ch.unit.clone(),
color: to_hex(color.to_rgb()),
min: Some(ylo),
max: Some(yhi),
});
panels.push(FramePanel {
channel: Some(c),
..FramePanel::new(panel)
});
}
out.marks = data_marks;
out.trace = Some(TracePreview {
trace: ti,
sweep,
sample_rate_hz: t.sample_rate_hz,
sweep_sample_count: sweep_len,
sample_count: drawn,
truncated: drawn < sweep_len,
x_axis: Some(ax),
channels: report,
});
Ok((fig, Frame::plots_labelled(panels, placer.taken())))
}
pub(crate) fn envelope_points(cols: &[Option<Col>], panel: &Panel) -> Vec<(f32, f32)> {
let mut pts = Vec::with_capacity(cols.len() * 4);
for c in cols.iter().flatten() {
let Some(px) = panel.x.px(c.x_at_max) else {
continue;
};
let py = |v: f64| panel.y.px(v).unwrap_or(f32::NAN);
pts.push((px, py(c.first)));
if c.min < c.max {
pts.push((px, py(c.min)));
pts.push((px, py(c.max)));
}
pts.push((px, py(c.last)));
}
pts
}
#[allow(clippy::too_many_arguments)]
fn spikes(
fig: &mut Figure,
panel: &Panel,
theme: &Theme,
volts: &[f64],
factor: f64,
t: &TraceInfo,
sweep: u32,
ax: &XAxis,
channel: u32,
notes: &mut Vec<String>,
) -> Vec<DataMark> {
let mv: Vec<f64> = volts.iter().map(|v| v * factor).collect();
let fs_hz = t.sample_rate_hz;
let found = openreadout_signal::ephys::ap::detect(
&mv,
fs_hz,
0,
mv.len(),
sweep,
&openreadout_signal::ephys::ApSettings::default(),
);
let to_axis = |s: f64| if ax.unit == "min" { s / 60.0 } else { s };
let start = t.start_s.unwrap_or(0.0);
fig.group(Layer::Annotation, "action potentials", |fig| {
let size = theme.font_size * 0.55;
let mut out = Vec::new();
for s in &found {
let x = to_axis(start + s.peak_time_s);
let y = s.peak_mv / factor;
if let Some((px, py)) = panel.pt(x, y) {
let ty = (py - size * 0.6).max(panel.rect.y + size);
fig.fill(
Path::polygon([
(px, ty),
(px - size * 0.5, ty - size * 0.85),
(px + size * 0.5, ty - size * 0.85),
]),
theme.accent,
);
}
out.push(DataMark {
kind: "spike".into(),
x,
y,
label: None,
channel: Some(channel),
});
}
let text = match found.len() {
0 => "no action potentials (−20 mV crossings)".to_string(),
1 => "1 action potential".to_string(),
n => format!("{n} action potentials"),
};
let st = TextStyle::new(theme.small_size(), theme.accent)
.face(Face::SansMedium)
.align(Anchor::End, Baseline::Alphabetic);
fig.text(
panel.rect.right(),
panel.rect.y - theme.font_size * 0.75,
&text,
&st,
);
notes.push(format!(
"{text}: action potentials are upward crossings of −20 mV (as openreadout_ephys_features counts them)"
));
out
})
}
pub(crate) fn x_axis(t: &TraceInfo, sweep_len: u64, drawn: u64) -> XAxis {
let last_i = drawn.saturating_sub(1) as f64;
if let Some(a) = t.extra.get("axis") {
let num = |k: &str| a.get(k).and_then(serde_json::Value::as_f64);
let first = num("first");
let step = num("step").or_else(|| {
let (f, l) = (num("first")?, num("last")?);
(sweep_len > 1).then(|| (l - f) / (sweep_len - 1) as f64)
});
if let (Some(first), Some(step)) = (first, step) {
return XAxis {
quantity: a
.get("quantity")
.and_then(|v| v.as_str())
.unwrap_or("x")
.into(),
unit: a.get("unit").and_then(|v| v.as_str()).unwrap_or("").into(),
first,
last: first + step * last_i,
};
}
}
if t.sample_rate_hz > 0.0 && t.sample_rate_hz.is_finite() {
let start = t.start_s.unwrap_or(0.0);
let end = start + last_i / t.sample_rate_hz;
if end - start > 300.0 {
return XAxis {
quantity: "time".into(),
unit: "min".into(),
first: start / 60.0,
last: end / 60.0,
};
}
return XAxis {
quantity: "time".into(),
unit: "s".into(),
first: start,
last: end,
};
}
XAxis {
quantity: "sample".into(),
unit: String::new(),
first: 0.0,
last: last_i,
}
}
pub(crate) fn fmt_num(v: f64) -> String {
format_value(v)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn numbers_are_short() {
assert_eq!(fmt_num(0.0), "0");
assert_eq!(fmt_num(12.3456), "12.35");
assert_eq!(fmt_num(1234.6), "1235");
assert_eq!(fmt_num(-0.5), "-0.5");
assert_eq!(fmt_num(2e7), "2e7");
let ax = XAxis {
quantity: "chemical_shift".into(),
unit: "ppm".into(),
first: 10.0,
last: 0.0,
};
assert_eq!(axis_title(&ax), "chemical shift (ppm)");
assert_eq!(channel_title("Vm", Some("mV")), "Vm (mV)");
}
}