prepare_powerup_data()
brings reference expression, response data, and optional user samples
into a common format for POWERUP model training and prediction.
At minimum, POWERUP needs:
- a reference feature matrix, with samples as rows and feature names (e.g. genes) as columns;
- a response matrix for the same reference samples, with one or more perturbations as columns.
The sample ID column should be named cell_line
(preferred) or sample, preferably as the first column.
POWERUP also accepts cell_lines, samples,
ModelID, or model_id when used as the first
column. Accepted aliases are renamed internally to
cell_line, which POWERUP uses consistently downstream.
If you need to generate a user_matrix from paired-end
RNA-seq FASTQs or BAMs, see Processing bulk RNA-seq
inputs from FASTQ or BAM files. For single-cell or single-nucleus
RNA-seq, see Generating
pseudobulk from single-cell and single-nucleus RNA-seq.
Example data
The bundled example contains 300 reference cell lines, 300 expression features, four dependency responses (CTNNB1, ERBB2, FGFR1, and FAM50A), and two expression profiles held out from the reference tables as prediction samples. It was constructed from DepMap Public 26Q1 for demonstration; see Example data and provenance for the source data, construction, and acknowledgements.
expression_path <- system.file("extdata", "powerup_example_gene_expression.csv", package = "powerup")
dependency_path <- system.file("extdata", "powerup_example_gene_dependency.csv", package = "powerup")
user_path <- system.file("extdata", "powerup_example_user_matrix.csv", package = "powerup")
example_expression <- read.csv(expression_path, check.names = FALSE)
example_dependency <- read.csv(dependency_path, check.names = FALSE)
example_user <- read.csv(user_path, check.names = FALSE)
dim(example_expression)## [1] 300 301
dim(example_dependency)## [1] 300 5
dim(example_user)## [1] 2 301The expression table contains the predictors used to train POWERUP models. The dependency table contains the measured responses to be modeled. The user matrix contains the samples that will receive predictions.
Preparing the data
In the simplest case, POWERUP automatically uses features shared between the reference and prediction data. Because this example contains 300 shared genes, all 300 are retained under the default feature limit.
prepared <- prepare_powerup_data(
gene_expression = example_expression,
response = example_dependency,
user_matrix = example_user
)## [powerup] top-variable feature selection source=reference_matrix reason=user_selected_reference_source reference_samples=300 n_ranked_reference_features=300 n_user_available_features=300The result contains separate training and prediction inputs:
names(prepared)## [1] "perturbations" "features_train" "features_user" "outcomes_train"
## [5] "metadata"
dim(prepared$features_train)## [1] 300 301
dim(prepared$outcomes_train)## [1] 300 5
dim(prepared$features_user)## [1] 2 301
prepared$perturbations## # A tibble: 4 × 2
## modelKey perturbation
## <chr> <chr>
## 1 crispr_model_00001 CTNNB1
## 2 crispr_model_00002 ERBB2
## 3 crispr_model_00003 FGFR1
## 4 crispr_model_00004 FAM50AIn this example:
-
features_traincontains expression for the 300 reference cell lines; -
outcomes_traincontains their measured CTNNB1, ERBB2, FGFR1, and FAM50A dependency values; -
features_usercontains the two held-out samples that will receive predictions; -
perturbationsidentifies the responses to model.
All training and prediction feature tables use the same set of genes.
Choosing features
Features can be chosen explicitly or limited to the top N most variable genes.
To use a specific set of genes, provide them with
selected_features:
features_to_use <- c(
"AXIN2", "BMP4", "RNF43", "NKD1", "SOX9", "ERBB2",
"NRG1", "GRB7", "FGFR1", "FGF2", "COL1A1", "FAM50B"
)
prepared_selected <- prepare_powerup_data(
gene_expression = example_expression,
response = example_dependency,
selected_features = features_to_use,
user_matrix = example_user
)
dim(prepared_selected$features_train)## [1] 300 13
prepared_selected$metadata$selected_genes## [1] "axin2" "bmp4" "rnf43" "nkd1" "sox9" "erbb2" "nrg1" "grb7"
## [9] "fgfr1" "fgf2" "col1a1" "fam50b"Alternatively, use n_features to retain only the most
variable shared features. By default, variability is calculated across
the reference samples:
prepared_reference_top50 <- prepare_powerup_data(
gene_expression = example_expression,
response = example_dependency,
n_features = 50,
user_matrix = example_user
)## [powerup] top-variable feature selection source=reference_matrix reason=user_selected_reference_source reference_samples=300 n_ranked_reference_features=300 n_user_available_features=300
dim(prepared_reference_top50$features_train)## [1] 300 51
prepared_reference_top50$metadata$selected_genes## [1] "krt19" "krt5" "tacstd2" "krt17" "krt8" "rps4y1"
## [7] "fxyd3" "lcn2" "s100a14" "agr2" "vim" "krt7"
## [13] "krt18" "s100p" "gpx2" "krt6a" "uchl1" "epcam"
## [19] "mal2" "sparc" "c19orf33" "slpi" "cd74" "ifi27"
## [25] "cldn4" "igfbp3" "tgfbi" "cav1" "s100a2" "mt1e"
## [31] "s100a6" "adirf" "elf3" "rab25" "s100a9" "mgst1"
## [37] "sfn" "krt13" "cldn7" "spint2" "efemp1" "tm4sf1"
## [43] "aldh1a1" "fn1" "cdh1" "tinagl1" "srgn" "dkk1"
## [49] "tspan8" "cd24"Variability can instead be calculated across the samples in
user_matrix:
prepared_user_top50 <- prepare_powerup_data(
gene_expression = example_expression,
response = example_dependency,
n_features = 50,
feature_selection_source = "user_matrix",
user_matrix = example_user
)## [powerup] top-variable feature selection source=user_matrix n_samples=2 n_candidate_features=300
dim(prepared_user_top50$features_train)## [1] 300 51
prepared_user_top50$metadata$selected_genes## [1] "hla_b" "agr2" "peg10" "s100a14" "wfdc2" "mgst1"
## [7] "bmp4" "cd44" "fst" "ifitm1" "uchl1" "snrpn"
## [13] "slpi" "tusc3" "ccnd1" "rbp1" "acsl5" "tuba1a"
## [19] "gprc5a" "adirf" "il32" "igfbp4" "eps8l3" "rnf43"
## [25] "klk10" "mdk" "dkk1" "gstp1" "fgfbp1" "prss3"
## [31] "klk6" "lcp1" "il18" "cdx2" "bcam" "magea4"
## [37] "clrn3" "epha1" "itgb4" "gpnmb" "hcls1" "anxa3"
## [43] "tpm2" "serpinb5" "anxa1" "cdh3" "myeov" "hnf4a"
## [49] "dmkn" "tmprss4"Using user_matrix as the feature selection source can be
useful when analyzing a collection of samples and the goal is to focus
the search on features that vary across that prediction cohort.
Adding user or held-out samples
user_matrix can contain samples that do not have
measured responses in the reference dataset. It should contain samples
as rows and feature names as columns, using data processed on a
comparable scale to the reference data.
Reference samples can also be held out of training with
test_cell_lines. When supplied, those reference samples are
moved into features_user so their predictions can later be
compared with known outcomes.
If both user_matrix and test_cell_lines are
supplied, features_user contains both sets of prediction
samples.
POWERUP uses only features shared between the reference data and the
prediction cohort. Feature names are matched case-insensitively. By
default, a terminal Entrez annotation is ignored, so names such as
TSPAN8, tspan8, and TSPAN8 (7105)
can match. If the same base feature name occurs more than once in either
matrix, terminal Entrez IDs are retained to distinguish the duplicated
features. Prefixes remain part of the feature name, so
CTNNB1, exp_CTNNB1, mut_CTNNB1,
and ko_CTNNB1 are distinct features. Set
ignore_entrez_suffix = FALSE to require the full normalized
feature names to match.
If selected_features is supplied, unavailable requested
features are omitted. Training and prediction matrices therefore use the
same feature set. Reference and prediction features should represent the
same measurements on a comparable scale. Sample identifiers should be
unique within each input table. Features absent from either side cannot
be used by the model, and selecting variable features from
user_matrix makes feature selection specific to that
prediction cohort.
Next step
The prepared object is ready for model training with fit_powerup_models().
See Training and
evaluating POWERUP models for the fitting, validation, and
uncertainty workflow.
Session information
## R version 4.4.2 (2024-10-31)
## Platform: aarch64-apple-darwin20
## Running under: macOS Sequoia 15.7.3
##
## Matrix products: default
## BLAS: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRlapack.dylib; LAPACK version 3.12.0
##
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
##
## time zone: America/New_York
## tzcode source: internal
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] powerup_1.0.99
##
## loaded via a namespace (and not attached):
## [1] vctrs_0.6.5 cli_3.6.5 knitr_1.50 rlang_1.1.6
## [5] xfun_0.51 generics_0.1.3 textshaping_1.0.0 jsonlite_2.0.0
## [9] glue_1.8.0 htmltools_0.5.8.1 ragg_1.5.1 sass_0.4.9
## [13] rmarkdown_2.29 tibble_3.3.0 evaluate_1.0.3 jquerylib_0.1.4
## [17] fastmap_1.2.0 yaml_2.3.10 lifecycle_1.0.4 compiler_4.4.2
## [21] dplyr_1.1.4 fs_1.6.5 pkgconfig_2.0.3 htmlwidgets_1.6.4
## [25] systemfonts_1.2.2 digest_0.6.37 R6_2.6.1 utf8_1.2.4
## [29] tidyselect_1.2.1 pillar_1.10.1 magrittr_2.0.3 bslib_0.9.0
## [33] withr_3.0.2 tools_4.4.2 pkgdown_2.2.0 cachem_1.1.0
## [37] desc_1.4.3