CellphoneDB Viz is a software for visualising the results of either differential or statistical analyses by CellphoneDB package (version >= 4.0.0 only). For visualisation examples see cellphonedb.org.
The software accepts the relevant input to and output files from a CellphoneDB analysis as well as a simple configuration yaml file telling CellphoneDB Viz which relevant files should be included in the visualisation, e.g.:
- data/endometrium_cpdbv5_deg/config.yml
- data/endometrium_cpdbv5_stat/config.yml
- data/gonads_cpdbv5_deg/config.yml
From the configuration file the software 'does the right thing' and produces visualisations of the data that was provided. Please see below for more information on the configuration file format.
The software consists of a web server, an API that serves the data to the front end for all the projects it knows of, and the html including the JavaScript that fetches the data from the API and visualises it in various plots. The plots have been implemented mostly in D3.
The instructions below use Linux commands as an example:
# Clone cellphonedbviz repository from github
git clone git@github.com:datasome/cellphonedbviz.git# Create a directory with a name that is meaningful to your project, e.g. my_cellphonedb_analysis
mkdir cellphonedbviz/data/my_cellphonedb_analysis
# For the sake of this example let's assume that:
# 1. Your output files are in directory e.g. ~/.cpdb/user_files/out/,
# 2. Your input files are in ~/.cpdb/user_files/in/my_cellphonedb_analysis/, and
# 3. All the output files's names from the analysis you wish to visualise end with the suffix e.g. _08_14_2023_104434.txt :
# Copy all the output files to the target directory
cp ~/.cpdb/user_files/out/*_08_14_2023_104434.txt cellphonedbviz/data/my_cellphonedb_analysis
# Copy any relevant input files to the target directory, e.g.
cp ~/.cpdb/user_files/in/my_cellphonedb_analysis/cellphonedb.zip cellphonedbviz/data/my_cellphonedb_analysis
cp ~/.cpdb/user_files/in/my_cellphonedb_analysis/microenvironments.tsv cellphonedbviz/data/my_cellphonedb_analysis
# Create cellphonedbviz/data/my_cellphonedb_analysis/config.yml file and populate it with the relevant file names and other options (see below)The following field names (in no particular order) are permitted within the configuration file. Please see above for example configuration files, and also note red squares below for compulsory fields. Click on each field name for an example file content:
analysis_means
- cellphonedb - this is the CellphoneDB database file you did your analysis against
- cellsign_active_interactions_deconvoluted - this file is available from CellphoneDB v5.0.0 or later
- celltype_composition
- deconvoluted_percents
- hash - a value for this field can be generated via the software itself, via the following API call http://localhost:8001/api/generate/hash. When this field is present in the config file, the project's visualisation can only be accessed if the auth argument is provided in the URL containing that hash, e.g. http://localhost:8001/viz.html?projectid=endometrium_cpdbv5_deg&auth=u09AAPT-Evv4royBk1myzg
- interaction_scores - this file is available from CellphoneDB v5.0.0 or later and only when score_interactions argument in the analysis call was set to True
- separator - the value provided for the separator argument in CellphoneDB analysis method call, e.g. '|'
# Create Docker image
docker-compose build --no-cache
# Deploy the image in a Docker container
docker-compose up -d
# Shut down the Docker container when you no longer need the service
docker-compose down- http://localhost:8001/ shows all the projects you included in CellphoneDB Viz, including the example ones that came with the software
- Please remember that if you specified a hash in config file, you cannot just click on that project's link on http://localhost:8001/ - you need to access it via a url that specifies the hash as a value of auth parameter, e.g. http://localhost:8001/viz.html?projectid=endometrium_cpdbv5_deg&auth=u09AAPT-Evv4royBk1myzg
- To the author's current knowledge, there is no theoretical maximum on the number of projects that can be included in a single CellphoneDB Viz web service so long as the service's memory footprint stays within that available on the server it is running on.
- Currently, up to maximum nine microenvironments can be visualised together within 'Cell-cell Communication - Summary' section. However, the user is able to select subsets of microenvironments to visualise - in order to get round this restriction.
Please report any issues you have with running the software via https://github.com/datasome/cellphonedbviz/issues.