Package {drugsens}


Title: Automated Analysis of 'QuPath' Output Data and Metadata Extraction
Description: A comprehensive toolkit for analyzing microscopy data output from 'QuPath' software. Provides functionality for automated data processing, metadata extraction, control normalization, dose-response modeling, and statistical visualization of imaging results. The methodology implemented in this package is based on Labrosse et al. (2024) <doi:10.1016/j.xpro.2024.103274> "Protocol for quantifying drug sensitivity in 3D patient-derived ovarian cancer models", which describes the complete workflow for drug sensitivity analysis in patient-derived cancer models.
Version: 0.2.0
BugReports: https://github.com/flalom/drugsens/issues
SystemRequirements: QuPath (>= 0.4.0)
URL: https://flalom.github.io/drugsens/, https://github.com/flalom/drugsens
License: MIT + file LICENSE
Imports: dplyr, ggplot2, grDevices, stats, stringr, tidyr, tidyselect, utils
Depends: R (≥ 4.2)
Encoding: UTF-8
VignetteBuilder: knitr
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Config/roxygen2/version: 8.1.1
NeedsCompilation: no
Packaged: 2026-11-15 20:12:13 UTC; flalom
Author: Flavio Lombardo ORCID iD [aut, cre]
Maintainer: Flavio Lombardo <fl@flaviolombardo.site>
Repository: CRAN
Date/Publication: 2026-11-16 08:50:30 UTC

Data format changer

Description

This function gets the count data data.frame, that has a wider format and it returns a longer-formatted data.frame

Usage

change_data_format_to_longer(
  .data,
  pattern_column_markers = "_ratio_of_total_cells",
  unique_name_row_identifier = "filter_image",
  additional_columns = TRUE
)

Arguments

.data

The markers count dataframe that is coming from the processing of the microscopy data

pattern_column_markers

The markers' pattern name to obtain the column with ratios of the markers (it defaults to "_ratio_of_total_cells")

unique_name_row_identifier

String that indicates the unique identifier for each image, defaults as "filter_image"

additional_columns

Logical; whether to keep all standard metadata columns (PID, Date, DOC, Tissue, Image_number, Treatment, Concentration1, Concentration2, ConcentrationUnits1, ConcentrationUnits2, ReplicaOrNot, Treatment_complete) in the long-format output. Defaults to TRUE.

Details

Reformat the counts data in longer format

Value

A dataframe/tibble.

Examples


# Load and process example data
bind_data <- data_binding(
  path_to_the_projects_folder = system.file("extdata/to_merge/", package = "drugsens")
)
counts_dataframe <- make_count_dataframe(bind_data)

# Convert to long format
plotting_ready_dataframe <- change_data_format_to_longer(counts_dataframe)


Merge all the dataframes coming out from the QuPath

Description

This function identifies string patterns in the dataset, fills the dataframe with that information, and combines all data into a single file. Marker relabeling is loaded from config_drugsens.txt via make_run_config() without modifying .GlobalEnv.

Usage

data_binding(
  path_to_the_projects_folder,
  files_extension_to_look_for = "csv",
  recursive_search = FALSE,
  forcePath = NULL
)

Arguments

path_to_the_projects_folder

String/Path The path where the files coming out of QuPath are located

files_extension_to_look_for

String The extension of the file outputted from QuPath, (default is "csv")

recursive_search

Boolean, it defined the behavior of the file search, if recursive or not, (default is FALSE)

forcePath

Optional directory path containing config_drugsens.txt. Defaults to NULL (tempdir()).

Value

A concatenated dataframe from all the files within the indicated path

Examples


bind_data <- data_binding(path_to_the_projects_folder = system.file("extdata/to_merge/",
                         package = "drugsens"))


Colorblind-safe categorical palette for drugsens plots

Description

An 8-color categorical palette ordered for high contrast and color-vision deficiency (CVD) safety across adjacent levels.

Usage

drugsens_palette

Format

A named character vector of 8 hex color codes: blue, orange, aqua, yellow, magenta, green, violet, red.

Examples

drugsens_palette

Publication-ready ggplot2 theme for drugsens

Description

Applies a clean, warm-neutral background, subtle gridlines, bold facet strips, and legible typography across all drugsens visualizations. Can also be added to custom ggplot2 plots.

Usage

drugsens_theme(base_size = 14)

