[](https://sc-dandelion.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/sc-dandelion/)
[](https://github.com/zktuong/dandelion/tree/master)
[]((https://github.com/zktuong/dandelion/actions/workflows/tests.yml))
[](https://codecov.io/gh/zktuong/dandelion)
[](https://docs.airr-community.org/en/stable/swtools/airr_swtools_standard.html)
[](https://colab.research.google.com/github/zktuong/dandelion/blob/master/container/dandelion_singularity.ipynb)
Hi there! I have put together a python package for analyzing single cell BCR/TCR data from 10x Genomics 5' solution! It streamlines the pre-processing, leveraging some tools from immcantation suite, and integrates with scanpy/anndata for single-cell BCR/TCR analysis. It also includes a couple of functions for visualization.
## Citation
`dandelion` is now published at [***Nature Biotechnology***](https://www.nature.com/articles/s41587-023-01734-7)!
Please cite the following if you use version 0.3.0 onwards:
Suo, C., Polanski, K., Dann, E. et al. ***Dandelion uses the single-cell adaptive immune receptor repertoire to explore lymphocyte developmental origins***. Nat Biotechnol (2023). https://doi.org/10.1038/s41587-023-01734-7
`dandelion` was originally published at [***Nature Medicine***](https://www.nature.com/articles/s41591-021-01329-2):
*Emily Stephenson, Gary Reynolds, Rachel A Botting, Fernando J Calero-Nieto, Michael Morgan, Zewen Kelvin Tuong, Karsten Bach, Waradon Sungnak, Kaylee B Worlock, Masahiro Yoshida, Natsuhiko Kumasaka, Katarzyna Kania, Justin Engelbert, Bayanne Olabi, Jarmila Stremenova Spegarova, Nicola K Wilson, Nicole Mende, Laura Jardine, Louis CS Gardner, Issac Goh, Dave Horsfall, Jim McGrath, Simone Webb, Michael W Mather, Rik GH Lindeboom, Emma Dann, Ni Huang, Krzysztof Polanski, Elena Prigmore, Florian Gothe, Jonathan Scott, Rebecca P Payne, Kenneth F Baker, Aidan T Hanrath, Ina CD Schim van der Loeff, Andrew S Barr, Amada Sanchez-Gonzalez, Laura Bergamaschi, Federica Mescia, Josephine L Barnes, Eliz Kilich, Angus de Wilton, Anita Saigal, Aarash Saleh, Sam M Janes, Claire M Smith, Nusayhah Gopee, Caroline Wilson, Paul Coupland, Jonathan M Coxhead, Vladimir Y Kiselev, Stijn van Dongen, Jaume Bacardit, Hamish W King, Anthony J Rostron, A John Simpson, Sophie Hambleton, Elisa Laurenti, Paul A Lyons, Kerstin B Meyer, Marko Z Nikolic, Christopher JA Duncan, Ken Smith, Sarah A Teichmann, Menna R Clatworthy, John C Marioni, Berthold Gottgens, Muzlifah Haniffa.* ***Single-cell multi-omics analysis of the immune response in COVID-19***. *Nature Medicine 2021.04.20; doi: https://dx.doi.org/10.1038/s41591-021-01329-2*
## Overview
Illustration of the `Dandelion` class slots
Please refer to the [documentation](https://sc-dandelion.readthedocs.io/).
The raw files for the examples can be downloaded from 10X's Single Cell Immune Profiling datasets [website](https://support.10xgenomics.com/single-cell-vdj/datasets).
## Installation
### Singularity container
`dandelion` now comes ready in the form of a singularity container:
```bash
singularity pull library://kt16/default/sc-dandelion:latest
singularity shell --writable-tmpfs -B $PWD sc-dandelion_latest.sif
```
This will load up a container that has all the required dependencies installed.
This can be used for the preprocessing steps by navigating to the data folder and use:
```bash
singularity run -B $PWD sc-dandelion_latest.sif dandelion-preprocess
```
If you have multiple samples to process, it is reccomended to specify the `--meta` option with a `.csv` file detailing the samples:
```bash
singularity run -B $PWD sc-dandelion_latest.sif dandelion-preprocess --meta meta.csv
```
### Python package
Start off by creating a conda environment containing scanpy, following [official scanpy instructions](https://scanpy.readthedocs.io/en/stable/installation.html). Once done, run the following:
```bash
conda install -c conda-forge graph-tool
pip install sc-dandelion
```
Between this and the pipelines within the singularity container, you should be covered for most of your needs.
### Manual Full Installation
I understand that the singularity container may not be for everyone, so here is a more detailed installation guide for those who want to install the package manually. The instructions may vary depending on your system, so please adjust accordingly. The easiest way is to still to just use the singularity container for the preprocessing steps.
```bash
# install igblast and blast
conda install -c bioconda igblast blast # if this doesn't work, download them manually
# https://ftp.ncbi.nih.gov/blast/executables/igblast/release/LATEST/
# https://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/
# Set the paths to them appropriately
echo 'export PATH=path/to/igblast/bin:$PATH' >> ~/.bash_profile
echo 'export PATH=path/to/blast+/bin:$PATH' >> ~/.bash_profile
```
You will need to download the database folder in this repository and place them somewhere accessible. There are [scripts](https://github.com/zktuong/dandelion/tree/master/container/scripts) in the `container` folder that will help you download the imgt/ogrdb databases and you can use them like this:
```bash
python prepare_imgt_database.py
python prepare_ogrdb_database.py
```
Also set the paths to the germline and igblast databases
```bash
echo 'export GERMLINE=path/to/database/germlines/' >> ~/.bash_profile
echo 'export IGDATA=path/to/database/igblast/' >> ~/.bash_profile
echo 'export BLASTDB=path/to/database/blast/' >> ~/.bash_profile
source ~/.bash_profile
```
For some of the pre-processing steps, you will need to install `rpy2` and some R packages. The easiest way to do this is to install them all via conda:
```bash
# in bash/zsh terminal
conda install -c conda-forge rpy2 r-optparse r-alakazam r-tigger r-airr r-shazam
```
Otherwise, you can also use `pip` to install `rpy2` and then install the R packages manually:
```bash
pip install rpy2
# If it fails because it's compiling using clang, first, work out where the path is to your gcc compiler (use brew to install gcc if needed):
# then run
# env CC=/path/to/location/of/bin/gcc-9 pip install rpy2
# Use pip to install the following with --no-cache-dir --upgrade if necessary
```
```R
# in R
install.packages(c("optparse", "alakazam", "tigger", "airr", "shazam"))
```
and then lastly install dandelion:
```bash
pip install sc-dandelion
# or
pip install git+https://github.com/zktuong/dandelion.git
# or installing from a specific branch
pip install git+https://github.com/zktuong/dandelion@branch_name
```
## Basic requirements
Python packages
```python
# conda
python>=3.7 (conda-forge)
numpy>=1.18.4 (conda-forge)
pandas>=1.0.3 (conda-forge)
distance>=0.1.3 (conda-forge)
jupyter (conda-forge) # if running via a notebook
scikit-learn>=0.23.0 (conda-forge)
numba>=0.48.0 (conda-forge)
pytables>=3.6.1 (conda-forge)
seaborn>=0.10.1 (conda-forge)
leidenalg>=0.8.0 (conda-forge)
plotnine>=0.6.0 (conda-forge)
graph-tool>=2.3.5 (conda-forge) # optional
# Other executables (through conda)
blast>=2.10.1 (bioconda)
igblast>=1.15.0 (bioconda)
# pip
anndata>=0.7.1
scanpy>=1.4.6
scrublet>=0.2.1
changeo>=1.0.0
presto>=0.6.0
polyleven>=0.5
networkx>=2.4
rpy2>=3.4.2
```
## Acknowledgements
I would like to acknowledge the contributions from Dr. Chenqu Suo, Dr. Krysztof Polanksi, Dr. Sarah Teichmann and Prof. Menna Clatworthy, who helped with the initial conception of the project and for all discussions.
I would also like to acknowledge Dr. Ondrej Suschanek, Dr. Benjamin Stewart, Dr. Rachel Bashford-Rogers, Dr. Jongeun Park, Dr. Cecilia-Dominguez Conde, Dr. Kirsten Stewart, Dr. Hamish King and Dr. Peng He with whom I have had very useful discussions. I would also like to thank my wife who helped name the package, because she thought the plots looked like a dandelion =D.
## Support
Support is provided on a voluntary basis, as time permits.
If there are any ideas, comments, suggestions, thing you would like to know more etc., please feel free to email me at z.tuong@uq.edu.au or post in the issue tracker and I will get back to you.
Raw data
{
"_id": null,
"home_page": null,
"name": "sc-dandelion",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "dandelion, single-cell, immune, TCR, BCR",
"author": null,
"author_email": "zktuong <z.tuong@uq.edu.au>",
"download_url": "https://files.pythonhosted.org/packages/fd/5c/789716b64065925b18b615f136eaf17d6c2d9c3f8137983b6b393281c9af/sc_dandelion-0.5.1.tar.gz",
"platform": null,
"description": "[](https://sc-dandelion.readthedocs.io/en/latest/?badge=latest)\n[](https://pypi.org/project/sc-dandelion/)\n[](https://github.com/zktuong/dandelion/tree/master)\n[]((https://github.com/zktuong/dandelion/actions/workflows/tests.yml))\n[](https://codecov.io/gh/zktuong/dandelion)\n[](https://docs.airr-community.org/en/stable/swtools/airr_swtools_standard.html)\n[](https://colab.research.google.com/github/zktuong/dandelion/blob/master/container/dandelion_singularity.ipynb)\n\n\n\nHi there! I have put together a python package for analyzing single cell BCR/TCR data from 10x Genomics 5' solution! It streamlines the pre-processing, leveraging some tools from immcantation suite, and integrates with scanpy/anndata for single-cell BCR/TCR analysis. It also includes a couple of functions for visualization.\n\n## Citation\n`dandelion` is now published at [***Nature Biotechnology***](https://www.nature.com/articles/s41587-023-01734-7)!\n\nPlease cite the following if you use version 0.3.0 onwards:\n\nSuo, C., Polanski, K., Dann, E. et al. ***Dandelion uses the single-cell adaptive immune receptor repertoire to explore lymphocyte developmental origins***. Nat Biotechnol (2023). https://doi.org/10.1038/s41587-023-01734-7\n\n\n`dandelion` was originally published at [***Nature Medicine***](https://www.nature.com/articles/s41591-021-01329-2):\n\n*Emily Stephenson, Gary Reynolds, Rachel A Botting, Fernando J Calero-Nieto, Michael Morgan, Zewen Kelvin Tuong, Karsten Bach, Waradon Sungnak, Kaylee B Worlock, Masahiro Yoshida, Natsuhiko Kumasaka, Katarzyna Kania, Justin Engelbert, Bayanne Olabi, Jarmila Stremenova Spegarova, Nicola K Wilson, Nicole Mende, Laura Jardine, Louis CS Gardner, Issac Goh, Dave Horsfall, Jim McGrath, Simone Webb, Michael W Mather, Rik GH Lindeboom, Emma Dann, Ni Huang, Krzysztof Polanski, Elena Prigmore, Florian Gothe, Jonathan Scott, Rebecca P Payne, Kenneth F Baker, Aidan T Hanrath, Ina CD Schim van der Loeff, Andrew S Barr, Amada Sanchez-Gonzalez, Laura Bergamaschi, Federica Mescia, Josephine L Barnes, Eliz Kilich, Angus de Wilton, Anita Saigal, Aarash Saleh, Sam M Janes, Claire M Smith, Nusayhah Gopee, Caroline Wilson, Paul Coupland, Jonathan M Coxhead, Vladimir Y Kiselev, Stijn van Dongen, Jaume Bacardit, Hamish W King, Anthony J Rostron, A John Simpson, Sophie Hambleton, Elisa Laurenti, Paul A Lyons, Kerstin B Meyer, Marko Z Nikolic, Christopher JA Duncan, Ken Smith, Sarah A Teichmann, Menna R Clatworthy, John C Marioni, Berthold Gottgens, Muzlifah Haniffa.* ***Single-cell multi-omics analysis of the immune response in COVID-19***. *Nature Medicine 2021.04.20; doi: https://dx.doi.org/10.1038/s41591-021-01329-2*\n\n## Overview\n\n\n\nIllustration of the `Dandelion` class slots\n\n\n\nPlease refer to the [documentation](https://sc-dandelion.readthedocs.io/).\n\nThe raw files for the examples can be downloaded from 10X's Single Cell Immune Profiling datasets [website](https://support.10xgenomics.com/single-cell-vdj/datasets).\n\n## Installation\n\n### Singularity container\n\n`dandelion` now comes ready in the form of a singularity container:\n```bash\nsingularity pull library://kt16/default/sc-dandelion:latest\nsingularity shell --writable-tmpfs -B $PWD sc-dandelion_latest.sif\n```\nThis will load up a container that has all the required dependencies installed.\n\nThis can be used for the preprocessing steps by navigating to the data folder and use:\n```bash\nsingularity run -B $PWD sc-dandelion_latest.sif dandelion-preprocess\n```\n\nIf you have multiple samples to process, it is reccomended to specify the `--meta` option with a `.csv` file detailing the samples:\n```bash\nsingularity run -B $PWD sc-dandelion_latest.sif dandelion-preprocess --meta meta.csv\n```\n\n### Python package\n\nStart off by creating a conda environment containing scanpy, following [official scanpy instructions](https://scanpy.readthedocs.io/en/stable/installation.html). Once done, run the following:\n\n```bash\nconda install -c conda-forge graph-tool\npip install sc-dandelion\n```\n\nBetween this and the pipelines within the singularity container, you should be covered for most of your needs.\n\n\n### Manual Full Installation\n\nI understand that the singularity container may not be for everyone, so here is a more detailed installation guide for those who want to install the package manually. The instructions may vary depending on your system, so please adjust accordingly. The easiest way is to still to just use the singularity container for the preprocessing steps.\n\n```bash\n# install igblast and blast\nconda install -c bioconda igblast blast # if this doesn't work, download them manually\n# https://ftp.ncbi.nih.gov/blast/executables/igblast/release/LATEST/\n# https://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/\n# Set the paths to them appropriately\necho 'export PATH=path/to/igblast/bin:$PATH' >> ~/.bash_profile\necho 'export PATH=path/to/blast+/bin:$PATH' >> ~/.bash_profile\n```\n\nYou will need to download the database folder in this repository and place them somewhere accessible. There are [scripts](https://github.com/zktuong/dandelion/tree/master/container/scripts) in the `container` folder that will help you download the imgt/ogrdb databases and you can use them like this:\n\n```bash\npython prepare_imgt_database.py\npython prepare_ogrdb_database.py\n```\n\nAlso set the paths to the germline and igblast databases\n```bash\necho 'export GERMLINE=path/to/database/germlines/' >> ~/.bash_profile\necho 'export IGDATA=path/to/database/igblast/' >> ~/.bash_profile\necho 'export BLASTDB=path/to/database/blast/' >> ~/.bash_profile\nsource ~/.bash_profile\n```\n\nFor some of the pre-processing steps, you will need to install `rpy2` and some R packages. The easiest way to do this is to install them all via conda:\n\n```bash\n# in bash/zsh terminal\nconda install -c conda-forge rpy2 r-optparse r-alakazam r-tigger r-airr r-shazam\n```\n\nOtherwise, you can also use `pip` to install `rpy2` and then install the R packages manually:\n```bash\npip install rpy2\n# If it fails because it's compiling using clang, first, work out where the path is to your gcc compiler (use brew to install gcc if needed):\n# then run\n# env CC=/path/to/location/of/bin/gcc-9 pip install rpy2\n# Use pip to install the following with --no-cache-dir --upgrade if necessary\n```\n```R\n# in R\ninstall.packages(c(\"optparse\", \"alakazam\", \"tigger\", \"airr\", \"shazam\"))\n```\nand then lastly install dandelion:\n```bash\npip install sc-dandelion\n# or\npip install git+https://github.com/zktuong/dandelion.git\n# or installing from a specific branch\npip install git+https://github.com/zktuong/dandelion@branch_name\n```\n\n## Basic requirements\nPython packages\n```python\n# conda\npython>=3.7 (conda-forge)\nnumpy>=1.18.4 (conda-forge)\npandas>=1.0.3 (conda-forge)\ndistance>=0.1.3 (conda-forge)\njupyter (conda-forge) # if running via a notebook\nscikit-learn>=0.23.0 (conda-forge)\nnumba>=0.48.0 (conda-forge)\npytables>=3.6.1 (conda-forge)\nseaborn>=0.10.1 (conda-forge)\nleidenalg>=0.8.0 (conda-forge)\nplotnine>=0.6.0 (conda-forge)\ngraph-tool>=2.3.5 (conda-forge) # optional\n\n# Other executables (through conda)\nblast>=2.10.1 (bioconda)\nigblast>=1.15.0 (bioconda)\n\n# pip\nanndata>=0.7.1\nscanpy>=1.4.6\nscrublet>=0.2.1\nchangeo>=1.0.0\npresto>=0.6.0\npolyleven>=0.5\nnetworkx>=2.4\nrpy2>=3.4.2\n```\n\n## Acknowledgements\nI would like to acknowledge the contributions from Dr. Chenqu Suo, Dr. Krysztof Polanksi, Dr. Sarah Teichmann and Prof. Menna Clatworthy, who helped with the initial conception of the project and for all discussions.\n\nI would also like to acknowledge Dr. Ondrej Suschanek, Dr. Benjamin Stewart, Dr. Rachel Bashford-Rogers, Dr. Jongeun Park, Dr. Cecilia-Dominguez Conde, Dr. Kirsten Stewart, Dr. Hamish King and Dr. Peng He with whom I have had very useful discussions. I would also like to thank my wife who helped name the package, because she thought the plots looked like a dandelion =D.\n\n## Support\n\nSupport is provided on a voluntary basis, as time permits.\n\nIf there are any ideas, comments, suggestions, thing you would like to know more etc., please feel free to email me at z.tuong@uq.edu.au or post in the issue tracker and I will get back to you.\n",
"bugtrack_url": null,
"license": "GNU Affero General Public License v3 or later (AGPLv3+)",
"summary": "sc-TCR/BCR-seq analysis tool",
"version": "0.5.1",
"project_urls": {
"documentation": "https://sc-dandelion.readthedocs.io/",
"homepage": "https://github.com/zktuong/dandelion/"
},
"split_keywords": [
"dandelion",
" single-cell",
" immune",
" tcr",
" bcr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b404b965fdea47251535d5a2545c8695f9a8193e74b2c2ccccd0e215d0b5b373",
"md5": "96b7e694da0642946d34bdc44d3de482",
"sha256": "14d02f4047d06b9553a616d0d5b9ab0305f11d5636bb3c96a5d7afaa0f72800e"
},
"downloads": -1,
"filename": "sc_dandelion-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96b7e694da0642946d34bdc44d3de482",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 200306,
"upload_time": "2025-01-16T22:40:59",
"upload_time_iso_8601": "2025-01-16T22:40:59.441096Z",
"url": "https://files.pythonhosted.org/packages/b4/04/b965fdea47251535d5a2545c8695f9a8193e74b2c2ccccd0e215d0b5b373/sc_dandelion-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd5c789716b64065925b18b615f136eaf17d6c2d9c3f8137983b6b393281c9af",
"md5": "61bf9c52f7a0c68a32e817835dbc8656",
"sha256": "c1965cb6344f9be53ccbdd141db536b87d45ec4e340f3e97c99014fd1b0fa973"
},
"downloads": -1,
"filename": "sc_dandelion-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "61bf9c52f7a0c68a32e817835dbc8656",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24927751,
"upload_time": "2025-01-16T22:41:04",
"upload_time_iso_8601": "2025-01-16T22:41:04.007035Z",
"url": "https://files.pythonhosted.org/packages/fd/5c/789716b64065925b18b615f136eaf17d6c2d9c3f8137983b6b393281c9af/sc_dandelion-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-16 22:41:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zktuong",
"github_project": "dandelion",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sc-dandelion"
}
JSON
