Ayuda
Resolución de problemas
Esta página enumera los errores comunes y las soluciones más rápidas.
Los nombres de contig no coinciden
Ejemplo:
[E002] Contig validation failedSolución:
- Asegúrate de usar los mismos nombres de contig en el archivo de variantes, el FASTA, el GFF/GTF y el BAM.
- Los nombres distinguen mayúsculas de minúsculas.
chr1y1son nombres distintos.
El REF del VCF no coincide con el FASTA
Ejemplo:
[E002] VCF REF/FASTA mismatch at <contig>:<pos>Solución:
- Comprueba que el VCF se generó a partir del mismo FASTA de referencia.
- Comprueba que las coordenadas y los nombres de contig no se modificaron después de la llamada de variantes.
No se detecta el TSV de iVar
Solución:
- Pasa el archivo con
--tsv sample_variants.tsv. - Comprueba que la cabecera del TSV contiene al menos
REGION,POS,REFyALT. - Si el archivo es en realidad un TSV de anotación de genes, pásalo con
--genes, no con--tsv.
Bases inválidas
Ejemplo:
[E002] Invalid base 'X' in REF/ALT alleleSolución:
- Elimina los alelos inválidos del archivo de variantes.
- get_MNV acepta bases IUPAC de ADN, pero no símbolos arbitrarios en REF/ALT.
Registros VCF multialélicos
Desde la 1.1.6 se dividen solos, así que el error Multiallelic VCF record is not supported ya no aparece. Una versión anterior necesita --split-multiallelic, o un VCF dividido de antemano con bcftools norm -m - input.vcf > split.vcf.
La división emite una fila anotada por cada ALT, incluso cuando varios alts comparten la misma posición de codón. Cada fila indica su propio efecto sobre el aminoácido, su codón y el soporte de lecturas derivado del BAM. Dividir el VCF de antemano con bcftools norm -m - produce la misma salida.
Entrada BCF
Desde la 1.1.6 un .bcf se lee directamente con --vcf. Las versiones anteriores se detienen con BCF input is not supported. Convert to VCF first; para ellas, conviértelo con bcftools view input.bcf > input.vcf.
Un BCF cortado, por ejemplo por una copia interrumpida, detiene la ejecución con un error invalid BCF record o invalid BCF header en lugar de leerse como un VCF con menos registros. Vuelve a copiar el archivo.
Anotación TSV con múltiples contigs
Ejemplo:
TSV annotation has 2 row(s) without a contig, which cannot be placed in a multi-contig VCFSolución:
- Nombra el contig de cada fila en una séptima columna (consulta Formatos de entrada).
- O usa
--gffpara datos de múltiples contigs. - O restringe la ejecución a un solo contig con
--chrom.
Las versiones anteriores a la 1.1.6 no tenían columna de contig y daban en su lugar TSV annotation does not include contig names.
Salen menos filas que registros tiene el VCF
Ejemplo:
Skipped 148 ALT alleles the selected sample's genotype does not carryCausa: un registro VCF enumera todos los ALT vistos en ese sitio en el conjunto de muestras, así que el GT de la muestra seleccionada decide cuáles le corresponden. Un genotipo 0/0 no lleva ninguno y, en un registro multialélico, 1/1 lleva solo el primer ALT.
Solución:
- Ninguna, si los genotipos son correctos: la ejecución anotó lo que tiene esa muestra.
- Elige la muestra que quieres con
--sample, o escribe un archivo por muestra con--sample all. - Si las llamadas no tienen un genotipo con sentido, quita el campo
GTo ponlo a./., que conserva todos los alelos porque desconocido no es ausente.
No se encuentra el nombre de la muestra
Ejemplo:
Sample '<name>' not found in VCF headerSolución:
- Comprueba el nombre de la muestra en la cabecera del VCF.
- Omite
--samplepara usar la primera muestra. - Usa
--sample allsolo cuando el VCF tiene columnas de muestra.
El modo estricto falla
Ejemplo:
--strict enabled, but original VCF metrics are missingSolución:
- Desactiva
--strict, o - Asegúrate de que cada variante tenga métricas de profundidad y frecuencia que get_MNV pueda leer.
Filtrado por frecuencia de alelos
Usa --min-snp-frequency <F> para los registros SNP y --min-mnv-frequency <F> para los haplotipos MNV. Los valores son fracciones de 0 a 1, así que 0.05 significa el 5 %.
Estos filtros requieren --bam porque get_MNV los calcula a partir del soporte de lecturas. No usan el valor OFREQ original del VCF/iVar. Los umbrales de SNP y MNV son independientes. En llamadas mixtas SNP/MNV, --min-snp-frequency filtra las observaciones de SNP y --min-mnv-frequency filtra el haplotipo MNV en fase; un MNV fuerte no debería desaparecer solo porque las observaciones individuales de SNP queden por debajo del umbral de SNP.
Soluciones comunes:
- Si ves un error
requires --bam, añade un BAM ordenado e indexado o elimina los filtros de frecuencia. - Si quieres filtrar por la frecuencia de alelos original del programa de llamada de variantes (
OFREQ), prefiltra el VCF o el TSV de iVar antes de ejecutar get_MNV. - Combina los filtros de frecuencia con filtros de soporte de lecturas como
--snp,--mnv,--min-snp-strandy--min-mnv-strandpara obtener llamadas más estrictas.
El directorio de salida no admite escritura
Ejemplo:
Read-only file systemSolución:
- Ejecuta el comando desde una carpeta con permiso de escritura, o
- En la GUI, elige un directorio de salida donde tengas permiso de escritura.
Avisos
Un aviso nunca detiene la ejecución, así que es fácil pasarlo por alto. Estos son los que cambian lo que acaba en la salida, y ninguno se ve en el propio TSV: si la anotación de una variante no es la que esperabas, o sus métricas vienen de una muestra que no elegiste, la razón estaba en stderr.
Ninguno elimina una variante. Una base que get_MNV no puede colocar en un codón se reporta igualmente, como una fila que nombra su gen con - en todas las columnas de aminoácido, así que el síntoma que hay que buscar es una fila sin anotar, no una fila que falta.
Falta el aminoácido de una variante que está dentro de un gen
| Aviso | Qué significa | Qué hacer |
|---|---|---|
falls in the phase-skipped region of CDS ... | El codón se mete en un exón vecino, y una sola fila del GFF no puede decir cuáles son las bases vecinas, así que no se construye codón para esa base. La variante sí se reporta: una fila que nombra el gen, - en todas las columnas de aminoácido y término SO coding_sequence_variant (MODIFIER). | Dale a las filas CDS un transcript_id o un Parent para que get_MNV pueda empalmar el transcrito, y ejecuta con --gff-features CDS. |
La anotación es más gruesa de lo que permitiría el archivo
Los tres primeros recaen en la anotación por feature, así que los codones se agrupan dentro de una fila CDS en vez de a lo largo del transcrito empalmado, y una variante cerca de un borde de exón puede recibir entonces otro aminoácido. El cuarto por sí solo no cambia nada.
| Aviso | Qué significa | Qué hacer |
|---|---|---|
has rows on both strands | Dos filas de un mismo transcrito discrepan sobre la orientación, y con ellas no se puede construir un CDS empalmado. | Corrige la columna de hebra, o separa las filas en transcritos distintos. |
has a single CDS row with non-zero phase / starts with non-zero phase | Las filas seleccionadas no parecen una secuencia codificante completa, así que no puede fiarse de la fase para colocar los codones. | Incluye en la ejecución todas las filas CDS del transcrito. |
contains CDS rows with non-zero phase, but --gff-features does not include 'CDS' | La agrupación de codones está ignorando una fase que el archivo sí trae. | Añade --gff-features CDS. |
lists N duplicate CDS row(s) | get_MNV descarta las repeticiones por su cuenta y construye igualmente el transcrito empalmado, así que la anotación es la misma que daría un archivo limpio. | Nada. Quitar los duplicados del GFF solo silencia el aviso. |
Las métricas vienen de una muestra que no elegiste
| Aviso | Qué significa | Qué hacer |
|---|---|---|
Multi-sample VCF detected (N samples). Using first sample | ODP y OFREQ se leen de la muestra que vaya primero en la cabecera, que rara vez es una elección deliberada. El genotipo de esa muestra decide además qué alelos ALT se conservan, así que la elección cambia también el número de filas (consulta Salen menos filas que registros tiene el VCF). | Nombra una con --sample, o anótalas todas con --sample all. |
El soporte de lecturas no es el que decía la entrada
| Aviso | Qué significa | Qué hacer |
|---|---|---|
has N spanning read(s) but 0 with exact CIGAR support | Hay lecturas que cubren el sitio pero ninguna lleva ese indel exacto, que es lo que pasa cuando el alelo está escrito en otra posición dentro de un homopolímero o una repetición. | Vuelve a ejecutar con --left-align, o alinea antes la entrada a la izquierda con bcftools norm -f ref.fa. Si la advertencia dice que el alelo ya está alineado a la izquierda, las lecturas ponen el hueco en otro sitio o no llevan el indel: mira el alineamiento. |
was declared X by the input VCF, but N of M reads spanning the site carry the whole haplotype | El llamador y las lecturas discrepan sobre si esos cambios viajan juntos. | Mira el alineamiento antes de fiarte de ninguno de los dos. |
shows N distinct combinations on the reads; reporting the K best supported | Una ventana con más haplotipos locales de los que get_MNV reporta. Los descartados son la cola con poco soporte. Consulta Indels y haplotipos locales. | Nada, salvo que te importe un haplotipo raro; --chrom toma nombres de contig enteros, no regiones, así que inspecciona la ventana en el alineamiento. |
Un flag no hizo nada
| Aviso | Qué significa |
|---|---|
--keep-original-info has no effect with iVar TSV input | Un TSV de iVar no tiene columna INFO que conservar. |
--gff-features is ignored when using TSV annotation format (--genes) | Los tipos de feature son una idea de GFF/GTF; el TSV de cuatro columnas no tiene ninguno. |
Un umbral llegó a menos de lo que pretendías
| Aviso | Qué significa |
|---|---|
The MNV thresholds will not remove any SNP/MNV row | Los umbrales de MNV siguen filtrando las filas MNV, de indel e intergénicas. A lo que no llegan es a las filas SNP/MNV: una sobrevive cuando cualquiera de los dos lados, sus SNV o su haplotipo, supera su listón, así que con los umbrales de SNP a 0 el lado SNP siempre pasa. Sube también --snp, --min-snp-frequency o --min-snp-strand para filtrar las filas a nivel de codón. |
Faltaba un programa externo opcional
| Aviso | Qué significa |
|---|---|
bcftools not found in PATH. Skipping BCF output. | Se pidió --bcf y no se escribió ningún BCF. La ejecución continúa y sale con 0; el TSV y el VCF no se ven afectados, y el resumen JSON no reporta ningún BCF. Instala bcftools, o quita --bcf. |
tabix not found in PATH. Skipping .tbi index | Se pidió --index-vcf-gz y no se escribió ningún .tbi. El propio .vcf.gz está completo. Instala samtools/htslib, o indéxalo después con tabix -p vcf <fichero>. |
Conflictos entre flags
| Error | Solución |
|---|---|
--index-vcf-gz requires --vcf-gz | Añade --vcf-gz. |
--bcf requires --convert or --both | Añade --convert o --both. |
--keep-original-info requires --convert or --both | Añade --convert o --both. |
--min-strand-bias-p must be between 0 and 1 | Usa un valor de 0 a 1. |
Códigos de salida
| Código | Significado |
|---|---|
0 | Éxito |
1 | Error genérico |
2 | Error de configuración |
3 | Error de validación de entrada |
10 | Error de lectura/escritura de archivo |
11 | Error de análisis de CSV/TSV |
12 | Error de análisis de BAM/VCF |
13 | Error de codificación UTF-8 |
14 | Error de análisis de enteros |
15 | Error de análisis de números en coma flotante |
16 | Error de JSON |
¿Sigues atascado?
Arriba está cada mensaje que la herramienta puede dar y qué pide cada uno. Si lo que ves no aparece, o la respuesta no encaja con tus datos, pregunta en Q&A.
Las respuestas se marcan como tales, así que la siguiente persona con tu mismo problema la encuentra sin tener que preguntar.