Arguments

base_size

Base font size in pts. Defaults to 14.

Value

A ggplot2 theme object.

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  drugsens_theme()

Generate the groovy script used for the analysis

Description

Generate a useful script to consistently save the output data from QuPath in .csv format following the naming conventions followed during the package development.

Usage

generate_qupath_script(output_dir = NULL)

Arguments

output_dir

Directory where the script should be saved. If NULL, uses tempdir()

Value

Invisibly returns the path to the generated script file.

Examples


  # Generate script in a temporary directory
  generate_qupath_script()

  # Generate script in a specific directory
  output_dir <- tempdir()
  generate_qupath_script(output_dir = output_dir)


Plot some QC plots to define that everything ran correctly

Description

Plot data to visualize immediate trends. This function expects data that has been processed through make_count_dataframe() and change_data_format_to_longer() to ensure the correct data structure for plotting.

Usage

get_QC_plots(
  .data,
  patient_column_name = "PID",
  colors = unname(drugsens_palette),
  save_plots = FALSE,
  folder_name = NULL,
  x_plot_var = "Treatment_complete",
  isolate_a_specific_patient = NULL,
  compare_to_control = FALSE,
  control_treatment_name = "Control",
  stat_method = c("wilcox", "t.test"),
  p_adjust_method = "BH",
  pvalue_label = c("p.adj.signif", "p.signif", "p.adj.format", "p.format")
)

Arguments

.data

The preprocessed data (after running make_count_dataframe() and change_data_format_to_longer()) merged data.frame that should be visualized

patient_column_name

The PID's column name in the merged data.frame (defaults to "PID")

colors

A character vector of colors to supply to personalize the plot, defaults to unname(drugsens_palette) (8-color CVD-safe palette).

save_plots

A Boolean value indicating if the plots should be saved or not (default is FALSE)

folder_name

Directory where plots are saved when save_plots = TRUE. Defaults to file.path(tempdir(), "figures") when NULL.

x_plot_var

A string indicating the treatment's full name for the QC plots (default is "Treatment_complete")

isolate_a_specific_patient

A string indicating the patient name to isolate for single plot case (default is NULL)

compare_to_control

Logical, whether to compute and display statistical comparisons against control_treatment_name within each marker facet. Defaults to FALSE.

control_treatment_name

Value in x_plot_var identifying the control/vehicle group when compare_to_control = TRUE. Defaults to "Control".

stat_method

Statistical test used when compare_to_control = TRUE: "wilcox" (default) or "t.test".

p_adjust_method

Multiple-testing correction method passed to stats::p.adjust() across treatments within each marker facet. Supports "BH" (Benjamini-Hochberg FDR, default), "bonferroni", "holm", "fdr", "hochberg", "hommel", "BY", or "none".

pvalue_label

Format for p-value annotations: "p.adj.signif" (adjusted *, ⁠**⁠, ⁠***⁠, ns, default), "p.signif" (unadjusted), "p.adj.format", or "p.format".

Value

When save_plots = FALSE, returns a ggplot object (if a single patient is plotted) or a named list of ggplot objects (keyed by patient ID). When save_plots = TRUE, invisibly returns the named list of ggplot objects after saving PDFs to disk.

Examples


# First process example data
example_path <- system.file("extdata/to_merge/", package = "drugsens")
raw_data <- data_binding(path_to_the_projects_folder = example_path)
count_data <- make_count_dataframe(raw_data)
processed_data <- change_data_format_to_longer(count_data)

# Create and save plots to temporary directory
temp_dir <- file.path(tempdir(), "qc_plots")
get_QC_plots(
  processed_data,
  save_plots = TRUE,
  folder_name = temp_dir
)

# Create plots for a specific patient
get_QC_plots(
  processed_data,
  isolate_a_specific_patient = "B39",
  save_plots = TRUE,
  folder_name = temp_dir
)


Plot QC plots and calculate statistics for bound data

Description

This function creates quality control plots and calculates basic statistics for microscopy data. The plots provide visual insights into marker expression patterns and data quality.

Usage

get_QC_plots_parsed_merged_data(
  .data,
  list_of_columns_to_plot = NULL,
  save_plots = FALSE,
  saving_plots_folder = NULL,
  save_plots_in_patient_specific_subfolders = TRUE,
  fill_color_variable = NULL,
  PID_column_name = "PID",
  isolate_specific_drug = NULL,
  isolate_specific_patient = NULL,
  drug_column_name = "Treatment",
  save_list_of_plots = TRUE,
  p_height = 10,
  p_width = 10,
  verbose = TRUE
)

