Przejdź do treści
Biblioteka skilli
Nauka i badania · Konwersja i formaty

alterlab-flowio

/alterlab-flowio

Odczytuje i zapisuje pliki cytometrii przepływowej FCS w wersjach 2.0 do 3.1, wyciąga dane zdarzeń jako tablice NumPy, metadane i definicje kanałów oraz konwertuje je do CSV lub pandas.

Licencja
MIT
Ostatnia zmiana repozytorium
23.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
6
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 23.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Odczytuje i zapisuje pliki cytometrii przepływowej FCS w wersjach 2.0 do 3.1, wyciąga dane zdarzeń jako tablice NumPy, metadane i definicje kanałów oraz konwertuje je do CSV lub pandas.

Oryginalny opis (EN)

Parse and write FCS (Flow Cytometry Standard) files v2.0-3.1 with FlowIO — extract event data as NumPy arrays, read $-keyword metadata and channel/parameter definitions, and convert events to CSV or pandas DataFrame. Use when loading raw .fcs flow-cytometry files, inspecting channels and metadata, or preprocessing cytometry data for downstream gating and analysis. Part of the AlterLab Academic Skills suite.

Jak działa

  1. Overview
  2. When to Use This Skill
  3. Installation
  4. Quick Start
  5. Core Workflow
  6. Routing Guidance
  7. References
  8. Summary
Sekcje z nagłówków SKILL.md, w oryginale · 122 linii, 675 słów
Podgląd SKILL.md
---
name: alterlab-flowio
description: Parse and write FCS (Flow Cytometry Standard) files v2.0-3.1 with FlowIO — extract event data as NumPy arrays, read $-keyword metadata and channel/parameter definitions, and convert events to CSV or pandas DataFrame. Use when loading raw .fcs flow-cytometry files, inspecting channels and metadata, or preprocessing cytometry data for downstream gating and analysis. Part of the AlterLab Academic Skills suite.
license: MIT
allowed-tools: Read Write Edit Bash(python:*) Bash(uv:*)
compatibility: "Self-contained — runs under `uv run python` with `flowio` installed (1.4.0 as of 2026-09; Python 3.9+, NumPy is the only dependency). No API key or account required."
metadata:
    skill-author: AlterLab
    version: "1.0.1"
    last_updated: "2026-09-23"
---

# FlowIO: Flow Cytometry Standard File Handler

## Overview

FlowIO is a lightweight Python library for reading and writing Flow Cytometry
Standard (FCS) files. Parse FCS metadata, extract event data, and create new FCS
files with minimal dependencies. Supports FCS versions 2.0, 3.0, and 3.1 —
ideal for backend services, data pipelines, and basic cytometry file operations.

## When to Use This Skill

Use this skill when:

- FCS files require parsing or metadata extraction
- Flow cytometry data needs conversion to NumPy arrays
- Event data requires export to FCS format
- Multi-dataset FCS files need separation
- Channel information (scatter, fluorescence, time) must be extracted
- Cytometry files need validation or inspection
- Pre-processing is needed before advanced analysis

**Related tool:** For advanced analysis (compensation, transformation, gating,
FlowJo 10 workspace import), recommend the **FlowKit** library (1.3.2 as of 2026-09),
which is built on FlowIO by the same author.

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| Compensation, transforms, gating, or FlowJo/GatingML workspaces | FlowKit (companion library, not a skill in this suite) |
| Clustering / dimensionality reduction of cytometry events | `alterlab-scanpy`, `alterlab-umap` |
| Statistical comparison of populations across samples | `alterlab-statistical-analysis` |
| Mass-cytometry or imaging-based spatial single-cell data | `alterlab-squidpy-spatial` |
| Registering and versioning the FCS files themselves | `alterlab-lamindb` |

## Installation

```bash
uv pip install flowio     # 1.4.0 as of 2026-09
```

Requires Python 3.9 or later; NumPy is the only runtime dependency.

## Quick Start

```python
from flowio import FlowData

# Read FCS file and inspect
flow = FlowData('experiment.fcs')
print(f"FCS Version: {flow.version}")
print(f"Events: {flow.event_count}")
print(f"Channels: {flow.pnn_labels}")

# Get event data as NumPy array, shape (events, channels)
events = flow.as_array()
```

```python
import numpy as np
from flowio import create_fcs

# Write a new FCS file from a NumPy array.
# Gotcha: create_fcs takes a WRITABLE BINARY FILE HANDLE (not a path) and a
# FLATTENED 1-D event array — pass data.flatten(), not the 2-D matrix.
data = np.array([[100, 200, 50], [150, 180, 60]], dtype='float32')  # 2 events, 3 channels
with open('output.fcs', 'wb') as fh:
    create_fcs(fh, data.flatten(), ['FSC-A', 'SSC-A', 'FL1-A'])
```

