1#![forbid(unsafe_code)]
33#![warn(missing_docs)]
34#![allow(clippy::type_complexity)]
36
37mod analysis;
38mod assurance;
39mod dataset;
40mod eds;
41mod export;
42mod ixo;
43mod lc96;
44mod model;
45mod rdml;
46mod rdml_write;
47mod report;
48mod rex;
49mod xml;
50
51use std::path::Path;
52
53use openreadout_core::model::{DetectConfidence, FormatDescriptor};
54use openreadout_core::provenance::Confidence;
55use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
56use openreadout_core::source::Input;
57use openreadout_core::zip;
58use openreadout_core::{Error, Result};
59
60pub use dataset::{CQ_STATUSES, QpcrDataset, RESULT_COLUMNS};
61pub use rdml_write::{RDML_WRITE_VERSION, RdmlExportReport, default_rdml_output, export_rdml};
62pub use report::{
63 CQ_DETERMINED, CQ_NO_RESULT, CQ_UNDETERMINED, CqComparison, CqCounts, CqMethod,
64 QpcrAssayRecord, QpcrReport, QpcrReportRequest, RelativeQuantity, StandardCurveFit,
65 TargetCqSummary, qpcr_report,
66};
67
68pub const RDML_FORMAT_ID: &str = rdml::FORMAT_ID;
70pub const EDS_FORMAT_ID: &str = eds::FORMAT_ID;
72pub const PCRD_FORMAT_ID: &str = "bio-rad-pcrd";
74pub const REX_FORMAT_ID: &str = rex::FORMAT_ID;
76pub const IXO_FORMAT_ID: &str = ixo::FORMAT_ID;
78pub const EXPORT_FORMAT_ID: &str = export::FORMAT_ID;
81
82fn first_member(head: &[u8]) -> Option<String> {
84 Some(
85 zip::first_member_name(head)?
86 .replace('\\', "/")
87 .to_ascii_lowercase(),
88 )
89}
90
91fn first_member_encrypted(head: &[u8]) -> bool {
93 zip::first_header(head)
94 .and_then(|at| head.get(at + 6))
95 .is_some_and(|f| f & 1 == 1)
96}
97
98fn descriptor(
99 id: &str,
100 name: &str,
101 vendor: &str,
102 exts: &[&str],
103 can_read: bool,
104 can_write: bool,
105 confidence: Confidence,
106 gaps: &[&str],
107) -> FormatDescriptor {
108 FormatDescriptor {
109 id: id.into(),
110 name: name.into(),
111 vendor: vendor.into(),
112 extensions: exts.iter().map(|s| (*s).to_string()).collect(),
113 family: "qpcr".into(),
114 can_read,
115 can_write,
116 confidence,
117 known_gaps: gaps.iter().map(|s| (*s).to_string()).collect(),
118 }
119}
120
121#[derive(Debug, Default, Clone, Copy)]
123pub struct RdmlReader;
124
125impl FormatReader for RdmlReader {
126 fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
127 Some(&assurance::RDML)
128 }
129
130 fn descriptor(&self) -> FormatDescriptor {
131 descriptor(
132 RDML_FORMAT_ID,
133 "RDML (Real-time PCR Data Markup Language)",
134 "RDML consortium (open standard); written by Bio-Rad CFX Maestro, Roche LightCycler 96/480, Applied Biosystems StepOne, qPCR analysis tools",
135 &["rdml", "rdm", "lc96p", "xml"],
136 true,
137 true,
138 assurance::RDML.confidence,
139 &[
140 "Digital PCR partitions (RDML 1.3 `partitions`, partition tables) are counted, not read",
141 "Documentation, xRef, cDNA synthesis and commercial-assay elements are kept only in the vendor tree",
142 "LightCycler 96 (.lc96p, or RDML with its app_data.xml/calculated_data.xml): the software's calls, replicate Cq mean/SD and exclusions are attached; an RDML cq under a call other than Positive is not a Cq, even when it is a plausible number (kept as cq_stored; the software's analyses list none for such graphs, and rdmlpython and other RDML readers report the stored number). Validated against the software's results table for 3 files (108 Cqs) and its absolute-quantification analysis in a fourth (56 Cqs, 8 Negative graphs without one); melting-peak Tm of LightCycler 96 analyses is not read",
143 ],
144 )
145 }
146
147 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
148 if zip::is_zip(head) {
149 let first = first_member(head).unwrap_or_default();
150 if first == "rdml_data.xml" {
151 return Some(Detection {
152 format_id: RDML_FORMAT_ID,
153 confidence: DetectConfidence::Definite,
154 note: None,
155 });
156 }
157 return has_extension(path, &["rdml", "rdm", "lc96p"]).then_some(Detection {
158 format_id: RDML_FORMAT_ID,
159 confidence: DetectConfidence::Likely,
160 note: Some("zip archive with an .rdml (or LightCycler 96 .lc96p) extension".into()),
161 });
162 }
163 let text = String::from_utf8_lossy(&head[..head.len().min(4096)]);
164 rdml::looks_like_rdml(&text).then_some(Detection {
165 format_id: RDML_FORMAT_ID,
166 confidence: DetectConfidence::Definite,
167 note: Some("uncompressed RDML XML".into()),
168 })
169 }
170
171 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
172 self.open_input(&Input::local(path))
173 }
174
175 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
176 Ok(Box::new(QpcrDataset::open_as(input, RDML_FORMAT_ID)?))
177 }
178
179 fn reads_any_source(&self) -> bool {
180 true
181 }
182}
183
184#[derive(Debug, Default, Clone, Copy)]
186pub struct EdsReader;
187
188impl FormatReader for EdsReader {
189 fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
190 Some(&assurance::APPLIED_BIOSYSTEMS_EDS)
191 }
192
193 fn descriptor(&self) -> FormatDescriptor {
194 descriptor(
195 EDS_FORMAT_ID,
196 "Applied Biosystems experiment document (.eds)",
197 "Thermo Fisher Scientific / Applied Biosystems (QuantStudio 1-7 Pro, 12K Flex, ViiA 7, StepOne, StepOnePlus, 7500)",
198 &["eds"],
199 true,
200 false,
201 assurance::APPLIED_BIOSYSTEMS_EDS.confidence,
202 &[
203 "Raw optical images (`apldbio/sds/images/*.tiff`, `quant/*.quant`) are listed, not decoded; files that keep only images have no curves",
204 "Genotyping (allelic discrimination): the vendor's calls are the table genotypes (SDS layout; codes mapped from 1000 Genomes genotypes of 4 reference samples at 2 markers of one QuantStudio 7 run); JSON-layout (Design & Analysis 2) genotyping results are not read",
205 "Relative-quantification results (RQ, ΔΔCt) computed by the vendor are not parsed; `analyze qpcr --ddcq` computes them",
206 "SDS/7500 layouts: the threshold comes from the analysis protocol (equal to the exported Ct Threshold in 8 StepOnePlus runs); an automatic baseline window is recovered per well from Rn − ΔRn (572 of 574 wells equal to the export) or left empty, never reported as the setting",
207 ],
208 )
209 }
210
211 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
212 if !zip::is_zip(head) {
213 return None;
214 }
215 let first = first_member(head).unwrap_or_default();
216 let known = first.starts_with("apldbio/")
217 || [
218 "manifest.mf",
219 "summary.json",
220 "checksum",
221 "setup/",
222 "primary/",
223 "run/",
224 "calibrations/",
225 "extensions/",
226 ]
227 .iter()
228 .any(|p| first.starts_with(p));
229 if known && has_extension(path, &["eds", "edt"]) {
230 return Some(Detection {
231 format_id: EDS_FORMAT_ID,
232 confidence: DetectConfidence::Definite,
233 note: None,
234 });
235 }
236 if first.starts_with("apldbio/sds/") {
237 return Some(Detection {
238 format_id: EDS_FORMAT_ID,
239 confidence: DetectConfidence::Likely,
240 note: Some("apldbio/sds/ zip without an .eds extension".into()),
241 });
242 }
243 has_extension(path, &["eds"]).then_some(Detection {
244 format_id: EDS_FORMAT_ID,
245 confidence: DetectConfidence::Likely,
246 note: Some("zip archive with an .eds extension".into()),
247 })
248 }
249
250 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
251 self.open_input(&Input::local(path))
252 }
253
254 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
255 Ok(Box::new(QpcrDataset::open_as(input, EDS_FORMAT_ID)?))
256 }
257
258 fn reads_any_source(&self) -> bool {
259 true
260 }
261}
262
263#[derive(Debug, Default, Clone, Copy)]
265pub struct PcrdReader;
266
267const PCRD_HINT: &str = "Bio-Rad .pcrd files are encrypted with a key only the vendor software has. Open the file in CFX Maestro (or CFX Manager) and use File > Export > RDML File (or Export > All Data Sheets), then read the .rdml with openreadout.";
269
270impl FormatReader for PcrdReader {
271 fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
272 Some(&assurance::BIO_RAD_PCRD)
273 }
274
275 fn descriptor(&self) -> FormatDescriptor {
276 descriptor(
277 PCRD_FORMAT_ID,
278 "Bio-Rad CFX data file (.pcrd)",
279 "Bio-Rad Laboratories (CFX96, CFX384, CFX Opus; CFX Maestro / CFX Manager)",
280 &["pcrd"],
281 false,
282 false,
283 assurance::BIO_RAD_PCRD.confidence,
284 &[
285 "Encrypted container (a zip whose single member is encrypted): detected and refused with exit 6; export RDML from CFX Maestro instead",
286 ],
287 )
288 }
289
290 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
291 if !zip::is_zip(head) {
292 return None;
293 }
294 let first = first_member(head).unwrap_or_default();
295 if first == "datafile.pcrd" {
296 return Some(Detection {
297 format_id: PCRD_FORMAT_ID,
298 confidence: DetectConfidence::Definite,
299 note: Some(if first_member_encrypted(head) {
300 "encrypted Bio-Rad CFX data file (not readable; export RDML from CFX Maestro)"
301 .into()
302 } else {
303 "Bio-Rad CFX data file".into()
304 }),
305 });
306 }
307 has_extension(path, &["pcrd"]).then_some(Detection {
308 format_id: PCRD_FORMAT_ID,
309 confidence: DetectConfidence::Likely,
310 note: Some("zip archive with a .pcrd extension".into()),
311 })
312 }
313
314 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
315 self.open_input(&Input::local(path))
316 }
317
318 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
319 let z = zip::ZipIndex::open(input.fs(), input.path(), PCRD_FORMAT_ID)?;
321 let encrypted = z.members.iter().any(|m| m.encrypted);
322 Err(Error::Unsupported {
323 format: PCRD_FORMAT_ID,
324 feature: if encrypted {
325 format!(
326 "reading an encrypted Bio-Rad CFX data file ({} encrypted zip member(s))",
327 z.members.iter().filter(|m| m.encrypted).count()
328 )
329 } else {
330 "reading Bio-Rad CFX data files".into()
331 },
332 hint: Some(PCRD_HINT.into()),
333 })
334 }
335
336 fn reads_any_source(&self) -> bool {
337 true
338 }
339}
340
341#[derive(Debug, Default, Clone, Copy)]
343pub struct RexReader;
344
345impl FormatReader for RexReader {
346 fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
347 Some(&assurance::ROTOR_GENE_REX)
348 }
349
350 fn descriptor(&self) -> FormatDescriptor {
351 descriptor(
352 REX_FORMAT_ID,
353 "Qiagen Rotor-Gene run file (.rex)",
354 "Qiagen (Rotor-Gene Q, Rotor-Gene 6000; Rotor-Gene Q Series Software)",
355 &["rex"],
356 true,
357 false,
358 assurance::ROTOR_GENE_REX.confidence,
359 &[
360 "No Cq values: Rotor-Gene files keep raw channel readings and the run setup; the analysis lives in the vendor software (`analyze qpcr --compute-cq` computes Cq)",
361 "Melt channels are read when the file records them as readings of a melt step; gain optimisation and other auxiliary readings are listed only",
362 ],
363 )
364 }
365
366 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
367 let text = String::from_utf8_lossy(&head[..head.len().min(4096)]);
368 if text.contains("<RexHeader>") || (text.contains("<Experiment>") && text.contains("REX "))
369 {
370 return Some(Detection {
371 format_id: REX_FORMAT_ID,
372 confidence: DetectConfidence::Definite,
373 note: None,
374 });
375 }
376 (has_extension(path, &["rex"]) && text.trim_start().starts_with('<')).then_some(Detection {
377 format_id: REX_FORMAT_ID,
378 confidence: DetectConfidence::Likely,
379 note: Some("XML file with a .rex extension".into()),
380 })
381 }
382
383 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
384 self.open_input(&Input::local(path))
385 }
386
387 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
388 Ok(Box::new(QpcrDataset::open_as(input, REX_FORMAT_ID)?))
389 }
390
391 fn reads_any_source(&self) -> bool {
392 true
393 }
394}
395
396#[derive(Debug, Default, Clone, Copy)]
398pub struct IxoReader;
399
400impl FormatReader for IxoReader {
401 fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
402 Some(&assurance::ROCHE_LIGHTCYCLER_IXO)
403 }
404
405 fn descriptor(&self) -> FormatDescriptor {
406 descriptor(
407 IXO_FORMAT_ID,
408 "Roche LightCycler 480 experiment (.ixo)",
409 "Roche Diagnostics (LightCycler 480, LightCycler 480 II; LightCycler 480 software 1.5)",
410 &["ixo"],
411 true,
412 false,
413 assurance::ROCHE_LIGHTCYCLER_IXO.confidence,
414 &[
415 "Read: run and instrument, thermal protocol, detection channels, sample names and per-channel target/type/concentration, raw fluorescence per cycle and melt readings (instrument units, no color compensation), and the vendor's absolute-quantification results (Cp and positive/negative call). Validated on 4 LightCycler 480 QC runs (software 1.5.0 and 1.5.1) against the depositor's own reader and on 6 plates against the LightCycler 480 software's Cp table and raw-data export",
416 "Fluorescence is the stored reading; the software shows and exports it times ScalingFactor / (RefValue × IntgrTime) of each acquisition, given per channel and cycle in `vendor.export_scale`",
417 "Melt readings are not confirmed by an independent reader (reported in `inferred`)",
418 "The instrument model is read from the run's instrument name only when that names a LightCycler; otherwise it is unset and the name is in `vendor.instrument_name`",
419 "Only `Legacy Absolute Quantification Analysis` results are read (one channel, no ratio); Tm calling, genotyping, relative quantification and other analyses are listed in the vendor tree, not read; a call other than 0 or 2 gives no Cq",
420 "Vendor melt smoothing and derivative arrays (DARZ/FORM binary properties) and the temperature log are not decoded; -dF/dT is computed from the raw melt readings",
421 "Our own Cq (`analyze qpcr --compute-cq`) is the second-derivative maximum: on average a few hundredths of a cycle from the LightCycler 480's Cp, up to 0.35 cycles; the vendor Cp is in `cq`",
422 "The closing checksum line is kept (`vendor.trailer`), not verified",
423 ],
424 )
425 }
426
427 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
428 let text = String::from_utf8_lossy(&head[..head.len().min(4096)]);
429 if text.contains("<objectstream") && text.contains("signature=\"IXOS\"") {
430 return Some(Detection {
431 format_id: IXO_FORMAT_ID,
432 confidence: DetectConfidence::Definite,
433 note: None,
434 });
435 }
436 (has_extension(path, &["ixo"]) && text.trim_start().starts_with('<')).then_some(Detection {
437 format_id: IXO_FORMAT_ID,
438 confidence: DetectConfidence::Likely,
439 note: Some("XML file with an .ixo extension".into()),
440 })
441 }
442
443 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
444 self.open_input(&Input::local(path))
445 }
446
447 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
448 Ok(Box::new(QpcrDataset::open_as(input, IXO_FORMAT_ID)?))
449 }
450
451 fn reads_any_source(&self) -> bool {
452 true
453 }
454}
455
456#[derive(Debug, Default, Clone, Copy)]
460pub struct ExportReader;
461
462const EXPORT_EXTENSIONS: [&str; 5] = ["xls", "xlsx", "csv", "txt", "tsv"];
464
465impl FormatReader for ExportReader {
466 fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
467 Some(&assurance::QPCR_RESULTS_EXPORT)
468 }
469
470 fn descriptor(&self) -> FormatDescriptor {
471 descriptor(
472 EXPORT_FORMAT_ID,
473 "qPCR results export (Applied Biosystems, Bio-Rad CFX)",
474 "Applied Biosystems / Thermo Fisher (StepOne, 7500, QuantStudio, ViiA 7 software); Bio-Rad (CFX Manager, CFX Maestro)",
475 &EXPORT_EXTENSIONS,
476 true,
477 false,
478 assurance::QPCR_RESULTS_EXPORT.confidence,
479 &[
480 "Applied Biosystems: the Results table (Cq or Undetermined, Cq mean and SD, threshold, baseline window, Amp Status, Tm, quantities, RQ and ΔCq), and amplification (Rn, ΔRn) and melt curves when the export holds those sheets; Sample Setup, Multicomponent Data and Raw Data sheets are not read",
481 "Bio-Rad CFX: the Quantification Cq Results table only (no curves); NaN and N/A Cq are read as no Cq; the export holds no plate size",
482 "Other exports (Amplification Results, Melt Curve Peak Results, End Point Results, Allelic Discrimination) are not recognised",
483 ],
484 )
485 }
486
487 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
488 if export::is_workbook(head) || !has_extension(path, &EXPORT_EXTENSIONS) {
490 return None;
491 }
492 let (_, sheets) = export::read_sheets(head.to_vec()).ok()?;
493 export::classify(&sheets).map(|layout| Detection {
494 format_id: EXPORT_FORMAT_ID,
495 confidence: DetectConfidence::Definite,
496 note: Some(format!("{} results export", layout.name())),
497 })
498 }
499
500 fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
501 let path = input.path();
502 if !has_extension(path, &EXPORT_EXTENSIONS) {
503 return None;
504 }
505 if !export::is_workbook(head) {
506 return self.sniff(head, path);
507 }
508 let size = input.fs().metadata(path).ok()?.len();
510 if size > 16 << 20 {
511 return None;
512 }
513 let bytes = input.fs().read(path).ok()?;
514 let (_, sheets) = export::read_sheets(bytes).ok()?;
515 export::classify(&sheets).map(|layout| Detection {
516 format_id: EXPORT_FORMAT_ID,
517 confidence: DetectConfidence::Definite,
518 note: Some(format!("{} results export (workbook)", layout.name())),
519 })
520 }
521
522 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
523 self.open_input(&Input::local(path))
524 }
525
526 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
527 Ok(Box::new(QpcrDataset::open_as(input, EXPORT_FORMAT_ID)?))
528 }
529
530 fn reads_any_source(&self) -> bool {
531 true
532 }
533}
534
535pub fn open_qpcr(reg: &openreadout_core::Registry, path: &Path) -> Result<QpcrDataset> {
538 let (reader, det) = reg.detect(path)?;
539 match det.format_id {
540 RDML_FORMAT_ID | EDS_FORMAT_ID | REX_FORMAT_ID | IXO_FORMAT_ID => QpcrDataset::open(path),
541 EXPORT_FORMAT_ID => QpcrDataset::open_as(&Input::local(path), EXPORT_FORMAT_ID),
542 other => {
543 reader.open(path)?;
545 Err(Error::unsupported(
546 "qpcr",
547 format!("qPCR analysis of a {other} file"),
548 "qPCR analysis reads real-time PCR files: RDML (.rdml, LightCycler 96 .lc96p), Applied Biosystems (.eds), Rotor-Gene (.rex), LightCycler 480 (.ixo), and the results exports of Applied Biosystems and Bio-Rad CFX software. Use `info` to see what this file holds.",
549 ))
550 }
551 }
552}
553
554pub(crate) fn descriptor_of(id: &str) -> FormatDescriptor {
556 match id {
557 RDML_FORMAT_ID => RdmlReader.descriptor(),
558 REX_FORMAT_ID => RexReader.descriptor(),
559 IXO_FORMAT_ID => IxoReader.descriptor(),
560 PCRD_FORMAT_ID => PcrdReader.descriptor(),
561 EXPORT_FORMAT_ID => ExportReader.descriptor(),
562 _ => EdsReader.descriptor(),
563 }
564}
565
566#[cfg(test)]
567mod tests {
568 use super::*;
569
570 #[test]
571 fn sniffs() {
572 let rdml = zip::zip_bytes(&[("rdml_data.xml", b"<rdml/>")]).unwrap();
573 let d = RdmlReader.sniff(&rdml, Path::new("x.zip")).unwrap();
574 assert_eq!(d.confidence, DetectConfidence::Definite);
575 assert!(EdsReader.sniff(&rdml, Path::new("x.zip")).is_none());
576 let eds = zip::zip_bytes(&[("apldbio/sds/experiment.xml", b"<Experiment/>")]).unwrap();
577 assert_eq!(
578 EdsReader
579 .sniff(&eds, Path::new("a.eds"))
580 .unwrap()
581 .confidence,
582 DetectConfidence::Definite
583 );
584 assert!(RdmlReader.sniff(&eds, Path::new("a.eds")).is_none());
585 let pcrd = zip::zip_bytes(&[("datafile.pcrd", b"x")]).unwrap();
586 assert_eq!(
587 PcrdReader
588 .sniff(&pcrd, Path::new("a.pcrd"))
589 .unwrap()
590 .format_id,
591 PCRD_FORMAT_ID
592 );
593 assert!(
594 RexReader
595 .sniff(
596 b"<?xml version=\"1.0\"?>\n<Experiment>\n<RexHeader>REX 3.15</RexHeader>",
597 Path::new("r.rex")
598 )
599 .is_some()
600 );
601 assert!(
602 RdmlReader
603 .sniff(b"<rdml version=\"1.2\">", Path::new("r.xml"))
604 .is_some()
605 );
606 assert!(RdmlReader.sniff(b"<html>", Path::new("r.xml")).is_none());
607 }
608
609 #[test]
610 fn pcrd_is_refused_with_exit_6() {
611 let dir = tempfile::tempdir().unwrap();
612 let p = dir.path().join("a.pcrd");
613 std::fs::write(&p, zip::zip_bytes(&[("datafile.pcrd", b"x")]).unwrap()).unwrap();
614 let err = PcrdReader.open(&p).map(|_| ()).unwrap_err();
615 assert_eq!(err.exit_code(), 6);
616 assert!(err.hint().unwrap().contains("RDML"));
617 std::fs::write(&p, b"PK\x03\x04truncated").unwrap();
618 assert_eq!(PcrdReader.open(&p).map(|_| ()).unwrap_err().exit_code(), 4);
619 }
620}