Arguments

.data

The preprocessed data frame to analyze (either raw bound data from data_binding() or long-format count data from change_data_format_to_longer()).

list_of_columns_to_plot

Columns to include in plots. If NULL, all numeric columns are used.

save_plots

Logical, whether to save plots to files. Defaults to FALSE.

saving_plots_folder

Directory for saving plots. If NULL and save_plots=TRUE, uses a subdirectory of tempdir().

save_plots_in_patient_specific_subfolders

Logical, whether to create patient subdirectories. Defaults to TRUE.

fill_color_variable

Variable name for plot color filling

PID_column_name

Column name for patient IDs. Defaults to "PID".

isolate_specific_drug

Drug name to subset data

isolate_specific_patient

Patient ID to subset data

drug_column_name

Column name for drug information. Defaults to "Treatment".

save_list_of_plots

Logical, whether to return list of plot objects. Defaults to TRUE.

p_height

Plot height in inches. Defaults to 10.

p_width

Plot width in inches. Defaults to 10.

verbose

Logical, whether to show progress messages. Defaults to TRUE.

Value

If save_list_of_plots=TRUE, returns a named list of ggplot objects. Otherwise returns invisible(NULL).

Examples


# First load and process example data
example_path <- system.file("extdata/to_merge/", package = "drugsens")
raw_data <- data_binding(path_to_the_projects_folder = example_path)
count_data <- make_count_dataframe(raw_data)
processed_data <- change_data_format_to_longer(count_data)

# Basic usage - create plots for all patients
plots <- get_QC_plots_parsed_merged_data(processed_data)

# Save plots to a temporary directory
temp_dir <- file.path(tempdir(), "qc_plots")
plots <- get_QC_plots_parsed_merged_data(
  processed_data,
  save_plots = TRUE,
  saving_plots_folder = temp_dir
)

# Focus on a specific patient
plots <- get_QC_plots_parsed_merged_data(
  processed_data,
  isolate_specific_patient = "B39"
)

# Color plots by tissue type
plots <- get_QC_plots_parsed_merged_data(
  processed_data,
  fill_color_variable = "Tissue"
)


Count the main marker expression

Description

This function counts every single marker present in the "Name" column of the data.frame and return a dataframe of the counts per marker

Usage

make_count_dataframe(
  .data,
  unique_name_row_identifier = "filter_image",
  name_of_the_markers_column = "Name"
)

Arguments

.data

The dataframe that is coming from the processing of the microscopy data

unique_name_row_identifier

The name of the column of the .data where the unique name can be used to counts (it defaults to "filter_image")

name_of_the_markers_column

The name of the column of the .data where the marker names are expressed (ie E-Caderin, DAPI), "Defaults as Name"

Value

A dataframe/tibble.

Examples


# First load example data
pkg_path <- system.file("extdata/to_merge/", package = "drugsens")
bind_data <- data_binding(
  path_to_the_projects_folder = pkg_path,
  files_extension_to_look_for = "csv"
)

# Process the data
counts_dataframe <- make_count_dataframe(bind_data)

# Convert to plotting format
plotting_ready_dataframe <- change_data_format_to_longer(counts_dataframe)



# Example with custom parameters
make_count_dataframe(
  bind_data,
  name_of_the_markers_column = "Name",
  unique_name_row_identifier = "filter_image"
)


Generates and loads a marker-relabeling configuration file

Description

Generates a config_drugsens.txt file in tempdir() (or in forcePath when specified) defining list_of_relabeling, evaluates it into an isolated local environment, and stores the relabeling map inside the package's internal configuration environment without modifying .GlobalEnv.

Usage

make_run_config(overwrite_config = FALSE, forcePath = NULL)

Arguments

overwrite_config

Boolean; if TRUE an existing config_drugsens.txt will be overwritten with the default template (default is FALSE).

forcePath

Optional directory path for config_drugsens.txt. Defaults to NULL, which uses tempdir().

Value

Invisibly returns the path to the configuration file.

Examples


# Generate and load config in a temporary directory
make_run_config(forcePath = tempdir())


Normalize marker values to percent of control

