Package 'gDRcore'

Description

Annotate cell line data with the provided annotation table

Usage

annotate_dt_with_cell_line(data, cell_line_annotation, fill = "unknown")

Arguments

Value

data.table with annotated cell lines

Examples

data <- data.table::data.table(
   clid = c("CL1", "CL2", "CL3"),
   Gnumber = c("D1", "D2", "D3")
)
cell_line_annotation <- get_cell_line_annotation(data)
annotated_metadata <- annotate_dt_with_cell_line(data, cell_line_annotation)

Description

Annotate drug data with the provided annotation table

Usage

annotate_dt_with_drug(data, drug_annotation, fill = "unknown")

Arguments

Value

data.table with annotated drugs

Examples

data <- data.table::data.table(
   clid = c("CL1", "CL2", "CL3"),
   Gnumber = c("D1", "D2", "D3")
)
drug_annotation <- get_drug_annotation(data)
annotated_metadata <- annotate_dt_with_drug(data, drug_annotation)

Description

Annotate MultiAssayExperiment object with cell line annotations

Usage

annotate_mae_with_cell_line(mae, cell_line_annotation, fill = "unknown")

Arguments

Value

MultiAssayExperiment object with annotated cell lines

Examples

mae <- MultiAssayExperiment::MultiAssayExperiment(
   experiments = list(exp1 = SummarizedExperiment::SummarizedExperiment(
     rowData = data.table::data.table(clid = c("CL1", "CL2", "CL3"))
   ))
)
cell_line_annotation <- get_cell_line_annotation(data.table::as.data.table(
   SummarizedExperiment::rowData(
     MultiAssayExperiment::experiments(mae)[[1]])))
annotated_mae <- annotate_mae_with_cell_line(mae, cell_line_annotation)

Description

Annotate MultiAssayExperiment object with drug annotations

Usage

annotate_mae_with_drug(mae, drug_annotation, fill = "unknown")

Arguments

Value

MultiAssayExperiment object with annotated drugs

Examples

mae <- MultiAssayExperiment::MultiAssayExperiment(
   experiments = list(exp1 = SummarizedExperiment::SummarizedExperiment(
     rowData = data.table::data.table(Gnumber = c("D1", "D2", "D3"))
   ))
)
drug_annotation <- get_drug_annotation(data.table::as.data.table(
   SummarizedExperiment::rowData(
     MultiAssayExperiment::experiments(mae)[[1]])))
annotated_mae <- annotate_mae_with_drug(mae, drug_annotation)

Description

Annotate SummarizedExperiment object with cell line annotations

Usage

annotate_se_with_cell_line(se, cell_line_annotation, fill = "unknown")

Arguments

Value

SummarizedExperiment object with annotated cell lines

Examples

se <- SummarizedExperiment::SummarizedExperiment(
   rowData = data.table::data.table(clid = c("CL1", "CL2", "CL3"))
)
cell_line_annotation <- get_cell_line_annotation(data.table::as.data.table(SummarizedExperiment::rowData(se)))
annotated_se <- annotate_se_with_cell_line(se, cell_line_annotation)

Description

Annotate SummarizedExperiment object with drug annotations

Usage

annotate_se_with_drug(se, drug_annotation, fill = "unknown")

Arguments

Value

SummarizedExperiment object with annotated drugs

Examples

se <- SummarizedExperiment::SummarizedExperiment(
   rowData = data.table::data.table(Gnumber = c("D1", "D2", "D3"))
)
drug_annotation <- get_drug_annotation(data.table::as.data.table(SummarizedExperiment::rowData(se)))
annotated_se <- annotate_se_with_drug(se, drug_annotation)

Description

Compute per-point HSA and Bliss excess values for a combination SE, writing the result to the excess assay. This is step 3 of the fit_SE.combinations pipeline.

Usage

apply_combo_excess(
  se,
  series_identifiers = NULL,
  normalization_types = c("GR", "RV"),
  averaged_assay = "Averaged",
  metrics_assay = "Metrics",
  excess_assay = "excess"
)

Arguments

Details

Requires the Averaged and Metrics assays to be present (the latter as produced by apply_combo_sa_fits or fit_SE.combinations).

Value

Updated SE with an excess_assay assay containing per-point smooth, hsa_excess, and bliss_excess columns.

See Also

apply_combo_sa_fits, apply_combo_isobolograms, apply_combo_scores, fit_SE.combinations

Examples

mae <- gDRutils::get_synthetic_data("finalMAE_combo_matrix_small")
combo_se <- mae[[gDRutils::get_supported_experiments("combo")]]
combo_se_excess <- apply_combo_excess(combo_se[1, 1])
"excess" %in% SummarizedExperiment::assayNames(combo_se_excess)

Description

Compute Loewe combination index isobolograms for a combination SE, writing results to the isobolograms and all_iso_points assays. This is step 4 of the fit_SE.combinations pipeline.

Usage

apply_combo_isobolograms(
  se,
  series_identifiers = NULL,
  normalization_types = c("GR", "RV"),
  averaged_assay = "Averaged",
  metrics_assay = "Metrics",
  isobolograms_assay = "isobolograms",
  iso_points_assay = "all_iso_points"
)

Arguments

Details

Requires the Averaged and Metrics assays (as produced by apply_combo_sa_fits or fit_SE.combinations). Isobologram analysis is only performed when at least 9 combo concentration points are available — otherwise NA is written, matching fit_SE.combinations behaviour.

Value

Updated SE with isobolograms_assay and iso_points_assay assays.

See Also

apply_combo_sa_fits, apply_combo_excess, apply_combo_scores, fit_SE.combinations

Examples

