← Về thư mục
📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / flowio / references / api_reference.md

FlowIO 1.4.0 API Reference

This reference records the public API and behavior of the stable flowio==1.4.0 release. Prefer the exact parameter names shown here.

Public Imports

from flowio import (
    FlowData,
    create_fcs,
    fcs_keywords,
    read_multiple_data_sets,
)
from flowio.exceptions import (
    DataOffsetDiscrepancyError,
    FCSParsingError,
    FlowIOException,
    FlowIOWarning,
    MultipleDataSetsError,
    PnEWarning,
)

Exception classes are not re-exported at the top-level flowio namespace. Import them from flowio.exceptions.

FlowData

Signature

FlowData(
    fcs_file,
    ignore_offset_error=False,
    ignore_offset_discrepancy=False,
    use_header_offsets=False,
    only_text=False,
    nextdata_offset=None,
    null_channel_list=None,
)

Parameters

File support

The FCS standard defines ASCII (A) DATA, but FlowIO 1.4.0 does not provide a reliable ASCII parser path. Do not claim ASCII event-data support without a fixture-specific test.

Core attributes

TEXT and ANALYSIS normalization

FlowIO removes $ from standard keyword names, converts every key to lowercase, and retains values as strings:

flow.text["par"]
flow.text.get("date")
flow.text.get("spillover", flow.text.get("spill"))
flow.text.get("nextdata", "0")

The same key normalization applies to analysis. FlowIO 1.4.0 removes every $ character from the decoded segment before splitting keys and values, so a value such as "a$b" is parsed as "ab". Keep the source file when exact metadata round-trip fidelity matters.

FlowData.as_array

Signature

flow.as_array(preprocess=True)

Returns a two-dimensional NumPy float64 array with shape:

(flow.event_count, flow.channel_count)

With preprocess=False, FlowIO reshapes the encoded values without applying metadata-driven scaling.

With preprocess=True, FlowIO:

  1. Multiplies the time channel by the timestep keyword when available.
  2. Converts logarithmically stored channels to linear values from PnE and PnR.
  3. Divides channel values by PnG when gain is neither zero nor one.

It does not perform spillover compensation, logicle/biexponential/asinh transformation, gating, or quality control.

The method materializes a new array in addition to flow.events.

FlowData.write_fcs

Signature

flow.write_fcs(filename, metadata=None)

Writes the instance to an FCS 3.1 file.

Metadata behavior:

Required interpretation fields are generated internally. The output is list-mode, single-precision floating-point data.

If the source $DATATYPE is not F, FlowIO calls as_array() with preprocessing, flattens the values, changes the output to F, resets PnE and PnG, and removes timestep. This is a representation conversion, not a byte-preserving copy.

write_fcs() raises AttributeError for a FlowData created with only_text=True.

For a floating-point source, write_fcs() keeps encoded events but its default metadata preservation does not retain PnG or timestep. Reopening the output can therefore produce different as_array(preprocess=True) values even when preprocess=False values match. Validate both representations.

read_multiple_data_sets

Signature

read_multiple_data_sets(
    filename_or_handle,
    ignore_offset_error=False,
    ignore_offset_discrepancy=False,
    use_header_offsets=False,
    only_text=False,
)

Returns a list of FlowData objects, including a one-element list for a single-dataset file.

Use this function for legacy files whose normalized nextdata keyword is nonzero. FlowIO follows positive relative offsets until it reaches nextdata == 0. Negative offsets raise MultipleDataSetsError.

The FCS 3.1 specification deprecated multi-dataset files, but FlowIO retains reader support for older files.

Pass a filesystem path for multi-dataset input. Although the documented signature accepts a file handle, each FlowData closes that handle; FlowIO 1.4.0 then fails when the utility seeks the closed handle for the next dataset.

create_fcs

Signature

create_fcs(
    file_handle,
    event_data,
    channel_names,
    opt_channel_names=None,
    metadata_dict=None,
)

Parameters

Correct pattern

from pathlib import Path

import numpy as np
from flowio import create_fcs

events_2d = np.asarray(source_values, dtype=np.float32)
if events_2d.ndim != 2:
    raise ValueError("source_values must be events x channels")

labels = ["FSC-A", "SSC-A", "FITC-A"]
if events_2d.shape[1] != len(labels):
    raise ValueError("channel count does not match labels")

with Path("created.fcs").open("xb") as handle:
    create_fcs(
        handle,
        events_2d.ravel(order="C"),
        labels,
        metadata_dict={"date": "23-JUL-2026", "src": "Example"},
    )

Writer rules

create_fcs() writes:

The output stores about 6-7 decimal digits of precision.

Big-endian portability is unverified: FlowIO declares little-endian metadata but writes native-endian array('f') bytes.

NumPy input is copied into an array('f') before writing. If event data is already available as array('f'), pass it directly to avoid that internal copy. Large writers must budget for the float32 output buffer in addition to the source array.

FlowIO owns required fields such as $PAR, $TOT, $MODE, $DATATYPE, PnB, PnN, and output offsets. Custom attempts to override required fields are ignored or normalized.

Writer-specific metadata behavior:

For a spillover string, the first item is the number of compensated fluorescence channels, followed by matching PnN labels and then matrix values, all comma-delimited with no newline characters. FlowIO stores this metadata but does not apply compensation.

Exceptions and Warnings

Import from flowio.exceptions.

Do not use except Exception to retry with every relaxed option. Catch the specific error, inspect provenance, and choose one justified recovery path.

Public FCS Keyword Lists

FlowIO 1.4.0 exposes:

from flowio import fcs_keywords

fcs_keywords.FCS_STANDARD_KEYWORDS
fcs_keywords.FCS_STANDARD_REQUIRED_KEYWORDS
fcs_keywords.FCS_STANDARD_OPTIONAL_KEYWORDS

These lists contain normalized names without $. They are useful for validation and separating standard from custom TEXT fields.

Changes Introduced in FlowIO 1.4.0

The 1.4.0 release: