DOCSEARCHbyAlgolia
Submit Docs

CellphoneDB

repository·master·Indexed 19 days ago

https://github.com/ventolab/cellphonedb

A tool for interrogating single-cell or bulk transcriptomics data to identify cell-cell communication using a curated database of human receptor-ligand interactions. Version 5.0.1 supports statistical, DEG-based, and basic analysis methods, accounting for subunit architecture and biosynthetic pathways. It provides utilities for database management, custom database generation, and result querying via search_utils.

Tokens
24.9K
Snippets
59
Records
95
Agent score
58%

What's inside cellphonedb

  1. New features in CellphoneDB v5

    master

    CellphoneDB v5 introduces several major improvements for users:

    • Jupyter/Colab Support: A new Python package designed for easy execution in interactive environments.
    • Scoring Methodology: A new way to rank interactions based on the expression specificity of the interacting partners.
    • CellSign Module: A module that leverages interactions based on the activity of transcription factors downstream of a receptor. It includes 211 well-described receptor-transcription factor direct relationships.
    • Improved Querying: A new method for querying results via search_utils.search_analysis_results.
    • Computational Efficiency: Improved performance for the cpdb_statistical_analysis_method (Method 2).
    • Updated Database (v5.0): Contains ~3,000 manually curated interactions, including non-protein ligands and signaling pathway classifications. Partners are ordered as (ligand: partner A, receptor: partner B).

  2. Overview of CellphoneDB Analysis Methods

    master

    CellphoneDB provides three primary methods to assess cellular crosstalk using single-cell transcriptome data:

    1. METHOD 1: analysis (Simple retrieval)

      • Calculates the mean expression for all interactions for each cell type pair combination.
      • Does not perform statistical significance testing.
      • Outputs: means.csv and deconvoluted.csv.

    2. METHOD 2: statistical_analysis (Statistical inference)

      • Evaluates the significance of interactions between all potential cell type pairs.
      • Uses empirical shuffling (randomly permuting cluster labels) to calculate P-values for cell-type specificity.
      • Outputs: means.csv, deconvoluted.csv, pvalues.csv, and significant_means.csv.

    3. METHOD 3: degs_analysis (Differential expression analysis)

      • An alternative to statistical inference designed for complex comparisons (e.g., disease vs. control, or specific lineage comparisons).
      • Requires an input file of differentially expressed genes (DEGs) or marker genes.
      • Selects interactions where at least one gene-cell type pair is present in the provided DEG file.

  3. Choose the right CellphoneDB analysis method

    master

    The optimal method depends on your biological question and experimental design:

    • Method 1 (Simple Analysis): Returns the mean expression of interacting partners for each interaction in each cell type pair. Use this for exploratory analysis to find all interactions where ligands/receptors are expressed above a threshold. It does not provide statistical significance.
    • Method 2 (Statistical Analysis): Extends Method 1 by assessing the probability that the mean interaction expression occurs by chance. It performs a 'One-versus-Rest' comparison to identify interactions significantly more expressed in a specific cell type pair compared to all other pairs in the dataset.
    • Method 3 (Differential Expression Analysis): A targeted approach for identifying interactions specific to individual cell states, conditions (e.g., disease vs. control), differentiation processes, or spatial axes. This method requires the user to provide a pre-computed list of Differentially Expressed Genes (DEGs).

  4. Understand the CellphoneDB database input file structure

    master

    The CellphoneDB database is constructed from several .csv files that define the relationships between genes, proteins, complexes, and interactions. Understanding these schemas is essential for creating user-defined databases or contributing to the official curation.

    Core input files include:

    • gene_input.csv: Maps scRNAseq gene data to protein-level identifiers.
    • protein_input.csv: Contains protein properties (location, receptor status, etc.).
    • complex_input.csv: Defines heteromeric ligands and receptors (complexes of multiple proteins).
    • interaction_input.csv: Defines the actual interaction pairs.
    • transcription_factor_input.csv: Maps receptor activity to transcription factor effects.

  5. Accelerate Method 2 using cell subsampling

    master

    For very large scRNA-seq datasets, Method 2 can be computationally expensive. You can use 'geometric sketching' (subsampling) to maintain transcriptomic heterogeneity while reducing the number of cells.

    Alternatively, you can manually downsample your dataset to even out the number of cells per cell type. This ensures the null distribution is not biased toward cell types with larger cell counts.

  6. Understand CellphoneDB output file structures

    master

    CellphoneDB generates several output files. Most files (except deconvoluted.txt) use a matrix structure where rows represent interacting proteins (ligand-receptor pairs) and columns represent interacting cell type pairs.

    Core Output Files

    • means.txt: Contains mean expression values for each ligand-receptor interaction per cell-cell interaction pair.
    • pvalues.txt: Contains P-values for the likelihood of cell-type specificity for each interaction pair (generated via statistical_analysis).
    • significant_means.txt: A subset of means.txt containing only interactions that are statistically significant (where p.value < 0.05).
    • relevant_interactions.txt: A binary matrix (1 or 0) indicating if an interaction is relevant. An interaction is relevant if a gene is a DEG (from the user-provided DEG.tsv file) and all participant genes are expressed. This is specific to degs_analysis.
    • deconvoluted.txt: Provides subunit-level information for interacting partners, which is critical for identifying functional heteromeric complexes.
    • percentages.txt: Provides the percentage of cells expressing a given gene.

  7. Rank interactions using the Scoring module

    master

    The Scoring module ranks interactions based on the specificity of the interacting partners.

    Protocol:

    1. Exclude genes not in any interaction or expressed in < k% of cells.
    2. Calculate mean expression per cell type.
    3. Aggregate heteromeric protein subunits using the geometric mean.
    4. Scale mean expression across cell types (0 to 10).
    5. Calculate the product of scaled mean expressions as the interaction relevance score.

    Requirements & Warnings:

    • Data Format: You MUST use log-normalized expression data. Do not use normalization procedures like z-scaling that transform zeros into non-zero values.
    • Microenvironments: If microenvironments are defined, the final scoring step (step 5) is only calculated for cells within the same microenvironment.
    • Discrepancies: An interaction might be statistically significant but have a low score if one partner is expressed in very few cells or has very low overall expression.
    score_interactions = True

  9. Understand interaction asymmetry in results

    master

    Cell-cell interactions are not symmetric. In the output, the direction of the interaction matters:

    • clusterA_clusterB: Cluster A expresses partner A and Cluster B expresses partner B.
    • clusterB_clusterA: Cluster B expresses partner A and Cluster A expresses partner B.

    Because the expression of the ligand and receptor is tied to specific clusters, the values for clusterA_clusterB and clusterB_clusterA will typically be different.

  10. Use the CellSign module for transcription factor activity

    master

    The CellSign module (v5) prioritizes high-confidence interactions by leveraging the activity status of transcription factors (TFs) downstream of receptors. It uses a database of 211 highly-specific direct receptor-to-TF relationships.

    To use this module in Methods 2 or 3, you must provide a file containing the TFs active in each cell type via the active_tfs_file_path argument.

    How to estimate active TFs:

    • Use TF expression.
    • Use target gene expression (e.g., via DoRothEA).
    • Use chromatin accessibility of binding motifs (e.g., via ChromVar or SCENIC).
    active_tfs_file_path = active_tf.txt

  11. Incorporate spatial microenvironments into analysis

    master

    You can prioritize interactions occurring between neighboring cell types by providing a microenvs file. CellphoneDB will restrict the tested cell type pairs to only those that coexist within the same spatial microenvironment.

    Microenvironment file format: A .txt file with two columns:

    1. Cell type name
    2. Spatial microenvironment name

    Note: Cell type names must exactly match those in your meta.txt file.

    To use this in any analysis method, pass the file path to the microenvs argument.

    microenvs = test_microenvs.txt

  12. Incorporate spatial information using microenvironments

    master

    CellphoneDB (v3+) supports spatial analysis by incorporating a microenvironments file. This file allows the tool to define possible interacting cell pairs based on clusters that coexist in the same spatial microenvironment.

    File Format: A two-column text file where:

    • Column 1: Cell type/cluster
    • Column 2: Spatial microenvironment

    You can define these microenvironments using prior knowledge, imaging data, or tools like cell2location.