Skill Tracer
Skills › Scientific Agent Skills › flowio › sources.md

sources.md

108 lines · skills/flowio/references/sources.md at 5f2bc03

Open on GitHub
1# Authoritative Sources
2
3This skill was refreshed on **2026-09-30** against the sources below. Examples
4target the current stable package release at that date: **FlowIO 1.4.0**,
5published **2025-05-09**.
6
7When upstream behavior and this skill differ, prefer the tagged upstream source
8and official API documentation, then update this skill and increment its
9version.

Authoritative Sources

This skill was refreshed on 2026-09-30 against the sources below. Examples target the current stable package release at that date: FlowIO 1.4.0, published 2025-05-09.

When upstream behavior and this skill differ, prefer the tagged upstream source and official API documentation, then update this skill and increment its version.

Raw lines 1 to 10
11## Package and Release
13- [FlowIO on PyPI](https://pypi.org/project/FlowIO/) — stable version, release
14 date, supported Python classifiers, dependency metadata, and project links.
15- [FlowIO 1.4.0 release notes](https://github.com/whitews/FlowIO/releases/tag/1.4.0)
16 — Python 3.13 support, `as_array()`, constructor rename, convenience
17 attributes, NumPy dependency, public `fcs_keywords`, `Path` support, and
18 writer/timestep changes.
19- [All FlowIO releases](https://github.com/whitews/FlowIO/releases) — migration
20 and bug-fix history.
21- [FlowIO 1.4.0 tagged source](https://github.com/whitews/FlowIO/tree/1.4.0) —
22 release-tagged implementation baseline used to verify edge behavior.
23- [FlowIO 1.4.0 package metadata](https://github.com/whitews/FlowIO/blob/1.4.0/pyproject.toml)
24 — supported Python versions and NumPy dependency.

Package and Release

Raw lines 11 to 25
26## Official Documentation and User Guide
28- [FlowIO documentation](https://flowio.readthedocs.io/en/latest/) — official
29 entry point and installation overview.
30- [FlowIO tutorial](https://flowio.readthedocs.io/en/latest/notebooks/flowio_tutorial.html)
31 — official 1.4.0 user guide covering FCS segments, metadata, event values,
32 export, keyword lists, multiple datasets, creation, and exceptions.
33- [FlowIO API](https://flowio.readthedocs.io/en/latest/api.html) — generated
34 signatures and public API reference.
35- [FlowData 1.4.0 source](https://github.com/whitews/FlowIO/blob/1.4.0/src/flowio/flowdata.py)
36 — metadata normalization, offset behavior, event parsing, preprocessing, and
37 `write_fcs()`.
38- [`create_fcs` 1.4.0 source](https://github.com/whitews/FlowIO/blob/1.4.0/src/flowio/create_fcs.py)
39 — writer signature, validation, metadata rules, output representation, and
40 float precision.
41- [`read_multiple_data_sets` 1.4.0 source](https://github.com/whitews/FlowIO/blob/1.4.0/src/flowio/utils.py)
42 — relative `$NEXTDATA` traversal and invalid-offset handling.
43- [FlowIO exceptions 1.4.0 source](https://github.com/whitews/FlowIO/blob/1.4.0/src/flowio/exceptions.py)
44 — warning and exception hierarchy.

Official Documentation and User Guide

  • FlowIO documentation — official entry point and installation overview.
  • FlowIO tutorial — official 1.4.0 user guide covering FCS segments, metadata, event values, export, keyword lists, multiple datasets, creation, and exceptions.
  • FlowIO API — generated signatures and public API reference.
  • FlowData 1.4.0 source — metadata normalization, offset behavior, event parsing, preprocessing, and write_fcs().
  • [create_fcs 1.4.0 source](https://github.com/whitews/FlowIO/blob/1.4.0/src/flowio/create_fcs.py) — writer signature, validation, metadata rules, output representation, and float precision.
  • [read_multiple_data_sets 1.4.0 source](https://github.com/whitews/FlowIO/blob/1.4.0/src/flowio/utils.py) — relative $NEXTDATA traversal and invalid-offset handling.
  • FlowIO exceptions 1.4.0 source — warning and exception hierarchy.
Raw lines 26 to 45
46## Flow Cytometry Standard
48- Spidlen J, et al. [Data File Standard for Flow Cytometry, version FCS
49 3.1](https://pubmed.ncbi.nlm.nih.gov/19937951/). *Cytometry Part A*.
50 2010;77A(1):97-100.
51 [doi:10.1002/cyto.a.20825](https://doi.org/10.1002/cyto.a.20825)
52- Bray C, Spidlen J, Brinkman RR. [FCS 3.1 Implementation
53 Guidance](https://pubmed.ncbi.nlm.nih.gov/22278913/). *Cytometry Part A*.
54 2012;81(6):523-526.
55 [doi:10.1002/cyto.a.22018](https://doi.org/10.1002/cyto.a.22018)
56- [Free full text of the FCS 3.1 implementation
57 guidance](https://pmc.ncbi.nlm.nih.gov/articles/PMC3676281/) — spillover,
58 display, and compatibility guidance.
60FlowIO reads FCS 2.0/3.0/3.1 and writes FCS 3.1. The standard publications are
61needed when byte offsets, keywords, spillover metadata, or representation
62details affect scientific interpretation.

Flow Cytometry Standard

FlowIO reads FCS 2.0/3.0/3.1 and writes FCS 3.1. The standard publications are needed when byte offsets, keywords, spillover metadata, or representation details affect scientific interpretation.

Raw lines 46 to 63
64## Array and Table Behavior
66- [NumPy mean](https://numpy.org/doc/stable/reference/generated/numpy.mean.html)
67 — accumulator dtype and precision; runtime fixtures also checked overflow.
68- [pandas duplicate labels](https://pandas.pydata.org/docs/user_guide/duplicates.html)
69 — duplicate columns are permitted by default, so exports explicitly create
70 unique labels and retain positional source-label provenance.

Array and Table Behavior

  • NumPy mean — accumulator dtype and precision; runtime fixtures also checked overflow.
  • pandas duplicate labels — duplicate columns are permitted by default, so exports explicitly create unique labels and retain positional source-label provenance.
Raw lines 64 to 71
72## Higher-Level Analysis Boundary
74- [FlowKit project](https://github.com/whitews/FlowKit) — related package for
75 compensation, transformations, gating, GatingML, and FlowJo workspace
76 support.
77- [FlowKit documentation](https://flowkit.readthedocs.io/en/latest/) — use when
78 a task moves beyond low-level FCS I/O.

Higher-Level Analysis Boundary

  • FlowKit project — related package for compensation, transformations, gating, GatingML, and FlowJo workspace support.
  • FlowKit documentation — use when a task moves beyond low-level FCS I/O.
Raw lines 72 to 79
80## Verification Notes
82During this refresh:
84- PyPI, the latest GitHub release endpoint, and official documentation all
85 identified 1.4.0 as the stable release.
86- Runtime signatures were checked in an isolated `flowio==1.4.0` environment.
87- Read/write behavior was round-tripped with a generated FCS 3.1 file.
88- Runtime edge tests covered null-channel storage, literal `$` removal from
89 TEXT values, caller-owned handle closure, and PnG/`timestep` loss during
90 `write_fcs()`.
91- The tagged implementation was used where generated API prose omitted details,
92 especially metadata normalization and writer behavior.
93- Current checks ran on Python 3.13 with FlowIO 1.4.0, NumPy 2.5.3, and
94 pandas 3.0.6 using local synthetic FCS 2.0/3.0/3.1 integer, float, double,
95 and multiple-dataset files. No scientific service credentials are needed.
96- FlowIO reads DATA without enforcing the declared `$TOT`; the inspector now
97 checks loaded value count before `as_array()`. Integer range masking occurs
98 before optional preprocessing, and recognized Time-channel gain is forced
99 to one. Tagged source and independent binary fixtures verify these details.
100- Generated DataFrame names now avoid collisions with existing suffixed names;
101 extreme finite doubles no longer overflow the inspector's mean calculation.
102- The inspector rejects unsupported mode/type metadata and reports truncated
103 DATA parsing failures cleanly. Its limits are not a process-memory sandbox.
104- This is local file-format functionality, not a hosted API. There are no
105 runtime HTTP endpoints, authentication, pagination, or paid service calls.
106- Big-endian writer portability remains unverified. The 1.4.0 writer declares
107 little-endian output while using Python's native-endian `array('f')` bytes;
108 validate exports on big-endian hardware rather than assuming portability.

Verification Notes

During this refresh:

  • PyPI, the latest GitHub release endpoint, and official documentation all identified 1.4.0 as the stable release.
  • Runtime signatures were checked in an isolated flowio==1.4.0 environment.
  • Read/write behavior was round-tripped with a generated FCS 3.1 file.
  • Runtime edge tests covered null-channel storage, literal $ removal from TEXT values, caller-owned handle closure, and PnG/timestep loss during write_fcs().
  • The tagged implementation was used where generated API prose omitted details, especially metadata normalization and writer behavior.
  • Current checks ran on Python 3.13 with FlowIO 1.4.0, NumPy 2.5.3, and pandas 3.0.6 using local synthetic FCS 2.0/3.0/3.1 integer, float, double, and multiple-dataset files. No scientific service credentials are needed.
  • FlowIO reads DATA without enforcing the declared $TOT; the inspector now checks loaded value count before as_array(). Integer range masking occurs before optional preprocessing, and recognized Time-channel gain is forced to one. Tagged source and independent binary fixtures verify these details.
  • Generated DataFrame names now avoid collisions with existing suffixed names; extreme finite doubles no longer overflow the inspector's mean calculation.
  • The inspector rejects unsupported mode/type metadata and reports truncated DATA parsing failures cleanly. Its limits are not a process-memory sandbox.
  • This is local file-format functionality, not a hosted API. There are no runtime HTTP endpoints, authentication, pagination, or paid service calls.
  • Big-endian writer portability remains unverified. The 1.4.0 writer declares little-endian output while using Python's native-endian array('f') bytes; validate exports on big-endian hardware rather than assuming portability.
Raw lines 80 to 108