Metadata-Version: 2.4
Name: crococlean
Version: 0.2.0
Summary: CroCoClean decontaminates species abundance profiles from metagenomic samples affected by cross-sample contamination.
License: GPL-3.0-or-later
License-File: COPYING
Keywords: Metagenomics
Author: Niya Ren
Requires-Python: >=3.12
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: numpy (>=2.4,<3.0)
Requires-Dist: pandas (>=2.3,<3.0)
Requires-Dist: tqdm (>=4.67,<5.0)
Project-URL: Repository, https://github.com/metagenopolis/CroCoClean
Description-Content-Type: text/markdown

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

[![install with conda](https://anaconda.org/fplazaonate/crococlean/badges/version.svg)](https://anaconda.org/fplazaonate/crococlean)
[![PyPI](https://img.shields.io/pypi/v/crococlean?label=pypi%20package)](https://pypi.org/project/crococlean/)

## 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](https://github.com/metagenopolis/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](https://doi.org/10.1186/s40168-018-0605-2) and [SCRuB](https://doi.org/10.1038/s41587-023-01696-w).

### 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, unless the `--no-normalization` option is used. The contamination rate can optionally be re-estimated from the abundance table rather than taken from the CroCoDeEL output.

## Installation

CroCoClean is available on [conda](https://anaconda.org/channels/fplazaonate/packages/crococlean/overview):
```
conda create --name crococlean_env -c conda-forge fplazaonate::crococlean
conda activate crococlean_env
```

Alternatively, you can use [pip](https://pypi.org/project/crococlean/) 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:

```bash
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  | ... |
| ...          |   ...   |   ...   |   ...   | ... |

By default, 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. This normalization can be disabled with the `--no-normalization` option, for instance when working with profiles expressed as estimated genome coverage.

CroCoClean was developed and optimized using species abundance profiles generated by [Meteor](https://github.com/metagenopolis/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](https://github.com/bluenote-1577/sylph) or [MetaPhlAn4](https://github.com/biobakery/metaphlan), although performance may vary depending on the profiling method and the characteristics of the resulting abundance profiles.

An example abundance table is available [here](https://github.com/metagenopolis/CroCoDeEL/blob/main/crococlean/test_data/mgs_profiles_test.tsv).

#### 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](https://github.com/metagenopolis/CroCoDeEL/blob/main/crococlean/test_data/results/contamination_events.tsv).

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](https://metagenopolis.github.io/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:

```bash
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:

```bash
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:

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

The optional `--no-normalization` flag disables the normalization to relative abundances of both the input and the output tables. Abundances are then kept in their original units, which is useful when profiles are expressed as estimated genome coverage rather than as relative abundances.

```bash
crococlean run \
    -s species_coverage.tsv \
    -c crocodeel_output.tsv \
    -o species_coverage_decontaminated.tsv \
    --no-normalization
```

With this flag, the expected contribution of the contamination source is subtracted directly in the units of the input table, without rescaling the source profile. CroCoDeEL estimates contamination rates on relative abundance profiles, so the rates reported in its output file are not directly applicable to abundances expressed in other units. The `--recompute-rate` option described below addresses this and is recommended whenever `--no-normalization` is used. CroCoClean emits a warning when `--no-normalization` is used without it.

The optional `--recompute-rate` flag recomputes the contamination rate of each event from the species abundance table instead of using the rate reported by CroCoDeEL.

For each contamination event, the rate is re-estimated as the geometric mean of the target-to-source abundance ratio over the species listed in the `contamination_specific_species` field. This reproduces the way CroCoDeEL estimates contamination rates, as the offset of a line of slope one fitted in log10 abundance space. The estimate depends only on abundance ratios and is therefore expressed in the units of the input table, which makes it directly applicable when `--no-normalization` is used.

```bash
crococlean run \
    -s species_coverage.tsv \
    -c crocodeel_output.tsv \
    -o species_coverage_decontaminated.tsv \
    --no-normalization \
    --recompute-rate
```

A contamination rate is recomputed only when at least 8 species, the minimum number of species CroCoDeEL requires to define a contamination line, remain after discarding species absent from either sample. Otherwise the rate reported by CroCoDeEL is used and a warning is emitted.

Recomputed rates may exceed one when abundances are not normalized, for instance when the contamination source has been sequenced much more deeply than the target sample.


### 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:

```text
<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:

```text
sample2_deconta_sample1
```

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

```text
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.