## Core Workflow

1. **Read** — Construct a `FlowData('file.fcs')` instance. Use `only_text=True`
   for metadata-only (memory-efficient) reads; pass offset/null-channel flags
   for problematic files.
2. **Inspect** — Read `flow.version`, `flow.event_count`, `flow.pnn_labels`,
   `flow.pns_labels`, channel-type indices, and the `flow.text` metadata dict.
3. **Extract** — Get a NumPy array via `flow.as_array()` (preprocessed) or
   `flow.as_array(preprocess=False)` (raw). Slice by channel type as needed.
4. **Transform / export** — Convert to a pandas DataFrame or CSV; or write a new
   FCS file with `flow.write_fcs(path, ...)` (takes a path) or `create_fcs(fh,
   data.flatten(), ...)` (takes a binary file handle + flattened events). Output
   is always FCS 3.1, single-precision float.
5. **Multi-dataset** — If a file holds multiple datasets, use
   `read_multiple_data_sets()` instead of the constructor.

## Routing Guidance

- **Need exact signatures, attributes, exceptions, or FCS keyword definitions?**
  Read `references/api_reference.md`.
- **Doing one of the core operations (read/parse, metadata, create, export,
  multi-dataset, preprocessing)?** Read `references/workflows.md` for full code.
- **Need a task recipe (inspect a file, batch a directory, FCS→CSV, filter
  events, extract channels)?** Read `references/recipes.md`.
- **Hitting an error, or want best practices / file-structure / troubleshooting?**
  Read `references/error-handling-and-troubleshooting.md`.

## References

- `references/api_reference.md` — Complete `FlowData` class, utility functions
  (`read_multiple_data_sets`, `create_fcs`), exception classes, FCS file
  structure, common TEXT-segment keywords, channel types, and example workflows.
- `references/workflows.md` — Full code for the core operations: reading/parsing,
  metadata & channel extraction, creating files, exporting/modifying,
  multi-dataset handling, and data preprocessing.
- `references/recipes.md` — Worked examples: inspecting contents, batch
  processing a directory, FCS→CSV conversion, event filtering & re-export, and
  channel extraction with statistics.
- `references/error-handling-and-troubleshooting.md` — Exception-handling
  patterns, best practices, FCS file-structure notes, a troubleshooting table,
  and integration notes (NumPy, pandas, FlowKit, web apps).

## Summary

FlowIO provides essential FCS file handling for flow cytometry workflows — use
it for parsing, metadata extraction, and file creation. For simple file
operations and data extraction, FlowIO alone is sufficient; for complex analysis
(compensation, gating), integrate with FlowKit or other specialized tools.

Part of the AlterLab Academic Skills suite.
Pliki w paczce (6)
  • SKILL.md 6 KB
  • evals/evals.json 5 KB
  • references/api_reference.md 11 KB
  • references/error-handling-and-troubleshooting.md 4 KB
  • references/recipes.md 4 KB
  • references/workflows.md 7 KB

Wersje

W bazie nie ma innych skilli o nazwie alterlab-flowio.

Migawka bazy z 13.11.2026 · wersja paczki bcfac7958269 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100flowio
    Czyta, sprawdza i zapisuje pliki FCS 2.0, 3.0 i 3.1 z cytometrii przepływowej przez FlowIO, w tym eksport do tabel i zdarzenia do NumPy.
  • 95bio-flow-cytometry-fcs-handling
    Czyta, sprawdza i zapisuje pliki FCS z cytometrii konwencjonalnej, spektralnej i CyTOF oraz parsuje przestrzenie robocze FlowJo, Cytobank i Diva w R (flowCore) i Pythonie (FlowKit).
  • 100flowkit
    Analizuje dane cytometrii przepływowej: kompensację, transformacje, bramkowanie i odtwarzanie analiz z FlowJo w Pythonie.
  • 95bio-workflows-cytometry-pipeline
    Prowadzi analizę cytometrii przepływowej, spektralnej i CyTOF od plików FCS do różnicowo obecnych populacji komórek w flowCore, CATALYST i diffcyt.
  • 100alterlab-dask
    Skaluje przepływy pandas i NumPy poza pamięć operacyjną dzięki Dask: równoległe ramki danych, tablice, grafy zadań i wykonanie na klastrach.
  • 100lasio
    Czyta, zapisuje i zmienia pliki LAS (Log ASCII Standard) z danymi otworowymi, wyciąga nagłówki i krzywe, konwertuje do DataFrame, CSV i Excela oraz radzi sobie z wadliwymi plikami.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.