mae <- gDRutils::get_synthetic_data("finalMAE_combo_matrix_small")
combo_se <- mae[[gDRutils::get_supported_experiments("combo")]]
combo_se_iso <- apply_combo_isobolograms(combo_se[1, 1])
"isobolograms" %in% SummarizedExperiment::assayNames(combo_se_iso)

Description

Fit single-agent dose-response curves for each co-treatment concentration in a combination SE and store the results in the Metrics assay. This is step 1+2 of the fit_SE.combinations pipeline:

Usage

apply_combo_sa_fits(
  se,
  series_identifiers = NULL,
  normalization_types = c("GR", "RV"),
  averaged_assay = "Averaged",
  metrics_assay = "Metrics",
  fit_source = "gDR"
)

Arguments

Details

1. Standardise concentrations and build the complete dose-response matrix.

2. Fit SA curves per co-treatment concentration via fit_combo_cotreatments() and fit_combo_codilutions().

3. Compute smooth SA predictions at every combo point via map_ids_to_fits() and store them together with the SA fit parameters.

The resulting Metrics assay contains dilution_drug, cotrt_value, ec50, h, x_inf, x_0, and normalization_type — the same schema as produced by fit_SE.combinations().

Value

Updated SummarizedExperiment with a metrics_assay assay containing SA fit parameters per co-treatment concentration.

See Also

apply_combo_excess, apply_combo_isobolograms, apply_combo_scores, fit_SE.combinations

Examples

mae <- gDRutils::get_synthetic_data("finalMAE_combo_matrix_small")
combo_se <- mae[[gDRutils::get_supported_experiments("combo")]]
SummarizedExperiment::assays(combo_se) <-
  SummarizedExperiment::assays(combo_se)["Averaged"]
combo_se_fitted <- apply_combo_sa_fits(combo_se[1, 1])
"Metrics" %in% SummarizedExperiment::assayNames(combo_se_fitted)

Description

Compute Bliss and HSA synergy scores for a combination SE, replicating the exact scoring logic of fit_SE.combinations.

Usage

apply_combo_scores(
  se,
  scores_assay = "scores",
  averaged_assay = "Averaged",
  metrics_assay = "Metrics",
  excess_assay = NULL,
  normalization_types = c("GR", "RV"),
  fit_source = "gDR",
  score_FUN = calculate_score
)

Arguments

Details

Unlike the low-level bliss_fit_fn and hss_fit_fn (which work on raw Averaged data per triplet), this function uses the SA fit parameters from the Metrics assay to generate curve-smoothed single-agent responses via predict_efficacy_from_conc before computing excess. This produces results numerically identical to fit_SE.combinations.

The function requires a Metrics assay containing columns dilution_drug, cotrt_value, ec50, h, x_inf, x_0, and normalization_type — as produced by fit_SE.combinations or apply_fit_to_se with fit_drug_response_metrics.

Scoring steps (per drug-combo × cell-line × normalization_type):

1. Predict smooth SA responses at every combo concentration using predict_efficacy_from_conc on drug_1 and drug_2 parameter sets from Metrics.

2. Average col_values (drug-1-along-conc1) and row_values (drug-2-along-conc2) → smooth.

3. Compute Bliss-expected using calculate_Bliss and HSA-expected using calculate_HSA on the smooth SA edges.

4. Compute excess via calculate_excess.

5. Score = mean of top 10-percentile excess via calculate_score.

Value

Updated SummarizedExperiment with a scores_assay assay containing bliss_score and hsa_score per triplet.

See Also

bliss_fit_fn, hss_fit_fn for the simplified raw-data variants.

Examples

mae <- gDRutils::get_synthetic_data("finalMAE_combo_matrix_small")
combo_se <- mae[[gDRutils::get_supported_experiments("combo")]]
combo_se_out <- apply_combo_scores(combo_se)
"scores" %in% SummarizedExperiment::assayNames(combo_se_out)

Description

Run different components of the gDR drug response processing pipeline. Either: create a SummarizedExperiment and normalize raw treated and control data (create_and_normalize_SE), average data (average_SE), or fit the processed data (fit_SE). See details for more in-depth explanations.

Usage

average_SE(
  se,
  data_type,
  series_identifiers = NULL,
  normalized_assay = "Normalized",
  averaged_assay = "Averaged"
)

create_SE(
  df_,
  data_type,
  readout = "ReadoutValue",
  nested_identifiers = NULL,
  nested_confounders = intersect(names(df_), gDRutils::get_env_identifiers("barcode")),
  override_untrt_controls = NULL
)

fit_SE(
  se,
  data_type = "single-agent",
  nested_identifiers = NULL,
  averaged_assay = "Averaged",
  metrics_assay = "Metrics",
  n_point_cutoff = 4,
  range_conc = c(0.005, 5),
  force_fit = FALSE,
  pcutoff = 0.05,
  cap = 0.1,
  curve_type = c("GR", "RV")
)

normalize_SE(
  se,
  data_type,
  nested_identifiers = NULL,
  nested_confounders = gDRutils::get_SE_identifiers(se, "barcode", simplify = TRUE),
  control_mean_fxn = function(x) {
     mean(x, trim = 0.25)
 },
  control_assay = "Controls",
  raw_treated_assay = "RawTreated",
  normalized_assay = "Normalized",
  ndigit_rounding = 4
)

create_and_normalize_SE(
  df_,
  data_type,
  readout = "ReadoutValue",
  control_mean_fxn = function(x) {
     mean(x, trim = 0.25)
 },
  nested_identifiers = NULL,
  nested_confounders = intersect(names(df_), gDRutils::get_env_identifiers("barcode")),
  override_untrt_controls = NULL,
  ndigit_rounding = 4,
  control_assay = "Controls",
  raw_treated_assay = "RawTreated",
  normalized_assay = "Normalized"
)

