Referencia

Formatos de salida

get_MNV puede escribir archivos de metadatos TSV, VCF, BCF y JSON.

Salida TSV por defecto#

Nombre de archivo por defecto:

<input_name>.MNV.tsv

Con --sample all se escribe un archivo por muestra, con la muestra en el nombre:

<input_name>.sample_<MUESTRA>.MNV.tsv

Los caracteres que no pueden aparecer en un nombre de archivo se sustituyen, así que una muestra llamada sample/1:bad pasa a ser sample_1_bad. Si dos muestras quedan con el mismo nombre tras esa sustitución escribirían en un solo archivo, así que la ejecución se detiene y las nombra en vez de dejar que una sobrescriba a la otra.

Cada archivo contiene las variantes que lleva esa muestra, no todas las de la cohorte. Un registro enumera todos los ALT vistos en ese sitio en el conjunto de muestras, así que el GT de la muestra decide cuáles le corresponden: un genotipo 0/0 no lleva ninguno, 1/2 lleva los dos alelos de un registro multialélico, y un genotipo ausente o sin llamada (./.) conserva el alelo, porque desconocido no es lo mismo que ausente. Una muestra que no lleva nada recibe un archivo solo con la cabecera. Dos sustituciones contiguas se juntan en un MNV únicamente para las muestras que llevan las dos.

Usa este formato para hojas de cálculo, análisis posteriores e inspección rápida.

Columnas principales:

Columnas adicionales cuando se usa --bam:

El soporte exacto del evento tiene en cuenta el CIGAR. Una lectura debe reconstruir la misma secuencia ALT local y, en el caso de los haplotipos complejos, contener los componentes de inserción y deleción esperados. Esto evita que las combinaciones de inserción/deleción de efecto neutro se contabilicen como soporte solo porque su secuencia se parezca a un MNV.

Las columnas de frecuencia se calculan a partir del soporte de lecturas del BAM. --min-snp-frequency y --min-mnv-frequency usan estos mismos valores derivados del BAM. Los filtros son independientes: --min-snp-frequency se aplica a las observaciones de SNP individuales y --min-mnv-frequency se aplica a los haplotipos MNV en fase. En las llamadas mixtas SNP/MNV, una fila o registro VCF se conserva cuando cualquiera de los dos componentes supera su propio umbral activo. Los filtros de recuento de lecturas y de soporte de hebra (--snp, --mnv, --min-snp-strand y --min-mnv-strand) siguen el mismo comportamiento independiente para SNP y MNV.

Cuando un MNV a nivel de codón se solapa con un indel, la fila del MNV se conserva como fila de contexto posicional, pero su efecto a nivel de aminoácido se marca como Unknown con Change Type = Indel overlap. Si las lecturas del BAM respaldan el evento combinado completo, get_MNV emite una fila complex_indel exacta aparte con el REF/ALT combinado, los componentes del evento y el soporte de lecturas del evento.

El solapamiento del indel sigue la semántica interbase de VCF. Las deleciones se solapan con una característica a lo largo del tramo de referencia eliminado. Las inserciones solo se solapan con una característica cuando la secuencia insertada cae entre dos bases de referencia situadas dentro de ella, de modo que una inserción anclada en la última base de la característica se reporta fuera de esta.

Ejemplo:

Chromosome	Gene	Positions	Base Changes	AA Changes	Variant Type	Change Type
MTB_anc	Rv0095c_Rv0095c	104838	T	Asp126Glu	SNP	Non-synonymous
MTB_anc	Rv0095c_Rv0095c	104941, 104942	T, G	Gly92Gln	SNP/MNV	Non-synonymous

Salida VCF#

Escribe VCF con:

--convert

o escribe tanto TSV como VCF con:

--both

Nombre de archivo por defecto:

<input_name>.MNV.vcf

Usa --vcf-gz para obtener salida comprimida:

<input_name>.MNV.vcf.gz

Campos INFO comunes:

