CellphoneDB

What is CellphoneDB?

CellphoneDB is a publicly available repository of HUMAN curated receptors, ligands and their interactions paired with a tool to interrogate your own single-cell transcriptomics data (or even bulk transcriptomics data if your samples represent pure populations!).

A distinctive feature of CellphoneDB is that the subunit architecture of either ligands and receptors is taken into account, representing heteromeric complexes accurately. This is crucial, as cell communication relies on multi-subunit protein complexes that go beyond the binary representation used in most databases and studies. CellphoneDB also incorporates biosynthetic pathways in which we use the last representative enzyme as a proxy of ligand abundance, by doing so, we include interactions involving non-peptidic molecules. CellphoneDB includes only manually curated & reviewed molecular interactions with evidenced role in cellular communication.

Documentation

For more details on using CellphoneDB and a more detailed description of the methods, visit the DOCUMENTATION.

Novel features in v5

1. New python package that can be easily executed in Jupyter Notebook and Collabs.
2. A scoring methodology to rank interaction based on the expression specificity of the interacting partners.
3. A CellSign module to leverage interactions based on the activity of the transcription factor downstream the receptor. This module is accompanied by a collection of 211 well described receptor-transcription factor direct relationships.
4. A new method of querying of CellphoneDB results search_utils.search_analysis_results.
5. Tutorials to run CellphoneDB (available here)
6. Improved computational efficiency of method 2 cpdb_statistical_analysis_method.
7. A new database (cellphonedb-data v5.0) with more manually curated interactions, making up to a total of ~3,000 interactions. This release of CellphoneDB database has three main changes:
   • Integrates new manually reviewed interactions with evidenced roles in cell-cell communication.
   • Includes non-protein molecules acting as ligands.
   • For interactions with a demonstrated signalling directionality, partners have been ordered according (ligand is partner A, receptor partner B).
   • Interactions have been classified within signaling pathways.
   • CellphoneDB no longer imports interactions from external resources. This is to avoid the inclusion of low-confidence interactions.

See updates from previous releases here.

Installing CellphoneDB

We highly recommend using an isolated python environment (as described in steps 1 and 2) using conda or virtualenv but you could of course omit these steps and install via pip immediately.

1. Create python=>3.8 environment

   • Using conda: conda create -n cpdb python=3.8
   • Using virtualenv: python -m venv cpdb

2. Activate environment

   • Using conda: source activate cpdb
   • Using virtualenv: source cpdb/bin/activate

3. Install CellphoneDB pip install cellphonedb

4. Set up the kernel for the Jupyter notebooks.

   • Install the ipython kernel: pip install -U ipykernel.
   • Add the environment as a jupyter kernel: python -m ipykernel install --user --name 'cpdb'.
   • Open/Start Jupyter and select the created kernel.

5. Download the database.

   • Follow this tutorial.

NOTE: Works with Python v3.8 or greater. If your default Python interpreter is for v2.x (you can check it with python --version), calls to python/pip should be substituted by python3/pip3.

Running CellphoneDB Methods

Please, activate your environment if you didn't previously

• Using conda: source activate cpdb
• Using virtualenv: source cpdb/bin/activate

We have created a set of tutorials that can be accessed for each To use the example data, please tutorials and data.

Preparing INPUTS

Preparing your counts input file (mandatory)

Counts file can be a text file or a h5ad (recommended), h5 or a path to a folder containing a 10x output with mtx/barcode/features files. NOTE: Your gene/protein ids must be HUMAN. If you are working with another specie such as mouse, we recommend you to convert the gene ids to their corresponding orthologous.

Preparing your DEGs file (optional, if method degs_analysis)

This is a two columns file indicating which gene is specific or up-regulated in a cell type (see example ). The first column should be the cell type/cluster name (matching those in meta.txt) and the second column the associated gene id. The remaining columns are ignored. We provide notebooks for both Seurat and Scanpy users. It is on you to design a DEG analysis that is appropriate to your research question.

