CroCoClean: decontamination of species abundance profiles from metagenomic samples affected by cross-sample contamination

Introduction

What is CroCoClean?

CroCoClean is a bioinformatics tool for decontaminating species abundance profiles from metagenomic samples affected by cross-sample contamination.

What CroCoClean is not

CroCoClean should not be confused with CroCoDeEL, which is designed to detect and estimate cross-sample contamination.

CroCoClean is designed to operate on species abundance profiles generated from shotgun metagenomic sequencing data. It is not designed for amplicon-based profiles, such as 16S rRNA gene sequencing abundance tables.

CroCoClean is not designed to remove sequencing reads originating from the contamination source; it operates directly on species abundance profiles.

CroCoClean is not designed to remove external or reagent-derived contamination, which can be addressed by tools such as decontam and SCRuB.

How CroCoClean works

For each contamination event, CroCoClean uses the species abundance profile of the contamination source and the estimated contamination rate to subtract the expected contribution of the contaminating sample from the target sample. Abundances falling below the minimum non-zero abundance observed in the original target profile are set to zero. Species identified by CroCoDeEL as being specifically introduced by the contamination event are also set to zero. The corrected profile is then renormalized so that its abundances sum to one.

Installation

CroCoClean is available on conda:

conda create --name crococlean_env -c conda-forge fplazaonate::crococlean
conda activate crococlean_env

Alternatively, you can use pip with Python ≥ 3.12:

pip install crococlean

Test the installation

After installation, you can run the built-in self-test to verify that CroCoClean is correctly installed:

crococlean test

Quick start

Input

CroCoClean requires two input files:

1. a species abundance table containing the abundance profile of each species in each sample
2. a CroCoDeEL output file containing the detected cross-sample contamination events and their estimated contamination rates.

Species abundance table

The species abundance table must be provided in TSV format. The first column should contain species names, and each subsequent column should correspond to a sample.

For example:

species_name	sample1	sample2	sample3	...
species 1	0.00	0.05	0.07	...
species 2	0.10	0.01	0.00	...
...	...	...	...	...

CroCoClean operates on relative abundances. The input table is automatically normalized so that the abundances in each sample sum to one. Consequently, the input values do not necessarily need to be normalized beforehand.

CroCoClean was developed and optimized using species abundance profiles generated by Meteor, and is therefore expected to perform best with Meteor-derived profiles. It can also be used with profiles generated by other shotgun metagenomic profilers, such as Sylph or MetaPhlAn4, although performance may vary depending on the profiling method and the characteristics of the resulting abundance profiles.

An example abundance table is available here.

CroCoDeEL output file

CroCoClean also requires the TSV output file generated by CroCoDeEL. This file must contain the contamination events detected by CroCoDeEL, including the source and target samples and their corresponding estimated contamination rates.

An example is available here.

The abundance table and the CroCoDeEL output file must refer to the same samples and species.

Manual curation of the CroCoDeEL results is strongly recommended before running CroCoClean. CroCoDeEL may produce false-positive contamination events, and CroCoClean will perform decontamination for every event provided in the input file.

The CroCoDeEL Interpreter can be used to facilitate the manual inspection and curation of CroCoDeEL contamination events.

Run CroCoClean

CroCoClean uses the run subcommand to perform decontamination:

crococlean run \
    -s species_abundance.tsv \
    -c crococlean_output.tsv \
    -o species_abundance_decontaminated.tsv

By default, CroCoClean uses a single process. The number of processes can be increased using the --nproc option:

crococlean run \
    -s species_abundance.tsv \
    -c crocodeel_output.tsv \
    -o species_abundance_decontaminated.tsv \
    --nproc 8

The optional --filter-low-ab parameter filters out low-abundance species that may be inaccurately quantified. The value should be the same as the --filter-low-ab parameter used when running CroCoDeEL.

A value of 20 is recommended for MetaPhlAn 4.

For example:

crococlean run \
    -s species_abundance.tsv \
    -c crocodeel_output.tsv \
    -o species_abundance_decontaminated.tsv \
    --filter-low-ab 20

Output

The original abundance profiles are retained in the output together with the decontaminated profiles generated for each contamination event.

Decontaminated profiles are named using the following convention:

<target>_deconta_<source>

where <target> is the contaminated sample and <source> is the sample identified as the contamination source.

For example, if sample2 was contaminated by sample1, the corresponding decontaminated profile will be named:

sample2_deconta_sample1

When a sample has multiple contamination sources, a separate decontaminated profile is generated independently for each contamination event. For example:

sample2_deconta_sample1
sample2_deconta_sample3

Current limitations

CroCoClean is an early release and has not yet been extensively tested across a broad range of datasets and contamination scenarios. Its results should therefore be interpreted with caution and independently validated before being used for downstream analyses. Use at your own risk.

CroCoClean is currently subject to the following limitations:

• Independent decontamination of multiple contamination events: When a target sample is affected by multiple contamination sources, each contamination event is decontaminated independently. CroCoClean therefore generates a separate corrected profile for each source rather than simultaneously removing all detected contamination sources from a single profile.

• Reduced accuracy at high contamination levels: When the estimated contamination rate is high, decontamination may be less accurate. In particular, some species introduced by the contamination may not be identified as contamination-specific and therefore may not be set to zero.

• Complex contamination scenarios: CroCoClean may produce inaccurate results in complex contamination scenarios. This includes cases where a contamination source is itself contaminated by another sample, as well as cases of reciprocal contamination where two samples contaminate each other.