1#![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
84pub const FORMAT_ID: &str = "neuralynx";
86
87pub const EXTENSIONS: [&str; 6] = ["ncs", "nev", "nse", "nst", "ntt", "nvt"];
89
90pub const SESSION_COMPANIONS: [&str; 8] = ["txt", "log", "cfg", "xml", "ini", "json", "md", "nrd"];
93
94pub 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
120pub 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#[derive(Debug, Default, Clone, Copy)]
156pub struct NeuralynxReader;
157
158pub 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}