flowio

FlowIO: Lightweight FCS Flow Cytometry File Parsing Library

Skill Overview

FlowIO is a Python library designed to parse FCS (Flow Cytometry Standard) files, supporting FCS versions 2.0 through 3.1. It can quickly extract event data as NumPy arrays, read metadata and channel information, or convert and export data to CSV/DataFrame formats.

Use Cases

1. FCS File Parsing and Data Extraction

When you need to extract event data from FCS files exported by flow cytometers, FlowIO provides a concise API. With just a few lines of code you can read files, get the event count, channel information, and convert data to NumPy arrays for further analysis. It is especially useful when you need quick access to file metadata without loading all events.

2. Flow Cytometry Data Format Conversion

If you need to convert FCS files to CSV, DataFrame, or other formats, FlowIO can output NumPy arrays directly, making it easy to integrate into Pandas workflows. It supports preserving raw data or applying preprocessing (such as gain scaling or log transformation), suitable for preprocessing pipelines or integration with other analysis tools.

3. Batch Processing and Data Pipelines

When processing large numbers of FCS files in backend services or automation scripts, FlowIO’s lightweight design and high memory efficiency (supports metadata-only reading mode) make it an ideal choice. You can quickly validate files, extract summary information, filter events, and re-export, making it well suited for building data processing pipelines or laboratory information systems.

Core Features

1. FCS File Reading and Writing

FlowIO provides full FCS file reading and writing capabilities. Use the FlowData class to read files and access version info, event counts, channel labels, etc.; use the create_fcs() function to create new FCS 3.1-compliant files from NumPy arrays, with support for custom channel names and metadata.

2. Metadata and Channel Information Extraction

Automatically parses the TEXT segment of FCS files to extract key metadata such as instrument name, acquisition date, and data type. Intelligently recognizes channel types (scatter, fluorescence, time), and provides channel labels, descriptive names, and range values, making it easy to understand file structure without loading event data.

3. Multi-dataset and Fault Tolerance

Supports FCS files containing multiple datasets, offering read_multiple_data_sets() to read all datasets at once. To handle common issues like offset mismatches or file corruption, it provides parameters such as ignore_offset_discrepancy and use_header_offsets to enhance robustness.

FAQs

Which FCS versions does FlowIO support?

FlowIO supports FCS 2.0, 3.0, and 3.1. When reading a file you can check the exact version via the flow.version property. When exporting new files, the default is FCS 3.1 format with single-precision floating point data.

How do I convert an FCS to CSV with FlowIO?

After reading the file with FlowData, call as_array() to get a NumPy array, then convert to a DataFrame with Pandas and export:

from flowio import FlowData
import pandas as pd

flow = FlowData('sample.fcs')
df = pd.DataFrame(flow.as_array(), columns=flow.pnn_labels)
df.to_csv('output.csv', index=False)

What’s the difference between FlowIO and FlowKit?

FlowIO focuses on basic FCS file parsing, metadata extraction, and file creation; it has few dependencies and is fast. FlowKit is built on top of FlowIO and adds advanced analysis features like compensation matrices, gating analysis, and Flow/GatingML support. If you only need file I/O and simple preprocessing, FlowIO is sufficient; for complex analyses, use FlowKit alongside FlowIO.