q2-mag

Rachis plugin for contig binning, bin quality assessment and MAG dereplication.

version: 2026.7.0

website: https://github.com

user support:

Please post to the QIIME 2 forum for help with this plugin: https://forum.qiime2.org

Actions¶

Artifact Classes¶

Formats¶

mag bin-contigs-metabat¶

This method uses MetaBAT 2 to bin provided contigs into MAGs.

Citations¶

Kang et al., 2019; Li et al., 2009; Zenodo, 2023

Inputs¶

contigs: SampleData[Contigs]

Contigs to be binned.[required]

alignment_maps: SampleData[AlignmentMap % Properties('sorted')]

Reads-to-contig alignment maps.[required]

Parameters¶

min_contig: Int % Range(1500, None)

Minimum size of a contig for binning.[optional]

max_p: Int % Range(1, 100)

Percentage of "good" contigs considered for binning decided by connection among contigs. The greater, the more sensitive.[optional]

min_s: Int % Range(1, 100)

Minimum score of a edge for binning. The greater, the more specific.[optional]

max_edges: Int % Range(1, None)

Maximum number of edges per node. The greater, the more sensitive.[optional]

p_tnf: Int % Range(0, 100)

TNF probability cutoff for building TNF graph. Use it to skip the preparation step. (0: auto)[optional]

no_add: Bool

Turning off additional binning for lost or small contigs.[optional]

min_cv: Int % Range(1, None)

Minimum mean coverage of a contig in each library for binning.[optional]

min_cv_sum: Int % Range(1, None)

Minimum total effective mean coverage of a contig (sum of depth over minCV) for binning.[optional]

min_cls_size: Int % Range(1, None)

Minimum size of a bin as the output.[optional]

num_threads: Int % Range(0, None)

Number of threads to use (0: use all cores).[optional]

seed: Int % Range(0, None)

For exact reproducibility. (0: use random seed)[optional]

debug: Bool

Debug output.[optional]

verbose: Bool

Verbose output.[optional]

Outputs¶

mags: SampleData[MAGs]

The resulting MAGs.[required]

contig_map: FeatureMap[MAGtoContigs]

Mapping of MAG identifiers to the contig identifiers contained in each MAG.[required]

unbinned_contigs: SampleData[Contigs % Properties('unbinned')]

Contigs that were not binned into any MAG.[required]

mag dereplicate-mags¶

This method dereplicates MAGs from multiple samples using distances between them found in the provided distance matrix. For each cluster of similar MAGs, the longest one will be selected as the representative. If metadata is given as input, the MAG with the highest or lowest value in the specified metadata column is chosen, depending on the parameter "find-max". If there are MAGs with identical values, the longer one is chosen. For example an artifact of type BUSCOResults can be passed as metadata, and the dereplication can be done by highest "completeness".

Inputs¶

mags: SampleData[MAGs]

MAGs to be dereplicated.[required]

distance_matrix: DistanceMatrix

Matrix of distances between MAGs.[required]

Parameters¶

threshold: Float % Range(0, 1, inclusive_end=True)

Similarity threshold required to consider two bins identical.[default: 0.99]

metadata: Metadata

Metadata table.[optional]

metadata_column: Str

Name of the metadata column used to choose the most representative bins.[default: 'complete']

find_max: Bool

Set to True to choose the bin with the highest value in the metadata column. Set to False to choose the bin with the lowest value.[default: True]

Outputs¶

dereplicated_mags: FeatureData[MAG]

Dereplicated MAGs.[required]

table: FeatureTable[PresenceAbsence]

Mapping between MAGs and samples.[required]

mag collate-busco-results¶

Collates BUSCO results.

Inputs¶

results: List[BUSCOResults]

<no description>[required]

Outputs¶

collated_results: BUSCOResults

<no description>[required]

mag -evaluate-busco¶

This method uses BUSCO to assess the quality of assembled MAGs and generates a table summarizing the results.

Citations¶

Manni et al., 2021

Inputs¶

mags: SampleData[MAGs] | FeatureData[MAG]

MAGs to be analyzed.[required]

db: ReferenceDB[BUSCO]

BUSCO database.[required]

unbinned_contigs: SampleData[Contigs]