La cabecera del VCF registra la versión de get_MNV, la línea de comandos y los umbrales usados. Cuando --emit-filtered está habilitado, los registros VCF que quedan por debajo de los umbrales de soporte de lecturas, frecuencia, soporte de hebra o sesgo de hebra se escriben con etiquetas FILTER como LowSupport, LowFrequency, StrandSupport o StrandBias; de lo contrario, se omiten.

El campo ANN#

Cada registro lleva además su anotación en el formato que escribe snpEff, que bcftools +split-vep, SnpSift y la mayoría de herramientas de VCF leen sin conocer las claves propias de get_MNV:

bcftools +split-vep -a ANN -f '%POS\t%REF\t%ALT\t%Gene_Name\t%Annotation\t%HGVS.c\t%HGVS.p\n' sample.MNV.vcf

Cada entrada habla del ALT de su propio registro. En el registro de una base de un codón que cambia dos o más, eso es la base por sí sola, como ya dice el AA del registro; el cambio combinado del codón está en el registro del codón, marcado INFO_COMPOUND_ANNOTATION, la marca de snpEff para un efecto que sale de combinar variantes. SO, IMPACT y CT siguen siendo los del codón en todos los registros.

El rango, las posiciones en el cDNA, la CDS y la proteína y la distancia quedan vacíos. Un valor que rompería el campo va percent-encoded, como la lista de alelos de c.[274G>C%3B275G>A].

Un ANN que ya traía la entrada no se pierde con --keep-original-info: sus entradas para el ALT del registro van detrás de las de get_MNV, así que las categorías propias de snpEff de un laboratorio siguen con la base para la que se escribieron. No pasan al registro de un codón, cuyo alelo no tenía ningún registro de entrada.

La entrada del ejemplo incluido se anotó con snpEff 4.1, y en sus 802 bases que anotan los dos, la entrada de get_MNV da la misma consecuencia, impacto, HGVS.c y HGVS.p que la de snpEff salvo en dos casos: snpEff 4.1 llama también región de splicing a las últimas bases de un gen de un solo exón, y el primer codón anotado de un gen no es un codón de inicio. En las dos bases que caen en genes de ARN los dos dicen lo mismo con dos nombres para un término: non_coding_transcript_exon_variant es como Sequence Ontology renombró el non_coding_exon_variant de snpEff.

Salida BCF#

Escribe BCF con:

--bcf

BCF requiere el modo de salida VCF, así que úsalo con --convert o --both.

La conversión la hace bcftools view, tomado del PATH. Sin bcftools instalado la ejecución avisa, no escribe ningún BCF y aun así sale con 0, con su TSV y su VCF intactos. --index-vcf-gz funciona igual, a través de tabix.

Nombre de archivo por defecto:

<input_name>.MNV.bcf

Archivos JSON#

Tres flags escriben JSON, y todos los payloads llevan un schema_version para que quien los consuma sepa qué forma está leyendo.

JSON de resumen#

Escribe con:

--summary-json run.summary.json

Claves de primer nivel:

Dentro de global:

import json

data = json.load(open("run.summary.json"))
if data.get("mode") == "sample_all":
    totals = data["aggregate"]["global"]
    per_sample = {s["sample"]: s["global"] for s in data["samples"]}
else:
    totals = data["global"]
    per_sample = {data["sample"]: data["global"]}

Manifiesto de la ejecución#

Escribe con:

--run-manifest run.manifest.json

Con --sample all el manifiesto sigue al resumen: mode, sample_names, aggregate y samples, sin clave summary de primer nivel, y cada entrada de samples lleva sus propias output_checksums.

JSON de errores#

Escribe los errores como JSON con:

--error-json run.error.json

Se escribe solo cuando la ejecución falla, así que su presencia ya es la señal:

{
  "schema_version": "1.0.0",
  "code": "E002",
  "exit_code": 3,
  "message": "Cannot open VCF file '/no/such.vcf': No such file or directory (os error 2)"
}

Informe HTML interactivo#

--report <FICHERO.html> escribe un único fichero HTML autocontenido para explorar las variantes llamadas. Incrusta sus datos y no carga scripts ni fuentes externas, así que se abre sin conexión con un doble clic y se puede adjuntar en un correo o archivar junto a los resultados.

