OneKGPd

OneKGPd: Consultas a Nivel Individual sobre el Proyecto 1000 Genomas

Alcance

Esta habilidad consulta el conjunto de datos del Proyecto 1000 Genomas (1000 Genomes Project), la cohorte extendida de alta cobertura de 3,202 individuos con genoma completo secuenciado, en el ensamblaje GRCh38. Todos los resultados provienen de esta cohorte, y los nombres de las muestras devueltos por la habilidad (por ejemplo, HG00096 o NA21130) identifican a sus participantes.

Las consultas se resuelven contra los datos de genotipo por individuo de la cohorte. Esto admite dos clases complementarias de preguntas: seleccionar variantes portadas dentro de una región (en toda la cohorte o dentro de un conjunto específico de individuos) y seleccionar los individuos que portan variantes que cumplen con criterios específicos. La selección de variantes se puede filtrar por frecuencia alélica, consecuencia predicha, significancia clínica, clasificación AlphaMissense y otros ejes de anotación que se enumeran a continuación. También está disponible el parentesco entre dos individuos nombrados.

El estado de genotipo en el que se porta una variante (heterocigoto u homocigoto) es un criterio que las consultas pueden especificar; los resultados se devuelven como variantes o nombres de muestra, no como genotipos brutos.

Cuándo Usar

Usa esta habilidad cuando necesites:

• Encontrar variantes portadas en una región o conjunto de regiones que coincidan con algún criterio en toda la cohorte (select-variants).
• Encontrar variantes portadas en una región o conjunto de regiones que coincidan con algún criterio en un conjunto específico de individuos (select-variants-in-samples).
• Encontrar qué individuos del Proyecto 1000 Genomas portan variantes que coincidan con algún criterio en una región o conjunto de regiones (select-samples).
• Contar cuántos individuos portan variantes específicas (count-samples).
• Restringir cualquier consulta de variantes a portación solo heterocigota o solo homocigota, o consultar ambas juntas (predeterminado).
• Identificar qué individuos son homocigotos de referencia en una sola posición (select-samples-hom-ref).
• Determinar el parentesco entre dos individuos nombrados del Proyecto 1000 Genomas: tanto el grado (gemelo / 1.º / 2.º / 3.º / no relacionado) como el coeficiente de parentesco KING (kinship).
• Obtener totales del conjunto de datos: recuento de muestras, división por sexo, recuento de variantes, ensamblaje (dataset-info).
• La selección de variantes se puede especificar mediante la frecuencia alélica de KGP, la frecuencia alélica del exoma de gnomAD 4.1 y del genoma de gnomAD 4.1, la Puntuación AlphaMissense y la Clase AlphaMissense, la significancia de ClinVar (202502), y las anotaciones de VEP (impacto, biotipo, tipo de característica, clase de variante, consecuencias).

NO uses esta habilidad para:

• Resolver un símbolo de gen, rsID o transcrito a coordenadas, u obtener la secuencia de referencia. Primero resuelve las coordenadas (ver Procedencia de Coordenadas más abajo), luego consulta esta habilidad con la región GRCh38 resuelta.
• Cualquier cohorte que no sea el Proyecto 1000 Genomas: esta habilidad solo sirve para ese conjunto de datos.

Requisitos Previos