runDrugResponseProcessingPipeline(
  x,
  readout = "ReadoutValue",
  control_mean_fxn = function(x) {
     mean(x, trim = 0.25)
 },
  nested_identifiers_l = NULL,
  nested_confounders = gDRutils::get_env_identifiers("barcode"),
  override_untrt_controls = NULL,
  ndigit_rounding = 4,
  n_point_cutoff = 4,
  control_assay = "Controls",
  raw_treated_assay = "RawTreated",
  normalized_assay = "Normalized",
  averaged_assay = "Averaged",
  metrics_assay = "Metrics",
  split_data = TRUE,
  data_dir = NULL,
  partial_run = FALSE,
  start_from = get_pipeline_steps()[1],
  selected_experiments = NULL
)

Arguments

Details

runDrugResponseProcessingPipeline is made up of 3 separate steps:

• "create_and_normalize_SE"

• "average_SE"

• "fit_SE"

For create_and_normalize_SE, this creates a SummarizedExperiment object from a data.table, where the data.table contains treatments on rows, and conditions on columns. A SummarizedExperiment object containing two asssays is created: treated readouts will live in an assay called "RawTreated", and reference readouts live in an assay called "Controls". Subsequently, the treated and control elements will be normalized to output two metrics:

For average_SE, take the normalized assay and average the nested DataFrames across uniquenested_identifiers.

For fit_SE, take the averaged assay and fit curves to obtain metrics, one set of metrics for each normalization type set.

Pipeline can be run partially with partial_run flag set to TRUE. The start_from string defines the step from which the pipeline will be launched. However, partial run of the pipeline is possible only if the whole pipeline was launched at least once with defined data_dir and intermediate data was saved as qs2 files into data_dir.

Pipeline can be run for the selected experiments by changing the default value of selected_experiments param. This scenario only works when partial_run is enabled.

Value

MAE object

Examples

d <- rep(seq(0.1, 0.9, 0.1), each = 4)
v <- rep(seq(0.1, 0.4, 0.1), 9)
df <- S4Vectors::DataFrame(
  Concentration = d,
  normalization_type = rep(c("GR", "RV"), length(v) * 2),
  x = rep(v, 2)
)
normalized <- BumpyMatrix::splitAsBumpyMatrix(row = 1, column = 1, x = df)

keys <- list(Trt = "Concentration")
assays <- list("Normalized" = normalized)
se <- SummarizedExperiment::SummarizedExperiment(assays = assays)
se <- gDRutils::set_SE_keys(se, keys)
se <- gDRutils::set_SE_identifiers(se, gDRutils::get_env_identifiers())
se1 <- average_SE(
  se,
  data_type = "single-agent",
  normalized_assay = "Normalized",
  averaged_assay = "Averaged"
)


td <- gDRimport::get_test_data()
l_tbl <- gDRimport::load_data(
  manifest_file = gDRimport::manifest_path(td),
  df_template_files = gDRimport::template_path(td),
  results_file = gDRimport::result_path(td)
)
imported_data <- merge_data(
  l_tbl$manifest,
  l_tbl$treatments,
  l_tbl$data
)

se <- purrr::quietly(create_SE)(imported_data, data_type = "single-agent")


td <- gDRimport::get_test_data()
l_tbl <- gDRimport::load_data(
  manifest_file = gDRimport::manifest_path(td),
  df_template_files = gDRimport::template_path(td),
  results_file = gDRimport::result_path(td)
)
imported_data <- merge_data(
  l_tbl$manifest,
  l_tbl$treatments,
  l_tbl$data
)

inl <- prepare_input(imported_data)
se <- create_SE(
 inl$df_list[["single-agent"]],
 data_type = "single-agent",
 nested_confounders = inl$nested_confounders)

normalize_SE(se, data_type = "single-agent")
p_dir <- file.path(tempdir(), "pcheck")
dir.create(p_dir)
td <- gDRimport::get_test_data()
l_tbl <- gDRimport::load_data(
  manifest_file = gDRimport::manifest_path(td),
  df_template_files = gDRimport::template_path(td),
  results_file = gDRimport::result_path(td)
)
imported_data <- merge_data(
  l_tbl$manifest,
  l_tbl$treatments,
  l_tbl$data
)
runDrugResponseProcessingPipeline(
  imported_data,
  data_dir = p_dir
)

Description

Reference fit function for Bliss independence synergy scoring on combination data. Computes Bliss-expected response from single-agent edges and derives excess and score from raw averaged data.

Usage

bliss_fit_fn(avg_dt)

Arguments

Details

Intended for use with apply_fit on combination SEs:

  gDRutils::apply_fit(
    combo_se, bliss_fit_fn, "combination",
    output_assay = "custom_bliss", fit_source = "bliss"
  )

Value

Named list with bliss_score, bliss_excess_mean, n_combo_points, and normalization_type.

Examples

mae <- gDRutils::get_synthetic_data("finalMAE_combo_matrix_small")
combo_se <- mae[[gDRutils::get_supported_experiments("combo")]]
combo_se_out <- gDRutils::apply_fit(
  combo_se, bliss_fit_fn, "combination",
  output_assay = "custom_bliss", fit_source = "bliss"
)

Description

Calculate the difference between values, likely representing the same metric, from two data.tables.

Usage

calculate_excess(
  metric,
  measured,
  series_identifiers,
  metric_col,
  measured_col
)

Arguments

Value

data.table of measured, now with an additional column named excess (positive values for synergy/benefit).

Examples

