Prepare data for POWERUP model training and prediction

Prepares reference expression, perturbation response, and optional user expression data for POWERUP model training and prediction.

Usage

prepare_powerup_data(
  gene_expression,
  response,
  user_matrix = NULL,
  response_set = "crispr",
  n_features = 6000L,
  feature_selection_source = "reference",
  targets = NULL,
  selected_samples = NULL,
  selected_features = NULL,
  train_cell_lines = NULL,
  test_cell_lines = NULL,
  perturbation_metadata = NULL,
  perturbation_tags = "ko_",
  ignore_entrez_suffix = TRUE
)

Arguments

gene_expression

Reference expression data with samples in rows. The sample ID column should be named cell_line (preferred) or sample; accepted first-column aliases are cell_lines, samples, ModelID, and model_id. All accepted aliases are renamed to cell_line internally.

response

Reference perturbation-response data with samples in rows. Sample IDs follow the same naming rules as gene_expression.

user_matrix

Optional user expression data to predict. Sample IDs follow the same naming rules as gene_expression.

response_set

Response-set label used to construct deterministic model keys.

n_features

Number of features to retain when variable-feature selection is used.

feature_selection_source

Source used for variable-feature selection, either "reference" (default) or "user_matrix".

targets

Optional perturbations to retain. Unmatched requested perturbations are skipped and reported in a compact message.

selected_samples

Optional prediction-cohort samples used only for feature selection.

selected_features

Optional ordered explicit feature list.

train_cell_lines

Optional explicit reference training sample IDs. If supplied, at least one ID must match the reference data.

test_cell_lines

Optional explicit reference test sample IDs. Unmatched IDs are ignored when a user prediction matrix is also supplied.

perturbation_metadata

Optional perturbation metadata table.

perturbation_tags

Optional perturbation prefixes used for target matching.

ignore_entrez_suffix

Whether terminal Entrez annotations such as (7105) should be ignored when matching feature names. Entrez IDs are retained when duplicate base feature names require disambiguation.

Value

A list containing perturbations, training features, prediction features, training outcomes, and preprocessing metadata.

Examples

gene_expression <- data.frame(
  cell_line = c("sample_a", "sample_b", "sample_c"),
  feature_a = c(1, 2, 3),
  feature_b = c(3, 2, 1)
)
response <- data.frame(
  cell_line = c("sample_a", "sample_b", "sample_c"),
  target_a = c(0.1, 0.8, 0.4)
)
user_matrix <- data.frame(
  cell_line = "new_sample",
  feature_a = 2.5,
  feature_b = 1.5
)

prepared <- prepare_powerup_data(
  gene_expression = gene_expression,
  response = response,
  user_matrix = user_matrix
)
#> [powerup] top-variable feature selection source=reference_matrix reason=user_selected_reference_source reference_samples=3 n_ranked_reference_features=2 n_user_available_features=2
prepared$perturbations
#> # A tibble: 1 × 2
#>   modelKey           perturbation
#>   <chr>              <chr>       
#> 1 crispr_model_00001 target_a