# Estrutura de Saída

Quando você executa `run-from-fasta`, o ViralQC cria a seguinte estrutura:

```
output/             # Diretório de saída especificado pelo usuário (ex: --output-dir meus_resultados)
└── .snakemake/     # Arquivos gerados na análise do Snakemake
└── outputs/        # Arquivos de saída do ViralQC
    ├── identified_datasets/
    │   ├── datasets_selected.tsv
    │   ├── viruses.tsv
    │   ├── viruses.external_datasets.tsv
    │   ├── unmapped_sequences.txt
    │   └── <virus>/sequences.fa
    ├── blast_results/
    │   ├── unmapped_sequences.blast.tsv
    │   └── blast_viruses.list
    ├── nextclade_results/
    │   ├── <virus>.nextclade.tsv
    │   └── <accession>.generic.nextclade.tsv
    ├── gff_files/
    │   ├── <virus>.nextclade.gff
    │   ├── <accession>.generic.nextclade.gff
    │   └── per_sample/
    │       └── <id>_<nome_amostra>.gff
    ├── tbl_files/
    │   ├── <virus>.nextclade.tbl
    │   ├── <accession>.generic.nextclade.tbl
    │   └── per_sample/
    │       └── <id>_<nome_amostra>.tbl
    ├── logs/
    │   ├── nextclade_sort.log
    │   ├── blast.log
    │   └── ...
    ├── results.tsv
    ├── sequences_target_regions.bed
    └── sequences_target_regions.fasta
```

### Arquivo Principal: results.tsv (ou .csv, .json)

Este é o arquivo que contém os resultados consolidados de todas as análises:

##### 1. Identificação da Sequência

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `seqName` | String | Nome da sequência no arquivo FASTA de entrada |
| `virus` | String | Nome do vírus identificado |
| `virus_tax_id` | Integer | ID taxonômico do vírus no NCBI Taxonomy |
| `virus_species` | String | Nome da espécie viral |
| `virus_species_tax_id` | Integer | ID taxonômico da espécie |
| `segment` | String | Segmento genômico (ex: "HA", "NA", "Unsegmented") |
| `ncbi_id` | String | Accession do genoma de referência no NCBI |
| `dataset` | String | Identificador do dataset usado |
| `datasetVersion` | String | Versão/tag do dataset |
| `clade` | String | Clado filogenético (quando disponível) |

##### 2. Métricas de Qualidade (Sistema A-D do ViralQC)

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `genomeQuality` | String | Qualidade geral do genoma (A, B, C ou D) |
| `genomeQualityScore` | Float | Score numérico normalizado (0-24) |
| `missingDataQuality` | String | Qualidade baseada em dados ausentes (A, B, C ou D) |
| `privateMutationsQuality` | String | Qualidade baseada em mutações privadas (A, B, C ou D) |
| `mixedSitesQuality` | String | Qualidade baseada em sítios mistos (A, B, C ou D) |
| `snpClustersQuality` | String | Qualidade baseada em clusters de SNPs (A, B, C ou D) |
| `frameShiftsQuality` | String | Qualidade baseada em frameshifts (A, B, C ou D) |
| `stopCodonsQuality` | String | Qualidade baseada em códons de parada (A, B, C ou D) |
| `cdsCoverageQuality` | String | Qualidade de cobertura por CDS (ex: "E: A, prM: B") |
| `targetRegionsQuality` | String | Qualidade das regiões-alvo (A, B, C, D ou vazio) |
| `targetGeneQuality` | String | Qualidade do gene-alvo (A, B, C, D ou vazio) |

##### 3. Métricas de Qualidade (Nextclade)

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `qc.overallScore` | Float | Score geral de qualidade do Nextclade |
| `qc.overallStatus` | String | Status de qualidade do Nextclade (good, mediocre, bad) |
| `qc.privateMutations.total` | Integer | Total de mutações privadas (Nextclade) |
| `qc.privateMutations.score` | Float | Score de mutações privadas (Nextclade) |
| `qc.privateMutations.status` | String | Status de mutações privadas (Nextclade) |
| `qc.missingData.score` | Float | Score de dados ausentes (Nextclade) |
| `qc.missingData.status` | String | Status de dados ausentes (Nextclade) |
| `qc.mixedSites.totalMixedSites` | Integer | Total de sítios mistos (Nextclade) |
| `qc.mixedSites.score` | Float | Score de sítios mistos (Nextclade) |
| `qc.mixedSites.status` | String | Status de sítios mistos (Nextclade) |
| `qc.snpClusters.totalSNPs` | Integer | Total de SNPs em clusters (Nextclade) |
| `qc.snpClusters.score` | Float | Score de clusters de SNPs (Nextclade) |
| `qc.snpClusters.status` | String | Status de clusters de SNPs (Nextclade) |
| `qc.frameShifts.totalFrameShifts` | Integer | Total de frameshifts (Nextclade) |
| `qc.frameShifts.score` | Float | Score de frameshifts (Nextclade) |
| `qc.frameShifts.status` | String | Status de frameshifts (Nextclade) |
| `qc.stopCodons.totalStopCodons` | Integer | Total de códons de parada (Nextclade) |
| `qc.stopCodons.score` | Float | Score de códons de parada (Nextclade) |
| `qc.stopCodons.status` | String | Status de códons de parada (Nextclade) |

