Skip to main content

openreadout_fcs/
lib.rs

1//! Reader for FCS (Flow Cytometry Standard) files, versions 2.0, 3.0, 3.1 and 3.2.
2//!
3//! FCS is an open ISAC standard. Layout and vocabulary: `docs/formats/fcs.md`.
4//! Provenance: `docs/provenance/fcs.md`. A file is one or more data sets, each a HEADER of
5//! ASCII offsets, a TEXT segment of delimited keyword-value pairs, a DATA segment of events,
6//! and optional supplemental TEXT, ANALYSIS and OTHER segments; `$NEXTDATA` links data sets.
7//! Each data set is exposed as one table (rows = events, columns = parameters).
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_fcs::FcsReader;
19//!
20//! let format = FcsReader.descriptor();
21//! assert_eq!(format.id, openreadout_fcs::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_fcs::FcsReader;
32//!
33//! let mut dataset = FcsReader.open(Path::new("sample.fcs"))?;
34//! let info = dataset.info()?; // headers only
35//! let table = &info.tables[0];
36//! println!("{} row(s) x {} column(s)", table.row_count, table.columns.len());
37//! // The first 100 rows, column-major (`columns[c][r]`).
38//! let rows = dataset.read_table(0, 0, 100)?;
39//! for (column, values) in table.columns.iter().zip(&rows.columns) {
40//!     println!("{}: {:?}", column.name, 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
57pub mod analysis;
58mod assurance;
59#[doc(hidden)]
60pub mod crc;
61#[doc(hidden)]
62pub mod dataset;
63#[doc(hidden)]
64pub mod datetime;
65#[doc(hidden)]
66pub mod events;
67#[doc(hidden)]
68pub mod file;
69pub mod filter;
70pub mod gating;
71#[doc(hidden)]
72pub mod header;
73#[doc(hidden)]
74pub mod keywords;
75#[doc(hidden)]
76pub mod layout;
77#[doc(hidden)]
78pub mod vendor;
79
80use std::path::Path;
81
82use openreadout_core::Result;
83use openreadout_core::model::{DetectConfidence, FormatDescriptor};
84use openreadout_core::reader::{Dataset, Detection, FormatReader, has_extension};
85use openreadout_core::source::Input;
86
87#[doc(hidden)]
88pub use crc::{Crc16, CrcField, read_crc_field};
89#[doc(hidden)]
90pub use dataset::{FcsDataset, keyword_prefix, spillover};
91#[doc(hidden)]
92pub use datetime::{FcsDate, acquisition_span, parse_date, parse_time, parse_timestamp};
93pub use events::{file_matrix, is_fluorescence_parameter, is_time_parameter, scale_columns};
94#[doc(hidden)]
95pub use file::{AuxSegment, DataSet, FcsFile, OffsetSource};
96#[doc(hidden)]
97pub use header::{
98    HEADER_LEN, Header, HeaderError, SegmentRange, VERSIONS, looks_like_fcs, parse_header,
99};
100#[doc(hidden)]
101pub use keywords::{Keyword, KeywordSet, TextParse, parse_float, parse_keywords, parse_uint};
102#[doc(hidden)]
103pub use layout::{
104    ByteOrder, DataType, FieldWidth, Mode, Parameter, SpilloverMatrix, decode_fixed,
105    decode_free_ascii, parse_spillover, read_parameters, storage_dtype,
106};
107
108/// Format id used on the command line and in JSON.
109pub const FORMAT_ID: &str = "fcs";
110
111/// The FCS reader.
112#[derive(Debug, Default, Clone, Copy)]
113pub struct FcsReader;
114
115impl FormatReader for FcsReader {
116    fn assurance(&self) -> Option<&'static openreadout_core::assurance::AssuranceProfile> {
117        Some(&assurance::FCS)
118    }
119
120    fn descriptor(&self) -> FormatDescriptor {
121        FormatDescriptor {
122            id: FORMAT_ID.into(),
123            name: "FCS (Flow Cytometry Standard)".into(),
124            vendor: "ISAC open standard (all cytometer vendors)".into(),
125            extensions: vec!["fcs".into(), "lmd".into()],
126            family: "flow-cytometry".into(),
127            can_read: true,
128            can_write: false,
129            confidence: assurance::FCS.confidence,
130            known_gaps: vec![
131                "Histogram data sets ($MODE C/U, deprecated in FCS 3.1) are described but not decoded".into(),
132                "Integer fields that are not a whole number of bytes (bit-packed $PnB) are not decoded".into(),
133                "$BYTEORD permutations other than 1,2,3,4 and 4,3,2,1 are not decoded".into(),
134                "read_table/export return raw values; `table --compensate/--transform` and `analyze gate` apply scale conversion, spillover, transforms and gates".into(),
135                "FlowJo workspaces: transforms other than linear, log, logicle, biex and ArcSinh, derived parameters and non-OLS spectral unmixing are reported as unsupported".into(),
136                "FCS 1.0 and FCS 4.0 files are detected but not read".into(),
137            ],
138        }
139    }
140
141    fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection> {
142        if looks_like_fcs(head) {
143            let version = String::from_utf8_lossy(&head[..6]).into_owned();
144            let known = VERSIONS.contains(&version.as_str());
145            return Some(Detection {
146                format_id: FORMAT_ID,
147                confidence: DetectConfidence::Definite,
148                note: (!known)
149                    .then(|| format!("version identifier {version} is not supported yet")),
150            });
151        }
152        // A file shorter than the 58-byte FCS header is a cut-off FCS file (exit 4); a longer
153        // one that does not start with `FCS` is another kind of file (exit 3).
154        if has_extension(path, &["fcs", "lmd"]) && (head.len() < 58 || head.starts_with(b"FCS")) {
155            return Some(Detection {
156                format_id: FORMAT_ID,
157                confidence: DetectConfidence::ExtensionOnly,
158                note: Some("FCS extension but no `FCS` version identifier at byte 0".into()),
159            });
160        }
161        None
162    }
163
164    fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
165        Ok(Box::new(FcsDataset::open(path)?))
166    }
167
168    fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
169        Ok(Box::new(FcsDataset::open_input(input)?))
170    }
171
172    fn reads_any_source(&self) -> bool {
173        true
174    }
175}