Description

Expresses each marker measurement (or a biological target-cell viability / cell-death metric computed from user-selected dead_markers and viable_markers / total_markers) as a percentage of the mean control (untreated/vehicle) value within the same patient. This is the standard first step for building dose response curves and estimating \mathrm{IC}_{50} in drug sensitivity assays, following Labrosse et al. (2024) https://doi.org/10.1016/j.xpro.2024.103274.

When dead_markers (e.g. "cCASP3") and viable_markers (e.g. "EpCAM_E-Cadherin") or total_markers (e.g. c("EpCAM_E-Cadherin", "cCASP3")) are supplied, normalize_to_control() first computes for each well/image:

and then normalizes the chosen response_metric ("viability" or "cell_death") against the matched control_treatment_name group.

Usage

normalize_to_control(
  .data,
  control_treatment_name = "Control",
  treatment_column_name = "Treatment",
  group_by_columns = "PID",
  value_columns = NULL,
  pattern_column_markers = "_ratio_of_total_cells",
  dead_markers = NULL,
  viable_markers = NULL,
  total_markers = NULL,
  response_metric = c("viability", "cell_death"),
  selected_treatments = NULL,
  consensus_only = FALSE
)

Arguments

.data

A data frame in either the wide format returned by make_count_dataframe() or the long format returned by change_data_format_to_longer().

control_treatment_name

Value identifying control/vehicle wells in treatment_column_name. Defaults to "Control".

treatment_column_name

Column holding the treatment label. Defaults to "Treatment".

group_by_columns

Columns that define a comparable batch: the control mean is computed within each combination of these columns. Defaults to "PID".

value_columns

Columns to normalize. If NULL, uses "marker_positivity_ratio" when present (long format), otherwise all columns matching pattern_column_markers (wide format).

pattern_column_markers

Pattern used to auto-detect marker columns in wide format. Defaults to "_ratio_of_total_cells".

dead_markers

Optional character vector of marker name(s) representing dead/dying cells (e.g. "cCASP3" or c("cCASP3", "E-Cadherin and cCASP3")). Matches names with or without the "_ratio_of_total_cells" suffix.

viable_markers

Optional character vector of marker name(s) representing viable target/cancer cells (e.g. "EpCAM_E-Cadherin" or "E-Cadherin"). When multiple viable_markers and dead_markers are supplied, markers are paired positionally if length(viable_markers) == length(dead_markers); otherwise all combinations are evaluated alongside a combined consensus panel.

total_markers

Optional character vector of marker name(s) representing the total target cell population (e.g. c("EpCAM_E-Cadherin", "cCASP3")). If NULL when dead_markers and viable_markers are provided, defaults to unique(c(viable_markers, dead_markers)).

response_metric

Metric to compute and normalize when dead_markers is provided: "viability" (default, 1 - dead / total, which starts at ⁠100%⁠ in control and decreases toward ⁠0%⁠ as cells die) or "cell_death" (dead / total).

selected_treatments

Optional character vector of treatment names to keep (in addition to control_treatment_name). Defaults to NULL (all treatments).

consensus_only

Logical; when multiple viable_markers or dead_markers are supplied and consensus_only = FALSE (the default), normalize_to_control() computes each individual marker pair's readout as well as a combined "Consensus (Combined)" readout across all selected markers. Set consensus_only = TRUE to return only the combined consensus readout.

Value

.data with an added column per normalized value: "<column>_pct_of_control" in wide format, or a single "pct_of_control" column in long format. When dead_markers is supplied, also includes dead_cells_ratio, viable_cells_ratio, total_target_cells_ratio, dead_fraction, viable_fraction, and is_consensus.

Examples

# A patient with a control group and one drug at three doses
df <- data.frame(
  PID = "PID1",
  Treatment = c("Control", "Control", "DrugA", "DrugA", "DrugA"),
  cCASP3_ratio_of_total_cells = c(10, 10, 5, 20, 40)
)
normalize_to_control(df)

Plot dose response curves from normalized data

Description

Plots percent-of-control marker values against drug concentration, the standard dose response view for drug sensitivity assays. Expects data that has already been processed with normalize_to_control(). Supports non-parametric LOESS smoothing (method = "loess"), 4-parameter log-logistic Hill curve fitting (method = "4pl"), or linear trend lines (method = "linear").

Usage