metric <- data.table::data.table(
  Concentration = c(1, 2, 3, 1, 2, 3),
  Concentration_2 = c(1, 1, 1, 2, 2, 2),
  GRvalue = c(100, 200, 300, 400, 500, 600)
)
measured <- data.table::data.table(
  Concentration = c(3, 1, 2, 2, 1, 3),
  Concentration_2 = c(1, 1, 1, 2, 2, 2),
  testvalue = c(200, 0, 100, 400, 300, 500)
)
series_identifiers <- c("Concentration", "Concentration_2")
metric_col <- "GRvalue"
measured_col <- "testvalue"
calculate_excess(
  metric,
  measured,
  series_identifiers,
  metric_col,
  measured_col
)

Description

Calculate a GR value for a given set of dose response values.

Usage

calculate_GR_value(
  rel_viability,
  corrected_readout,
  day0_readout,
  untrt_readout,
  ndigit_rounding,
  duration,
  ref_div_time,
  cap = 1.25
)

calculate_time_dep_GR_value(
  corrected_readout,
  day0_readout,
  untrt_readout,
  ndigit_rounding
)

calculate_endpt_GR_value(
  rel_viability,
  duration,
  ref_div_time,
  cap = 1.25,
  ndigit_rounding
)

Arguments

Details

Note that this function expects that all numeric vectors are of the same length. calculate_GR_value will try to greedily calculate a GR value. If no day 0 readouts are available, the duration and ref_div_time will be used to try to back-calculate a day 0 value in order to produce a GR value.

In the case of calculating the reference GR value from multiple reference readout values, the vectorized calculation is performed and then the resulting vector should be averaged outside of this function.

Note that it is expected that the ref_div_time and duration are reported in the same units.

Value

numeric vector containing GR values, one value for each element of the input vectors.

See Also

normalize_SE2

Examples

duration <- 144
rv <- seq(0.1, 1, 0.1)
corrected <- seq(41000, 50000, 1000)
day0 <- seq(91000, 95500, 500)
untrt <- rep(c(115000, 118000), 5)

calculate_GR_value(
  rel_viability = rv,
  corrected_readout = corrected,
  day0_readout = day0,
  untrt_readout = untrt,
  ndigit_rounding = 4,
  duration = duration,
  ref_div_time = duration / 2
)

readouts <- rep(10000, 5)
calculate_time_dep_GR_value(readouts, readouts * 1.32, readouts * 2, 2)

readouts <- rep(10000, 5)
calculate_endpt_GR_value(readouts, 72, 1, ndigit_rounding = 2)

Description

Calculate score for HSA and Bliss

Usage

calculate_score(excess)

Arguments

Value

numeric vector with calculated score

Examples

metric <- data.table::data.table(
  Concentration = c(1, 2, 3, 1, 2, 3),
  Concentration_2 = c(1, 1, 1, 2, 2, 2),
  GRvalue = c(100, 200, 300, 400, 500, 600)
)
measured <- data.table::data.table(
  Concentration = c(3, 1, 2, 2, 1, 3),
  Concentration_2 = c(1, 1, 1, 2, 2, 2),
  testvalue = c(200, 0, 100, 400, 300, 500)
)
series_identifiers <- c("Concentration", "Concentration_2")
metric_col <- "GRvalue"
measured_col <- "testvalue"
x <- calculate_excess(
  metric,
  measured,
  series_identifiers,
  metric_col,
  measured_col
)
calculate_score(x$x)

Description

Cleanup a data.table with metadata

Usage

cleanup_metadata(
  df_metadata,
  cell_line_annotation = NULL,
  drug_annotation = NULL
)

Arguments

Details

Adds annotations and check whether user provided correct input data.

Value

a data.table with cleaned metadata

Examples

df <- data.table::data.table(
  clid = "CELL_LINE",
  Gnumber = "DRUG_1",
  Concentration = c(0, 1),
  Duration = 72
)
cleanup_df <- cleanup_metadata(df)

Description

Stage 1 of the time-course pipeline: fits a growth rate per well within each time window, aggregates replicates, and normalises the rates to the control wells of a reference period. The returned table keeps every treatment, controls included, together with the raw rate and its standard deviation, so it can be reported on directly. Pass it through growth_rates_to_se to obtain the stage 2 input, or use fit_SE.timecourse to run both stages at once.

Usage

compute_growth_rates(
  se,
  periods,
  normalization_map,
  lfc_assay = NULL,
  rate_fn = NULL
)

Arguments

Details

Growth rates are computed per (Barcode, WellRow, WellColumn, CellLine, Drug, Concentration, partner drug/concentration slots) group, so single-agent, doublet and triplet arms are never pooled. Control wells are detected via gDRutils::get_env_identifiers("untreated_tag") and a single baseline per (CellLine, period) is used for normalization.

Value

A data.table with one row per (CellLine, Drug, Concentration, partner slots, period) — controls included — holding GrowthRate (doublings/day), sd_GrowthRate across replicate wells, rate_0 (the control baseline used, NA for periods mapped to "None" and when no control rows are present), NormalizedGrowthRate and normalization_type. All of these columns are always present, whatever the normalization map or the availability of controls. NormalizedGrowthRate is NA where the control baseline is not meaningfully positive: such a denominator either inverts the sign of the ratio (when negative) or leaves it undefined (when zero, within fitting tolerance) rather than scaling it, so no meaningful normalized rate exists. A warning names the cell line and period.

See Also

growth_rates_to_se, fit_SE.timecourse, apply_fit

Examples

## Not run: 
periods <- list(early = c(0, 48), late = c(48, 96))
norm_map <- c(early = "None", late = "early")
growth_dt <- compute_growth_rates(se_tc, periods, norm_map)

# Stage 2 with any custom fit function:
se_fit <- gDRutils::apply_fit(
  growth_rates_to_se(growth_dt),
  fit_fn = my_fit_fn,
  data_type = "time-course-metrics",
  output_assay = "Metrics",
  merge = "replace",
  fit_source = "custom"
)

## End(Not run)

Description

Transform mae into raw data

