| 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 |
| 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 ( |
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 |
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 |
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
|
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 |
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 |
Value in |
stat_method |
Statistical test used when |
p_adjust_method |
Multiple-testing correction method passed to |
pvalue_label |
Format for p-value annotations: |
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 |
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 |
forcePath |
Optional directory path for |
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:
-
dead_cells_ratio: sum ofdead_markers -
total_target_cells_ratio: sum oftotal_markers(living target cells + dying cells, excluding unrelated DAPI-only stromal cells) -
viable_cells_ratio:total_target_cells_ratio - dead_cells_ratio -
dead_fraction:dead_cells_ratio / total_target_cells_ratio -
viable_fraction:1 - dead_fraction(viable_cells_ratio / total_target_cells_ratio)
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
|
control_treatment_name |
Value identifying control/vehicle wells in
|
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 |
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. |
viable_markers |
Optional character vector of marker name(s) representing
viable target/cancer cells (e.g. |
total_markers |
Optional character vector of marker name(s) representing
the total target cell population (e.g. |
response_metric |
Metric to compute and normalize when |
selected_treatments |
Optional character vector of treatment names to keep
(in addition to |
consensus_only |
Logical; when multiple |
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 |
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: |
show_ic50 |
Logical; when |
dead_markers |
Optional character vector of marker name(s) representing
dead/dying cells (e.g. |
viable_markers |
Optional character vector of marker name(s) representing
viable target/cancer cells (e.g. |
total_markers |
Optional character vector of marker name(s) representing
all target cells (e.g. |
response_metric |
Metric to compute when |
selected_treatments |
Optional character vector of drug treatment names to
plot (e.g. |
consensus_only |
Logical; when multiple |
consensus_dispersion |
Coefficient of variation or dispersion metric to
compute per point on the Consensus panel (attached as |
show_cv |
Logical; whether to print the per-point CV (or selected
|
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 |
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 |
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 |
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 |
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 |
compare_to_control |
Logical; whether to compute and annotate p-values
comparing each treatment against |
stat_method |
Statistical test used when |
p_adjust_method |
Multiple-testing correction method passed to
|
pvalue_label |
Format for p-value annotations: |
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 |
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 |
stat_method |
Statistical test used when |
p_adjust_method |
Multiple-testing correction method passed to
|
pvalue_label |
Format for p-value annotations: |
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")
)