OneKGPd: Consultas em Nível de Indivíduo sobre o Projeto 1000 Genomas

Escopo

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

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

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

O serviço público é TLS gRPC em db.dnaerys.org:443, acessado com dnaerys 0.2.1 (Python 3.11+); não é uma URL base REST. O instantâneo mantido do serviço anuncia VEP 115 / GENCODE 49, ClinVar 202502 e gnomAD 4.1. Estas são as versões de anotação do serviço, não a versão mais recente de cada recurso upstream. Registre-as ao interpretar os resultados.

Quando Usar

Use esta habilidade quando precisar:

• Encontrar variantes carregadas em uma região ou conjunto de regiões que correspondam a alguns critérios em toda a coorte (select-variants).
• Encontrar variantes carregadas em uma região ou conjunto de regiões que correspondam a alguns critérios em um conjunto específico de indivíduos (select-variants-in-samples).
• Encontrar quais indivíduos do 1000 Genomas carregam variantes que correspondem a alguns critérios 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 portadores apenas heterozigotos ou apenas homozigotos, 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 a relação entre dois indivíduos nomeados do 1000 Genomas — tanto o grau (gêmeo / 1º / 2º / 3º / não relacionado) 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 por frequência alélica KGP, exoma gnomAD 4.1 e frequência alélica do genoma gnomAD 4.1, Pontuação AlphaMissense e Classe AlphaMissense, significado ClinVar (202502) e anotações VEP (impacto, biotipo, tipo de característica, classe de variante, consequências).

NÃO use esta habilidade para:

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

Pré-requisitos

1. uv: O script desta habilidade é executado com uv run, que lê os metadados de dependência inline do script e provisiona um ambiente efêmero. Certifique-se de que uv esteja instalado e no PATH (https://docs.astral.sh/uv/).
2. Termos de uso de dados: Os dados do Projeto 1000 Genomas são abertos; os usuários devem estar cientes dos termos de uso de dados 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. Tempos limite: comandos de rede usam --timeout 30 segundos por RPC por padrão. Um tempo limite positivo e finito é permitido. A paginação faz vários RPCs e falhas recuperáveis tentam buscar novamente até três vezes, portanto, este não é um prazo para o comando inteiro.

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 variantes/amostras/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).

…