onekgpd

OneKGPd: Consultas em Nível Individual sobre o Projeto 1000 Genomas

Escopo

Este skill consulta o conjunto de dados do Projeto 1000 Genomas — a coorte estendida de alta cobertura de 3.202 indivíduos sequenciados por genoma completo, na montagem GRCh38. Todos os resultados são extraídos desta coorte, e os nomes das amostras retornados pelo skill (por exemplo HG00096 ou NA21130) identificam seus participantes.

As consultas são resolvidas com base nos dados genotípicos por indivíduo da coorte. Isso suporta duas classes complementares de perguntas: selecionar variantes carregadas dentro de uma região (em toda a coorte ou dentro de um conjunto especificado de indivíduos) e selecionar os indivíduos que carregam variantes correspondentes a critérios determinados. A seleção de variantes pode ser filtrada por frequência alélica, consequência prevista, significado clínico, classificação AlphaMissense e os outros eixos de anotação listados abaixo. O parentesco entre dois indivíduos nomeados também está disponível.

O estado genotípico no qual uma variante é carregada — heterozigoto ou homozigoto — é um critério que as consultas podem especificar; os resultados são retornados como variantes ou nomes de amostras, não como genótipos brutos.

Quando Usar

Use este skill quando precisar:

• Encontrar variantes carregadas em uma região ou conjunto de regiões que correspondam a algum critério em toda a coorte (select-variants).
• Encontrar variantes carregadas em uma região ou conjunto de regiões que correspondam a algum critério em um conjunto específico de indivíduos (select-variants-in-samples).
• Descobrir quais indivíduos do 1000 Genomas carregam variantes que correspondem a algum critério em uma região ou conjunto de regiões (select-samples).
• Contar quantos indivíduos carregam variantes específicas (count-samples).
• Restringir qualquer consulta de variante a carregamento apenas heterozigoto ou apenas homozigoto, ou consultar ambos juntos (padrão).
• Identificar quais indivíduos são homozigotos de referência em uma única posição (select-samples-hom-ref).
• Determinar o parentesco entre dois indivíduos nomeados do 1000 Genomas — tanto o grau (gêmeo / 1º / 2º / 3º / não aparentado) quanto o coeficiente de parentesco KING (kinship).
• Obter totais do conjunto de dados — contagem de amostras, divisão por sexo, contagem de variantes, montagem (dataset-info).
• A seleção de variantes pode ser especificada pela frequência alélica KGP, frequência alélica do exoma gnomAD 4.1 e genoma gnomAD 4.1, Pontuação e Classe AlphaMissense, significado ClinVar (202502) e anotações VEP (impacto, biótipo, tipo de recurso, classe de variante, consequências).

NÃO use este skill para:

• Resolver um símbolo de gene, rsID ou transcrito para coordenadas, ou buscar sequência de referência. Resolva as coordenadas primeiro (veja Procedência de Coordenadas abaixo), depois consulte este skill com a região GRCh38 resolvida.
• Qualquer coorte que não seja o Projeto 1000 Genomas — este skill serve apenas para esse conjunto de dados.

Pré-requisitos