##### 4. Cobertura e Regiões

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `coverage` | Float | Cobertura do genoma (0.0 a 1.0) |
| `cdsCoverage` | String | Cobertura de cada CDS (formato: "gene1: 0.98, gene2: 1.0") |
| `targetRegionsCoverage` | String | Cobertura das regiões-alvo definidas em `target_regions` |
| `targetGeneCoverage` | String | Cobertura do gene-alvo definido em `target_gene` |
| `targetRegions` | String | Lista de regiões-alvo (separadas por \|) |
| `targetGene` | String | Nome do gene-alvo principal |

##### 5. Mutações Nucleotídicas

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `totalSubstitutions` | Integer | Total de substituições nucleotídicas |
| `totalDeletions` | Integer | Total de deleções nucleotídicas |
| `totalInsertions` | Integer | Total de inserções nucleotídicas |
| `totalFrameShifts` | Integer | Total de frameshift mutations |
| `totalMissing` | Integer | Total de nucleotídeos faltantes (N's ou gaps) |
| `totalNonACGTNs` | Integer | Total de caracteres não-ACGTN |
| `substitutions` | String | Lista de substituições (formato: gene:pos:ref>alt) |
| `deletions` | String | Lista de deleções |
| `insertions` | String | Lista de inserções |
| `frameShifts` | String | Lista de frameshifts |
| `alignmentScore` | Float | Score do alinhamento |

##### 6. Mutações de Aminoácidos

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `totalAminoacidSubstitutions` | Integer | Total de substituições de aminoácidos |
| `totalAminoacidDeletions` | Integer | Total de deleções de aminoácidos |
| `totalAminoacidInsertions` | Integer | Total de inserções de aminoácidos |
| `totalUnknownAa` | Integer | Total de aminoácidos desconhecidos |
| `aaSubstitutions` | String | Lista de substituições de aminoácidos |
| `aaDeletions` | String | Lista de deleções de aminoácidos |
| `aaInsertions` | String | Lista de inserções de aminoácidos |

##### 7. Mutações Privadas (Detalhadas)

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `privateNucMutations.totalPrivateSubstitutions` | Integer | Total de substituições privadas |
| `privateNucMutations.totalLabeledSubstitutions` | Integer | Total de mutações privadas conhecidas/catalogadas |
| `privateNucMutations.totalUnlabeledSubstitutions` | Integer | Total de mutações privadas não catalogadas |
| `privateNucMutations.totalReversionSubstitutions` | Integer | Total de reversões (mutações que revertem à referência ancestral) |

**Nota sobre formatos de saída:**
- **TSV/CSV**: Todas as colunas são strings ou valores numéricos
- **JSON**: Colunas como `cdsCoverage`, `cdsCoverageQuality` e `targetRegionsCoverage` são formatadas como arrays de objetos para facilitar parsing programático


## Arquivos de Regiões-Alvo

### sequences_target_regions.bed

```
seq1    94      2419    C,prM,E
seq2    0       10735   genome
```

### sequences_target_regions.fasta

Sequências extraídas das regiões que atendem aos critérios de qualidade.

## Arquivos de Anotação

### gff_files/

Contém arquivos de anotação GFF3 produzidos pelo Nextclade para cada dataset de vírus.
Cada arquivo abrange todas as amostras analisadas para aquele vírus (identificadas por IDs numéricos).

| Arquivo | Descrição |
|---------|-----------|
| `<virus>.nextclade.gff` | GFF multi-amostra da execução padrão do Nextclade |
| `<accession>.generic.nextclade.gff` | GFF multi-amostra da execução genérica do Nextclade via BLAST |

#### gff_files/per_sample/

Um arquivo GFF por amostra, gerado automaticamente a partir da saída combinada acima.
O ID numérico utilizado internamente pelo viralQC é substituído pelo cabeçalho
original da amostra em todo o arquivo (diretiva de região, coluna 1 e atributos).

- **Formato do nome:** `{id}_{nome_amostra}.gff`

### tbl_files/

Contém arquivos de tabela de features (TBL) de 5 colunas produzidos pelo Nextclade
para cada dataset de vírus. O formato TBL é compatível com as ferramentas de
submissão do NCBI.

| Arquivo | Descrição |
|---------|-----------|
| `<virus>.nextclade.tbl` | TBL multi-amostra da execução padrão do Nextclade |
| `<accession>.generic.nextclade.tbl` | TBL multi-amostra da execução genérica do Nextclade via BLAST |

#### tbl_files/per_sample/

Um arquivo TBL por amostra, gerado automaticamente a partir da saída combinada acima.
O cabeçalho `>Feature <id>` de cada bloco é substituído pelo nome original da amostra.

- **Formato do nome:** `{id}_{nome_amostra}.tbl`

> **Nota:** Arquivos em `per_sample/` podem estar vazios (zero bytes) para amostras
> nas quais o Nextclade foi executado sem arquivo GFF de referência.