polars-bio

Use esta habilidade para aritmética de intervalos genômicos e I/O de arquivos de bioinformática através do Polars e DataFusion. Ela tem como alvo polars-bio 0.36.0, testada com Polars 1.44.2 no Python 3.13. O pacote upstream requer Polars >=1.37.1, PyArrow >=23.0.1,<25, DataFusion >=53,<54 e polars-config-meta >=0.3.2,<1. Mantenha este ambiente separado de pacotes que necessitam de releases incompatíveis de Arrow ou DataFusion.

uv pip install "polars-bio==0.36.0" "polars==1.44.2"
# Optional pandas interoperability (requires pandas >=3):
uv pip install "polars-bio[pandas]==0.36.0" "polars==1.44.2"

Verifique novas releases contra as notas oficiais de release e requisitos do pacote. Os exemplos abaixo com arquivos nomeados são templates: substitua arquivos reais e verifique seus esquemas. O exemplo de intervalo sintético e os pequenos round trips de formato local foram executados durante esta revisão.

Fluxo de Trabalho

1. Registre a montagem, a nomenclatura de contigs, a convenção de coordenadas, a política de strand e a unidade de análise. Nomes de contigs idênticos não provam montagens idênticas.
2. Escolha leitores por formato; BCF tem seu próprio leitor. Inspecione esquemas e metadados de origem antes de selecionar atributos ou genótipos.
3. Normalize todas as entradas para um sistema de coordenadas e valide seus limites.
4. Escolha pares de saída, contagens de hits, bases cobertas ou profundidade de leitura deliberadamente.
5. Filtre e projete preguiçosamente, então inspecione um pequeno resultado antes de escalar.
6. Valide contagens e limites de saída contra um fixture computável manualmente; preserve IDs, metadados de coordenadas e proveniência ao salvar resultados.

Contrato de Coordenadas

O padrão é 1-based fechado, incluindo leituras BED convertidas. Use use_zero_based=True em leitores genômicos para saída 0-based semiaberto. Este argumento converte posições; não é apenas um rótulo de metadados. Por exemplo, BED [0,10) se torna [1,10] por padrão e permanece [0,10) com o override. O POS do texto SAM é 1-based, enquanto BAM armazena sua posição de alinhamento internamente como 0-based. Ambos os leitores expõem a convenção de saída solicitada.

Para DataFrames construídos manualmente, rótulos de metadados existem números e não os converte. Converter fechado [s,e] para semiaberto significa s-1,e. Defina metadados apenas após a conversão. Nunca converta duas vezes.

import polars as pl
import polars_bio as pb

pb.set_option("datafusion.bio.coordinate_system_zero_based", True)
pb.set_option("datafusion.bio.coordinate_system_check", True)

query = pl.DataFrame({
    "query_id": ["q1", "q2", "q3"],
    "chrom": ["chr1", "chr1", "chr2"],
    "start": [0, 10, 0], "end": [10, 20, 10],
})
target = pl.DataFrame({
    "chrom": ["chr1", "chr1"], "start": [5, 8], "end": [12, 15],
})
for frame in (query, target):
    frame.config_meta.set(coordinate_system_zero_based=True)

pairs = pb.overlap(query, target).collect()
counts = pb.count_overlaps(query, target).collect().sort("query_id")
covered = pb.coverage(query, target).collect().sort("query_id")
assert pairs.height == 4
assert counts["count"].to_list() == [2, 2, 0]
assert covered["coverage"].to_list() == [5, 5, 0]

Requer contigs não nulos, posições inteiras e intervalos de comprimento positivo válidos (0 <= start < end na forma semiaberta), dentro da montagem escolhida. Não silenciosamente transforme pontos/inserções em intervalos não vazios: escolha a convenção biológica. Metadados de entrada incompatíveis geram CoordinateSystemMismatchError; metadados ausentes avisam e usam a configuração global por padrão, ou geram MissingCoordinateSystemError em modo estrito. Inspecione pb.get_metadata(frame) após transformações e SQL. Veja configuração.

Escolha a operação

…