# CroCoDeEL : **CRO**ss-sample **CO**ntamination **DE**tection and **E**stimation of its **L**evels 🐊
[](https://anaconda.org/fplazaonate/crocodeel)
[](https://pypi.org/project/crocodeel/)
## Introduction
CroCoDeEL is a tool that detects cross-sample (aka well-to-well) contamination in shotgun metagenomic data.\
It accurately identifies contaminated samples but also pinpoints contamination sources and estimates contamination rates.\
CroCoDeEL relies only on species abundance tables and does not need negative controls.
## Installation
CroCoDeEL can be easily installed with conda:
```
conda create --name crocodeel_env -c conda-forge -c fplazaonate crocodeel
conda activate crocodeel_env
```
Alternatively, you can use pip:
```
pip install crocodeel
```
Finally, you can test that CroCoDeEL is correctly installed with the following command:
```
crocodeel test_install
```
## Quick start
### Input
CroCoDeEL takes as input a species abundance table in TSV format.\
The first column should correspond to species names. The other columns correspond to the abundance of species in each sample.
| species_name | sample1 | sample2 | sample3 | ... |
|:----------------|:-------:|:-------:|:-------:|:--------:|
| species 1 | 0 | 0.05 | 0.07 | ... |
| species 2 | 0.1 | 0.01 | 0 | ... |
| ... | ... | ... | ... | ... |
CroCoDeEL works with relative abundances.
The table will automatically be normalized so the abundance of each column equals 1.
**Important**: CroCoDeEL requires the abundance of subdominant species to be accurately estimated.\
We strongly recommend using [the Meteor software suite](https://github.com/metagenopolis/meteor) to generate the species abundance table.\
Alternatively, you can use [sylph](https://github.com/bluenote-1577/sylph) although low-level contaminations may go unnoticed.\
We advise against the use of other taxonomic profilers (e.g. MetaPhlan4 or mOTUs) that do not meet this requirement according to our benchmarks.
### Search contamination
Run the following command to search for cross-sample contamination:
```
crocodeel search_conta -s species_abundance.tsv -c contamination_events.tsv
```
CroCoDeEL will report all detected contamination events in the _contamination_events.tsv_ output file.\
This TSV file reports for each event the contamination source, the contaminated sample (target) and the estimated contamination rate.\
The score (probability) computed by the Random Forest model as well as species specifically introduced by contamination in the target are also given.
### Visualization of the results
Contaminations events can be visually inspected by generating a PDF file consisting in scatterplots.
```
crocodeel plot_conta -s species_abundance.tsv -c contamination_events.tsv -r contamination_events.pdf
```
Each scatterplot compares in a log-scale the species abundance profiles of a contaminated sample (x-axis) and its contamination source (y-axis).\
The contamination line (in red) highlights species specifically introduced by contamination.
### Easy workflow
Alternatively, you can search for cross-sample contamination and create the PDF report in one command.
```
crocodeel easy_wf -s species_abundance.tsv -c contamination_events.tsv -r contamination_events.pdf
```
### Results interpretation
CroCoDeEL will probably report false contamination events for samples with similar species abundances profiles (e.g. longitudinal data, animals raised together).\
For non-related samples, CroCoDeEL may occasionally generate false positives that can be filtered out by a human-expert.\
Thus, we strongly recommend inspecting scatterplots of each contamination event to discard potential false positives.\
_We will explain how to do it soon._
## Authors
* Lindsay Goulet: lindsay.goulet@inrae.fr
* Florian Plaza Oñate: florian.plaza-onate@inrae.fr
* Edi Prifti: edi.prifti@ird.fr
* Eugeni Belda: eugeni.belda@ird.fr
* Emmanuelle Le Chatelier: emmanuelle.le-chatelier@inrae.fr
* Guillaume Gautreau: guillaume.gautreau@inrae.fr
Raw data
{
"_id": null,
"home_page": "https://github.com/metagenopolis/CroCoDeEL",
"name": "crocodeel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "Metagenomics",
"author": "Lindsay Goulet",
"author_email": "lindsay.goulet@inrae.fr",
"download_url": "https://files.pythonhosted.org/packages/ac/97/a4f1eca6e095f5213ef2e9da12d2afe83c892454074fba96165f6775b7ce/crocodeel-1.0.2.tar.gz",
"platform": null,
"description": "# CroCoDeEL : **CRO**ss-sample **CO**ntamination **DE**tection and **E**stimation of its **L**evels \ud83d\udc0a\n\n[](https://anaconda.org/fplazaonate/crocodeel)\n[](https://pypi.org/project/crocodeel/)\n\n## Introduction\n\nCroCoDeEL is a tool that detects cross-sample (aka well-to-well) contamination in shotgun metagenomic data.\\\nIt accurately identifies contaminated samples but also pinpoints contamination sources and estimates contamination rates.\\\nCroCoDeEL relies only on species abundance tables and does not need negative controls.\n\n## Installation\n\nCroCoDeEL can be easily installed with conda:\n```\nconda create --name crocodeel_env -c conda-forge -c fplazaonate crocodeel\nconda activate crocodeel_env\n```\n\nAlternatively, you can use pip:\n```\npip install crocodeel\n```\n\nFinally, you can test that CroCoDeEL is correctly installed with the following command:\n```\ncrocodeel test_install\n```\n\n## Quick start\n### Input\nCroCoDeEL takes as input a species abundance table in TSV format.\\\nThe first column should correspond to species names. The other columns correspond to the abundance of species in each sample.\n\n| species_name | sample1 | sample2 | sample3 | ... | \n|:----------------|:-------:|:-------:|:-------:|:--------:| \n| species 1 | 0 | 0.05 | 0.07 | ... | \n| species 2 | 0.1 | 0.01 | 0 | ... | \n| ... | ... | ... | ... | ... | \n\nCroCoDeEL works with relative abundances.\nThe table will automatically be normalized so the abundance of each column equals 1.\n\n**Important**: CroCoDeEL requires the abundance of subdominant species to be accurately estimated.\\\nWe strongly recommend using [the Meteor software suite](https://github.com/metagenopolis/meteor) to generate the species abundance table.\\\nAlternatively, you can use [sylph](https://github.com/bluenote-1577/sylph) although low-level contaminations may go unnoticed.\\\nWe advise against the use of other taxonomic profilers (e.g. MetaPhlan4 or mOTUs) that do not meet this requirement according to our benchmarks.\n\n### Search contamination\nRun the following command to search for cross-sample contamination:\n```\ncrocodeel search_conta -s species_abundance.tsv -c contamination_events.tsv\n```\nCroCoDeEL will report all detected contamination events in the _contamination_events.tsv_ output file.\\\nThis TSV file reports for each event the contamination source, the contaminated sample (target) and the estimated contamination rate.\\\nThe score (probability) computed by the Random Forest model as well as species specifically introduced by contamination in the target are also given.\n\n### Visualization of the results\nContaminations events can be visually inspected by generating a PDF file consisting in scatterplots.\n```\ncrocodeel plot_conta -s species_abundance.tsv -c contamination_events.tsv -r contamination_events.pdf\n```\nEach scatterplot compares in a log-scale the species abundance profiles of a contaminated sample (x-axis) and its contamination source (y-axis).\\\nThe contamination line (in red) highlights species specifically introduced by contamination.\n\n### Easy workflow\nAlternatively, you can search for cross-sample contamination and create the PDF report in one command.\n```\ncrocodeel easy_wf -s species_abundance.tsv -c contamination_events.tsv -r contamination_events.pdf\n```\n\n### Results interpretation\nCroCoDeEL will probably report false contamination events for samples with similar species abundances profiles (e.g. longitudinal data, animals raised together).\\\nFor non-related samples, CroCoDeEL may occasionally generate false positives that can be filtered out by a human-expert.\\\nThus, we strongly recommend inspecting scatterplots of each contamination event to discard potential false positives.\\\n_We will explain how to do it soon._\n\n## Authors\n* Lindsay Goulet: lindsay.goulet@inrae.fr\n* Florian Plaza O\u00f1ate: florian.plaza-onate@inrae.fr\n* Edi Prifti: edi.prifti@ird.fr\n* Eugeni Belda: eugeni.belda@ird.fr\n* Emmanuelle Le Chatelier: emmanuelle.le-chatelier@inrae.fr\n* Guillaume Gautreau: guillaume.gautreau@inrae.fr\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "CroCoDeEL is a tool that detects cross-sample (aka well-to-well) contamination in shotgun metagenomic data",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/metagenopolis/CroCoDeEL",
"Repository": "https://github.com/metagenopolis/CroCoDeEL"
},
"split_keywords": [
"metagenomics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "907069b11804914fffa1213c8e69bb8d75cbc8525288b0719a48918a00ee934c",
"md5": "42beefac44d91684bed2ef0b2d135c54",
"sha256": "d20f2fb6d2611b8f4ddeda712ec65b0c769275c38852a7b7e0de84b4534132af"
},
"downloads": -1,
"filename": "crocodeel-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "42beefac44d91684bed2ef0b2d135c54",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 734872,
"upload_time": "2024-05-03T09:00:01",
"upload_time_iso_8601": "2024-05-03T09:00:01.684585Z",
"url": "https://files.pythonhosted.org/packages/90/70/69b11804914fffa1213c8e69bb8d75cbc8525288b0719a48918a00ee934c/crocodeel-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac97a4f1eca6e095f5213ef2e9da12d2afe83c892454074fba96165f6775b7ce",
"md5": "a7ce6272f189cda4a6725becb413ab72",
"sha256": "5c9488cb425474771350f2d0b7bcb1ad3d4b25e599ed5fcac9327af81f549aa2"
},
"downloads": -1,
"filename": "crocodeel-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a7ce6272f189cda4a6725becb413ab72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 737790,
"upload_time": "2024-05-03T09:00:08",
"upload_time_iso_8601": "2024-05-03T09:00:08.346228Z",
"url": "https://files.pythonhosted.org/packages/ac/97/a4f1eca6e095f5213ef2e9da12d2afe83c892454074fba96165f6775b7ce/crocodeel-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 09:00:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "metagenopolis",
"github_project": "CroCoDeEL",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "crocodeel"
}
JSON