Usage

convert_mae_to_raw_data(mae)

Arguments

Value

data.table with raw data

Examples

mae <- gDRutils::get_synthetic_data("finalMAE_small")
convert_mae_to_raw_data(mae)

Description

Transform se into raw_data

Usage

convert_se_to_raw_data(se)

Arguments

Value

data.table with raw data

Examples

mae <- gDRutils::get_synthetic_data("finalMAE_small")
se <- mae[[1]]
convert_se_to_raw_data(se)

Description

Detect model of data

Usage

data_model(x)

Arguments

Value

string with the information of the raw data follows single-agent or combination data model

Examples

data_model("single-agent")

Description

Detect model of data from experiment name

Usage

## S3 method for class 'character'
data_model(x)

Arguments

Value

string with the information of the raw data follows single-agent or combination data model

Description

Detect model of data in data.table

Usage

## S3 method for class 'data.table'
data_model(x)

Arguments

Value

string with the information of the raw data follows single-agent or combination data model

Description

Perform fittings for combination screens.

Usage

fit_SE.combinations(
  se,
  data_type = gDRutils::get_supported_experiments("combo"),
  series_identifiers = NULL,
  normalization_types = c("GR", "RV"),
  averaged_assay = "Averaged",
  metrics_assay = "Metrics",
  score_FUN = calculate_score
)

Arguments

Details

This function assumes that the combination is set up with both concentrations nested in the assay.

Value

A SummarizedExperiment object with an additional assay containing the combination metrics.

Examples

fmae_cms <- gDRutils::get_synthetic_data("finalMAE_combo_matrix_small")

se1 <- fmae_cms[[gDRutils::get_supported_experiments("combo")]]
SummarizedExperiment::assays(se1) <-
  SummarizedExperiment::assays(se1)["Averaged"]
fit_SE.combinations(se1[1, 1])

Description

Two-stage pipeline for time-course dose-response data:

1. Compute growth rates per user-defined time window and normalise them to the control of the reference period (compute_growth_rates).

2. Fit a 3-parameter Hill (logistic) curve on the NormalizedGrowthRate ~ log10(Concentration) dose-response for each (Drug, CellLine, period) combination.

Usage

fit_SE.timecourse(
  se,
  periods,
  normalization_map,
  lfc_assay = NULL,
  metrics_assay = "Metrics",
  rate_fn = NULL,
  fit_fn = NULL,
  fit_source = NULL,
  n_point_cutoff = 4L,
  range_conc = c(0.005, 5),
  force_fit = FALSE,
  pcutoff = 0.05,
  cap = 0.1
)

Arguments

Details

The LogFoldChange assay consumed by this function is produced by normalize_SE when data_type = "time-course".

Both stages accept a replacement function, so custom fitting works for time-course data the same way it does for single-agent and combination screens. The two stages can also be run separately: compute_growth_rates returns the growth rate table (controls included) and growth_rates_to_se turns it into the input of apply_fit with data_type = "time-course-metrics".

Value

A new SummarizedExperiment where rows = (Drug, CellLine) and columns = period names, holding the GrowthRates assay from stage 1 and the Metrics assay (or metrics_assay) from stage 2. With the default fit_fn the metrics are: ec50, xc50, h, x_inf, x_0, r2, x_mean, x_AOC, x_AOC_range, x_max, fit_type, N_conc, maxlog10Concentration, and period.

See Also

compute_growth_rates for stage 1 on its own, fit_SE for single-agent fitting, fit_SE.combinations for combination screens, apply_fit for the generic fitting engine.

Examples

## Not run: 
# After normalize_SE(se_tc, data_type = "time-course"):
periods <- list(early = c(0, 48), mid = c(48, 96), late = c(96, 144))
norm_map <- c(early = "None", mid = "early", late = "early")
se_fit <- fit_SE.timecourse(se_tc, periods = periods,
                            normalization_map = norm_map)
gDRutils::convert_se_assay_to_dt(se_fit, "Metrics")

# Custom growth-rate estimator and custom dose-response fit:
se_custom <- fit_SE.timecourse(
  se_tc,
  periods = periods,
  normalization_map = norm_map,
  rate_fn = function(dt) 24 * stats::median(diff(dt$LogFoldChange) /
                                            diff(dt$Duration)),
  fit_fn = function(dt) data.table::data.table(x_mean = mean(dt$NormalizedGrowthRate))
)

## End(Not run)

Description

get info about created/present assays in SE at the given pipeline step

Usage

get_assays_per_pipeline_step(
  step,
  data_model,
  status = c("created", "present")
)

Arguments

Value

assay

Description

Get cell line annotation data table

Usage

get_cell_line_annotation(
  data,
  fname = "cell_lines.csv",
  fill = "unknown",
  annotation_package = if ("gDRinternal" %in% .packages(all.available = TRUE)) {
    
    "gDRinternal"
 } else {
     "gDRtestData"
 }
)

Arguments

Value

data.table with cell line annotations

Examples

data <- data.table::data.table(clid = c("CL1", "CL2", "CL3"))
cell_line_annotation <- get_cell_line_annotation(data)

Description

Retrieve the cell line annotation from the annotated dt input

Usage

get_cellline_annotation_from_dt(dt)

Arguments

Value

data.table with cell line annotation

Examples

dt <- data.table::data.table(Gnumber = "A",
clid = "CL123",
CellLineName = "cl name",
Tissue = "Bone",
parental_identifier = "some cl",
subtype = "cortical",
ReferenceDivisionTime = 5)
get_cellline_annotation_from_dt(dt)

Description

Get default nested identifiers

Usage

get_default_nested_identifiers(x, data_model = NULL)

## S3 method for class 'data.table'
get_default_nested_identifiers(x, data_model = NULL)

