Skip to main content

Crate openreadout_fcs

Crate openreadout_fcs 

Source
Expand description

Reader for FCS (Flow Cytometry Standard) files, versions 2.0, 3.0, 3.1 and 3.2.

FCS is an open ISAC standard. Layout and vocabulary: docs/formats/fcs.md. Provenance: docs/provenance/fcs.md. A file is one or more data sets, each a HEADER of ASCII offsets, a TEXT segment of delimited keyword-value pairs, a DATA segment of events, and optional supplemental TEXT, ANALYSIS and OTHER segments; $NEXTDATA links data sets. Each data set is exposed as one table (rows = events, columns = parameters).

§Example

Every reader implements openreadout_core::FormatReader: descriptor says what it reads, sniff recognises a file from its first bytes, and open returns a openreadout_core::Dataset with a header-only info() summary and lazy data access.

use openreadout_core::FormatReader;
use openreadout_fcs::FcsReader;

let format = FcsReader.descriptor();
assert_eq!(format.id, openreadout_fcs::FORMAT_ID);
println!("{} ({}): .{}", format.name, format.family, format.extensions.join(", ."));

Reading a file:

use std::path::Path;

use openreadout_core::FormatReader;
use openreadout_fcs::FcsReader;

let mut dataset = FcsReader.open(Path::new("sample.fcs"))?;
let info = dataset.info()?; // headers only
let table = &info.tables[0];
println!("{} row(s) x {} column(s)", table.row_count, table.columns.len());
// The first 100 rows, column-major (`columns[c][r]`).
let rows = dataset.read_table(0, 0, 100)?;
for (column, values) in table.columns.iter().zip(&rows.columns) {
    println!("{}: {:?}", column.name, values.first());
}

Applications that accept any instrument file usually register every reader in an openreadout_core::Registry and let it detect the format; that is what the openreadout command-line tool does.

§API stability

The supported API is what this page documents. The parser modules are public only so that tests and fuzz targets can reach them: they are hidden from this documentation and may change in any release.

Modules§

analysis
What openreadout analyze gate and table --compensate/--transform/--workspace/--gatingml do: read a gating file, bind it to an FCS data set, stream the events through the evaluator, and build the JSON shapes in openreadout_core::flow.
filter
table --filter 'FITC-A > 1000' --count: rows of a whole table that meet conditions, counted (and paged) without exporting. Works on any reader’s table; FCS values can be compensated and transformed first (the conditions then test the processed values).
gating
Flow analysis on FCS events: FlowJo workspaces (.wsp), Gating-ML 2.0 documents, compensation and data-scale transforms, and a gate evaluator that counts populations.

Structs§

FcsReader
The FCS reader.

Constants§

FORMAT_ID
Format id used on the command line and in JSON.

Functions§

file_matrix
The file’s own compensation matrix: $SPILLOVER, $SPILL or SPILL (the latter only when its names are this data set’s parameters). $COMP is not used: FCS 3.0 does not say whether it holds spillover or compensation coefficients.
is_fluorescence_parameter
True for fluorescence (or mass) parameters: not scatter (FSC-…, SSC-…) and not time, the split FlowIO also makes. Used as the default set for --transform.
is_time_parameter
True for the time parameter ($PnN Time, any case).
scale_columns
Convert raw DATA values to scale values in place: $PnE f1,f2 with f1 > 0 gives 10^(f1·x/$PnR)·f2 (f2 = 0 read as 1); $PnG other than 0 or 1 divides; the time parameter is multiplied by $TIMESTEP and never divided by a gain. Returns what was done, one entry per changed parameter.