FlowIO

Propósito

Use o FlowIO como um leitor e gravador leve e de baixo nível para arquivos do padrão Flow Cytometry Standard (FCS). Os exemplos nesta habilidade visam o FlowIO 1.4.0, a versão estável atual verificada em 30/09/2026. Testes independentes do FlowIO usaram Python 3.13, NumPy 2.5.3 e pandas 3.0.6.

O FlowIO é apropriado para:

• Ler arquivos FCS 2.0, 3.0 e 3.1
• Inspecionar metadados de HEADER, TEXT, ANALYSIS e canais
• Recuperar dados de eventos como um array NumPy bidimensional
• Ler arquivos legados que contêm múltiplos conjuntos de dados
• Gravar arquivos FCS 3.1 em modo lista, de precisão simples
• Preparar dados para pandas, machine learning ou ferramentas de citometria downstream

O FlowIO não realiza compensação, transformações logicle/biexponenciais, gating, clustering ou processamento de workspaces do FlowJo. Use o FlowKit ou outro pacote de análise para essas tarefas.

Instalação

Crie ou ative um ambiente Python, então instale a versão verificada:

uv pip install "flowio==1.4.0"

Confirme a versão de tempo de execução:

uv run python -c "import flowio; print(flowio.__version__)"

O FlowIO 1.4.0 suporta Python 3.9 a 3.13 e depende do NumPy.

Fluxo de Operação

1. Clarifique a operação. Distinga o inventário de metadados, a extração de eventos, o reparo de arquivos, a conversão e a análise biológica downstream.
2. Inspecione antes de carregar eventos. Use only_text=True para trabalhos apenas de metadados, especialmente com arquivos grandes ou desconhecidos.
3. Escolha a semântica de eventos explicitamente. Use as_array(preprocess=True) para escalonamento de ganho/log/tempo a partir de metadados FCS, ou preprocess=False para valores DATA decodificados sem essas etapas de escalonamento. Registre a escolha.
4. Mantenha a análise estrita por padrão. Não suprima automaticamente erros de offset. Relaxe as verificações apenas para um defeito conhecido no formato do fornecedor e revise os dados de eventos resultantes.
5. Trate metadados como potencialmente sensíveis. Valores TEXT do FCS podem incluir identificadores de amostra, sujeito, operador e instrumento. Exporte apenas os campos necessários para a tarefa.
6. Valide as gravações reabrindo-as. Verifique contagens de eventos/canais, rótulos, metadados e valores representativos após qualquer exportação FCS.

Semânticas Críticas

Chaves TEXT são normalizadas

FlowData.text armazena chaves em minúsculas e remove o $ inicial das palavras-chave padrão do FCS:

from flowio import FlowData

flow = FlowData("sample.fcs", only_text=True)
acquisition_date = flow.text.get("date")
instrument = flow.text.get("cyt")
next_dataset = int(flow.text.get("nextdata", "0"))

Não procure por "$DATE", "$CYT" ou outras chaves com prefixo de dólar em maiúsculas. Valores TEXT permanecem strings. O FlowIO 1.4.0 também remove todo caractere $ do segmento TEXT decodificado, incluindo caracteres $ dentro dos valores; preserve o arquivo original quando a fidelidade exata dos metadados for importante.

Eventos têm duas representações

• flow.events é o array de eventos unidimensional decodificado e achatado. A análise de inteiros já aplica máscaras de intervalo PnR; esta não é uma cópia em nível de byte das palavras DATA originais.
• flow.as_array() retorna um array NumPy float64 com uma coluna por canal. Para entrada válida, sua forma é (event_count, channel_count), mas o FlowIO infere linhas de DATA e não impõe $TOT; verifique a forma.
• flow.as_array(preprocess=True) aplica escalonamento de ganho, logarítmico e de tempo do FCS. Não aplica compensação ou transformações de exibição logicle/biexponenciais.
• flow.as_array(preprocess=False) remodela os valores de eventos decodificados sem essas etapas de escalonamento. Um canal Time reconhecido e não nulo (case-insensitive) tem seu ganho forçado para 1.0 pelo FlowIO; timestep ainda se aplica ao pré-processamento.

as_array() cria outro array em memória. O FlowIO não fornece acesso a eventos fragmentados ou mapeados em memória.

Numeração de canais usa duas convenções

• Colunas NumPy e fluoro_indices, scatter_indices e time_index usam índices baseados em zero.
• flow.channels usa números de parâmetro FCS começando em 1.
• null_channels contém as strings de rótulo PnN fornecidas através de null_channel_list, incluindo rótulos fornecidos que não foram encontrados.
• pns_labels sempre corresponde a pnn_labels em comprimento; rótulos PnS opcionais ausentes aparecem como strings vazias.

Gravação é intencionalmente limitada

create_fcs() requer:

• Um handle de arquivo binário já aberto
• Dados de eventos unidimensionais achatados em ordem de evento/canal em linha principal
• Um nome PnN por canal
• Nomes PnS opcionais e metadados com valores de string via metadata_dict

…