plot_dose_response(
  .data,
  concentration_column_name = "Concentration1",
  treatment_column_name = "Treatment",
  patient_column_name = "PID",
  control_treatment_name = "Control",
  log_scale_x = TRUE,
  method = c("loess", "4pl", "linear"),
  show_ic50 = FALSE,
  dead_markers = NULL,
  viable_markers = NULL,
  total_markers = NULL,
  response_metric = c("viability", "cell_death"),
  selected_treatments = NULL,
  consensus_only = FALSE,
  consensus_dispersion = c("cv", "rcvq", "rcv_mad", "sd", "se", "iqr", "mad", "none"),
  show_cv = TRUE
)

Arguments

.data

Data frame that has been through normalize_to_control() on the long format (must contain "pct_of_control", "marker_positivity", and a concentration column).

concentration_column_name

Column holding the drug concentration. Defaults to "Concentration1".

treatment_column_name

Column holding the treatment label. Defaults to "Treatment".

patient_column_name

Column holding the patient ID. Defaults to "PID".

control_treatment_name

Value identifying control/vehicle wells, excluded from the dose response curve. Defaults to "Control".

log_scale_x

Logical, whether to plot concentration on a log10 axis (the usual view when doses span orders of magnitude). Defaults to TRUE; rows with a non-positive concentration are dropped when TRUE.

method

Curve fitting method: "loess" (default), "4pl" (4-parameter log-logistic Hill model estimated via stats::optim()), or "linear". When "4pl" is used, a data frame of estimated ic50, hill_slope, bottom, and top parameters is attached as attr(plot, "ic50").

show_ic50

Logical; when TRUE and method = "4pl", draws a vertical dashed reference line at the estimated IC50 concentration for each fitted curve. Defaults to FALSE.

dead_markers

Optional character vector of marker name(s) representing dead/dying cells (e.g. "cCASP3"). If provided, normalize_to_control() is called automatically to compute the target cell response before plotting.

viable_markers

Optional character vector of marker name(s) representing viable target/cancer cells (e.g. "EpCAM_E-Cadherin").

total_markers

Optional character vector of marker name(s) representing all target cells (e.g. c("EpCAM_E-Cadherin", "cCASP3")).

response_metric

Metric to compute when dead_markers is supplied: "viability" (default) or "cell_death".

selected_treatments

Optional character vector of drug treatment names to plot (e.g. "Paclitaxel").

consensus_only

Logical; when multiple viable_markers or dead_markers are supplied, FALSE (default) plots individual panels for each marker pair plus a "Consensus Viability (Combined)" panel and attaches the consensus IC50 table as attr(plot, "consensus_ic50"). Set to TRUE to plot only the combined consensus panel.

consensus_dispersion

Coefficient of variation or dispersion metric to compute per point on the Consensus panel (attached as attr(plot, "consensus_cv") and plotted as error bars / point labels): "cv" (standard coefficient of variation 100 * SD / Mean, default), "rcvq" (robust quartile CV 100 * 0.75 * IQR / Median), "rcv_mad" (robust MAD CV 100 * MAD / Median), "sd" (standard deviation), "se" (standard error), "iqr" (interquartile range), "mad" (median absolute deviation), or "none". Note that rcvq and rcv_mad require multiple marker pairs/replicates per dose (most informative when >= 3 values per dose are available).

show_cv

Logical; whether to print the per-point CV (or selected consensus_dispersion value) on the Consensus panel. Defaults to TRUE.

Value

A ggplot object (with attr(plot, "ic50"), attr(plot, "consensus_ic50"), and attr(plot, "consensus_cv") populated).

Examples

df <- data.frame(
  PID = rep("PID1", 10),
  Treatment = c("Control", "Control", rep("DrugA", 8)),
  Concentration1 = c(NA, NA, "0.1", "0.1", "1", "1", "10", "10", "100", "100"),
  marker_positivity = "Viability",
  marker_positivity_ratio = c(10, 10, 9.5, 9.2, 7.0, 6.8, 3.0, 2.8, 1.0, 0.9)
)
normalized <- normalize_to_control(df)
plot_dose_response(normalized)
plot_dose_response(normalized, method = "4pl", show_ic50 = TRUE)

Plot a treatment by concentration heatmap of percent-of-control values

Description

