Skip to content

SingleM.md

Latest commit

 

History

History
170 lines (111 loc) · 6.29 KB

SingleM.md

File metadata and controls

170 lines (111 loc) · 6.29 KB
Raw

SingleM

The singleM module runs SingleM on paired-end shotgun metagenomic reads. It produces a SingleM taxonomic profile, a SingleM OTU table, and an archive containing relative-abundance tables at all taxonomic levels generated by singlem summarise.

SingleM is designed mainly for microbial shotgun metagenomes. It searches reads for conserved bacterial and archaeal single-copy marker genes, then estimates community composition from those marker genes. It is therefore most appropriate for bacteria and archaea. It is not a broad eukaryotic, fungal, viral, or plasmid classifier.

Module Inputs

Forward Reads Pattern

Pattern selecting the forward reads. Use a wildcard pattern created by the wildcard-creator module when processing several samples together, for example:

ERR*_1.fastq.gz

In the saved pipeline configuration, SLIM stores this internally with € to preserve grouped file patterns, but the interface shows *.

Reverse Reads Pattern

Pattern selecting the reverse reads, for example:

ERR*_2.fastq.gz

The number and ordering of forward and reverse files must match.

Outputs

SingleM Taxonomic Profile

Default:

singleM.profile.tsv

This is the condensed SingleM taxonomic profile produced by:

singlem pipe --taxonomic-profile

The values are estimated coverage, not simple read counts.

SingleM OTU Table

Default:

singleM.otu_table.tsv

This is the marker-gene OTU table produced by:

singlem pipe --otu-table

Relative-Abundance Tables Archive

Default:

singleM.relative_abundance_tables.tar.gz

SLIM runs singlem summarise and stores the resulting relative-abundance tables in this archive. The archive contains tables for the taxonomic levels generated by SingleM, such as species, genus, family, order, class, phylum, and domain when available.

fastp Reports Archive

Default:

singleM.fastp_reports.tar.gz

If fastp preprocessing is enabled, this archive contains one HTML report and one JSON report per sample. If fastp preprocessing is disabled, the archive contains a small text file saying that fastp was skipped.

Options

Trim Adapters and Low-Quality Bases with fastp

Default in SLIM:

enabled

When enabled, SLIM runs fastp before SingleM with:

--detect_adapter_for_pe
--thread <SLIM threads>

fastp then uses its own default filtering parameters unless they are changed in the script. Important fastp defaults are:

Parameter fastp default Meaning
--qualified_quality_phred 15 A base is considered qualified if its Phred score is at least this value.
--unqualified_percent_limit 40 A read can contain this percentage of unqualified bases before being filtered.
--length_required 15 Reads shorter than this after trimming are discarded.
--average_qual 0 No average-read-quality filter by default.
--detect_adapter_for_pe disabled by fastp, enabled by SLIM Enables paired-end adapter detection.

fastp also trims adapters and, when relevant, handles polyG tails for Illumina two-color systems.

Advanced SingleM Parameters

The current SLIM interface does not expose these SingleM parameters, but they are useful to know when interpreting results or extending the module later.

Parameter SingleM default Meaning
--metapackage SLIM uses the mounted SingleM metapackage Database/metapackage used for marker genes and taxonomy. This is the most important SingleM database setting.
--evalue 1e-05 HMMSEARCH e-value cutoff used during sequence gathering. Lower values are more stringent.
--min-orf-length 72 for reads, 300 for genomes Minimum uninterrupted ORF length in base pairs. Lowering this can help short reads but may increase noise.
--restrict-read-length no restriction Uses only the first part of each read if set.
--translation-table 4 Codon table used for translation. Table 4 is close to the usual bacterial/archaeal table but handles TGA differently.
--assignment-threads 1 Number of processes used during taxonomy assignment.

Unlike Kraken2, SingleM is not controlled by a k-mer size in the main user-facing workflow. The most important choices are the metapackage, read preprocessing, and the sensitivity settings above.

Practical Advice

Standard Illumina Shotgun Data

Using fastp is usually reasonable because it removes adapters and very poor reads. Keep in mind that SingleM can lose sensitivity if reads become too short after trimming.

Ancient DNA or Very Short Reads

Be careful with aggressive trimming. Ancient DNA reads can be short, damaged, and adapter-rich. Adapter trimming is useful, but strict length or quality filtering can remove the signal. The current SLIM default keeps fastp's minimum length at 15 bp, which is permissive. If you modify the script later, avoid high values such as --length_required 75 or 100 for ancient DNA.

For ancient DNA, SingleM can work for bacterial or archaeal communities if enough marker-gene signal remains, but it is not an authentication tool. Damage patterns, contamination controls, and independent validation should be assessed outside this module.

Eukaryotes, Fungi, and Viruses

Use kraken2-bracken or a custom classifier database instead. SingleM's default marker-gene approach is not intended for broad eukaryotic or viral taxonomic annotation.

Current Command Structure

The SLIM wrapper runs approximately:

fastp -i R1.fastq.gz -I R2.fastq.gz \
  -o trimmed.R1.fastq.gz -O trimmed.R2.fastq.gz \
  --detect_adapter_for_pe \
  --thread <threads>

singlem pipe \
  -1 <forward files> \
  -2 <reverse files> \
  --metapackage <SingleM metapackage> \
  --taxonomic-profile singleM.profile.tsv \
  --otu-table singleM.otu_table.tsv \
  --threads <threads>

singlem summarise \
  --input-taxonomic-profiles singleM.profile.tsv \
  --metapackage <SingleM metapackage> \
  --output-species-by-site-relative-abundance-prefix singleM.relative_abundance

References