1. uv: O script deste skill é executado com uv run, que lê os metadados de dependência inline do script e provisiona um ambiente efêmero. Certifique-se de que o uv está instalado e no PATH (https://docs.astral.sh/uv/).
2. Termos de uso dos dados: Os dados do Projeto 1000 Genomas são abertos; os usuários devem estar cientes dos termos de uso do Projeto 1000 Genomas / IGSR (https://www.internationalgenome.org/data).
3. Restrições de acesso: Não há chave de API, nenhum arquivo .env e nenhum token de limite de taxa para configurar.
4. Nenhuma credencial necessária

Regras Principais

• Use os Wrappers: SEMPRE execute os scripts auxiliares fornecidos em vez de construir suas próprias chamadas de cliente ou requisições de rede. Use scripts/onekgpd_api.py para consultas de variante/amostra/parentesco (ele lida com a conexão, streaming, paginação e serialização JSON) e scripts/onekgpd_meta.py para metadados de amostra/população (offline, veja Metadados de amostra e população).
• As coordenadas DEVEM ser resolvidas em uma fonte autoritativa primeiro — veja Procedência de Coordenadas. Isso é obrigatório, não aconselhável.
• Conte antes de selecionar: toda seleção de variante e amostra tem um comando de contagem emparelhado. Chame o comando de contagem PRIMEIRO para dimensionar o conjunto de resultados, depois selecione apenas se a contagem for gerenciável.
• Zigosidade padrão para ambos: comandos de seleção e contagem incluem carregamento heterozigoto e homozigoto por padrão. Restrinja com --het-only ou --hom-only quando a pergunta for especificamente sobre um estado. (Você não precisa passar nada para obter ambos.)
• Saída: scripts escrevem JSON completo em um arquivo (--output, padrão em /tmp/) e imprimem um resumo conciso no stdout. Não leia arquivos JSON grandes no contexto — use jq ou um pequeno trecho descartável uv run python para extrair campos.

Procedência de Coordenadas (ETAPA OBRIGATÓRIA INICIAL)

Antes de qualquer consulta baseada em região, resolva o gene ou recurso para coordenadas GRCh38 em uma fonte autoritativa (por exemplo, Ensembl) e consulte com essas coordenadas resolvidas. A montagem deve ser explícita, e um intervalo de genes deve ser resolvido para posições precisas antes do uso. Isso é estrutural, não aconselhável: não há barreira de proteção no lado da fonte que detectaria uma região mal colocada, então uma coordenada não verificada produz resultados para um local não intencional sem erro.

# Resolver símbolo do gene -> região GRCh38 com uma fonte autoritativa PRIMEIRO,
# em seguida, passar as coordenadas verificadas para a consulta OneKGPd abaixo.

[!CAUTION] O conjunto de dados é GRCh38. Uma coordenada GRCh37, ou qualquer região que não corresponda corretamente ao recurso pretendido no GRCh38, retornará resultados para um local não intencional sem gerar um erro. Verifique a montagem e as coordenadas resolvidas antes de consultar.

Guia de Seleção de Comandos

Combine a pergunta ao comando. Comandos de contagem são baratos e devem preceder sua contraparte de seleção.

• Quais indivíduos carregam variantes correspondentes em uma região → count-samples depois select-samples
• Quais variantes são carregadas em uma região, em toda a coorte → count-variants depois select-variants
• Quais variantes são carregadas em uma região, dentro de um conjunto nomeado de indivíduos → count-variants-in-samples depois select-variants-in-samples
• Quem é homozigoto de referência em uma única posição → count-samples-hom-ref depois select-samples-hom-ref
• Parentesco (grau + coeficiente) entre dois indivíduos nomeados → kinship
• Totais do conjunto de dados (contagem de amostras, divisão por sexo, total de variantes, montagem) → dataset-info

Filtros de anotação (compartilhados entre seleção/contagem de variante e amostra)

Todos os comandos de seleção e contagem de variantes e amostras (count-variants, select-variants, suas formas -in-samples, count-samples, select-samples) aceitam os mesmos filtros de anotação. Campos de filtro diferentes são combinados com E; múltiplos valores dentro de um campo são combinados com OU. Valores de enumeração não diferenciam maiúsculas de minúsculas (por exemplo, missense_variant ou MISSENSE_VARIANT).

Estes são critérios de seleção aplicados no servidor. Os campos retornados em uma variante selecionada estão listados em Comandos que retornam variantes; um critério usado para filtragem não é necessariamente ecoado de volta na variante retornada.

• --af-lt / --af-gt: Limites de frequência alélica do conjunto de dados 1000 Genomas
• --gnomad-exomes-af-lt / --gnomad-exomes-af-gt: Limites de AF do exoma gnomAD v4.1
• --gnomad-genomes-af-lt / --gnomad-genomes-af-gt: Limites de AF do genoma gnomAD v4.1
• --clin-significance: Termos de significado ClinVar, CSV (por exemplo, PATHOGENIC,LIKELY_PATHOGENIC)
• --consequence: Termos de consequência da Ontologia de Sequência, CSV (por exemplo, MISSENSE_VARIANT,STOP_GAINED)
• --impact: Impacto VEP, CSV (HIGH,MODERATE,LOW,MODIFIER)
• --variant-type, --feature-type, --bio-type: Classe de variante SO / recurso VEP / biótipo VEP, CSV
• --alpha-missense-class: AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS (CSV)
• --alpha-missense-score-lt / --alpha-missense-score-gt: Limites de pontuação AlphaMissense
• --biallelic-only / --multiallelic-only
• --exclude-males / --exclude-females
• --min-len-bp / --max-len-bp: Limites de comprimento do alelo alternativo (pb)

[!NOTE] --alpha-missense-class e --alpha-missense-score-* são mutuamente exclusivos (o mecanismo ignora a classe quando um limite de pontuação é definido). --biallelic-only e --multiallelic-only são mutuamente exclusivos. --exclude-males e --exclude-females são mutuamente exclusivos. Definir um limite *-gt maior ou igual ao seu limite *-lt correspondente define um intervalo vazio e não retornará nada.

[!NOTE] Campos de frequência alélica usam 0.0 para significar "não presente naquela fonte." Portanto, --gnomad-exomes-af-gt 0 seleciona variantes que estão em exomas gnomAD; um gnomad_exomes_af retornado de 0.0 significa que a variante está ausente dos exomas gnomAD. A mesma convenção para AF do genoma gnomAD. Por outro lado, limites --gnomad-exomes-af-lt / --gnomad-genomes-af-lt incluem variantes não anotadas: "AF < X no gnomAD" inclui variantes com AF gnomAD = 0, ou seja, não anotadas; combine-o com --gnomad-*-af-gt 0 para exigir presença no gnomAD.

[!NOTE] am_score de 0.0 significa não pontuado ou não anotado pelo AlphaMissense - não significa benign. Uma pontuação AlphaMissense real é sempre maior que 0.

Início Rápido

# Etapa 1. Resolver coordenadas em uma fonte autoritativa — veja Procedência de Coordenadas.
#    exemplo: BRCA1: chr17:43044292-43170245
# Etapa 2. Dimensionar o conjunto de resultados: quantos indivíduos carregam variantes
#    missense previstas como provavelmente patogênicas nesta região?
uv run scripts/onekgpd_api.py count-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/count.json
# Etapa 3. Se a contagem for gerenciável, liste esses indivíduos.
uv run scripts/onekgpd_api.py select-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --consequence MISSENSE_VARIANT \
  --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/samples.json
# Etapa 4: Para esse conjunto de indivíduos, veja as variantes reais que eles carregam.
uv run scripts/onekgpd_api.py select-variants-in-samples \
  --chrom chr17 --start 43044292 --end 43170245 \
  --samples HG03169,NA20506 \
  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
  --output /tmp/variants.json

Comandos

Cada comando escreve JSON completo em um arquivo (--output PATH, padrão um arquivo temporário) e imprime um resumo conciso no stdout. Todos os comandos de região/amostra compartilham: a entrada de região (--chrom/--start/--end com --ref/--alt opcionais, ou um ou mais --region CHR:START-END repetidos), as flags de zigosidade (--het-only/--hom-only, padrão ambos), e os filtros de anotação acima. As tabelas completas por flag estão em references/onekgpd_commands.md.

Comandos que retornam variantes

select-* retorna variantes correspondentes; count-* retorna uma contagem inteira.

• count-variants — conta variantes em uma região, em toda a coorte.
• select-variants — seleciona variantes em uma região, em toda a coorte. Use --limit N (limite máximo, padrão 200) ou --page-size N (recupera o conjunto completo em páginas); os dois são mutuamente exclusivos. A flag de resumo truncated quando o limite é atingido.
• count-variants-in-samples — como count-variants, restrito a --samples NAME1,NAME2,... (obrigatório).
• select-variants-in-samples — como select-variants, restrito a --samples NAME1,NAME2,... (obrigatório).

Cada variante retornada carrega estas 22 chaves: chr, start, end, ref, alt, af, ac, an, hom_samples, het_samples, mis_samples, hom_samples_fx, het_samples_fx, mis_samples_fx, hom_samples_mxy, het_samples_mxy, mis_samples_mxy, gnomad_exomes_af, gnomad_genomes_af, am_score, amino_acids, biallelic. Significado ClinVar e consequência VEP são apenas critérios de filtro e não são retornados. Esquema completo: references/onekgpd_commands.md.

Comandos que retornam amostras

• count-samples — conta indivíduos que carregam uma variante correspondente em uma região.
• select-samples — lista os nomes dos indivíduos que carregam uma variante correspondente. Suporta --skip N e --limit N. Retorna apenas nomes; para ver quais variantes qualificaram um indivíduo, alimente os nomes em select-variants-in-samples.

Comandos de homozigoto de referência

Posição única via --chrom + --position (não uma região).

• count-samples-hom-ref — conta indivíduos com uma chamada 0/0 na posição. A contagem é um sentinela: -1 = não existe variante naquela posição; 0 = uma variante existe, mas nenhum indivíduo é homozigoto de referência; >0 = o número de indivíduos homozigotos de referência. O resumo indica qual caso.
• select-samples-hom-ref — lista os indivíduos com uma chamada 0/0 na posição.

Comando de parentesco

• kinship --sample1 NAME --sample2 NAME — parentesco entre dois indivíduos nomeados: o grau (TWINS_MONOZYGOTIC / FIRST_DEGREE / SECOND_DEGREE / THIRD_DEGREE / UNRELATED) e o coeficiente de parentesco KING (phi_bwf).

Comando de metadados do conjunto de dados

• dataset-info — totais do conjunto de dados: samples_total (3.202), divisão feminino/masculino, variants_total, assembly (GRCh38) e a distribuição da coorte. Nenhuma região necessária; funciona também como uma verificação de conectividade.

Metadados de amostra e população (offline)

Perguntas sobre população, sexo, pedigree e superpopulação são respondidas por um segundo script, scripts/onekgpd_meta.py, a partir de um arquivo de dados incluído no skill — sem rede, sem credenciais, sem coordenadas. Os IDs das amostras são os mesmos nomes que os comandos de variante usam, então as duas camadas se compõem (por exemplo, escolha uma coorte por população e depois consulte suas variantes). Execute uv run scripts/onekgpd_meta.py <command>.

A coorte tem 5 superpopulações (AFR, AMR, EAS, EUR, SAS) e 26 populações.