get_MNV
English GitHub

Referencia

Referencia de la CLI

Referencia completa de las opciones de línea de comandos de get_mnv (versión 1.1.6). Ejecuta get_mnv --help para ver la misma lista en tu terminal.

Sinopsis

get_mnv [OPTIONS] --fasta <FASTA_FILE> <--vcf <VCF_FILE>|--tsv <TSV_FILE>>

Debes proporcionar una referencia (--fasta) y exactamente una fuente de variantes (--vcf o --tsv), además de una anotación de genes (--gff o --genes). La única excepción es --report-from, que construye un report a partir de salidas TSV ya existentes y no necesita ninguna de las tres.

Entrada

OpciónDescripción
-v, --vcf <FILE>Entrada de variantes en VCF plano, VCF comprimido con BGZF o BCF (SNV/MNV e indels).
--tsv <FILE>Entrada variants.tsv de iVar.
-b, --bam <FILE>Lecturas alineadas opcionales para soporte de lecturas, en BAM o CRAM. Debe estar ordenado por coordenadas e indexado; un CRAM se decodifica con --fasta.
-f, --fasta <FILE>FASTA de referencia (requerido).
--sample <NAME>Muestra que se anota en un VCF multimuestra (por defecto: primera muestra; all para todas). Sus métricas FORMAT pasan a ser la profundidad y la frecuencia originales, y su genotipo decide qué alelos ALT lleva.
--chrom <NAME>Restringe el procesamiento a un solo contig (por defecto: todos los contigs de la entrada).

Anotación

OpciónDescripción
--gff <FILE>Anotación de genes en formato GFF/GFF3.
-g, --genes <FILE>Tabla de genes TSV simple: gene,start,end,strand. Úsala en lugar de --gff.
--gff-features <LIST>Tipos de característica GFF separados por comas a analizar (por defecto: gene,pseudogene). Usa CDS para transcritos con splicing.
--translation-table <N>Código genético NCBI (por defecto: 11, bacteriano). Admitidos: 1, 2, 3, 4, 5, 6, 11, 12, 25.
--exclude-intergenicDescarta las variantes fuera de los genes anotados.

Soporte de lecturas y calidad

Estas solo aplican cuando se proporciona --bam.

OpciónPor defectoDescripción
-q, --quality <N>20Calidad Phred de base mínima.
--min-mapq <N>0Calidad de mapeo mínima (MAPQ).
-s, --snp <N>0Lecturas mínimas que soportan el SNP.
--min-snp-frequency <F>0.0Frecuencia alélica mínima del SNP derivada del BAM (0.0–1.0).
-m, --mnv <N>0Lecturas mínimas que soportan el MNV.
--min-mnv-frequency <F>0.0Frecuencia mínima del haplotipo MNV derivada del BAM (0.0–1.0).
--min-snp-strand <N>0Lecturas mínimas que soportan el SNP en cada hebra.
--min-mnv-strand <N>0Lecturas mínimas que soportan el MNV en cada hebra.
--min-strand-bias-p <F>0.0Valor p mínimo del test exacto de Fisher aceptado para las métricas de sesgo de hebra. Solo afecta a la salida VCF: el escritor de TSV no tiene umbral de sesgo, así que esto nunca quita una fila del TSV.

Cómo se combinan los umbrales de SNP y MNV

Los filtros de frecuencia y recuento de lecturas usan el soporte recalculado a partir de --bam, no los OFREQ/ODP originales de la entrada.

Una fila a nivel de codón (SNP/MNV) se conserva cuando cualquiera de los dos lados supera su listón: sus SNV individuales pasan los umbrales de SNP, o su haplotipo pasa los de MNV. Eso conserva un haplotipo bien soportado cuyos SNV individuales son débiles, y funciona también en el otro sentido: con los umbrales de SNP en su valor por defecto de 0, el lado SNP pasa siempre, así que subir --mnv a solas no quita nada. Sube los dos, o ninguno. La ejecución avisa cuando has pedido un umbral MNV que no puede llegar a una fila a nivel de codón.

Qué umbrales gobiernan cada fila:

FilaLa juzgan
SNPlos umbrales de SNP
MNV, SNP/MNVcualquiera de los dos lados, como arriba
INDELlos umbrales de MNV, medidos contra el soporte de evento del propio indel (Event Reads, Event Forward Reads, Event Reverse Reads, Event Depth), no contra ninguna columna SNP

Una fila del TSV se conserva o se descarta entera, y una fila a nivel de codón supera el lado SNP solo cuando lo superan todas sus sustituciones. Un registro del VCF es un alelo, y se filtra por su cuenta. Así que una ejecución con --both bajo un umbral que una sustitución cumple y otra no escribe ese alelo en el VCF sin que ninguna fila del TSV lo lleve: falló la fila, no el alelo. Ninguna de las dos salidas está mal; son unidades distintas.

Así que un indel se filtra con --mnv, --min-mnv-frequency y --min-mnv-strand; --snp no lo toca nunca. Eso vale también fuera de los genes: un indel intergénico se cuenta y se juzga por su propio soporte como cualquier otro. Solo queda exenta una fila que no llegó a ningún contador, porque no se puede aplicar un umbral a una medición que nadie tomó.

Ajuste de indels

OpciónPor defectoDescripción
--frameshift-min-freq <F>0.5Frecuencia mínima que debe alcanzar un indel aguas arriba para marcar con frameshift los codones de SNV/MNV aguas abajo. Por defecto solo propaga desde un indel aguas arriba mayoritario; pon 0.0 para propagar desde cualquiera. Con --bam la frecuencia es la que get_MNV cuenta de las lecturas (el mismo número que reporta como EFREQ), no el AF que declaró el llamador; sin BAM se cae al AF declarado. Un indel cuya frecuencia no se conoce por ninguna de las dos vías siempre propaga, porque no hay nada que comparar.
--legacy-indel-depthdesactivadoRestringe la profundidad del locus del indel (el denominador de EFREQ) a las lecturas que abarcan el alelo REF entero. Por defecto se cuenta desde las que observan la base de anclaje, lo que evita subcontar profundidad en deleciones multibase; este flag recupera el denominador antiguo, más estrecho.
--phased-indel-min-reads <N>2Lecturas mínimas que soportan en el BAM para emitir una fila de haplotipo indel/complejo en fase. Una sola lectura no es evidencia de un haplotipo.
--count-mates-separatelyapagadoCuenta los dos mates de un fragmento como dos observaciones en vez de una molécula.
--phased-indel-min-freq <F>0.0Frecuencia mínima derivada del BAM para emitir una fila de haplotipo indel/complejo en fase.
--normalize-allelesoffRecorta el prefijo/sufijo compartido de REF/ALT antes del procesamiento.
--left-alignoffAlinea a la izquierda los indels sobre la referencia antes del procesamiento, como hace bcftools norm -f: un indel en un homopolímero o una repetición pasa a su posición equivalente más a la izquierda, donde los alineadores ponen el hueco, para que se pueda contar su soporte de lecturas. Un indel se detiene en una base que cambia otro registro de la muestra en las mismas moléculas, donde sus lecturas ponen el hueco. Incluye el recorte de --normalize-alleles; los registros complejos se recortan pero no se mueven. Vale para la entrada VCF y para la TSV de iVar. Mira Alineamiento a la izquierda.
--split-multiallelicactivadaDivide los registros VCF multialélicos en alelos ALT independientes. Activada por defecto desde la 1.1.6; se sigue aceptando para que los comandos existentes no fallen.

Salida

OpciónDescripción
--output-dir <DIR>Dónde escribir el TSV, el VCF y el BCF. Se crea si no existe. Sin esta opción van al directorio actual.
--output-prefix <PREFIX>Nombre base de esos ficheros, en lugar del de la entrada. Con --sample all se sigue añadiendo el nombre de la muestra.
--convertEscribe salida VCF (.MNV.vcf) en lugar de TSV.
--bothEscribe TSV y VCF en una sola ejecución.
--vcf-gzEscribe .vcf.gz comprimido con BGZF (modo de salida VCF).
--index-vcf-gzConstruye un índice Tabix .tbi (requiere --vcf-gz).
--bcfEscribe también un BCF convertido a partir del VCF generado (requiere --convert/--both).
--strand-bias-infoAñade los valores p de sesgo de hebra del test exacto de Fisher al INFO del VCF (SBP/MSBP).
--keep-original-infoConserva los campos INFO originales del VCF en la salida (requiere --convert/--both).
--emit-filteredEmite los registros que no superan los umbrales con etiquetas FILTER en lugar de omitirlos.

