Coordenadas Genômicas

Quando usar

Sempre que uma coordenada cruzar uma fronteira: entre dois formatos de arquivo, entre duas ferramentas, entre duas montagens, ou entre o genoma e um transcrito.

A regra

Uma coordenada são três fatos, não um: o número, a convenção em que está escrita e a montagem contra a qual foi medida. Carregue os três ou o número não é interpretável.

Erros de coordenada são a classe mais silenciosa de bug em genômica. Um arquivo BED com um número a mais ou a menos é analisado, classificado e intersectado sem reclamações. Um VCF GRCh37 unido contra uma anotação GRCh38 retorna linhas. Um indel deslocado para a direita simplesmente falha em corresponder à sua entrada no ClinVar, e o resultado é uma variante relatada como nova. Nada gera um erro; a resposta está simplesmente errada, e está errada em uma direção que parece plausível.

Portanto: converta com a tabela, não de memória, e verifique contra a referência sempre que uma referência estiver disponível.

As duas conversões

1-based inclusive  ->  0-based half-open :  start - 1,  end
0-based half-open  ->  1-based inclusive :  start + 1,  end

Essas fórmulas se aplicam a intervalos não vazios na mesma referência e fita. Elas não codificam inserções, contornos circulares, liftover ou mapeamento de transcritos.

Qual formato é qual

Ambos os formatos "MAF" existem, significam coisas diferentes e discordam. O UCSC serve arquivos 0-baseados através de uma caixa de navegador 1-baseada. references/format-conventions.md tem a tabela completa com detalhes por formato.

cd skills/genomic-coordinates/scripts

python3 convert_coords.py --list                          # the table
python3 convert_coords.py --from bed --to gff chr1 999 1000
python3 convert_coords.py --from ucsc --to bed "chr7:5,530,601-5,530,625"
python3 convert_coords.py --from granges --to pyranges --input regions.tsv

contig  input                 output           length  status  detail
chr7    chr7:5530601-5530625  5530600-5530625  25      ok

Recursos BED de comprimento zero (chromStart == chromEnd, um ponto de inserção legal) são relatados como unrepresentable para um alvo inclusivo porque o conversor não possui semântica de recurso. O GFF3 pode codificar locais de inserção com extremidades iguais e um tipo de recurso; isso é diferente de um intervalo comum de base única. O código de saída é 1 para saída inválida ou não representável; saída semiaberta de comprimento zero válida sai com 0. A saída é uma tabela diagnóstica TSV/JSON, não um GFF/VCF reescrito.

--input analisa BED/bedGraph, GFF/GTF, intervalos REF VCF de alelos literais, strings de região explícitas e TSVs GRanges/PyRanges/Python de três colunas. Outras linhas de tabela são apenas convenções: extraia um intervalo com um analisador nativo e passe um triplo. Todos os leitores de texto empacotados esperam arquivos não compactados.

Variantes não são intervalos

Para um indel VCF simples, POS normalmente identifica a base de preenchimento inalterada antes do evento. Na posição 1 da contagem, o preenchimento pode seguir o evento. Substituições complexas não precisam ter uma âncora inalterada. E a mesma alteração pode ser escrita de várias maneiras: chr1:7:CAC:C, chr1:3:CAC:C e chr1:2:GCA:G são uma deleção. Unir, deduplicar ou procurar variantes antes de normalizar perde correspondências reais silenciosamente, e as perde preferencialmente em repetições, onde os indels se concentram.

Normalizar — aparar para parcimônia, depois alinhar à esquerda contra a referência — antes de qualquer comparação:

python3 normalize_variant.py --fasta ref.fa chr1 7 CAC C
python3 normalize_variant.py --fasta ref.fa --split --input cohort.vcf
python3 normalize_variant.py --fasta ref.fa --compare chr1:7:CAC:C chr1:2:GCA:G

input         normalized    type      pos_shift  ref_check  changed
chr1:7:CAC:C  chr1:2:GCA:G  deletion  5          ok         yes

Alelos literais são verificados contra o FASTA usando nomes de contagem exatos. Um MISMATCH pode indicar um erro de montagem, sequência, fita ou coordenada; pare e investigue com check_contigs.py e proveniência da sequência. O auxiliar rejeita listas ALT não divididas: use --split para chaves de alelos normalizadas independentemente. Seu TSV descarta genótipos e anotações; use bcftools norm para produção

…