Flowio

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

• fcs_file: Local path string, pathlib.Path, or readable binary file handle. FlowData closes the handle after parsing, including a caller-provided handle.

• ignore_offset_error: Permit a DATA end offset that is off by one byte. FlowIO emits a warning because event values still require review.

• ignore_offset_discrepancy: Suppress the error raised when HEADER and TEXT DATA offsets disagree. FlowIO uses the TEXT offsets unless use_header_offsets=True.

• use_header_offsets: Use DATA offsets from HEADER. This also suppresses the HEADER/TEXT discrepancy error.

• only_text: Parse metadata without loading the DATA segment. events is None, so as_array() must not be called. HEADER, TEXT, and ANALYSIS are still parsed.

• nextdata_offset: Internal/careful-use byte offset for one dataset in a multi-dataset file. Prefer read_multiple_data_sets().

• null_channel_list: PnN labels for channels not intended for analysis. Matching channels are omitted from fluoro_indices, scatter_indices, and time_index. The supplied label list is stored unchanged in null_channels; it is not converted to indices and may include labels that were not present.

File support

• FCS versions: 2.0, 3.0, and 3.1

• DATA mode: list mode ($MODE=L)

• Event types used in practice: integer (I), single precision (F), and double precision (D)

• Correlated and uncorrelated histogram modes (C and U) are unsupported. The released parser only explicitly rejects lowercase c/u; uppercase values can be interpreted as list data. Validate flow.text["mode"].upper() == "L" before downstream use. The bundled inspector enforces this.

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

• name: Source file name, or "InMemoryFile" for a nameless handle.

• file_size: Source size in bytes.

• version: FCS version string.

• header: Parsed HEADER values.

• text: Parsed TEXT keyword/value mapping.

• analysis: Parsed ANALYSIS keyword/value mapping, or an empty mapping when absent.

• data_type: $DATATYPE value from the file.

• channel_count: Number of parameters/channels ($PAR).

• event_count: Number of events ($TOT).

• events: Flattened one-dimensional sequence of decoded event values, usually array.array. Mixed-width integer channels use a Python list. events is None when only_text=True.

• channels: Mapping whose keys are one-based FCS parameter numbers. Each value contains:

  • pnn: required PnN label

  • pns: optional PnS label, or ""

  • pne: (decades, log_zero) tuple

  • png: gain as float, defaulting to 1.0; forced to 1.0 for a recognized, non-null Time channel regardless of the TEXT PnG value

  • pnr: range as float

• pnn_labels: Required channel labels in array-column order.

• pns_labels: Optional channel labels in array-column order; missing values are empty strings.

• pnr_values: Channel ranges in array-column order.

• fluoro_indices: Zero-based fluorescence-channel indices inferred by FlowIO.

• scatter_indices: Zero-based scatter-channel indices inferred by FlowIO.

• time_index: Zero-based time-channel index, or None.

• null_channels: PnN label strings supplied through null_channel_list.

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. For valid input its shape is:

(flow.event_count, flow.channel_count)

FlowIO actually reshapes to (-1, channel_count) and does not compare DATA length with $TOT. Validate the resulting shape or check len(flow.events) == flow.event_count * flow.channel_count first.

With preprocess=False, FlowIO reshapes decoded values without applying metadata-driven scaling. Integer decoding has already applied PnR bit masks, so this does not recover the original binary words.

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. FlowIO forces the recognized Time channel gain to one.

For logarithmic PnE with log_zero == 0, channel extraction substitutes 1.0.

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:

• metadata=None: preserve source cyt, date, and spillover/spill when present, plus PnR values needed by the writer.

• metadata={}: omit those selected defaults.

• Any other dictionary: write the supplied custom metadata instead of merging it with the selected defaults.

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

• file_handle: Seekable binary output handle opened in a writable mode such as "xb" (new file) or "wb" (intentional overwrite).

• event_data: Flattened one-dimensional event values. Values must be ordered event by event, with channels varying within each event. The total number of values must be divisible by len(channel_names).

• channel_names: PnN labels, one per channel.

• opt_channel_names: Optional PnS labels. Its length must match channel_names; None and empty-string entries are omitted.

• metadata_dict: Extra FCS metadata with string values.

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": "30-SEP-2026", "src": "Example"},
    )

Writer rules

create_fcs() writes:

• FCS version 3.1

• List mode ($MODE=L)

• Single-precision 32-bit float values ($DATATYPE=F)

• Little-endian byte order

• No ANALYSIS segment

• No additional datasets ($NEXTDATA=0)

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:

• Keys are treated case-insensitively and leading $ is removed.

• Use strings for all values.

• Nonzero PnE values are invalid for floating-point output; FlowIO writes 0,0 and emits PnEWarning.

• PnG can be supplied; otherwise it defaults to 1.0.

• PnR can be supplied; otherwise it defaults to 262144.

• The number of PnS labels must equal the number of PnN labels.

• Empty event data is supported when at least one channel is defined.

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.

• FlowIOWarning: Base warning for FlowIO warnings.

• PnEWarning: Invalid PnE supplied while creating floating-point FCS.

• FlowIOException: Base FlowIO exception.

• FCSParsingError: Parse or structural errors.

• DataOffsetDiscrepancyError: HEADER and TEXT DATA offsets disagree. It is a subclass of FCSParsingError.

• MultipleDataSetsError: A normal FlowData open encountered multiple datasets, or multi-dataset offsets were invalid.

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:

• Added Python 3.13 support and dropped 3.7/3.8

• Added NumPy and FlowData.as_array()

• Renamed the FlowData constructor argument from filename_or_handle to fcs_file

• Added the convenience attributes documented above

• Made fcs_keywords public

• Added pathlib.Path support for FlowData

• Reduced writer memory use for array.array inputs

• Accepted empty timestep values

• Added the official tutorial notebook