MagQC

Basic Usage

magqc.sh vector=<vec.tsv> out=<report.tsv>

MagQC reads a marker-vector TSV file generated by markervector.sh and computes quality metrics for a metagenome-assembled genome (MAG). The marker vector contains family IDs, representative sequences, and copy counts for marker proteins detected in the genome.

Input Format

The marker-vector TSV must be in the format written by markervector.sh / MarkerVectorCLI. The file contains three columns per data row: family_id, representative, and count. The file also includes #-prefixed header and derived scalar lines (domain assignment, proteins matched/unmatched). These metadata lines are read from the vector; the domain assignment is carried into the output report.

Output Format

The output is a tab-separated report with metric\tvalue lines. The two primary metrics are completeness_pct and contamination_pct (headline, excess-copy), with contamination_pct_multicopy as a secondary metric. Additional fields include raw counts (expected_markers, detected_markers, multicopy_markers, excess_copies, effective_denominator), domain assignment, marker set metadata, and confidence scores.

Common Use Cases

Computing Completeness and Contamination for a Single MAG

Generate a marker vector using markervector.sh, then compute QC metrics:

markervector.sh in=genome.fa out=markers.tsv
magqc.sh vector=markers.tsv out=qc_report.tsv

The output report will contain completeness_pct, contamination_pct, and all supporting metrics.

Validating Neural Net Performance

Generate oracle estimates for a set of genomes and compare against neural net predictions to assess accuracy:

magqc.sh vector=genome_markers.tsv out=oracle_report.tsv
magqc.sh vector=genome_markers.tsv out=oracle_report.tsv ow=t

The oracle report serves as ground truth for neural net calibration and validation studies.

Batch Processing Multiple MAGs

Process marker vectors for a collection of metagenome-assembled genomes:

for vec in bin*.tsv; do
    magqc.sh vector="$vec" out="${vec%.tsv}.qc.tsv"
done

Each MAG's marker vector produces a separate QC report with completeness and contamination metrics.

Parameters

MagQC supports both required and optional parameters. All parameters use the format parameter=value.

Output Metrics

The MagQC output report contains the following metrics in tab-separated format:

Primary Metrics

completeness_pct

Percentage of expected marker families detected in the genome. Calculated as (detected marker families / expected marker families) × 100. Ranges from 0-100%.

contamination_pct

Headline contamination estimate (excess-copy) in percentage. Calculated as (excess copies / expected families) × 100, where excess copies = sum over families of max(0, copies-1). A family with 3 copies contributes 2 to excess_copies. Ranges from 0% upward (can exceed 100%).

contamination_pct_multicopy

Secondary contamination metric based on multicopy family count. Provides an alternative perspective on contamination for comparison with headline metric.

Supporting Counts

expected_markers

Total number of marker families expected for the genome's domain assignment (based on marker set used).

detected_markers

Number of marker families with at least one copy detected in the genome.

multicopy_markers

Number of marker families detected with more than one copy (indicating potential contamination).

excess_copies

Total excess copies across all families. For each family with n copies where n > 1, contributes (n-1) to this count.

effective_denominator

The effective denominator used in completeness calculation. May differ from expected_markers in some edge cases.

Domain and Taxonomy Information

domain_assignment

The taxonomic domain (Bacteria, Archaea, Viruses, etc.) assigned during marker vector generation.

marker_set_id

Identifier for the marker set used for this analysis.

lineage_taxid

Taxonomic ID of the lineage used for the analysis.

rank

Taxonomic rank of the lineage assignment.

assignment_confidence

Confidence score of the domain/lineage assignment (0-1 scale, or NA if not computed).

assignment_confidence_model

Name of the model used for confidence scoring.

ood_status

Out-of-distribution status. Fixed to 'unknown' pending OD-9 implementation.

sufficient_evidence

Indicator of whether sufficient evidence exists for reliable completeness/contamination estimation.

Examples

Example 1: Basic QC Report

magqc.sh vector=MAG_001.markers.tsv out=MAG_001.qc.tsv

Generates a QC report for a single genome bin. The vector file should be generated by markervector.sh in=MAG_001.fa out=MAG_001.markers.tsv. Output is written to MAG_001.qc.tsv with completeness, contamination, and all supporting metrics.

Example 2: Write to Standard Output

magqc.sh vector=genome.markers.tsv

When out parameter is omitted (or set to stdout), the report is written to standard output. Useful for piping to other commands or viewing results directly in the terminal.

Example 3: Prevent Overwriting Existing Files

magqc.sh vector=MAG_002.markers.tsv out=MAG_002.qc.tsv ow=f

Sets ow=f to prevent overwriting if MAG_002.qc.tsv already exists. The tool will throw an error if the output file exists, protecting against accidental data loss.

Example 4: Specify Java Memory for Large Analyses

magqc.sh -Xmx8g vector=large_genome.markers.tsv out=qc.tsv

Explicitly allocates 8GB of Java heap memory for the analysis. Useful when processing very large marker sets or in memory-constrained environments.

Support

For questions and support:

• Email: bbushnell@lbl.gov
• Documentation: bbmap.org