--index-vcf-gz y --bcf llaman a programas externos

Todo lo demás que escribe get_MNV lo escribe get_MNV. Estos dos no: --index-vcf-gz ejecuta tabix y --bcf ejecuta bcftools, ambos tomados del PATH. Vienen con samtools/htslib y con bcftools, y ninguno es dependencia de compilación, así que una máquina puede tener get_MNV y no tenerlos.

Que falte un programa no es una ejecución fallida. get_MNV avisa, se salta ese paso y termina: el TSV y el VCF se escriben igualmente y la ejecución sale con 0. Nada reclama después el fichero que no se escribió, así que el resumen JSON no reporta ningún BCF y --run-manifest no anota ninguna suma de comprobación para él. Mira los avisos, o mira si está el fichero, cuando un paso posterior lo necesite.

Informe HTML interactivo

OpciónDescripción
--report <HTML_FILE>Escribe un informe HTML interactivo y autocontenido de las variantes llamadas. Necesita la salida TSV, que es la de por defecto. --convert escribe el VCF en lugar del TSV, y los dos flags son mutuamente excluyentes, así que usa --both en vez de --convert cuando quieras un informe junto a la salida VCF. Con --sample all el informe cubre todas las muestras.
--report-from <TSV>...Construye el informe a partir de TSV de get_MNV ya existentes, sin ejecutar el pipeline, para cohortes procesadas muestra a muestra. Cada fichero es una muestra, etiquetada con su nombre de archivo. Requiere --report, --matrix o ambos para la salida.
--matrix <TSV_FILE>Escribe una matriz de variantes por muestra en TSV: una fila por variante y una columna por muestra, con la frecuencia alélica que dieron las lecturas, called para una llamada sin frecuencia medida, o NA donde la muestra no tiene llamada. Funciona en una ejecución normal, con --sample all y con --report-from; necesita la salida TSV, igual que --report.
--catalogue <TSV_FILE>Marca las llamadas que coinciden con un catálogo de variantes conocidas: una tabla separada por tabuladores con columnas gene, variant y label opcional, con la variante escrita como p., c., n., g. o LoF. Las coincidencias van a la columna Catalogue y a la clave INFO CAT. Consulta Formatos de entrada. example/who_catalogue_2023.tsv es el catálogo de la OMS de mutaciones de resistencia de M. tuberculosis en esta forma.
--keep-unphased-codon-matchesLista una coincidencia del catálogo que solo hace una de las lecturas de un codón aunque ninguna lectura lleve esa lectura. Por defecto, con --bam, esa coincidencia va a la columna Catalogue Withheld y a la clave INFO CATW, con el motivo. Consulta Ligamiento a nivel de lectura.
--phase-conflict-dprime <F>Cuánto debe alejarse D' de cero para que las lecturas desmientan una lectura del codón: a menos de este valor o por debajo, la lectura de codón; a este valor o por encima, la lectura por SNV; y en los dos casos solo cuando ninguna lectura lleva la lectura desmentida. Entre 0 y 1. Por defecto: 0.5.
--phase-conflict-p <F>Mayor p-valor exacto de Fisher aceptado como esa prueba, para que un puñado de moléculas no desmienta nada. Entre 0 y 1. Por defecto: 0.05.

Consulta Formatos de salida para saber qué contiene el informe.

Validación y metadatos

OpciónDescripción
--dry-runValida las entradas e imprime un resumen por contig sin escribir salidas.
--strictFalla si faltan en la entrada las métricas originales de profundidad/frecuencia (ODP/OFREQ).
--summary-json <FILE>Escribe un resumen de la ejecución legible por máquina.
--run-manifest <FILE>Escribe un manifiesto de reproducibilidad (entradas, salidas, checksums, metadatos de ejecución).
--error-json <FILE>Escribe detalles de error estructurados en formato JSON cuando el comando falla.
--threads <N>Número de hilos de trabajo (por defecto: automático de Rayon).
-h, --helpImprime la ayuda.
-V, --versionImprime la versión.

Editar esta página en GitHub