## S3 method for class 'SummarizedExperiment'
get_default_nested_identifiers(x, data_model = NULL)

Arguments

Value

vector of nested identifiers

Examples

get_default_nested_identifiers(data.table::data.table())

Description

Get drug annotation data table

Usage

get_drug_annotation(
  data,
  fname = "drugs.csv",
  fill = "unknown",
  annotation_package = if ("gDRinternal" %in% .packages(all.available = TRUE)) {
    
    "gDRinternal"
 } else {
     "gDRtestData"
 }
)

Arguments

Value

data.table with drug annotations

Examples

data <- data.table::data.table(Gnumber = c("drug1", "drug2", "drug3"))
drug_annotation <- get_drug_annotation(data)

Description

Retrieve the drug annotation from the annotated dt input

Usage

get_drug_annotation_from_dt(dt)

Arguments

Value

data.table with drug annotation

Examples

dt <- data.table::data.table(Gnumber = "A",
DrugName = "drugA",
drug_moa = "drug_moa_A")
get_drug_annotation_from_dt(dt)

Description

Reports which durations actually go into the fit for every period, so that a report or a log can state the measurements it used rather than only the window bounds. The bounds alone are ambiguous: whether a timepoint sitting exactly on a boundary is included depends on the window convention, and a window may silently contain far fewer points than intended.

Usage

get_period_timepoints(se, periods, lfc_assay = NULL)

Arguments

Details

Uses the same half-open [start, end) rule as compute_growth_rates, so the answer always matches what was fitted.

Value

data.table with one row per period: period, window (the bounds as "start - end"), n (number of distinct timepoints) and timepoints (those timepoints, sorted, comma-separated). Periods matching no measurement yield n = 0.

timepoints is the union of the durations present anywhere in se, not a per-plate or per-well listing. On a uniform sampling grid the two coincide; if plates were read on different schedules, a duration contributed by only one barcode still appears here, and n is therefore an upper bound on what any single well contributed to the fit.

See Also

compute_growth_rates, fit_SE.timecourse

Examples

## Not run: 
get_period_timepoints(se_tc, list(early = c(44, 92), late = c(92, 140)))

## End(Not run)

Description

Builds the GrowthRates SummarizedExperiment consumed by apply_fit with data_type = "time-course-metrics": rows are (Drug, partner drug/concentration slots, CellLine) — so every combination arm is fitted as its own dose-response curve — and columns are the period names. Control and zero-concentration rows are dropped, since they carry no dose-response information.

Usage

growth_rates_to_se(growth_dt)

Arguments

Value

A SummarizedExperiment with a GrowthRates assay holding Concentration, the partner concentrations, NormalizedGrowthRate and normalization_type per cell.

See Also

compute_growth_rates, fit_SE.timecourse

Examples

## Not run: 
growth_dt <- compute_growth_rates(se_tc, periods, norm_map)
se_gr <- growth_rates_to_se(growth_dt)

## End(Not run)

Description

Returns a lookup table or list of the positions of ALL matches of its first argument in its second and vice versa. Similar to match, though that function only returns the first match.

Usage

grr_matches(
  x,
  y,
  all.x = TRUE,
  all.y = TRUE,
  list = FALSE,
  indexes = TRUE,
  nomatch = NA
)

Arguments

Details

This behavior can be imitated by using joins to create lookup tables, but matches is simpler and faster: usually faster than the best joins in other packages and thousands of times faster than the built in merge.

all.x/all.y correspond to the four types of database joins in the following way:

left

all.x=TRUE, all.y=FALSE

right

all.x=FALSE, all.y=TRUE

inner

all.x=FALSE, all.y=FALSE

full

all.x=TRUE, all.y=TRUE

Note that NA values will match other NA values.

Source of the function: https://github.com/cran/grr/blob/master/R/grr.R

Value

data.table

Examples

mat_elem <- data.table::data.table(
  DrugName = rep(c("untreated", "drugA", "drugB", "untreated"), 2),
  DrugName_2 = rep(c("untreated", "vehicle", "drugA", "drugB"), 2),
  clid = rep(c("C1", "C2"), each = 4)
)
untreated_tag <- gDRutils::get_env_identifiers("untreated_tag")
ref_idx <- which(
  mat_elem$DrugName %in% untreated_tag |
   mat_elem$DrugName_2 %in% untreated_tag
)
ref <- mat_elem[ref_idx, ]
treated <- mat_elem[-ref_idx, ]
valid <- c("DrugName", "DrugName_2")
trt <- lapply(valid, function(x) {
  colnames <- c("clid", x)
  treated[, colnames, with = FALSE]
})
trt <- do.call(paste,
  do.call(rbind, lapply(trt, function(x) setNames(x, names(trt[[1]]))))
)
ref <- lapply(valid, function(x) {
  colnames <- c("clid", x)
  ref[, colnames, with = FALSE]
})
ref <- do.call(paste,
  do.call(rbind, lapply(ref, function(x) setNames(x, names(ref[[1]]))))
)
grr_matches(trt, ref, list = FALSE, all.y = FALSE)

Description

Reference fit function for Highest Single Agent (HSA) synergy scoring on combination data. Uses raw averaged single-agent edges.

Usage

hss_fit_fn(avg_dt)

Arguments

Details

Intended for use with apply_fit on combination SEs:

  gDRutils::apply_fit(
    combo_se, hss_fit_fn, "combination",
    output_assay = "custom_hss", fit_source = "hss"
  )

Value

Named list with hss_score, hss_excess_mean, n_combo_points, and normalization_type.

Examples

mae <- gDRutils::get_synthetic_data("finalMAE_combo_matrix_small")
combo_se <- mae[[gDRutils::get_supported_experiments("combo")]]
combo_se_out <- gDRutils::apply_fit(
  combo_se, hss_fit_fn, "combination",
  output_assay = "custom_hss", fit_source = "hss"
)

