# CLIMB

CLIMB (**C**ellular-level **LI**near **M**odel of **B**ulk deconvolution) deconvolutes bulk RNA-seq data using a single-cell RNA-seq reference dataset. See [Methods](../methods.md) for the underlying model.

This page documents `climb()`, the package's single deconvolution function.

## Usage

```r
climb(sc, bulk, mode = "abundance", up.lim = Inf, verbose = TRUE, cancer_pattern = "*",
      min_common_genes = 100, n.iter.subsampling = 5, 
      min.n.cells = 50, n.top_mean.genes = 500, confidence_weighting = TRUE)
```

## Parameters

**Required**

| Parameter | Description |
|---|---|
| `sc` | `ExpressionSet` containing the single-cell RNA-seq reference dataset, with cell-type labels in `sc$cellType` |
| `bulk` | `ExpressionSet` containing the bulk RNA-seq mixtures to be deconvoluted |

**Optional**

| Parameter | Description | Default |
|---|---|---|
| `mode` | `"abundance"` predicts only cell-type proportions; `"expression"` additionally predicts cell-type-specific expression | `"abundance"` |
| `up.lim` | Upper bound for coefficients (L-infinity norm constraint) | `Inf` |
| `verbose` | Print progress messages | `TRUE` |
| `cancer_pattern` | String pattern matching the cancer cell-types in `sc$cellType`; CLIMB assumes differentially expressed genes only for these. Only used in expression-predicting modes (`"expression"`, `"all"`, `"all+"`); ignored in `"abundance"` mode | `"*"` (matches every cell-type) |
| `min_common_genes` | Minimum number of genes required in common between `bulk` and `sc` | `100` |
| `n.iter.subsampling` | Number of reference sub-sampling iterations per Empirical Bayes round (averaged) | `5` |
| `min.n.cells` | Minimum cells per cell type to sub-sample | `50` |
| `n.top_mean.genes` | Number of genes used for bulk-sample-specific gene selection | `500` |
| `confidence_weighting` | If `TRUE`, blends `props.corrected` back toward `props.init` per sample, weighted by the correlation between that sample's `props.init` and the reference's raw per-cell-type cell counts — improves robustness in poorly-identified cases at a small cost to average-case accuracy. If `FALSE`, returns the raw second-pass estimate | `TRUE` |

## Output

`climb()` returns a list. Fields present in every mode:

| Field | Description |
|---|---|
| `props.init` | Cell-type proportions from the initial run (samples × cell-types) |
| `props.corrected` | Cell-type proportions after Empirical Bayes sub-sampling (samples × cell-types) |

Fields present only in `mode = "expression"`:

| Field | Description |
|---|---|
| `coefs` | Single-cell-level coefficients after Empirical Bayes correction (samples × cells) |
| `expr.highres` | High-resolution cell-type expression (samples × genes × cell-types) |
| `expr.overall` | Cell-type expression averaged across all samples |

A few additional internal/diagnostic fields (`coefs.init`, `sc_norm`, `bulk_norm`, `expr.mapping`) are also returned; full documentation of these is coming soon.

```{note}
`cliff()` reads `expr.highres`, `expr.overall`, and `props.corrected` from its `climb_output` argument, so CLIMB must be run with `mode = "expression"` before its output can be passed to CLIFF — `mode = "abundance"` alone is not sufficient.
```

## Example

Using the [bundled in-vitro dataset](../example_data.md) (4 leukemia cell lines mixed into 6 bulk samples, Fig. 2):

```r
library(Biobase)
data(sc.es); data(bulk.es)

# Predict proportions only
result <- climb(sc = sc.es, bulk = bulk.es, mode = "abundance")
head(result$props.corrected)
head(pData(bulk.es))  # compare to the known true mixing proportions

# Predict proportions and cell-type expression
result <- climb(sc = sc.es, bulk = bulk.es, mode = "expression", n.iter.subsampling = 10)
result$expr.highres[1, 1:5, ]  # first sample, first 5 genes
```