Flowio

FlowIO is a community skill for reading and writing flow cytometry data files using the FlowIO Python library, covering FCS file parsing, event extraction, metadata access, compensation matrices, and data export for cytometry analysis workflows.

What Is This?

Overview

FlowIO provides patterns for programmatically handling Flow Cytometry Standard (FCS) files in Python. It covers FCS file reading for versions 2.0, 3.0, and 3.1 with automatic format detection, event data extraction as NumPy arrays for numerical analysis, metadata and parameter access from FCS header and text segments, compensation matrix parsing for spectral overlap correction, and FCS file writing for exporting processed cytometry data. The skill enables bioinformaticians to build automated cytometry data processing pipelines that read instrument output files and prepare data for downstream gating, population identification, and statistical analysis.

Who Should Use This

This skill serves bioinformaticians building automated flow cytometry analysis pipelines, immunologists processing experimental cytometry data programmatically, and developers creating cytometry data management tools that handle FCS files at scale across large experimental datasets.

Why Use It?

Problems It Solves

FCS files use a binary format with multiple segments that requires specialized parsers to read correctly. Different instrument manufacturers such as BD Biosciences, Beckman Coulter, and Miltenyi produce FCS files with vendor-specific metadata conventions that complicate generic parsing. Extracting event data as numerical arrays for downstream analysis needs proper handling of data types and byte ordering. Compensation matrices embedded in FCS files require parsing from text fields with varying formats.

Core Highlights

FlowData class reads FCS files and provides access to events, channels, and metadata. Event extraction returns NumPy arrays ready for numerical analysis. Channel information maps parameter indices to fluorochrome names and detector settings. FCS writer exports processed data back to standard FCS format.

How to Use It?

Basic Usage

import flowio
import numpy as np

fcs = flowio.FlowData("sample.fcs")
print(f"Events: {fcs.event_count}")
print(f"Channels: {fcs.channel_count}")

events = np.array(fcs.events).reshape(
    fcs.event_count, fcs.channel_count)
print(f"Shape: {events.shape}")
print(f"Mean FSC: {events[:, 0].mean():.1f}")

channels = fcs.channels
for idx, info in channels.items():
    label = info.get("PnN", "")
    stain = info.get("PnS", "")
    print(f"Ch {idx}: {label} ({stain})")

text = fcs.text
print(f"Cytometer: {text.get('cyt', '')}")
print(f"Date: {text.get('date', '')}")

Real-World Examples

import flowio
import numpy as np
import os

class CytometryProcessor:
    def __init__(self, data_dir: str):
        self.data_dir = data_dir

    def load_sample(self, filename: str) -> dict:
        path = os.path.join(
            self.data_dir, filename)
        fcs = flowio.FlowData(path)
        events = np.array(fcs.events).reshape(
            fcs.event_count, fcs.channel_count)
        channels = {int(k): v.get("PnN", "")
                    for k, v in
                    fcs.channels.items()}
        return {"events": events,
                "channels": channels,
                "n_events": fcs.event_count,
                "metadata": dict(fcs.text)}

    def batch_summary(self) -> list[dict]:
        summaries = []
        for f in os.listdir(self.data_dir):
            if not f.endswith(".fcs"):
                continue
            sample = self.load_sample(f)
            summaries.append({
                "file": f,
                "events": sample["n_events"],
                "channels": len(
                    sample["channels"]),
                "mean_fsc": round(
                    sample["events"][:, 0]
                    .mean(), 1)})
        return summaries

proc = CytometryProcessor("fcs_data/")
summary = proc.batch_summary()
for s in summary:
    print(f"{s['file']}: {s['events']} events")

Advanced Tips

Use the compensation matrix from the FCS SPILL keyword to correct spectral overlap before analysis. Filter events by scatter parameters such as FSC-A and SSC-A to remove debris and dead cells before fluorescence analysis. Process large FCS file collections in parallel using multiprocessing to reduce batch processing time significantly across experiments with many samples.

When to Use It?

Use Cases

Build a cytometry data ingestion pipeline that reads FCS files from instrument output and extracts event matrices for automated gating. Create a sample quality checker that validates event counts and channel configurations across an experiment. Implement a data export tool that converts processed cytometry results back to FCS format for downstream software.

Related Topics

Flow cytometry, FCS file format, immunology data analysis, cell population gating, and cytometry bioinformatics.

Important Notes

Requirements

Python with the flowio package installed. NumPy for event array manipulation. FCS files from flow cytometry instruments as input data.

Usage Recommendations

Do: check the FCS version and channel configuration before processing to handle instrument differences. Apply compensation before fluorescence analysis to correct spectral spillover. Validate event counts against expected sample sizes to detect acquisition issues early in the pipeline.

Don't: assume channel ordering is consistent across different instruments or panel configurations. Process raw events without compensation when analyzing fluorescence markers. Ignore metadata fields that document acquisition settings and instrument calibration.

Limitations

FlowIO handles file reading and writing but does not perform gating or statistical analysis. Some proprietary FCS extensions from specific vendors may not be fully parsed. Very large FCS files with millions of events require sufficient memory for the full event matrix.