/flowio

name: flowio
description: Reads, inspects, and writes Flow Cytometry Standard (FCS) 2.0, 3.0, and 3.1 files with FlowIO. Use for low-level FCS metadata and channel inspection, NumPy event extraction, multi-dataset files, table export, and FCS 3.1 creation; use FlowKit for compensation, cytometry transforms, gating, or FlowJo workspaces.
allowed-tools: Read Write Bash
license: BSD-3-Clause license
compatibility: Requires Python 3.9-3.13, uv, and FlowIO 1.4.0. NumPy is installed with FlowIO; pandas is optional for DataFrame workflows. Runtime parsing is local and needs no credentials or network access.
metadata:
  version: "2.3"
  last-reviewed: "2026-09-30"
  skill-author: K-Dense Inc.

FlowIO

Purpose

Use FlowIO as a lightweight, low-level reader and writer for Flow Cytometry Standard files. Examples in this skill target **FlowIO 1.4.0**, the current stable release verified on 2026-09-30. Standalone FlowIO checks used Python 3.13, NumPy 2.5.3, and pandas 3.0.6.

FlowIO is appropriate for:

• Reading FCS 2.0, 3.0, and 3.1 files
• Inspecting HEADER, TEXT, ANALYSIS, and channel metadata
• Retrieving event data as a two-dimensional NumPy array
• Reading legacy files that contain multiple datasets
• Writing list-mode, single-precision FCS 3.1 files
• Preparing data for pandas, machine-learning, or downstream cytometry tools

FlowIO does **not** perform compensation, logicle/biexponential transforms, gating, clustering, or FlowJo workspace processing. Use FlowKit or another analysis package for those tasks.

Install

Create or activate a Python environment, then install the verified release:

uv pip install "flowio==1.4.0"

Confirm the runtime version:

uv run python -c "import flowio; print(flowio.__version__)"

FlowIO 1.4.0 supports Python 3.9 through 3.13 and depends on NumPy.

Operating Workflow

1. **Clarify the operation.** Distinguish metadata inventory, event extraction, file repair, conversion, and downstream biological analysis. 2. **Inspect before loading events.** Use `only_text=True` for metadata-only work, especially with large or unfamiliar files. 3. **Choose event semantics explicitly.** Use `as_array(preprocess=True)` for gain/log/time scaling from FCS metadata, or `preprocess=False` for decoded DATA values without those scaling steps. Record the choice. 4. **Keep parsing strict by default.** Do not automatically suppress offset errors. Relax checks only for a known vendor-format defect, and review the resulting event data. 5. **Treat metadata as potentially sensitive.** FCS TEXT values can include sample, subject, operator, and instrument identifiers. Export only fields needed for the task. 6. **Validate writes by reopening them.** Check event/channel counts, labels, metadata, and representative values after any FCS export.

Critical Semantics

TEXT keys are normalized

`FlowData.text` stores keys in lowercase and strips the leading `$` from standard FCS keywords:

from flowio import FlowData

flow = FlowData("sample.fcs", only_text=True)
acquisition_date = flow.text.get("date")
instrument = flow.text.get("cyt")
next_dataset = int(flow.text.get("nextdata", "0"))

Do not look up `"$DATE"`, `"$CYT"`, or other uppercase dollar-prefixed keys. TEXT values remain strings. FlowIO 1.4.0 also removes every `$` character from the decoded TEXT segment, including `$` characters inside values; preserve the original file when exact metadata fidelity matters.

Events have two representations

• `flow.events` is the decoded, flattened one-dimensional event array.

Integer parsing already applies PnR range masks; this is not a byte-level copy of the original DATA words.

• `flow.as_array()` returns a NumPy `float64` array with one column per

channel. For valid input its shape is `(event_count, channel_count)`, but FlowIO infers rows from DATA and does not enforce `$TOT`; check the shape.

• `flow.as_array(preprocess=True)` applies FCS gain, logarithmic, and time

scaling. It does not apply compensation or logicle/biexponential display transforms.

• `flow.as_array(preprocess=False)` reshapes the decoded event values without

those scaling steps. A recognized, non-null `Time` channel (case-insensitive) has its gain forced to 1.0 by FlowIO; `timestep` still applies when preprocessing.

`as_array()` creates another in-memory array. FlowIO does not provide chunked or memory-mapped event access.

Channel numbering uses two conventions

• NumPy columns and `fluoro_indices`, `scatter_indices`, and `time_index` use

zero-based indices.

• `flow.channels` uses FCS parameter numbers beginning at 1.
• `null_channels` contains the PnN label strings supplied through

`null_channel_list`, including supplied labels that were not found.

• `pns_labels` always matches `pnn_labels` in length; missing optional PnS

labels appear as empty strings.

Writing is intentionally limited

`create_fcs()` requires:

• An already-open binary file handle
• Flattened one-dimensional event data in row-major event/channel order
• One PnN name per channel
• Optional PnS names and string-valued metadata via `metadata_dict`

It writes FCS 3.1 list-mode (`$MODE=L`) single-precision float (`$DATATYPE=F`) data. Required interpretation keywords are generated by FlowIO and cannot be overridden through metadata.

Quick Start: Read an FCS File

from pathlib import Path

from flowio import FlowData

flow = FlowData(Path("sample.fcs"))
events = flow.as_array(preprocess=True)
if events.shape != (flow.event_count, flow.channel_count):
    raise ValueError("DATA shape disagrees with declared $TOT/$PAR")

print(
    {
        "version": flow.version,
        "events": flow.event_count,
        "channels": flow.channel_count,
        "shape": events.shape,
        "pnn": flow.pnn_labels,
        "pns": flow.pns_labels,
        "date": flow.text.get("date"),
        "instrument": flow.text.get("cyt"),
    }
)

For