Summarizes normalize_to_control() output into a treatment x concentration heatmap of the mean percent-of-control value, a compact overview of an entire dose response experiment across many drugs at once.

Usage

plot_dose_response_heatmap(
  .data,
  concentration_column_name = "Concentration1",
  treatment_column_name = "Treatment",
  control_treatment_name = "Control",
  show_values = FALSE
)

Arguments

.data

Data frame that has been through normalize_to_control() on the long format (must contain "pct_of_control", "marker_positivity", a concentration column, and a treatment column).

concentration_column_name

Column holding the drug concentration. Defaults to "Concentration1".

treatment_column_name

Column holding the treatment label. Defaults to "Treatment".

control_treatment_name

Value identifying control/vehicle wells, excluded from the heatmap. Defaults to "Control".

show_values

Logical; whether to print the numeric mean ⁠% of control⁠ inside each heatmap tile. Defaults to FALSE.

Value

A ggplot object.

Examples

df <- data.frame(
  PID = "PID1",
  Treatment = c("Control", "Control", rep(c("DrugA", "DrugB"), each = 3)),
  Concentration1 = c(NA, NA, "1", "10", "100", "1", "10", "100"),
  marker_positivity = "cCASP3",
  marker_positivity_ratio = c(10, 10, 8, 6, 4, 12, 14, 16)
)
normalized <- normalize_to_control(df)
plot_dose_response_heatmap(normalized)

Plot the raw values next to the normalized values, before and after

Description

Shows the raw marker ratio (before) side by side with the percent-of-control value (after normalize_to_control()), one pair of panels per marker, so you can see at a glance what control normalization did to the data.

Usage

plot_normalization_before_after(.data, treatment_column_name = "Treatment")

Arguments

.data

Data frame that has been through normalize_to_control() on the long format (must contain "marker_positivity_ratio", "pct_of_control", "marker_positivity" and a treatment column).

treatment_column_name

Column holding the treatment label. Defaults to "Treatment".

Value

A ggplot object.

Examples

df <- data.frame(
  PID = "PID1",
  Treatment = c("Control", "Control", "DrugA", "DrugA", "DrugB", "DrugB"),
  marker_positivity = "cCASP3",
  marker_positivity_ratio = c(10, 12, 4, 6, 18, 20)
)
normalized <- normalize_to_control(df)
plot_normalization_before_after(normalized)

Plot a patient by treatment heatmap of percent-of-control values

Description

Summarizes normalize_to_control() output into a patient x treatment heatmap of the mean percent-of-control value (averaged across concentrations), a cohort-level view of how every patient responded to every drug in the panel.

Usage

plot_patient_heatmap(
  .data,
  patient_column_name = "PID",
  treatment_column_name = "Treatment",
  control_treatment_name = "Control",
  show_values = FALSE,
  compare_to_control = FALSE,
  stat_method = c("wilcox", "t.test"),
  p_adjust_method = "BH",
  pvalue_label = c("p.adj.signif", "p.signif", "p.adj.format", "p.format")
)

Arguments

.data

Data frame that has been through normalize_to_control() on the long format (must contain "pct_of_control", "marker_positivity", a patient column and a treatment column).

patient_column_name

Column holding the patient ID. Defaults to "PID".

treatment_column_name

Column holding the treatment label. Defaults to "Treatment".

control_treatment_name

Value identifying control/vehicle wells, excluded from the heatmap. Defaults to "Control".

show_values

Logical; whether to print the numeric mean ⁠% of control⁠ inside each heatmap tile. Defaults to FALSE.

compare_to_control

Logical; whether to compute and annotate p-values comparing each treatment against control_treatment_name per patient and marker facet. Defaults to FALSE.

stat_method

Statistical test used when compare_to_control = TRUE: "wilcox" (default) or "t.test".

p_adjust_method

Multiple-testing correction method passed to stats::p.adjust() across treatments within each patient and marker facet. Supports "BH" (default), "bonferroni", "holm", "fdr", "hochberg", "hommel", "BY", or "none".

pvalue_label

Format for p-value annotations: "p.adj.signif" (adjusted *, ⁠**⁠, ⁠***⁠, ns, default), "p.signif" (unadjusted), "p.adj.format", or "p.format".

Details