Contigs which were not assigned to any bin.[optional]

Parameters¶

mode: Str % Choices('genome')

Specify which BUSCO analysis mode to run.Currently only the 'genome' option is supported, for genome assemblies. In the future modes for transcriptome assemblies and for magd gene sets (proteins) will be made available.[default: 'genome']

lineage_dataset: Str

Specify the name of the BUSCO lineage to be used. To see all possible options run busco --list-datasets.[optional]

augustus: Bool

Use augustus gene predictor for eukaryote runs.[default: False]

augustus_parameters: Str

Pass additional arguments to Augustus. All arguments should be contained within a single string with no white space, with each argument separated by a comma. Example: '--PARAM1=VALUE1,--PARAM2=VALUE2'.[optional]

augustus_species: Str

Specify a species for Augustus training.[optional]

cpu: Int % Range(1, None)

Specify the number (N=integer) of threads/cores to use.[default: 1]

contig_break: Int % Range(0, None)

Number of contiguous Ns to signify a break between contigs. See https://gitlab.com/ezlab/busco/-/issues/691 for a more detailed explanation.[default: 10]

evalue: Float % Range(0, None, inclusive_start=False)

E-value cutoff for BLAST searches. Allowed formats, 0.001 or 1e-03.[default: 0.001]

limit: Int % Range(1, 20)

How many candidate regions (contig or transcript) to consider per BUSCO.[default: 3]

long: Bool

Optimization Augustus self-training mode (Default: Off); adds considerably to the run time, but can improve results for some non-model organisms.[default: False]

metaeuk_parameters: Str

Pass additional arguments to Metaeuk for the first run. All arguments should be contained within a single string with no white space, with each argument separated by a comma. Example: --PARAM1=VALUE1,--PARAM2=VALUE2.[optional]

metaeuk_rerun_parameters: Str

Pass additional arguments to Metaeuk for the second run. All arguments should be contained within a single string with no white space, with each argument separated by a comma. Example: --PARAM1=VALUE1,--PARAM2=VALUE2.[optional]

miniprot: Bool

Use miniprot gene predictor for eukaryote runs.[default: False]

additional_metrics: Bool

Adds completeness and contamination values to the BUSCO report. Check here for documentation: https://github.com/metashot/busco?tab=readme-ov-file#documetation[default: False]

Outputs¶

results: BUSCOResults

BUSCO result table.[required]

mag fetch-busco-db¶

Downloads BUSCO database for the specified lineage. Output can be used to run BUSCO with the 'evaluate-busco' action.

Citations¶

Manni et al., 2021

Parameters¶

lineages: List[Str]

Lineages to be included in the database. Can be any valid BUSCO lineage or any of the following: 'all' (for all lineages), 'prokaryota', 'eukaryota', 'virus'.[optional]

Outputs¶

db: ReferenceDB[BUSCO]

BUSCO database for the specified lineages.[required]

mag filter-derep-mags¶

Filter dereplicated MAGs based on metadata.

Inputs¶

mags: FeatureData[MAG]

Dereplicated MAGs to filter.[required]

Parameters¶

metadata: Metadata

Sample metadata indicating which MAG ids to filter. The optional where parameter may be used to filter ids based on specified conditions in the metadata. The optional exclude_ids parameter may be used to exclude the ids specified in the metadata from the filter.[optional]

where: Str

Optional SQLite WHERE clause specifying MAG metadata criteria that must be met to be included in the filtered data. If not provided, all MAGs in metadata that are also in the MAG data will be retained.[optional]

exclude_ids: Bool

Defaults to False. If True, the MAGs selected by the metadata and optional where parameter will be excluded from the filtered data.[default: False]

remove_empty: Bool

Remove empty MAGs.[default: False]

Outputs¶

filtered_mags: FeatureData[MAG]

<no description>[required]

mag filter-mags¶

Filter MAGs based on metadata.

Inputs¶

mags: SampleData[MAGs]

MAGs to filter.[required]

Parameters¶

metadata: Metadata

Sample metadata indicating which MAG ids to filter. The optional where parameter may be used to filter ids based on specified conditions in the metadata. The optional exclude_ids parameter may be used to exclude the ids specified in the metadata from the filter.[optional]

where: Str

