Visualization and Output¶

This page describes the output files generated by PopMAG and how to use the interactive Shiny dashboard.

Output Directory Structure¶

After a successful run, PopMAG creates the following directory structure:

results/
├── checkm2/                        # Quality assessment
├── filtered_bins/                  # Quality-filtered MAGs
├── dRep/                           # Dereplication results
├── competitive_mapping/            # Read alignments
│   ├── concatenated_genomes/
│   └── {sample}_definition_files/
├── coverm/                         # Abundance data
├── prodigal/                       # Gene predictions
│   └── {sample}/{mag_id}/
├── metacerberus/                   # Functional annotations
├── instrain_profile/               # InStrain results
│   └── {sample}/
├── instrain_compare/               # Sample comparisons
├── VCFs/                           # Variant calls
│   └── {sample}/
├── pogenom/                        # Population genetics
│   └── {sample}/
├── singleM/                        # Community profiles
│   └── {sample}/
├── merged_reports/                 # Combined results
└── pipeline_info/                  # Execution reports

Output Descriptions¶

CheckM2 Results¶

Location: results/checkm2/

Contains quality assessment metrics for all input MAGs.

File	Description
`quality_report.tsv`	CheckM2 quality metrics including completeness, contamination, and genome size

Filtered Bins¶

Location: results/filtered_bins/

MAGs that passed the defined quality filtering thresholds.

dRep Results¶

Location: results/dRep/

Genome dereplication output from dRep.

Directory/File	Description
`dRep_results/`	Full dRep output including clustering information
`dereplicated_genomes/`	Representative genomes after dereplication

Competitive Mapping¶

Location: results/competitive_mapping/

Bowtie2 alignment results for competitive read mapping.

File Type	Description
`*.bam`	Sorted BAM alignment files
`*.bai`	BAM index files
`*_concatenated.fa`	Concatenated reference genomes
`*_contigs_to_bin.tsv`	Contig-to-genome mapping

CoverM Abundance¶

Location: results/coverm/

Genome abundance calculations.

File	Description
`coverage.tsv`	Relative abundance of each genome per sample
`heatmap.html`	Interactive abundance heatmap

Prodigal Gene Predictions¶

Location: results/prodigal/{sample}/{mag_id}/

Gene predictions for each MAG.

File	Description
`*.faa`	Predicted protein sequences (amino acids)
`*.fna`	Predicted gene sequences (nucleotides)
`*.gff`	Gene annotations in GFF format

MetaCerberus Annotations¶

Location: results/metacerberus/

Functional annotations for predicted genes.

File	Description
`*_annotations.tsv`	Functional annotations with database hits
`*_KEGG.tsv`	KEGG pathway annotations
`*_COG.tsv`	COG category annotations

InStrain Profile¶

Location: results/instrain_profile/{sample}/

Per-sample population genomics analysis.

File	Description
`*.IS_SNVs.tsv`	Single nucleotide variants
`*.IS_gene_info.tsv`	Gene-level diversity metrics
`*.IS_genome_info.tsv`	Genome-level diversity metrics
`*.IS_linkage.tsv`	Linkage information
`*.IS_mapping_info.tsv`	Read mapping statistics
`*.IS_scaffold_info.tsv`	Per-scaffold metrics

Key metrics in genome_info:

coverage: Mean read coverage
breadth: Fraction of genome covered
nucl_diversity: Nucleotide diversity (π)
SNV_count: Number of SNVs detected

InStrain Compare¶

Location: results/instrain_compare/

Pairwise comparisons between samples.

File	Description
`*_comparisons.tsv`	Pairwise ANI and population overlap
`*_strain_clusters.tsv`	Strain clustering results

VCF Files¶

Location: results/VCFs/{sample}/

Variant call files in standard VCF format.

File	Description
`*.vcf`	Combined VCF for all genomes
`{genome}.vcf`	Per-genome VCF files

POGENOM Results¶

Location: results/pogenom/{sample}/

Population genetics metrics from POGENOM.

File	Description
`*.fst.txt`	Fixation index (FST) values
`*.intradiv`	Intra-population diversity
`*.pi`	Nucleotide diversity

SingleM Profiles¶

Location: results/singleM/{sample}/

Microbial community profiling results.

File	Description
`*.profile.tsv`	Taxonomic profile of the community

Merged Reports¶

Location: results/merged_reports/

Combined analysis files ready for visualization.

File	Description
`*_combined_summary.tsv`	Summary of SNVs across all samples
`*_merged.tsv`	InStrain metrics merged with annotations
`*_genome_reports.tsv`	Combined genome-level reports

Pipeline Info¶

Location: results/pipeline_info/

Execution reports and logs.

File	Description
`execution_report.html`	Detailed execution statistics
`execution_timeline.html`	Visual timeline of processes
`execution_trace.txt`	Resource usage per process

Shiny Dashboard¶

PopMAG includes an interactive Shiny dashboard for exploring results.

Accessing the Dashboard¶

The dashboard launches automatically at the end of the pipeline run:

To access the shiny app please open 0.0.0.0:3838 or localhost:3838 in your browser.

Open your web browser and navigate to:

Local machine: http://localhost:3838

If you are working in a remote server you might need to create an ssh tunnel using a command like this one:

ssh -NfL 3838:localhost:3838 username@server-ip

If you ran PopMAG with --skip_shiny you can visualize results locally using the files available in the merged_reports folder:

docker run -p 3838:3838 \
  -v /path/to/popmag/results/merged_reports/:/srv/shiny-server/app \
  daasabogalro/popmag_shiny

Then open http://localhost:3838 in your browser.

Timeout

The dashboard has a default timeout of 1500 seconds (25 minutes). Adjust with --shiny_timeout if you need more time.