When multiple drug concentrations or imaged fields of view are present per patient, compare_to_control = TRUE pools observations across doses and fields of view within each patient and treatment against control_treatment_name. For dose-specific tests, filter .data to a single concentration beforehand or use get_QC_plots(..., x_plot_var = "Treatment_complete", compare_to_control = TRUE).

Value

A ggplot object (with attr(plot, "stats") populated when compare_to_control = TRUE).

Examples

df <- data.frame(
  PID = rep(c("PID1", "PID2"), each = 4),
  Treatment = rep(c("Control", "DrugA"), 4),
  marker_positivity = "cCASP3",
  marker_positivity_ratio = c(10, 5, 10, 8, 12, 4, 12, 6)
)
normalized <- normalize_to_control(df)
plot_patient_heatmap(normalized)

Plot a ranked summary of mean percent-of-control by treatment

Description

Summarizes normalize_to_control() output into one bar per treatment: the mean percent-of-control value across all concentrations and replicates, with a standard error bar, ranked from strongest to weakest effect. A quick way to rank an entire drug panel by response.

Usage

plot_treatment_summary(
  .data,
  treatment_column_name = "Treatment",
  control_treatment_name = "Control",
  compare_to_control = FALSE,
  stat_method = c("wilcox", "t.test"),
  p_adjust_method = "BH",
  pvalue_label = c("p.adj.signif", "p.signif", "p.adj.format", "p.format")
)

Arguments

.data

Data frame that has been through normalize_to_control() on the long format (must contain "pct_of_control", "marker_positivity" and a treatment column).

treatment_column_name

Column holding the treatment label. Defaults to "Treatment".

control_treatment_name

Value identifying control/vehicle wells, excluded from the summary. Defaults to "Control".

compare_to_control

Logical; whether to compute and annotate p-values comparing each treatment against control_treatment_name per marker facet. Defaults to FALSE.

stat_method

Statistical test used when compare_to_control = TRUE: "wilcox" (default) or "t.test".

p_adjust_method

Multiple-testing correction method passed to stats::p.adjust() across treatments within each marker facet. Supports "BH" (Benjamini-Hochberg FDR, default), "bonferroni", "holm", "fdr", "hochberg", "hommel", "BY", or "none".

pvalue_label

Format for p-value annotations: "p.adj.signif" (adjusted *, ⁠**⁠, ⁠***⁠, ns, default), "p.signif" (unadjusted), "p.adj.format", or "p.format".

Details

When multiple drug concentrations or imaged fields of view are present in .data, compare_to_control = TRUE pools all normalized observations for each treatment against control_treatment_name to test for an overall treatment effect across the tested condition. To test specific concentrations individually without pooling across doses, subset .data to a single concentration first or use get_QC_plots(..., x_plot_var = "Treatment_complete", compare_to_control = TRUE).

Value

A ggplot object (with attr(plot, "stats") populated when compare_to_control = TRUE).

Examples

df <- data.frame(
  PID = "PID1",
  Treatment = c("Control", "Control", "DrugA", "DrugA", "DrugB", "DrugB"),
  marker_positivity = "cCASP3",
  marker_positivity_ratio = c(10, 10, 4, 6, 14, 16)
)
normalized <- normalize_to_control(df)
plot_treatment_summary(normalized)

Process a Single File

Description

This function returns a processed single file

Usage

process_file(
  file_path,
  extension,
  relabeling_map = .drugsens_env$list_of_relabeling
)

Arguments

file_path

Path to the file

extension

String File extension to filter

relabeling_map

Named list mapping raw marker names to standardized names

Value

dataframe


Parse image filenames to extract metadata

Description

This function will parse the data from the Image name and will return the metadata there contained The metadata will be then associated to the count file as well

Usage

string_parsing(.data)

Arguments

.data

dataframe with parsed metadata

Value

A dataframe/tibble.

Examples

# Basic example with sample data
input_data <- data.frame(
  Image = "B516_Ascites_2023-11-25_DOC2020-12-14_dmso_rep_Ecad_cCasp3_(series 01).tif"
)
test <- drugsens::string_parsing(input_data)


# Example with actual data processing
data.parsed <- string_parsing(input_data)


Internal utility functions for file handling

Description

This file contains internal utility functions for file handling and processing

Usage

list_all_files(define_path, extension, recursive_search)

Examples


# Load example data from package
bind_data <- data_binding(
  path_to_the_projects_folder = system.file("extdata/to_merge/", package = "drugsens")
)