Description

Identify type of data

Usage

identify_data_type(dt, codilution_conc = 2, matrix_conc = 1)

Arguments

Value

data.table of raw drug response data with additional column type with the info of data type for a given row of data.table

Author(s)

Bartosz Czech [email protected]

Examples

conc <- rep(seq(0, 0.3, 0.1), 2)
ctrl_dt <- S4Vectors::DataFrame(
  ReadoutValue = c(2, 2, 1, 1, 2, 1),
  Concentration = rep(0, 6),
  masked = FALSE,
  DrugName = rep(c("DRUG_10", "vehicle", "DRUG_8"), 2),
  CellLineName = "CELL1"
)

trt_dt <- S4Vectors::DataFrame(
  ReadoutValue = rep(seq(1, 4, 1), 2),
  Concentration = conc,
  masked = rep(FALSE, 8),
  DrugName = c("DRUG_10", "DRUG_8"),
  CellLineName = "CELL1"
)
input_dt <- data.table::as.data.table(rbind(ctrl_dt, trt_dt))
input_dt$Duration <- 72
input_dt$CorrectedReadout2 <- input_dt$ReadoutValue
identify_data_type(input_dt)

Description

Group columns from a data.table that correspond to different

Usage

identify_keys(
  df_,
  nested_keys = NULL,
  override_untrt_controls = NULL,
  identifiers = gDRutils::get_env_identifiers()
)

Arguments

Details

This is most likely to be used for provenance tracking and will be placed on the SummarizedExperiment metadata for downstream analyses to reference.

Value

named list of key types and their corresponding key values.

See Also

map_df, create_SE

Examples

n <- 64
md_df <- data.table::data.table(
  Gnumber = rep(c("vehicle", "untreated", paste0("G", seq(2))), each = 16),
  DrugName = rep(c("vehicle", "untreated", paste0("GN", seq(2))), each = 16),
  clid = paste0("C", rep_len(seq(4), n)),
  CellLineName = paste0("N", rep_len(seq(4), n)),
  replicates = rep_len(paste0("R", rep(seq(4), each = 4)), 64),
  drug_moa = "inhibitor",
  ReferenceDivisionTime = rep_len(c(120, 60), n),
  Tissue = "Lung",
  parental_identifier = "CL12345",
  Duration = 160
)
md_df <- unique(md_df)
ref <- md_df$Gnumber %in% c("vehicle", "untreated")
trt_df <- md_df[!ref, ]
identify_keys(trt_df)

Description

Map treated conditions to their respective Day0, untreated, or single-agent references using condition metadata.

Usage

map_df(
  trt_md,
  ref_md,
  override_untrt_controls = NULL,
  ref_cols,
  ref_type = c("Day0", "untrt_Endpoint")
)

Arguments

Details

If override_untrt_controls is specified, the values in the named list will supersede the values in trt_md during the matching process. This is useful for mapping treatments to specific "standard" untreated controls.

Value

named list mapping treated metadata to untreated metadata.

See Also

identify_keys

Examples

# Standard Endpoint Mapping
trt_dt <- data.table::data.table(
  clid = c("C1", "C2"),
  Duration = 72,
  rn = c("T1", "T2")
)
ref_dt <- data.table::data.table(
  clid = c("C1", "C2"),
  Duration = 72,
  rn = c("R1", "R2")
)
map_df(trt_dt, ref_dt, ref_cols = "clid", ref_type = "untrt_Endpoint")

Description

Map fittings to identifiers and compute the predicted values for corresponding fits.

Usage

map_ids_to_fits(pred, match_col, fittings, fitting_id_col)

Arguments

Value

Numeric vector of predicted values given pred inputs and fittings values.

Examples

pred <- c(1, 5, 5)
match_col <- c(1, 1, 2)
fitting_id_col <- "match_on_me"

fit1 <- data.table::data.table(h = 2.09, x_inf = 0.68, x_0 = 1, ec50 = 0.003)
fit2 <- data.table::data.table(h = 0.906, x_inf = 0.46, x_0 = 1, ec50 = 0.001)
fittings <- do.call(rbind, list(fit1, fit2))
fittings[[fitting_id_col]] <- c(1, 2)

map_ids_to_fits(pred, match_col, fittings, fitting_id_col)

Description

Identify untreated rows based on Drug treatment alone

Usage

map_untreated(mat_elem)

Arguments

Value

logical vector

Description

Merge all the input data into a single data.table

Usage

merge_data(
  manifest,
  treatments,
  data,
  cell_line_annotation = NULL,
  drug_annotation = NULL
)

Arguments

Value

a data.table with merged data and metadata.

Examples

td <- gDRimport::get_test_data()
l_tbl <- gDRimport::load_data(
  manifest_file = gDRimport::manifest_path(td),
  df_template_files = gDRimport::template_path(td),
  results_file = gDRimport::result_path(td)
)
merge_data(
  l_tbl$manifest,
  l_tbl$treatments,
  l_tbl$data
)

Description

Current steps

• refining nested confounders

• refining nested identifiers

• splitting df_ into (per experiment) df_list

Usage

prepare_input(x, ...)

Arguments

Value

list of input data

Examples

td <- gDRimport::get_test_data()
l_tbl <- gDRimport::load_data(
  manifest_file = gDRimport::manifest_path(td),
  df_template_files = gDRimport::template_path(td),
  results_file = gDRimport::result_path(td)
)
df_ <- merge_data(
  l_tbl$manifest,
  l_tbl$treatments,
  l_tbl$data
)
nested_confounders = intersect(
  names(df_),
  gDRutils::get_env_identifiers("barcode")
)
prepare_input(df_, nested_confounders, NULL)

