multideconv/README.Rmd at main · VeraPancaldiLab/multideconv · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
---
output: github_document
---

# multideconv <img src="man/figures/logo.png" align="right" height="139" alt="multideconv logo" />

[![R-CMD-check](https://github.com/VeraPancaldiLab/multideconv/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/VeraPancaldiLab/multideconv/actions/workflows/R-CMD-check.yaml)
[![pkgdown](https://github.com/VeraPancaldiLab/multideconv/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/VeraPancaldiLab/multideconv/actions/workflows/pkgdown.yaml)

An integrative pipeline for combining first and second generation cell type deconvolution results

<!-- badges: start -->

<!-- badges: end -->

<p align="center">
<img src="man/figures/overview.png?raw=true"/>
</p>

<p align="center">
  <em>Figure 1. A schematic overview of the `multideconv` pipeline</em>
</p>

## Installation

To avoid GitHub API rate limit issues during installation, we recommend setting up GitHub authentication by creating and storing a Personal Access Token (PAT). You can do this with the following steps:

``` r
# install.packages(c("usethis", "gitcreds"))
usethis::create_github_token() #Create a Personal Access Token (if you don't have)
gitcreds::gitcreds_set() #Add the token
```

You can install the development version of `multideconv` from [GitHub](https://github.com/) with:

``` r
# install.packages("pak")
pak::pkg_install("VeraPancaldiLab/multideconv")
```

## General usage

These are basic examples which shows you how to use `multideconv` for different tasks. For a detailed tutorial, see [Get started](https://VeraPancaldiLab.github.io/multideconv/articles/multideconv.html)

Before running `multideconv`, make sure to set your working directory. The `Results/` folder, where outputs will be saved, will be created in this directory.
``` r
setwd('~/path/to/directory')
library(multideconv)
```

The function calculates cell abundance based on cell type signatures using different methods and signatures through the function `compute.deconvolution` which takes as input the bulk RNAseq gene expression matrix either as raw or normalized counts.

``` r
deconv = compute.deconvolution(raw.counts, normalized = T, credentials.mail = "xxxx", credentials.token = "xxxxxx", file_name = "Tutorial")
deconv = compute.deconvolution(raw.counts, normalized = T, credentials.mail = "xxxx", credentials.token = "xxxxxx", methods = c("Quantiseq", "MCP", "XCell", "DWLS"), file_name = "Test")
deconv = compute.deconvolution(raw.counts, normalized = T, credentials.mail = "xxxx", credentials.token = "xxxxxx", signatures_exclude = "BPRNACan", file_name = "Tutorial")
deconv = compute.deconvolution(raw.counts, normalized = T, credentials.mail = "xxxx", credentials.token = "xxxxxx", sc_deconv = T, sc_matrix = sc.object, cell_label = cell_labels, sample_label = bath_ids, name_sc_signature = "Signature_test", file_name = "Test")
```

**NOTE**: `CIBERSORTx` is included in the deconvolution methods, but it's not an open-source program. To run it, please ask for a token in [CIBERSORTx](https://cibersortx.stanford.edu/register.php) and once obtained, provided your username and password on the parameters `credentials.mail` and `credentials.token`.

Also CIBERSORTx ask to have [docker](https://kinsta.com/blog/install-docker-ubuntu/#installing-docker-desktop-on-ubuntu) install in your computer. Once installed, be sure to concede permission to manage docker as a non-root user. For verify this, go to the terminal and run:

```
docker ps
```

If you don't have any error, congrats you are go to go!

If you receive an error of permission, just run:

```
sudo groupadd docker
sudo usermod -aG docker ${USER}
```

Then restart your computer and try again

```
docker ps
```

Now, you should be able to run deconvolution using CIBERSORTx without any problems :)

For processing the deconvolution features obtained from `compute.deconvolution`, you can use the `compute.deconvolution.analysis` function.

``` r
processed_deconvolution = compute.deconvolution.analysis(deconvolution, corr = 0.7, seed = 123, return = T)
```

Users can also compute second-generation deconvolution methods using their single cell data. For this use the function `compute_sc_deconvolution_methods`. Remember that this function is already included in `compute.deconvolution` when setting `sc_deconv = T`.

``` r
deconv_sc = compute_sc_deconvolution_methods(raw_counts, sc_object, sc_metadata, cell_annotations, samples_ids, name_object, normalized = T, n_cores = 4, cbsx_name = "XXX", cbsx_token = "XXX")
```

## Shiny app

`multideconv` includes an interactive Shiny app for non-coding users with four tabs: **Welcome**, **Deconvolution**, **Analysis**, and **Benchmark**.

From the repository root, run:

``` bash
Rscript -e "shiny::runApp('inst/shiny', host='127.0.0.1', port=3838, launch.browser=TRUE)"
```

Or from an R session:

``` r
setwd("~/path/to/multideconv")
shiny::runApp("inst/shiny", host = "127.0.0.1", port = 3838, launch.browser = TRUE)
```

If port `3838` is already in use, choose another one (for example `3840`) and open:

`http://127.0.0.1:3840`

You can stop old Shiny processes with:

``` bash
pkill -f "shiny::runApp\\('inst/shiny'"
```

## Cell types nomenclature

`multideconv` works based on established cell naming conventions (Figure 2) to simplify analysis and processing. Thus, if you would like to use your own deconvolution results or signatures, please make sure to follow these formats.

<p align="center">
<img src="man/figures/cell_types.png?raw=true"/>
</p>

<p align="center">
  <em>Figure 2. Cell types nomenclature for `multideconv`</em>
</p>

## How to add cell types other than the ones present in the nomenclature?

If you want `multideconv` to consider other cells, it is pretty simple! Just use the argument cells_extra in the function `compute.deconvolution.analysis()`.

Let's say you want to add mesenchymal and basophils cells:

``` r
processed_deconvolution = compute.deconvolution.analysis(deconvolution, corr = 0.7, seed = 123, cells_extra = c("mesenchymal", "basophils"))
```

And that's it, just make sure the name you are putting in cells_extra is exactly the name of your cells in your deconvolution matrix!

## How to add other signatures?

You can include other signatures into the analysis by adding them as .txt into the folder `Results/custom_signatures`.
Please make sure that your signature name is not splitted by "_" or any other character, use single-word names.

## How does my single cell data is used for deconvolution?

`multideconv` includes second generation methods that allows users to input single cell data and use it for constructing signatures 'on-the-fly' and deconvolve the bulk RNAseq data.

Because most of the times scRNAseq data can be big and sparse matrices, we applied 'preprocessing' steps to avoid crashing the computer. For this, `multideconv` construct metacells per cell type and patient from the single cell data using the KNN algorithm. This is done essentially by executing different tasks per cluster in parallel for N workers and once finished, it computes deconvolution using the reduced single cell object.

**NOTE**:  If you encounter missing packages for certain deconvolution methods (e.g., `MuSiC`, `SCDC`) during the pipeline, make sure to install the versions maintained by the `omnideconv` team. These versions are patched to work seamlessly with `omnideconv` functions:
``` r
devtools::install_github("omnideconv/MuSiC")
devtools::install_github("omnideconv/SCDC")
```

## Issues
If you encounter any problems or have questions about the package, we encourage you to open an issue [here](https://github.com/VeraPancaldiLab/multideconv/issues). We’ll do our best to assist you!

## Authors

`multideconv` was developed by [Marcelo Hurtado](https://github.com/mhurtado13) in supervision of [Vera Pancaldi](https://github.com/VeraPancaldi) and is part of the [Pancaldi](https://github.com/VeraPancaldiLab) team. Currently, Marcelo is the primary maintainer of this package.

## Citing `multideconv`

If you use `multideconv` in a scientific publication, we would appreciate citation to the :

*Hurtado, M., Essabbar, A., Khajavi, L., & Pancaldi, V. (2025). multideconv – Integrative pipeline for cell type deconvolution from bulk RNAseq using first and second generation methods. bioRxiv. https://doi.org/10.1101/2025.04.29.651220*