Skip to main content

openreadout_blackrock/
lib.rs

1//! Reader for Blackrock Neurotech NSx continuous files (spec 2.1, 2.2/2.3, 3.0 including PTP)
2//! and NEV event files.
3//!
4//! Layout and vocabulary: `docs/formats/blackrock.md`. Provenance: `docs/provenance/blackrock.md`
5//! (Blackrock's public NEV/NSx specification LB-0023; Neo, BSD-3, read as documentation for
6//! spec 2.1). An NSx file is one trace whose sweeps are its data packets (recording pauses); a
7//! NEV file is one table of data packets (spikes with waveforms, digital events, comments).
8//!
9//! # Example
10//!
11//! Every reader implements [`openreadout_core::FormatReader`]: `descriptor`
12//! says what it reads, `sniff` recognises a file from its first bytes, and `open` returns a
13//! [`openreadout_core::Dataset`] with a header-only `info()` summary and lazy data
14//! access.
15//!
16//! ```
17//! use openreadout_core::FormatReader;
18//! use openreadout_blackrock::BlackrockReader;
19//!
20//! let format = BlackrockReader.descriptor();
21//! assert_eq!(format.id, openreadout_blackrock::FORMAT_ID);
22//! println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));
23//! ```
24//!
25//! Reading a file:
26//!
27//! ```no_run
28//! use std::path::Path;
29//!
30//! use openreadout_core::FormatReader;
31//! use openreadout_blackrock::BlackrockReader;
32//!
33//! let mut dataset = BlackrockReader.open(Path::new("session.ns5"))?;
34//! let info = dataset.info()?; // headers only
35//! let trace = &info.traces[0];
36//! println!("{} sweep(s) at {} Hz, {} channel(s)", trace.sweep_count, trace.sample_rate_hz, trace.channels.len());
37//! // The first 1000 samples of sweep 0, every channel, scaled to physical units.
38//! let samples = dataset.read_trace(0, 0, 0, 1000)?;
39//! for (channel, values) in trace.channels.iter().zip(&samples.channels) {
40//!     println!("{} ({}): {:?}", channel.name, channel.unit.as_deref().unwrap_or("?"), values.first());
41//! }
42//! # Ok::<(), openreadout_core::Error>(())
43//! ```
44//!
45//! Applications that accept any instrument file usually register every reader in an
46//! [`openreadout_core::Registry`] and let it detect the format; that is what the
47//! `openreadout` command-line tool does.
48//!
49//! # API stability
50//!
51//! The supported API is what this page documents. The parser modules are public only so that
52//! tests and fuzz targets can reach them: they are hidden from this documentation and may change
53//! in any release.
54#![forbid(unsafe_code)]
55#![warn(missing_docs)]
56
57mod assurance;
58#[doc(hidden)]
59pub mod dataset;
60#[doc(hidden)]
61pub mod nev;
62#[doc(hidden)]
63pub mod nsx;
64
65use std::path::Path;
66
67use openreadout_core::Result;
68use openreadout_core::model::{DetectConfidence, FormatDescriptor};
69use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
70use openreadout_core::source::Input;
71
72#[doc(hidden)]
73pub use dataset::{
74    KIND_COMMENT, KIND_DIGITAL, KIND_OTHER, KIND_SPIKE, MAX_COMMENTS, MAX_TABLE_READ, NevDataset,
75    NsxDataset,
76};
77#[doc(hidden)]
78pub use nev::{
79    COMMENT_PACKET, ExtHeader, MAX_ELECTRODE_ID, NEV_BASIC_LEN, NEV_EXT_LEN, NevFile, NevPacket,
80    WaveformHeader, nev_packet, parse_nev,
81};
82#[doc(hidden)]
83pub use nsx::{
84    BASIC_HEADER_LEN, CC_LEN, MAX_CHANNELS, NsxChannel, NsxFile, NsxPacket, NsxSpec, NsxSweep,
85    PERIOD_CLOCK_HZ, PTP_RESOLUTION, SPEC21_HEADER_LEN, cc_scaling, parse_nsx, spec21_factor,
86    spec21_label, systemtime,
87};
88
89/// Format id used on the command line and in JSON.
90pub const FORMAT_ID: &str = "blackrock";
91
92/// Extensions this reader opens.
93pub const EXTENSIONS: [&str; 7] = ["ns1", "ns2", "ns3", "ns4", "ns5", "ns6", "nev"];
94
95/// Leading bytes of the file kinds.
96pub const SIGNATURES: [&[u8; 8]; 5] = [
97    b"NEURALSG",
98    b"NEURALCD",
99    b"BRSMPGRP",
100    b"NEURALEV",
101    b"BREVENTS",
102];
103
104/// Files a Blackrock recording directory may hold besides NSx/NEV data: the Central
105/// configuration (`.ccf`), logs and notes.
106pub const SESSION_COMPANIONS: [&str; 6] = ["ccf", "txt", "log", "xml", "json", "md"];
107
108/// The NSx and NEV files of a Blackrock recording directory, or `None` when `dir` is not one
109/// (see [`openreadout_core::session::session_files`]).
110pub fn session_files(dir: &Path) -> Option<Vec<std::path::PathBuf>> {
111    session_files_in(&Input::local(dir))
112}
113
114fn session_files_in(input: &Input) -> Option<Vec<std::path::PathBuf>> {
115    let dir = input.path();
116    let fs = input.fs();
117    openreadout_core::session::session_files_in(
118        fs,
119        dir,
120        &|p| has_extension(p, &EXTENSIONS),
121        &SESSION_COMPANIONS,
122        0,
123    )
124}
125
126/// Open a Blackrock recording directory: each NSx file (`.ns1`–`.ns6`, one sampling group each)
127/// is a trace with its own rate and clock, each NEV file a table. Spec 2.1 NSx files take their
128/// scaling from the NEV of the same name, as when opened alone.
129pub fn open_session(dir: &Path) -> Result<openreadout_core::session::SessionDataset> {
130    open_session_input(&Input::local(dir))
131}
132
133fn open_session_input(input: &Input) -> Result<openreadout_core::session::SessionDataset> {
134    let dir = input.path();
135    let files = session_files_in(input).ok_or_else(|| {
136        openreadout_core::Error::unsupported(
137            FORMAT_ID,
138            "a directory that is not a Blackrock recording",
139            "A Blackrock session directory holds .ns1-.ns6 and .nev files (plus .ccf/logs); open a single file otherwise.",
140        )
141    })?;
142    let mut members = Vec::new();
143    for f in &files {
144        members.push(BlackrockReader.open_input(&input.with_path(f))?);
145    }
146    openreadout_core::session::SessionDataset::new(
147        FORMAT_ID,
148        dir,
149        members,
150        openreadout_core::session::Combine::Separate,
151    )
152}
153
154/// The Blackrock reader.
155#[derive(Debug, Default, Clone, Copy)]
156pub struct BlackrockReader;
157
158impl FormatReader for BlackrockReader {
159    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
160        Some(&assurance::BLACKROCK)
161    }
162
163    fn descriptor(&self) -> FormatDescriptor {
164        FormatDescriptor {
165            id: FORMAT_ID.into(),
166            name: "Blackrock NSx/NEV".into(),
167            vendor: "Blackrock Neurotech (Cerebus, NeuroPort)".into(),
168            extensions: EXTENSIONS.iter().map(|e| (*e).to_string()).collect(),
169            family: "electrophysiology".into(),
170            can_read: true,
171            can_write: false,
172            confidence: assurance::BLACKROCK.confidence,
173            known_gaps: vec![
174                "A recording directory is one session (each NSx file a trace, each NEV a table, clocks kept); NEV rows are not assigned to NSx sweeps".into(),
175                "NEV video-sync, tracking, button, configuration and log packets are counted (kind 3), not decoded; comment text is in `info --view full`".into(),
176                "Spec 2.1 NSx scaling needs the .nev with the same name next to it".into(),
177            ],
178        }
179    }
180
181    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
182        self.sniff_input(head, &Input::local(path))
183    }
184
185    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
186        let path = input.path();
187        if input.is_dir() {
188            let files = session_files_in(input)?;
189            let signed = files.iter().take(8).any(|f| {
190                let mut head = [0u8; 8];
191                input
192                    .fs()
193                    .open(f)
194                    .and_then(|mut h| std::io::Read::read(&mut h, &mut head))
195                    .is_ok_and(|n| n == 8 && SIGNATURES.iter().any(|s| head == **s))
196            });
197            return Some(Detection {
198                format_id: FORMAT_ID,
199                confidence: if signed {
200                    DetectConfidence::Definite
201                } else {
202                    DetectConfidence::Likely
203                },
204                note: Some("Blackrock recording directory (NSx + NEV, read as one session)".into()),
205            });
206        }
207        if head.len() >= 8 && SIGNATURES.iter().any(|s| &head[..8] == *s) {
208            return Some(Detection {
209                format_id: FORMAT_ID,
210                confidence: DetectConfidence::Definite,
211                note: None,
212            });
213        }
214        // a longer file without a signature is another kind of file (exit 3)
215        (has_extension(path, &EXTENSIONS) && head.len() < 8).then(|| Detection {
216            format_id: FORMAT_ID,
217            confidence: DetectConfidence::ExtensionOnly,
218            note: Some("Blackrock extension but no NSx/NEV signature at byte 0".into()),
219        })
220    }
221
222    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
223        self.open_input(&Input::local(path))
224    }
225
226    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
227        let path = input.path();
228        if input.is_dir() {
229            return Ok(Box::new(open_session_input(input)?));
230        }
231        let mut head = [0u8; 8];
232        let mut f = input.open()?;
233        let n = std::io::Read::read(&mut f, &mut head)
234            .map_err(|e| openreadout_core::Error::io(path, e))?;
235        if n == 8 && (&head == b"NEURALEV" || &head == b"BREVENTS") {
236            Ok(Box::new(NevDataset::open_input(input)?))
237        } else {
238            Ok(Box::new(NsxDataset::open_input(input)?))
239        }
240    }
241
242    fn reads_any_source(&self) -> bool {
243        true
244    }
245}