Optional SQLite WHERE clause specifying MAG metadata criteria that must be met to be included in the filtered data. If not provided, all MAGs in metadata that are also in the MAG data will be retained.[optional]

exclude_ids: Bool

Defaults to False. If True, the MAGs selected by the metadata and optional where parameter will be excluded from the filtered data.[default: False]

on: Str % Choices('sample', 'mag')

Whether to filter based on sample or MAG metadata.[default: 'mag']

remove_empty: Bool

Remove empty MAGs.[default: False]

Outputs¶

filtered_mags: SampleData[MAGs]

<no description>[required]

mag get-feature-lengths¶

This method extract lengths for the provided feature set.

Inputs¶

features: FeatureData[MAG | Sequence] | SampleData[MAGs | Contigs]

Features to get lengths for.[required]

Outputs¶

lengths: FeatureData[SequenceCharacteristics % Properties('length')]

Feature lengths.[required]

mag estimate-abundance¶

This method estimates MAG/contig abundances by mapping the reads to them and calculating respective metric valueswhich are then used as a proxy for the frequency.

Inputs¶

alignment_maps: FeatureData[AlignmentMap] | SampleData[AlignmentMap]

Bowtie2 alignment maps between reads and features for which the abundance should be estimated.[required]

feature_lengths: FeatureData[SequenceCharacteristics % Properties('length')]

Table containing length of every feature (MAG/contig).[required]

Parameters¶

metric: Str % Choices('rpkm') | Str % Choices('tpm')

Metric to be used as a proxy of feature abundance.[default: 'rpkm']

min_mapq: Int % Range(0, 255)

Minimum mapping quality.[default: 0]

min_query_len: Int % Range(0, None)

Minimum query length.[default: 0]

min_base_quality: Int % Range(0, None)

Minimum base quality.[default: 0]

min_read_len: Int % Range(0, None)

Minimum read length.[default: 0]

threads: Int % Range(1, None)

Number of threads to pass to samtools.[default: 1]

Outputs¶

abundances: FeatureTable[Frequency % (Properties('rpkm')¹ | Properties('tpm')²)]

Feature abundances.[required]

mag bin-contigs-semibin2¶

This method uses SemiBin2 to bin provided contigs into MAGs. Note that SemiBin2 does not output what it considers ‘unbinned’ contigs

Citations¶

Pan et al., 2022; Pan et al., 2023

Inputs¶

contigs: SampleData[Contigs]

Contigs to be binned.[required]

alignment_maps: SampleData[AlignmentMap % Properties('sorted')]

Reads-to-contig alignment maps.[required]

Parameters¶

training_type: Str % Choices('semi', 'self')

Training algorithm used to train the model.[optional]

orf_finder: Str % Choices('fast-naive', 'prodigal', 'fraggenescan')

Gene predictor used to estimate the number of bins.[default: 'fast-naive']

environment: Str % Choices('human_gut', 'dog_gut', 'ocean', 'soil', 'cat_gut', 'human_oral', 'mouse_gut', 'pig_gut', 'built_environment', 'wastewater', 'chicken_caecum', 'global')

Which pre-trained model to use.[default: 'global']

engine: Str % Choices('auto', 'gpu', 'cpu')

Device used to train the model.[default: 'auto']

sequencing_type: Str % Choices('short_read', 'long_read')

Specify whether your data consists of short- or long-reads. For hybrid data (long- and short-reads), it is recommended to use the long-reads pipeline.[default: 'short_read']

minfasta_kbs: Int % Range(1, None)

Minimum bin size in kilo-basepairs.[default: 200]

no_recluster: Bool

Do not recluster bins. This saves a small amount of time, but pre-reclustering bins are always output.[default: False]

epochs: Int % Range(1, None)

Number of epochs used in the training process.[default: 15]

batch_size: Int % Range(1, None)

Number of epochs used in the training process.[default: 2048]

max_node: Int % Range(1, None)

Percentage of contigs that considered to be binned.[default: 1]

max_edges: Int % Range(1, None)

The maximum number of edges that can be connected to one contig.[default: 200]

ratio: Float % Range(0.0, None)

If the ratio of the number of base pairs of contigs between 1000-2500 bp smaller than this value, the minimal length will be set as 1000 bp, otherwise 2500 bp. Setting --p-min-length overrules this parameter.[default: 0.05]