Description

Current steps

• refining nested confounders

• refining nested identifiers

• splitting df_ into (per experiment) df_list

Usage

## S3 method for class 'data.table'
prepare_input(
  x,
  nested_confounders = gDRutils::get_env_identifiers("barcode"),
  nested_identifiers_l = .get_default_nested_identifiers(),
  ...
)

Arguments

Value

list of input data

Description

Current steps

• refining nested confounders

• refining nested identifiers

• splitting df_ into (per experiment) df_list

Usage

## S3 method for class 'MultiAssayExperiment'
prepare_input(
  x,
  nested_confounders = gDRutils::get_SE_identifiers(x[[1]], "barcode"),
  nested_identifiers_l = .get_default_nested_identifiers(x[[1]]),
  raw_data_field = "experiment_raw_data",
  split_data = TRUE,
  ...
)

Arguments

Value

list of input data

Description

This function processes drug and concentration columns in a data.table. It checks if there is only one unique drug (excluding a specified untreated tag) and if there are exactly two doses (one of which is 0). If these conditions are met, it creates a new column named after the drug and fills it with the doses, then removes the original drug and concentration columns.

Usage

process_perturbations(
  dt,
  drugs_cotrt_ids,
  conc_cotrt_ids,
  untreated_tag = "vehicle"
)

Arguments

Value

A modified data.table with new columns for the drugs and removed original drug and concentration columns.

Examples

dt <- data.table::data.table(
  drug1 = c("vehicle", "drugA", "drugA"),
  conc1 = c(0, 10, 0),
  drug2 = c("vehicle", "drugB", "drugB"),
  conc2 = c(0, 20, 0)
)
drugs_cotrt_ids <- c("drug1", "drug2")
conc_cotrt_ids <- c("conc1", "conc2")
dt <- process_perturbations(dt, drugs_cotrt_ids, conc_cotrt_ids)
print(dt)

Description

Utilize a map to standardize concentrations.

Usage

replace_conc_with_standardized_conc(
  original_concs,
  conc_map,
  original_conc_col,
  standardized_conc_col
)

Arguments

Value

numeric vector of standardized concentrations.

See Also

map_conc_to_standardized_conc

Examples

conc_map <- data.table::data.table(
  orig = c(0.99, 0.6, 0.456, 0.4),
  std = c(1, 0.6, 0.46, 0.4)
)
original_concs <- c(0.456, 0.456, 0.4, 0.99)
exp <- c(0.46, 0.46, 0.4, 1)
obs <- replace_conc_with_standardized_conc(
  original_concs,
  conc_map,
  original_conc_col = "orig",
  standardized_conc_col = "std"
)

Description

Split raw data into list based on the data types

Usage

split_raw_data(dt, type_col = "type")

Arguments

Value

list with split data based on its data type

Author(s)

Bartosz Czech [email protected]

Examples

cell_lines <- gDRtestData::create_synthetic_cell_lines()
drugs <- gDRtestData::create_synthetic_drugs()
dt_layout <- drugs[4:6, as.list(cell_lines[7:8, ]), names(drugs)]
dt_layout <- gDRtestData::add_data_replicates(dt_layout)
dt_layout <- gDRtestData::add_concentration(
  dt_layout,
  concentrations = 10 ^ (seq(-3, .5, .5))
)

dt_2 <-
  drugs[c(21, 26), as.list(cell_lines[which(cell_lines$clid %in% dt_layout$clid)]), names(drugs)]
dt_2 <- gDRtestData::add_data_replicates(dt_2)
dt_2 <- gDRtestData::add_concentration(
  dt_2,
  concentrations = 10 ^ (seq(-3, .5, .5))
)
colnames(dt_2)[colnames(dt_2) %in% c(colnames(drugs), "Concentration")] <-
  paste0(
    colnames(dt_2)[colnames(dt_2) %in% c(colnames(drugs), "Concentration")],
    "_2"
  )
dt_layout_2 <- dt_layout[dt_2, on = intersect(names(dt_layout), names(dt_2)),
                        allow.cartesian = TRUE]
dt_merged_data <- gDRtestData::generate_response_data(dt_layout_2, 0)
dt <- identify_data_type(dt_merged_data)
split_raw_data(dt)

conc <- rep(seq(0, 0.3, 0.1), 2)
ctrl_dt <- S4Vectors::DataFrame(
  ReadoutValue = c(2, 2, 1, 1, 2, 1),
  Concentration = rep(0, 6),
  masked = FALSE,
  DrugName = rep(c("DRUG_10", "vehicle", "DRUG_8"), 2),
  CellLineName = "CELL1"
)

trt_dt <- S4Vectors::DataFrame(
  ReadoutValue = rep(seq(1, 4, 1), 2),
  Concentration = conc,
  masked = rep(FALSE, 8),
  DrugName = c("DRUG_10", "DRUG_8"),
  CellLineName = "CELL1"
)
input_dt <- data.table::as.data.table(rbind(ctrl_dt, trt_dt))
input_dt$Duration <- 72
input_dt$CorrectedReadout2 <- input_dt$ReadoutValue
split_dt <- identify_data_type(input_dt)
split_raw_data(split_dt)

Description

Testing synthetic data form gDRtestData package

Usage

test_synthetic_data(
  original,
  data,
  dataName,
  override_untrt_controls = NULL,
  assays = c("Normalized", "Averaged", "Metrics"),
  tolerance = 0.001
)

Arguments

Value

NULL

Examples

set.seed(2)
cell_lines <- gDRtestData::create_synthetic_cell_lines()
drugs <- gDRtestData::create_synthetic_drugs()
data <- "finalMAE_small"
original <- gDRutils::get_synthetic_data(data)
test_synthetic_data(original, original, "test")