FlowIO

FlowIO - FCS File Parsing and Flow Cytometry Data Processing Library

Overview

FlowIO is a lightweight Python library for reading and writing Flow Cytometry Standard (FCS) files. It supports FCS versions 2.0, 3.0, and 3.1, and can extract flow cytometry data as NumPy arrays or convert it to CSV/DataFrame formats.

Use Cases

Backend Services and Web Applications: With minimal dependencies, FlowIO is suitable for server-side processing of user-uploaded FCS files, including file validation, metadata extraction, and data previews, without deploying heavyweight analysis tools.

Data Pipelines and Batch Processing: In bioinformatics data pipelines, FlowIO can batch-parse FCS files and extract metadata and event data, providing clean NumPy arrays or Pandas DataFrames for downstream analysis.

Flow Cytometry Data Preprocessing: Before importing data into FlowJo or other analysis tools, use FlowIO for file validation, channel information extraction, data format conversion, and quality checks to quickly screen qualified samples.

Core Features

FCS File Parsing and Data Extraction

- Read FCS 2.0/3.0/3.1 files and parse the HEADER, TEXT, DATA, and ANALYSIS segments
- Extract event data as NumPy arrays, with support for both preprocessed and raw data
- Read channel information, including PnN short names, PnS descriptive names, and PnR range values
- Automatically identify scatter, fluorescence, and time channel types

Metadata Extraction and File Validation

- Access all keywords in the TEXT segment, including acquisition date, instrument model, and data type
- Parse metadata only with the only_text=True option to reduce memory usage
- Handle offset discrepancies and non-standard file formats
- Detect FCS files containing multiple data sets

FCS File Creation and Export

- Create standard FCS 3.1 files from NumPy arrays
- Support custom channel names and descriptive names
- Add custom metadata, such as source, date, and instrument
- Export data in CSV format for cross-platform analysis

Frequently Asked Questions

Which FCS versions does FlowIO support?

FlowIO supports FCS versions 2.0, 3.0, and 3.1. When reading files, it automatically detects the file version. Files created by default are output in FCS 3.1 format. If you encounter version compatibility issues, try using the ignore_offset_discrepancy or ignore_offset_error parameters to handle non-standard files.

What is the difference between FlowIO and FlowKit?

FlowIO focuses on basic FCS file reading and writing, making it suitable for file parsing, metadata extraction, and data preprocessing. FlowKit is built on FlowIO and provides advanced analysis features such as fluorescence compensation, gating analysis, and FlowJo/GatingML support. If you only need to read and convert FCS files, FlowIO’s lightweight design is more suitable. For a complete analysis workflow, using FlowIO together with FlowKit is recommended.

How do I read an FCS file with Python?

Reading an FCS file with FlowIO requires only a few lines of code:

from flowio import FlowData

# Read an FCS file
flow = FlowData('sample.fcs')

# Get basic information
print(f"Version: {flow.version}, Event count: {flow.event_count}")
print(f"Channels: {flow.pnn_labels}")

# Extract event data as a NumPy array
events = flow.as_array()

If you only need the metadata, use the only_text=True parameter to skip the data segment and significantly reduce memory usage.

What should I do if an error occurs while parsing an FCS file?

Common errors include offset mismatches (DataOffsetDiscrepancyError) and multiple-data-set errors (MultipleDataSetsError). For offset errors, try using the ignore_offset_discrepancy=True or use_header_offsets=True parameters. For files containing multiple data sets, use the read_multiple_data_sets() function to read all data sets. It is recommended to use a try-except block in your code to catch FCSParsingError and select the appropriate handling strategy based on the error type.

Can multiple FCS files be processed in batches?

Yes. FlowIO’s lightweight design makes it particularly suitable for batch processing:

from pathlib import Path
from flowio import FlowData

for fcs_file in Path('data/').glob('*.fcs'):
    flow = FlowData(str(fcs_file), only_text=True)
    print(f"{fcs_file.name}: {flow.event_count} events")

Using only_text=True allows you to quickly extract metadata without loading the complete event data, greatly improving batch-processing speed.

How do I extract metadata from an FCS file?

FlowIO provides complete access to the TEXT segment:

from flowio import FlowData

flow = FlowData('sample.fcs')
text = flow.text  # Metadata in dictionary format

# Common metadata keywords
date = text.get('$DATE')      # Acquisition date
instrument = text.get('$CYT')  # Instrument model
source = text.get('$SRC')      # Data source

You can also use flow.pnn_labels and flow.pns_labels to obtain channel names, and flow.scatter_indices and flow.fluoro_indices to identify channel types.

Can FCS files be converted to CSV?

Yes, using a Pandas DataFrame:

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)

The DataFrame can retain FCS metadata in its attrs attribute, making it easier to trace the file source during subsequent analysis.

Does FlowIO support writing FCS files?

Yes. Use the create_fcs() function to create an FCS file from a NumPy array:

import numpy as np
from flowio import create_fcs

# Prepare data (rows are events, columns are channels)
data = np.random.rand(10000, 5) * 1000
channels = ['FSC-A', 'SSC-A', 'FL1-A', 'FL2-A', 'Time']

# Create an FCS file
create_fcs('output.fcs', data, channels)

You can also add descriptive channel names and custom metadata. The resulting file complies with the FCS 3.1 standard and can be opened in mainstream flow cytometry analysis software.

Author

Category

Install