Metadata-Version: 2.4
Name: crococlean
Version: 0.1.1
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: 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.

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

## 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](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

Run the following command to decontaminate the species abundance table:

```bash
crococlean \
    -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 \
    -s species_abundance.tsv \
    -c crococlean_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 \
    -s species_abundance.tsv \
    -c crococlean_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:

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