Abrir el informe de ejemplo: 941 variantes llamadas sobre el conjunto de una muestra incluido en example/, o sea la salida real del comando de abajo y no una maqueta. Se regenera con scripts/build_example_report.sh. Las vistas de cohorte (las filas de la matriz, la recurrencia de haplotipos) se llenan con --sample all o --report-from sobre varias muestras.

# Informe de un run
get_mnv --vcf muestra.vcf --fasta ref.fasta --gff ref.gff --report muestra.html

# Un informe que cubre todas las muestras de un VCF multi-muestra
get_mnv --vcf cohorte.vcf --fasta ref.fasta --gff ref.gff --sample all --report cohorte.html

# Cohorte procesada muestra a muestra: agrega los TSV al final
get_mnv --report-from resultados/*.MNV.tsv --report cohorte.html

Con --report-from no se ejecuta el pipeline: el informe se construye a partir de TSV de get_MNV ya existentes, que es la forma habitual en un flujo de Nextflow o Snakemake que llama a get_MNV una vez por muestra. Cada fichero es una muestra, etiquetada con su nombre de archivo sin el sufijo .MNV.tsv (TB-001.MNV.tsv pasa a ser TB-001).

El informe contiene:

• Una cifra principal de las variantes mostradas, con tarjetas de apoyo para muestras, genes, filas MNV y variantes de alto impacto, y la distribución de consecuencias por término de Sequence Ontology. Todo sigue los filtros activos.

• Espectros mutacionales, que se alternan entre tres de COSMIC: SBS96 (las sustituciones de una base por contexto de trinucleótido, agrupadas por tipo de sustitución), DBS78 (dobletes de bases sustituidas adyacentes, caigan donde caigan, por doblete de referencia) e ID83 (inserciones y deleciones pequeñas por tamaño, base, número de repeticiones y microhomología, en los dos niveles de COSMIC). Cada evento cuenta una vez por muestra, aunque lo nombren varias filas, y una base de un doblete cuenta en DBS78, no en SBS96. Al pasar por una barra se lee su clase y su recuento, y Download matrix guarda el espectro que se muestra, por muestra, con la disposición MutationType que leen SigProfiler y MutationalPatterns, con los nombres de clase de COSMIC en el orden de COSMIC. Como lo demás, siguen los filtros.

• Una matriz de variantes, dibujada como un pequeño navegador genómico: las muestras en el lateral, coordenadas genómicas reales arriba y color por la base alternativa. Rueda para hacer zoom alrededor del cursor, arrastrar para desplazarse, arrastrar sobre la tira del contig completo para saltar, y doble clic para volver al inicio. Arrastrar a lo largo de la tira del contig completo selecciona un rango; un clic simple sobre ella recentra. La caja de región acepta inicio-fin, contig:inicio-fin, una coordenada suelta o un nombre de gen, y lo encuadra. Sobre la regla, una pista de densidad muestra las llamadas por bin genómico en carriles independientes: uno por cada métrica (todas las llamadas, SNP, MNV, indel, impacto HIGH y número de muestras distintas con llamada). Cada carril tiene su propia escala y su propio máximo, así una clase rara se lee al lado de una común en vez de quedar aplastada en la base de un apilado, y el control Tracks alterna entre todos los carriles, un conjunto compacto y ninguno. Una pista de genes marca la extensión de los sitios llamados de cada gen (que es donde hubo llamadas, no el límite anotado del gen, que el informe no lleva). Al acercarse lo suficiente aparece la letra de la base dentro de cada celda. Las muestras se pueden ordenar por perfil compartido (los patrones idénticos quedan juntos), por número de variantes o por nombre, y cada etiqueta de muestra lleva una barra con cuántas llamadas tiene en la ventana visible, por eso no hay un gráfico aparte por muestra. El color significa una sola cosa: los tonos de nucleótido son de las celdas de la matriz, toda magnitud va en neutro, y el color de estado reservado marca el impacto HIGH. Las posiciones llamadas juntas en las mismas lecturas (MNV de codón, indels complejos faseados) llevan una marca sobre sus columnas, y aparece un selector de contig con datos multi-contig, ya que un eje de coordenadas continuo no puede abarcar varios contigs.

  Una celda solo puede ser "llamada ALT" o "no llamada". La salida de get_MNV no distingue una base de referencia de una posición sin cobertura, así que una celda vacía nunca se presenta como referencia. Ese estado se lee como "referencia o sin cobertura".

• Haplotipos respaldados por lecturas: las combinaciones de alelos que get_MNV observó realmente en las mismas lecturas, es decir MNV de codón e indels complejos faseados localmente, ordenados por cuántas muestras llevan cada uno y con su soporte de fasing cuando se usó un BAM. El fasing de largo alcance entre sitios distantes no se infiere ni se muestra nunca.

• Una tabla ordenable y filtrable con todas las variantes, virtualizada para que decenas de miles de filas sigan siendo fluidas. Cada columna tiene su propio filtro: lista de casillas para muestra, contig, gen, tipo de variante, consecuencia e impacto (varios valores a la vez, con buscador cuando la lista es larga), coincidencia por texto para posición, cambio de bases y cambio de aminoácido, y rango mínimo/máximo para Grantham y frecuencia. Los filtros de columna se combinan entre sí y con el buscador libre, y gobiernan toda la página: las cifras principales, los gráficos, la matriz y el panel de haplotipos siguen la misma selección.

• Un panel de detalle de la variante seleccionada con su localización, consecuencia, descriptores HGVS g./c./p., distancia de Grantham, clase DBS, predicción de NMD, codones, componentes del evento y soporte de lecturas.

• Exportar TSV filtrado, que descarga exactamente las filas mostradas.

• Enlaces al repositorio y a la documentación en la cabecera. Son hiperenlaces normales: no se descarga nada al abrir el informe, así que sigue siendo autocontenido sin conexión.

El informe sigue el tema claro u oscuro del sistema operativo y tiene su propio selector. Como se construye desde el TSV, --report necesita salida TSV: funciona con el modo de salida por defecto y con --both, pero no con --convert a solas ni con --dry-run. Las columnas de soporte de lecturas (frecuencia, profundidad) solo se rellenan si el run usó --bam.

El tamaño escala con el número de variantes. Los campos repetidos se codifican con diccionario, así que una cohorte de decenas de miles de variantes se queda en pocos megabytes.

Notas#

• Para los registros MNV, la profundidad y la frecuencia se calculan a partir de las lecturas que abarcan todas las posiciones del haplotipo agrupado.
• Las frecuencias se imprimen con 4 decimales.
• --min-snp-frequency y --min-mnv-frequency son valores de 0 a 1 y requieren --bam.
• Los filtros de frecuencia de SNP y MNV son independientes, de modo que un haplotipo MNV fuerte no se elimina por un umbral de frecuencia de SNP más estricto.
• Los filtros de soporte de lecturas y de soporte de hebra de SNP y MNV también son independientes.
• --sample all escribe un conjunto de salida por cada muestra del VCF, con las variantes que lleva el genotipo de esa muestra.
• --keep-original-info conserva los campos INFO del VCF de entrada que no son de get_MNV. El registro de una base de un codón lleva los campos del registro de entrada de esa misma base, y un ANN de entrada va detrás de las entradas de get_MNV (El campo ANN).

Matriz de variantes por muestra#

--matrix <FICHERO.tsv> escribe las mismas variantes que muestra el informe como una tabla con una columna por muestra, para cargarla en R o en pandas:

get_mnv --report-from resultados/*.MNV.tsv --matrix matriz_cohorte.tsv
get_mnv --vcf cohorte.vcf --fasta ref.fasta --gff ref.gff --sample all --matrix matriz_cohorte.tsv

Se construye a partir de los mismos TSV que el informe, así que funciona en una ejecución normal, con --sample all y con --report-from, con o sin --report al lado.

NA nunca se escribe como 0 a propósito: un TSV de get_MNV no distingue una base de referencia de una posición que no cubrió ninguna lectura, así que una llamada que falta significa "referencia o sin cobertura". Las filas van ordenadas por contig y después por posición.

Editar esta página en GitHub