GreyCat FCS Library

@library("fcs", "0.0.0");

Reader for Flow Cytometry Standard (FCS) files. Parses and streams multi-parameter flow cytometry data used in cell analysis experiments.

Quick Start

var reader = FcsReader { path: "experiment.fcs" };

// Read file metadata
var meta = reader.meta();
info("File: ${meta.file_name}, Version: ${meta.version}");
info("Events: ${meta.total_events}, Channels: ${meta.total_channels}");

// Print channel names
for (i, ch in meta.channels!!) {
    info("Channel ${i}: ${ch.short_name} (${ch.long_name}), range: ${ch.range}");
}

// Stream events
while (reader.can_read()) {
    var event = reader.event();  // Array<float?> — one value per channel
    // process event...
}

API Reference

`FcsReader`

Streaming reader for FCS files. Events are read one at a time to support large files without loading everything into memory.

Method	Returns	Description
`meta()`	`FcsMeta`	Read file header metadata (channels, version, event count)
`event()`	`Array<float?>`	Read next event — array length equals number of channels
`can_read()`	`bool`	Check if more events are available

Constructor:

var reader = FcsReader { path: "path/to/file.fcs" };

`FcsMeta`

Metadata extracted from the FCS file header.

Field	Type	Description
`file_name`	`String?`	Original FCS file name
`version`	`String?`	FCS format version (e.g., `"FCS3.0"`, `"FCS3.1"`)
`channels`	`Array<FcsChannel>?`	Channel (parameter) definitions
`total_events`	`int?`	Total number of events in the file
`total_channels`	`int?`	Total number of channels (parameters)
`begin_time`	`String?`	Experiment start timestamp
`end_time`	`String?`	Experiment end timestamp

`FcsChannel`

Describes a single measured parameter (e.g., fluorescence intensity, scatter).

Field	Type	Description
`short_name`	`String`	Short identifier (e.g., `"FSC-A"`, `"PE-A"`, `"SSC-H"`)
`long_name`	`String`	Descriptive name (e.g., `"Forward Scatter"`, `"CD4"`)
`range`	`int?`	Maximum value range for this channel
`gain`	`float?`	Amplification gain applied
`scale`	`Tuple<float, float>?`	Linear scale transform as `(offset, multiplier)`

Example — Loading Events into a Tensor

var reader = FcsReader { path: "sample.fcs" };
var meta = reader.meta();

var data = Tensor {};
data.init(TensorType::f64, Array<int> { 0, meta.total_channels!! });

while (reader.can_read()) {
    var event = reader.event();
    var row = Array<float> {};
    for (i, v in event) {
        row.add(v ?? 0.0);
    }
    data.append(row);
}
info("Loaded ${meta.total_events} events with ${meta.total_channels} channels");

About FCS Format

FCS (Flow Cytometry Standard) is the standard file format for flow cytometry data, maintained by the International Society for Advancement of Cytometry (ISAC). Each file contains:

Header — file version and byte offsets
TEXT segment — key-value metadata (channels, experiment info)
DATA segment — event measurements (one row per cell/particle, one column per channel)

Common channels include forward scatter (FSC), side scatter (SSC), and various fluorescence parameters for detecting labeled antibodies or dyes.