1. uv: El script de esta habilidad se ejecuta con uv run, que lee los metadatos de dependencias en línea del script y aprovisiona un entorno efímero. Asegúrate de que uv esté instalado y en el PATH (https://docs.astral.sh/uv/).
2. Términos de uso de datos: Los datos del Proyecto 1000 Genomas son abiertos; los usuarios deben conocer los términos de uso de datos del Proyecto 1000 Genomas / IGSR (https://www.internationalgenome.org/data).
3. Restricciones de acceso: No hay clave de API, archivo .env ni token de límite de tasa que configurar.
4. No se requieren credenciales

Reglas Principales

• Usa los Wrappers: SIEMPRE ejecuta los scripts auxiliares proporcionados en lugar de construir tus propias llamadas de cliente o solicitudes de red. Usa scripts/onekgpd_api.py para consultas de variantes/muestras/parentesco (maneja la conexión, transmisión, paginación y serialización JSON), y scripts/onekgpd_meta.py para metadatos de muestras/poblaciones (sin conexión, ver Metadatos de muestra y población).
• Las coordenadas DEBEN resolverse primero contra una fuente autorizada — ver Procedencia de Coordenadas. Esto es obligatorio, no opcional.
• Cuenta antes de seleccionar: cada selección de variante y muestra tiene un comando de conteo emparejado. Ejecuta el comando de conteo PRIMERO para dimensionar el conjunto de resultados, luego selecciona solo si el conteo es manejable.
• La cigosidad predeterminada es ambas: los comandos de selección y conteo incluyen tanto la portación heterocigota como homocigota de forma predeterminada. Limita con --het-only o --hom-only cuando la pregunta sea específicamente sobre un estado. (No necesitas pasar nada para obtener ambas).
• Salida: los scripts escriben JSON completo en un archivo (--output, por defecto en /tmp/) e imprimen un resumen conciso en la salida estándar. No leas archivos JSON grandes en el contexto — usa jq o un pequeño fragmento desechable de uv run python para extraer campos.

Procedencia de Coordenadas (PASO OBLIGATORIO PREVIO)

Antes de cualquier consulta basada en regiones, resuelve el gen o característica a coordenadas GRCh38 contra una fuente autorizada (por ejemplo, Ensembl), y consulta con esas coordenadas resueltas. El ensamblaje debe ser explícito, y un rango de genes debe resolverse a posiciones precisas antes de su uso. Esto es estructural, no opcional: no hay una barrera de seguridad del lado de la fuente que detecte una región mal colocada, por lo que una coordenada no verificada produce resultados para una ubicación no deseada sin ningún error.

# Resuelve el símbolo del gen -> región GRCh38 con una fuente autorizada PRIMERO,
# luego pasa las coordenadas verificadas a la consulta OneKGPd a continuación.

[!CAUTION] El conjunto de datos es GRCh38. Una coordenada GRCh37, o cualquier región que no corresponda correctamente a la característica prevista en GRCh38, devolverá resultados para una ubicación no deseada sin generar un error. Verifica el ensamblaje y las coordenadas resueltas antes de consultar.

Guía de Selección de Comandos

Relaciona la pregunta con el comando. Los comandos de conteo son económicos y deben preceder a su contraparte de selección.

• Qué individuos portan variantes coincidentes en una región → count-samples luego select-samples
• Qué variantes se portan en una región, en toda la cohorte → count-variants luego select-variants
• Qué variantes se portan en una región, dentro de un conjunto nombrado de individuos → count-variants-in-samples luego select-variants-in-samples
• Quién es homocigoto de referencia en una sola posición → count-samples-hom-ref luego select-samples-hom-ref
• Parentesco (grado + coeficiente) entre dos individuos nombrados → kinship
• Totales del conjunto de datos (recuento de muestras, división por sexo, total de variantes, ensamblaje) → dataset-info

Filtros de anotación (compartidos entre la selección/recuento de variantes y muestras)

Todos los comandos de selección y recuento de variantes y muestras (count-variants, select-variants, sus formas -in-samples, count-samples, select-samples) aceptan los mismos filtros de anotación. Diferentes campos de filtro se combinan con AND; múltiples valores dentro de un campo se combinan con OR. Los valores de enumeración no distinguen entre mayúsculas y minúsculas (por ejemplo, missense_variant o MISSENSE_VARIANT).

Estos son criterios de selección aplicados en el servidor. Los campos devueltos en una variante seleccionada se enumeran en Comandos que devuelven variantes; un criterio utilizado para el filtrado no necesariamente se repite en la variante devuelta.

• --af-lt / --af-gt: límites de frecuencia alélica del conjunto de datos de 1000 Genomas
• --gnomad-exomes-af-lt / --gnomad-exomes-af-gt: límites de FA del exoma de gnomAD v4.1
• --gnomad-genomes-af-lt / --gnomad-genomes-af-gt: límites de FA del genoma de gnomAD v4.1
• --clin-significance: términos de significancia de ClinVar, CSV (por ejemplo, PATHOGENIC,LIKELY_PATHOGENIC)
• --consequence: términos de consecuencia de Sequence Ontology, CSV (por ejemplo, MISSENSE_VARIANT,STOP_GAINED)
• --impact: impacto de VEP, CSV (HIGH,MODERATE,LOW,MODIFIER)
• --variant-type, --feature-type, --bio-type: clase de variante SO / característica VEP / biotipo VEP, CSV
• --alpha-missense-class: AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS (CSV)
• --alpha-missense-score-lt / --alpha-missense-score-gt: límites de puntuación AlphaMissense
• --biallelic-only / --multiallelic-only
• --exclude-males / --exclude-females
• --min-len-bp / --max-len-bp: límites de longitud del alelo alternativo (pb)

[!NOTE] --alpha-missense-class y --alpha-missense-score-* son mutuamente excluyentes (el motor ignora la clase cuando se establece un límite de puntuación). --biallelic-only y --multiallelic-only son mutuamente excluyentes. --exclude-males y --exclude-females son mutuamente excluyentes. Establecer un límite *-gt mayor o igual que su límite *-lt correspondiente define un rango vacío y no devolverá nada.

[!NOTE] Los campos de frecuencia alélica usan 0.0 para significar "no presente en esa fuente". Por lo tanto, --gnomad-exomes-af-gt 0 selecciona variantes que están en exomas de gnomAD; un gnomad_exomes_af devuelto de 0.0 significa que la variante está ausente de los exomas de gnomAD. La misma convención para la FA del genoma de gnomAD. Por el contrario, los límites --gnomad-exomes-af-lt / --gnomad-genomes-af-lt incluyen variantes no anotadas: "FA < X en gnomAD" incluye variantes con FA de gnomAD = 0, es decir, no anotadas; combínalo con --gnomad-*-af-gt 0 para requerir presencia en gnomAD.

[!NOTE] am_score de 0.0 significa que no ha sido puntuado o anotado por AlphaMissense - no significa benigno. Una puntuación real de AlphaMissense siempre es mayor que 0.

Inicio Rápido

# Paso 1. Resuelve coordenadas contra una fuente autorizada — ver Procedencia de Coordenadas.
#    ejemplo: BRCA1: chr17:43044292-43170245
# Paso 2. Dimensiona el conjunto de resultados: ¿cuántos individuos portan variantes
#    de cambio de sentido (missense) probablemente patogénicas en esta región?
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
# Paso 3. Si el recuento es manejable, enumera esos individuos.
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
# Paso 4: Para ese conjunto de individuos, observa las variantes reales que portan.
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 escribe JSON completo en un archivo (--output RUTA, por defecto un archivo temporal) e imprime un resumen conciso en la salida estándar. Todos los comandos de región/muestra comparten: la entrada de región (--chrom/--start/--end con --ref/--alt opcional, o una o más --region CHR:START-END repetidas), las banderas de cigosidad (--het-only/--hom-only, por defecto ambas), y los filtros de anotación anteriores. Las tablas completas por bandera se encuentran en references/onekgpd_commands.md.

Comandos que devuelven variantes

select-* devuelve variantes coincidentes; count-* devuelve un recuento entero.

• count-variants — cuenta variantes en una región, en toda la cohorte.
• select-variants — selecciona variantes en una región, en toda la cohorte. Usa --limit N (límite máximo, predeterminado 200) o --page-size N (recupera el conjunto completo en páginas); los dos son mutuamente excluyentes. La salida indica truncated cuando se alcanza el límite.
• count-variants-in-samples — como count-variants, restringido a --samples NOMBRE1,NOMBRE2,... (requerido).
• select-variants-in-samples — como select-variants, restringido a --samples NOMBRE1,NOMBRE2,... (requerido).

Cada variante devuelta lleva estas 22 claves: 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. La significancia de ClinVar y la consecuencia de VEP son solo criterios de filtro y no se devuelven. Esquema completo: references/onekgpd_commands.md.

Comandos que devuelven muestras

• count-samples — cuenta individuos que portan una variante coincidente en una región.
• select-samples — enumera los nombres de los individuos que portan una variante coincidente. Soporta --skip N y --limit N. Devuelve solo nombres; para ver qué variantes calificaron a un individuo, introduce los nombres en select-variants-in-samples.

Comandos de homocigotos de referencia

Posición única mediante --chrom + --position (no una región).

• count-samples-hom-ref — cuenta individuos con una llamada 0/0 en la posición. El recuento es un valor centinela: -1 = no existe ninguna variante en esa posición; 0 = existe una variante pero ningún individuo es homocigoto de referencia; >0 = el número de individuos homocigotos de referencia. El resumen indica qué caso.
• select-samples-hom-ref — enumera los individuos con una llamada 0/0 en la posición.

Comando de parentesco

• kinship --sample1 NOMBRE --sample2 NOMBRE — parentesco entre dos individuos nombrados: el grado (TWINS_MONOZYGOTIC / FIRST_DEGREE / SECOND_DEGREE / THIRD_DEGREE / UNRELATED) y el coeficiente de parentesco KING (phi_bwf).

Comando de metadatos del conjunto de datos

• dataset-info — totales del conjunto de datos: samples_total (3,202), desglose femenino/masculino, variants_total, assembly (GRCh38) y el desglose de la cohorte. No requiere región; funciona como verificación de conectividad.

Metadatos de muestra y población (sin conexión)

Las preguntas sobre población, sexo, pedigrí y superpoblación son respondidas por un segundo script, scripts/onekgpd_meta.py, a partir de un archivo de datos incluido en la habilidad — sin red, sin credenciales, sin coordenadas. Los IDs de muestra son los mismos nombres que usan los comandos de variantes, por lo que las dos capas se combinan (por ejemplo, selecciona una cohorte por población, luego consulta sus variantes). Ejecuta uv run scripts/onekgpd_meta.py <command>.

La cohorte tiene 5 superpoblaciones (AFR, AMR, EAS, EUR, SAS) y 26 poblaciones.

Referencias

• Referencia completa de comandos: tablas detalladas de todos los parámetros de la línea de comandos.
• Referencia de metadatos de muestra: comandos y columnas para onekgpd_meta.py.
• Sitio web del Proyecto 1000 Genomas: https://www.internationalgenome.org/