# Methods

This page summarizes the CLIMB and CLIFF algorithms as implemented in this package, simplified from the Methods section of Coudray et al., *Computational deconvolution of drug sensitivity via single-cell–to–bulk transcriptome mapping* (manuscript in revision). See the paper's Methods and Supplemental Methods for full derivations.

## CLIMB: cell-level linear model for bulk-to-single-cell deconvolution

Unlike deconvolution methods that fit one coefficient per cell type against a signature matrix of average expression, CLIMB fits one coefficient $\alpha_i$ per **individual single cell** $i$ in the reference. For a bulk sample $n$ with expression vector $\mathbf{x}_n$, and a reference matrix $\mathbf{C}$ of raw single-cell counts ($G$ genes $\times$ $C$ cells):

$$
\mathbf{x}_n \sim \mathbf{C} \cdot \boldsymbol{\alpha}_n
$$

```{image} _static/climb_sketch.png
:alt: CLIMB single-cell coefficient fitting and aggregation into cell-type proportions
:width: 100%
```

Coefficients are fit with `glmnet`, under a non-negativity constraint and no regularization:

$$
L(\boldsymbol{\alpha}_n \mid \mathbf{C}, \mathbf{x}_n) = \min_{\boldsymbol{\alpha}} \frac{1}{2G} \left\lVert \mathbf{x}_n - \mathbf{C} \cdot \boldsymbol{\alpha}_n \right\rVert^2, \quad \alpha_{ni} \in [0, +\infty)
$$

Cell-level coefficients are then grouped and normalized by cell-type annotation to obtain proportions $w_{nk}$ for cell type $k$:

$$
w_{nk} = \frac{\sum_{i=1}^{C} \tau_{ki} \cdot \alpha_{ni}}{\sum_{i=1}^{C} \alpha_{ni}}
$$

where $\tau_{ki}$ is 1 if cell $i$ is of type $k$. This first pass is returned as `props.init`.

### Empirical Bayes sub-sampling

A single fit against the full reference is biased toward the reference's own cell-type composition. CLIMB corrects for this with an iterative sub-sampling step: cells are resampled from the reference according to the current proportion estimate (with a floor of `min.n.cells` cells per type), CLIMB is refit against the resampled reference, and the process is repeated across `n.iter.subsampling` resamples, averaged, over two rounds. The result — less biased toward the raw reference composition — is returned as `props.corrected`, and is CLIMB's main output for downstream use.

### Cell-type expression deconvolution

When run with `mode = "expression"`, CLIMB additionally predicts cell-type-specific expression in two parts:

1. **Mapping-based expression** — summing the expression of cells assigned to each type by the fitted coefficients ($s^{(mapping)}_{ngk} = \sum_i \alpha_{in} \cdot c_{ig} \cdot \tau_{ik}$). This captures expression already present in the reference.
2. **Residual expression** — for genes differentially expressed between the bulk sample and the reference (assumed to originate mainly from cancer cell types), the residual $\epsilon_{ng} = y_{ng} - \hat{y}^{(mapping)}_{ng}$ is used to fit an additional correction term, learned jointly across all bulk samples.

The two components are combined into the final high-resolution expression estimate, returned as `expr.highres` (per-sample) and `expr.overall` (averaged across samples).

## CLIFF: cell-type-specific drug sensitivity via Expectation-Maximization

CLIFF takes CLIMB's cell-type proportions and expression as fixed inputs, together with bulk drug-response data, and infers a latent per-cell-type survival probability $\pi_{kn}$ for each cell type $k$ and sample $n$. The observed bulk survival rate $y_n$ is modeled as the proportion-weighted mixture of these latent probabilities, and $\pi_{kn}$ is linked to cell-type expression through a sigmoid model with coefficients $\tilde{\boldsymbol{\beta}}$.

Because the resulting log-likelihood is not directly tractable, CLIFF is fit by Expectation-Maximization:

- **E-step** — using the current $\tilde{\boldsymbol\beta}$, compute responsibilities $q^{(0)}_{nk}$ and $q^{(1)}_{nk}$ that assign each observed outcome to the cell types most consistent with it, weighted by cell-type proportions.
- **M-step** — with those responsibilities held fixed, refit $\tilde{\boldsymbol\beta}$ by a weighted logistic regression, updating $\pi_{kn}$.

The two steps alternate until early stopping (the fit-to-data error plateaus). The default starting point, $\tilde{\boldsymbol\beta} = 0$ (equivalently $\pi^{(t=0)}_{kn} = 0.5$ for all cell types), requires no tuning and was found empirically to be among the best-performing initializations tested.

```{note}
Internally, CLIFF recenters the input `auc` values so their mean is exactly `0.5` before fitting. Predicted sensitivities (`pi_hat` / `PI_hat_nk`) should therefore be interpreted relative to that recentering, not on the raw input scale.
```

## What's implemented vs. described in the manuscript

The manuscript additionally describes **CLIMB-SC** and **CLIFF-SC**, single-cell-resolution extensions that link CLIMB's per-cell coefficients directly to CLIFF's sigmoid model, bypassing the cell-type aggregation step. These are not currently exposed as separate functions in this package — `climb()` and `cliff()` implement the cell-type-level model described above.