Skip to main content

openreadout_neuralynx/
lib.rs

1//! Reader for Neuralynx Cheetah/Pegasus files: NCS continuous channels, NEV events, and
2//! NSE/NST/NTT spike waveforms.
3//!
4//! Layout and vocabulary: `docs/formats/neuralynx.md`. Provenance: `docs/provenance/neuralynx.md`
5//! (Neuralynx's public "Data File Formats" document; Neo, BSD-3, read as documentation). Every
6//! file is a 16 KiB text header followed by fixed-size records. An NCS file is one trace whose
7//! sweeps are its gap-free segments; event and spike files are tables.
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_neuralynx::NeuralynxReader;
19//!
20//! let format = NeuralynxReader.descriptor();
21//! assert_eq!(format.id, openreadout_neuralynx::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_neuralynx::NeuralynxReader;
32//!
33//! let mut dataset = NeuralynxReader.open(Path::new("CSC1.ncs"))?;
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 header;
62#[doc(hidden)]
63pub mod records;
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::{MAX_LABELS, MAX_TABLE_READ, NeuralynxDataset};
74#[doc(hidden)]
75pub use header::{HEADER_LEN, HEADER_MAGIC, HeaderEntry, TextHeader, decode_text, parse_header};
76#[doc(hidden)]
77pub use records::{
78    ContinuousIndex, EventRecord, FileKind, NCS_RECORD_LEN, NCS_SAMPLES, NEV_RECORD_LEN,
79    NVT_POINTS, NVT_RECORD_LEN, NVT_RECORD_START, NVT_TARGETS, RecordHead, SPIKE_FEATURES,
80    SPIKE_PREFIX_LEN, SPIKE_SAMPLES, Segment, SpikeRecord, VideoRecord, event_record,
81    index_continuous, record_head, segments_from, spike_record, video_record,
82};
83
84/// Format id used on the command line and in JSON.
85pub const FORMAT_ID: &str = "neuralynx";
86
87/// Extensions this reader opens.
88pub const EXTENSIONS: [&str; 6] = ["ncs", "nev", "nse", "nst", "ntt", "nvt"];
89
90/// Files next to the recording that a session directory may hold besides the data files: logs,
91/// settings, and the raw-data files this reader does not decode.
92pub const SESSION_COMPANIONS: [&str; 8] = ["txt", "log", "cfg", "xml", "ini", "json", "md", "nrd"];
93
94/// The data files of a Neuralynx recording directory, or `None` when `dir` is not one (see
95/// [`openreadout_core::session::session_files`]). Continuous files holding only the text header
96/// (no records) are left out.
97pub fn session_files(dir: &Path) -> Option<Vec<std::path::PathBuf>> {
98    session_files_in(&Input::local(dir))
99}
100
101fn session_files_in(input: &Input) -> Option<Vec<std::path::PathBuf>> {
102    let dir = input.path();
103    let fs = input.fs();
104    let files = openreadout_core::session::session_files_in(
105        fs,
106        dir,
107        &|p| has_extension(p, &EXTENSIONS),
108        &SESSION_COMPANIONS,
109        0,
110    )?;
111    let kept: Vec<_> = files
112        .into_iter()
113        .filter(|p| {
114            !has_extension(p, &["ncs"]) || fs.metadata(p).is_ok_and(|m| m.len() > HEADER_LEN)
115        })
116        .collect();
117    (!kept.is_empty()).then_some(kept)
118}
119
120/// Open a Neuralynx recording directory: every `.ncs` channel on the same sample grid (rate,
121/// segments and their start stamps) joins one multi-channel trace, and each `.nev` / `.nse` /
122/// `.nst` / `.ntt` file is a table.
123pub fn open_session(dir: &Path) -> Result<openreadout_core::session::SessionDataset> {
124    open_session_input(&Input::local(dir))
125}
126
127fn open_session_input(input: &Input) -> Result<openreadout_core::session::SessionDataset> {
128    let dir = input.path();
129    let files = session_files_in(input).ok_or_else(|| {
130        openreadout_core::Error::unsupported(
131            FORMAT_ID,
132            "a directory that is not a Neuralynx recording",
133            "A Neuralynx session directory holds .ncs/.nev/.nse/.nst/.ntt files (plus logs); open a single file otherwise.",
134        )
135    })?;
136    let mut members: Vec<Box<dyn Dataset>> = Vec::new();
137    for f in &files {
138        members.push(Box::new(NeuralynxDataset::open_input(&input.with_path(f))?));
139    }
140    let mut s = openreadout_core::session::SessionDataset::new(
141        FORMAT_ID,
142        dir,
143        members,
144        openreadout_core::session::Combine::SameGrid,
145    )?;
146    for t in &mut s.info_mut().traces {
147        if t.channels.len() > 1 {
148            t.name = Some(format!("continuous_{}Hz", t.sample_rate_hz));
149        }
150    }
151    Ok(s)
152}
153
154/// The Neuralynx reader.
155#[derive(Debug, Default, Clone, Copy)]
156pub struct NeuralynxReader;
157
158/// True when the head looks like a Neuralynx text header: the header line, or `-FileType` /
159/// `-RecordSize` / `NLX_Base_Class` keys in the first kilobytes.
160pub fn looks_like_neuralynx(head: &[u8]) -> bool {
161    let n = head.len().min(4096);
162    let text = decode_text(&head[..n]);
163    text.trim_start().starts_with(HEADER_MAGIC)
164}
165
166fn has_header_keys(head: &[u8]) -> bool {
167    let n = head.len().min(4096);
168    let text = decode_text(&head[..n]);
169    [
170        "-RecordSize",
171        "-FileType",
172        "NLX_Base_Class_Type",
173        "-ADBitVolts",
174    ]
175    .iter()
176    .any(|k| text.contains(k))
177}
178
179impl FormatReader for NeuralynxReader {
180    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
181        Some(&assurance::NEURALYNX)
182    }
183
184    fn descriptor(&self) -> FormatDescriptor {
185        FormatDescriptor {
186            id: FORMAT_ID.into(),
187            name: "Neuralynx (NCS/NEV/NSE/NTT)".into(),
188            vendor: "Neuralynx (Cheetah, Pegasus)".into(),
189            extensions: EXTENSIONS.iter().map(|e| (*e).to_string()).collect(),
190            family: "electrophysiology".into(),
191            can_read: true,
192            can_write: false,
193            confidence: assurance::NEURALYNX.confidence,
194            known_gaps: vec![
195                "A recording directory is one session: channels on different sample grids (rate, segment boundaries) are separate traces, never resampled; event and spike files are separate tables".into(),
196                "Raw data (.nrd) files are not read; video-tracker (.nvt) records give the extracted position, angle and target count, not the colour-transition points or target bitfields".into(),
197                "Sampling rate is the header value; when timestamps imply another rate (pre-Cheetah-5 1 MHz clock) it is reported in extra.timestamp_rate_hz, not applied".into(),
198            ],
199        }
200    }
201
202    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
203        self.sniff_input(head, &Input::local(path))
204    }
205
206    fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
207        let path = input.path();
208        if input.is_dir() {
209            let files = session_files_in(input)?;
210            let signed = files.iter().take(8).any(|f| {
211                let mut head = [0u8; 1024];
212                input
213                    .fs()
214                    .open(f)
215                    .and_then(|mut h| std::io::Read::read(&mut h, &mut head))
216                    .is_ok_and(|n| looks_like_neuralynx(&head[..n]))
217            });
218            return Some(Detection {
219                format_id: FORMAT_ID,
220                confidence: if signed {
221                    DetectConfidence::Definite
222                } else {
223                    DetectConfidence::Likely
224                },
225                note: Some("Neuralynx recording directory (read as one session)".into()),
226            });
227        }
228        let ext = has_extension(path, &EXTENSIONS);
229        if looks_like_neuralynx(head) {
230            return Some(Detection {
231                format_id: FORMAT_ID,
232                confidence: DetectConfidence::Definite,
233                note: None,
234            });
235        }
236        if ext && has_header_keys(head) {
237            return Some(Detection {
238                format_id: FORMAT_ID,
239                confidence: DetectConfidence::Likely,
240                note: Some("Neuralynx header keys without the header line".into()),
241            });
242        }
243        if ext {
244            return Some(Detection {
245                format_id: FORMAT_ID,
246                confidence: DetectConfidence::ExtensionOnly,
247                note: Some("Neuralynx extension but no Neuralynx text header".into()),
248            });
249        }
250        None
251    }
252
253    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
254        self.open_input(&Input::local(path))
255    }
256
257    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
258        if input.is_dir() {
259            return Ok(Box::new(open_session_input(input)?));
260        }
261        Ok(Box::new(NeuralynxDataset::open_input(input)?))
262    }
263
264    fn reads_any_source(&self) -> bool {
265        true
266    }
267}