threads: Int % Range(0, None)

Number of threads to use (0: use all cores).[default: 1]

min_len: Int % Range(1, None)

Minimal contig length (bp) to include in binning. Contigs shorter than this length are excluded. This parameter overrules --p-ratio.[optional]

ml_threshold: Int % Range(1, None)

Length threshold for generating must-link constraints. (By default, the threshold is calculated from the contig, and the default minimum value is 4,000 bp).[optional]

random_seed: Int % Range(0, None)

For exact reproducibility. (0: use random seed)[optional]

debug: Bool

Debug output.[default: False]

Outputs¶

mags: SampleData[MAGs]

The resulting MAGs.[required]

contig_map: FeatureMap[MAGtoContigs]

Mapping of MAG identifiers to the contig identifiers contained in each MAG.[required]

mag -visualize-busco¶

This method generates a visualization from the BUSCO results table.

Citations¶

Manni et al., 2021

Inputs¶

results: BUSCOResults

BUSCO results table.[required]

unbinned_contigs: SampleData[Contigs]

Contigs which were not assigned to any bin.[optional]

Outputs¶

visualization: Visualization

<no description>[required]

mag evaluate-busco¶

This method uses BUSCO to assess the quality of assembled MAGs and generates a table summarizing the results.

Citations¶

Manni et al., 2021

Inputs¶

mags: SampleData[MAGs] | FeatureData[MAG]

MAGs to be analyzed.[required]

db: ReferenceDB[BUSCO]

BUSCO database.[required]

unbinned_contigs: SampleData[Contigs]

Contigs which were not assigned to any bin.[optional]

Parameters¶

mode: Str % Choices('genome')

Specify which BUSCO analysis mode to run.Currently only the 'genome' option is supported, for genome assemblies. In the future modes for transcriptome assemblies and for magd gene sets (proteins) will be made available.[default: 'genome']

lineage_dataset: Str

Specify the name of the BUSCO lineage to be used. To see all possible options run busco --list-datasets.[optional]

augustus: Bool

Use augustus gene predictor for eukaryote runs.[default: False]

augustus_parameters: Str

Pass additional arguments to Augustus. All arguments should be contained within a single string with no white space, with each argument separated by a comma. Example: '--PARAM1=VALUE1,--PARAM2=VALUE2'.[optional]

augustus_species: Str

Specify a species for Augustus training.[optional]

cpu: Int % Range(1, None)

Specify the number (N=integer) of threads/cores to use.[default: 1]

contig_break: Int % Range(0, None)

Number of contiguous Ns to signify a break between contigs. See https://gitlab.com/ezlab/busco/-/issues/691 for a more detailed explanation.[default: 10]

evalue: Float % Range(0, None, inclusive_start=False)

E-value cutoff for BLAST searches. Allowed formats, 0.001 or 1e-03.[default: 0.001]

limit: Int % Range(1, 20)

How many candidate regions (contig or transcript) to consider per BUSCO.[default: 3]

long: Bool

Optimization Augustus self-training mode (Default: Off); adds considerably to the run time, but can improve results for some non-model organisms.[default: False]

metaeuk_parameters: Str

Pass additional arguments to Metaeuk for the first run. All arguments should be contained within a single string with no white space, with each argument separated by a comma. Example: --PARAM1=VALUE1,--PARAM2=VALUE2.[optional]

metaeuk_rerun_parameters: Str

Pass additional arguments to Metaeuk for the second run. All arguments should be contained within a single string with no white space, with each argument separated by a comma. Example: --PARAM1=VALUE1,--PARAM2=VALUE2.[optional]

miniprot: Bool

Use miniprot gene predictor for eukaryote runs.[default: False]

additional_metrics: Bool

Adds completeness and contamination values to the BUSCO report. Check here for documentation: https://github.com/metashot/busco?tab=readme-ov-file#documetation[default: True]

num_partitions: Int % Range(1, None)

The number of partitions to split the data into. Defaults to partitioning into individual samples.[optional]

Outputs¶

results: BUSCOResults

BUSCO result table.[required]

visualization: Visualization

Visualization of the BUSCO results.[required]