Preparing your microenvironments file (optional, if microenvs_file_path)

This is a two columns file indicating which cell type is in which spatial microenvironment (see example ). CellphoneDB will use this information to define possible pairs of interacting cells (i.e. pairs of clusters co-appearing in a microenvironment).

Preparing your active transcription factor file (optional, if active_tfs_file_path)

This is a two columns file indicating which cell type and which TFs are active (see example). CellphoneDB will use this information to highlight relevant/significant interactions whose downstream TF is active. The information defined in this file (which TFs are active per cell) must be provided by the user.

RUN examples

For more detailed examples refer to our tutorials here.

Example with running the DEG-based method

from cellphonedb.src.core.methods import cpdb_degs_analysis_method

cpdb_results = cpdb_degs_analysis_method.call(
        cpdb_file_path = cellphonedb.zip,
        meta_file_path = test_meta.txt,
        counts_file_path = test_counts.h5ad,
        degs_file_path = degs_file_path,
        counts_data = 'hgnc_symbol',
        active_tfs_file_path = active_tf.txt,
        score_interactions = True,
        microenvs_file_path = microenvs_file_path,
        threshold = 0.1,
        output_path = out_path)

Example with running the statistical method

from cellphonedb.src.core.methods import cpdb_statistical_analysis_method

cpdb_results = cpdb_statistical_analysis_method.call(
        cpdb_file_path = cellphonedb.zip,
        meta_file_path = test_meta.txt,
        counts_file_path = test_counts.h5ad,
        counts_data = 'hgnc_symbol',
        active_tfs_file_path = active_tf.txt,
        microenvs_file_path = microenvs_file_path
        score_interactions = True,
        threshold = 0.1,
        output_path = out_path)

Example without using the statistical method

• Using text files

from cellphonedb.src.core.methods import cpdb_analysis_method

cpdb_results = cpdb_analysis_method.call(
        cpdb_file_path = cellphonedb.zip,
        meta_file_path = test_meta.txt,
        counts_file_path = test_counts.txt,
        counts_data = 'hgnc_symbol',
        score_interactions = True,
        output_path = out_path)

• Using h5ad count file

from cellphonedb.src.core.methods import cpdb_analysis_method

cpdb_results = cpdb_analysis_method.call(
        cpdb_file_path = cellphonedb.zip,
        meta_file_path = test_meta.txt,
        counts_file_path = test_counts.h5ad,
        counts_data = 'hgnc_symbol',
        output_path = out_path)

Results are saved as files in output_path and as a dictionary of dataframes in the output variable cpdb_results.

To understand the different analysis and results, please check the results documentation.

Optional Parameters

Optional Method parameters:

• counts_data: Type of gene identifiers in the counts data [ensembl | gene_name | hgnc_symbol]
• iterations: Number of iterations for the statistical analysis [1000]
• threshold: % of cells expressing the specific ligand/receptor
• result_precision: Number of decimal digits in results [3]
• output_path: Directory where the results will be saved (the directory must exist) [out]
• output_suffix: Output format of the results files (time stamp will be added to filename if not present) [txt]
• subsampling: Enable subsampling based on geometric sketching
• subsampling_log: Enable subsampling log1p for non log-transformed data inputs !!mandatory!!
• subsampling_num_pc: Subsampling NumPC argument (number of PCs to use) [100]
• subsampling_num_cells: Number of cells to subsample the dataset [1/3 of cells by default]

~ Optional Method Statistical parameters

• microenvs_file_path: Spatial microenvironments input file. Restricts the cluster/cell_type interacting pairs to the cluster/cell_type sharing a microenviroment (i.e. only test a combination of clusters if these coexist in a microenviroment). This file should contain two columns: 1st column indicates the cluster/cell_type, 2nd column indicates the microenviroment name. See example here.
• `pva