Database Utility Functions

Display CellphoneDB Database Versions

cellphonedb.utils.db_releases_utils.get_remote_database_versions_html(include_file_browsing: bool = False, min_version: float = 4.1)

Retrieve a html table containing CellphoneDB database versions and release dates.

Parameters:

• include_file_browsing (bool.) – False by default; True when invoked by cellphonedb.org website only - to allow the user to select and browse individual input files from https://github.com/ventolab/cellphonedb-data.

• min_version (float) – If not None, the only versions returned should be >= min_version

Returns:

A string containing html table containing database versions and release dates

Return type:

str

Generate Your Own Input Files

cellphonedb.utils.generate_input_files.generate_all(target_dir, cpdb_version, user_complex=None, user_interactions=None, user_interactions_only=False) → None

Generate your own CellphoneDB input files, using your own complexes and interactions (if provided). This allows the user to run CellphoneDB analyses against either just their own interactions/complexes, or against a combined data comprising their own interactions/complexes and the curated ones from https://github.com/ventolab/cellphonedb-data.

Parameters:

• target_dir (str) – The directory in which the generated *_input files should be placed

• db_version (str) – CellphoneDB version (and the name of the subdirectory containing the curated input files from https://github.com/ventolab/cellphonedb-data)

• user_complex (str) – A path to the user’s csv file containing information about complexes, in the format exemplified in https://github.com/ventolab/CellphoneDB/blob/bare-essentials/example_data/test_complex.csv

• user_interactions (str) – A path to the user’s csv file containing information about interactions, in the format exemplified in https://github.com/ventolab/CellphoneDB/blob/bare-essentials/example_data/test_interaction.csv

• user_interactions_only (bool) – If true, only the user’s interactions should be included in the generated input files. If false (the default) the user’s interactions will be appended to the curated interactions in the db_version above in https://github.com/ventolab/cellphonedb-data.

Create Local CellphoneDB Database File and Load it into Memory

cellphonedb.utils.db_utils.get_interactions_genes_complex(cpdb_file_path) → Tuple[DataFrame, DataFrame, DataFrame, DataFrame, dict, dict]

Returns a tuple of four DataFrames containing data from <cpdb_dir>/cellphonedb.zip.

Parameters:

cpdb_file_path (str) – CellphoneDB database file path

Returns:

• interactions: pd.DataFrame

• genes: pd.DataFrame

• complex_composition: pd.DataFrame

• complex_expanded: pd.DataFrame

• gene_synonym2gene_name: dict

• receptor2tfs: dict

Return type:

Tuple

cellphonedb.utils.db_utils.get_db_path(user_dir_root, db_version)

Retrieves the path to the local database file corresponding to db_version

Parameters:

• user_dir_root (str) – The directory in which user stores CellphoneDB files

• db_version (str) – CellphoneDB version (and the name of the subdirectory containing the curated input files from https://github.com/ventolab/cellphonedb-data)

Returns:

The path to the local database file corresponding to db_version

Return type:

str

cellphonedb.utils.db_utils.create_db(target_dir) → None

Creates CellphoneDB databases file (cellphonedb.zip) in <target_dir> directory. The assumption is that <target_dir> contains the four *_input.csv files required to create the database file. This simple zip file contains a number of CSV files that CellphoneDB package reads into memory and uses to drive its analysis of user data.

Parameters:

• target_dir (str) – The directory in which to place the database file (and which contains the four *_input.csv files required to

• create the database file

Search CellphoneDB interactions for genes/complexes

cellphonedb.utils.search_utils.search(query_str: str = '', cpdb_file_path: str | None = None) -> (<class 'list'>, <class 'map'>, <class 'map'>, <class 'map'>, <class 'map'>)

Searches CellphoneDB interactions for genes/proteins/complexes in query_str

Parameters:

• query_str (str) – A comma- or space-separated list of Ensembl ID (e.g. ENSG00000165029), Gene name (e.g. ABCA1), UniProt ID (e.g. KLRG2_HUMAN), UniProt Accession (e.g. A4D1S0) or Complex name (e.g. 12oxoLeukotrieneB4_byPTGR1)

• cpdb_file_path (str) – CellphoneDB database file path

Returns:

• A list of sub-lists, where each sub-list represents details of a single interaction

• For all complexes that participate in the interactions found, a mapping to their constituent proteins

Return type:

Tuple

cellphonedb.utils.search_utils.get_html_table(data, complex_name2proteins, protein2Info, complex2Info, resource2Complex2Acc, proteinAcc2Name) → str

Parameters:

• data (list) – A list of sub-lists, where each sub-list represents details of a single interaction

• complex_name2proteins (map) – For all complexes that participate in the interactions found, a mapping to their constituent proteins

• protein2Info (map) – A mapping between a protein and the list of its details (e.g. ‘transmembrane’) to be displayed in the sidebar when the user clicks in a protein accession in the search results table

• protein2Info (map) – A mapping between a protein and the list of its details (e.g. ‘transmembrane’) to be displayed in the sidebar when the user clicks in a protein accession in the search results table

• resource2Complex2Acc (map) – A mapping between a external resource name (a key in EXTERNAL_RESOURCE2URI) and a map between a complex name and its corresponding accession in that external resource

Returns:

A string containing html representation of interactions in data and complex_name2proteins. The mapping in the latter is used to populate tooltips showing proteins that are a part of a complex.

Return type:

str