FlowKit

Quando usar

Use o FlowKit para aplicar ou construir estratégias de gating de citometria, analisar lotes de amostras FCS ou reproduzir análises de espaço de trabalho do FlowJo suportadas. Ele suporta GatingML 2.0 e um subconjunto de recursos do FlowJo 10. O sucesso da importação por si só não estabelece concordância com o FlowJo.

Os exemplos e o auxiliar agrupado visam o FlowKit 1.3.2 no Python 3.13. O upstream suporta versões adicionais do Python; estas não foram exercitadas aqui. O auxiliar e os exemplos foram testados em dados FCS sintéticos, incluindo um fixture de espaço de trabalho sintético público do FlowJo 10.7.1. Eles não são validação biológica.

Instalar

Use um ambiente separado; FlowKit 1.3.2 requer NumPy >2 e pandas <3:

uv venv --python 3.13 .venv-flowkit
uv pip install --python .venv-flowkit/bin/python "flowkit==1.3.2"
.venv-flowkit/bin/python -c "import flowkit; print(flowkit.__version__)"

O pacote científico é licenciado sob BSD-3-Clause; esta habilidade é licenciada sob MIT.

Fluxo de trabalho

1. Identifique a definição da análise. Use Session para uma estratégia programática ou GatingML; use Workspace para gates específicos de amostra do FlowJo, compensação e transformações. Solicite a estratégia real ou controles quando limiares biológicos não tiverem sido fornecidos.
2. Inspecione amostras e identidades de canais. Combine rótulos de detector/PnN com matrizes de compensação e dimensões de gate; nomes de marcadores PnS podem estar vazios ou repetidos. Verifique IDs de amostra: o padrão é FCS $FIL, que pode diferir do nome do arquivo atual. Rejeite colisões de ID antes de carregar um lote.
3. Estabeleça o sistema de coordenadas. Determine se os eventos fornecidos já estão compensados. Aplique a compensação antes das transformações não lineares; combine os limiares de gate com as mesmas coordenadas transformadas ou não transformadas. Veja compensação e gating.
4. Verifique a hierarquia. Preserve gates pais e caminhos de gate completos, incluindo root. Para um estudo, revise a estabilidade de aquisição/tempo, exclusão de detritos, células únicas, viabilidade e gates de fenótipo, conforme apropriado para seu painel. Use controles de single-stain para compensação e controles negativos/FMO adequados para positividade; limiares de demonstração não são biologia transferível.
5. Analise e inspecione. Execute em todos os eventos, em seguida, verifique sobreposições de gates e QC em nível de amostra. Uma subamostra de um gráfico não é o denominador da população. Revise avisos e compare resultados importados representativos com o FlowJo.
6. Exporte contagens com denominadores e proveniência. Mantenha caminhos de gate, IDs de amostra, contagens totais de eventos, hashes de entrada, versões de pacote e a definição de análise. Mantenha réplicas biológicas identificáveis; eventos de um espécime não são réplicas experimentais independentes.

Aplicar uma estratégia existente

Defina FLOWKIT_SKILL_DIR para o diretório instalado desta habilidade. A partir da raiz do repositório, é skills/flowkit. Os caminhos abaixo representam as entradas locais do usuário.

FLOWKIT_SKILL_DIR="skills/flowkit"
uv run --no-project --python 3.13 --with "flowkit==1.3.2" \
  python "$FLOWKIT_SKILL_DIR/scripts/analyze_gates.py" \
  --gatingml gates.xml --fcs sample.fcs --output-dir results-gatingml

Para um espaço de trabalho do FlowJo, forneça todos os arquivos FCS do grupo selecionado:

uv run --no-project --python 3.13 --with "flowkit==1.3.2" \
  python "$FLOWKIT_SKILL_DIR/scripts/analyze_gates.py" \
  --workspace study.wsp --group "Study" \
  --fcs sample-a.fcs sample-b.fcs --output-dir results-workspace

O auxiliar grava gate_report.csv e provenance.json em um novo diretório. Cada linha inclui sample_event_count, parent_event_count e um population_path completo; porcentagens de pais vazios estão em branco e marcadas com relative_percent_defined=False. Ele rejeita IDs de amostra duplicados, amostras de grupo de espaço de trabalho ausentes/extras, amostras com zero eventos e estratégias sem gates. Ele usa arquivos de entrada explícitos, não segue caminhos embutidos no espaço de trabalho e é executado sem multiprocessamento ou cache de eventos transformados. Ele ainda carrega cada amostra na memória; use lotes gerenciáveis via API Python para estudos grandes.

--filename-as-id muda deliberadamente de $FIL para nomes base de arquivo. Use-o apenas quando esses nomes corresponderem à definição da análise. Veja análise de espaço de trabalho para análise de grupo parcial, interpretação de resultados e resumos de fluorescência.

Construir uma estratégia em Python

Este exemplo executável usa sample.fcs com FSC-A, FL1-A e FL2-A.

…