A key strength of drugsens is that it eliminates manual
spreadsheet curation: experimental metadata (patient ID, tissue origin,
experiment date, sample collection date, single or combination drug
names, concentrations, units, and replicate status) is automatically
parsed from the Image column exported by
QuPath.
This guide walks through:
generate_qupath_script()).string_parsing()).make_run_config()).Run generate_qupath_script() in R to create a
ready-to-use Groovy export template
(script_for_qupath.txt):
library(drugsens)
out_dir <- tempdir()
generate_qupath_script(output_dir = out_dir)
script_lines <- readLines(file.path(out_dir, "script_for_qupath.txt"))
cat( paste(head(script_lines, 25), collapse = "\n") )
#>
#> //This code script was tested with QuPath 4
#>
#> import qupath.lib.gui.tools.MeasurementExporter
#> import qupath.lib.objects.PathCellObject
#> import qupath.lib.objects.PathDetectionObject
#>
#> // Get the list of all images in the current project
#> def project = getProject()
#> def imagesToExport = project.getImageList()
#>
#> // Separate each measurement value in the output file with a tab (" ")
#> def separator = ","
#>
#> // Choose the columns that will be included in the export
#> // Note: if columnsToInclude is empty, all columns will be included
#> def columnsToInclude = new String[]{"Image", "Name", "Class","Centroid X um","Centroid Y um","Nucleus: Area", "Nucleus: DAPI mean","Nucleus: E-Cadherin mean", "Nucleus: Cleaved caspase 3 mean", "Cell: Area","Cell: E-Cadherin mean", "Cell: Cleaved caspase 3 mean","Cytoplasm: E-Cadherin mean","Cytoplasm: Cleaved caspase 3 mean","Nucleus/Cell area ratio"}
#>
#> // Choose the type of objects that the export will process
#> // Other possibilities include:
#> // 1. PathAnnotationObject
#> // 2. PathDetectionObject
#> // 3. PathRootObject
#> // Note: import statements should then be modified accordingly
#> def exportType = PathCellObject.classAutomate \(\rightarrow\)
Show script editor (Ctrl + [ on
Windows/Linux, Cmd + [ on macOS).File \(\rightarrow\) New in
the Script Editor and paste the cell detection & object
classification script from the package
README (or save it in your project’s scripts/ folder so
it appears under Automate \(\rightarrow\)
Project scripts).Run \(\rightarrow\)
Run for project in the Script Editor menu.script_for_qupath.txt):
File \(\rightarrow\) Open...
and select the script_for_qupath.txt file generated by
generate_qupath_script() (or paste it into a new tab via
File \(\rightarrow\)
New).<...> placeholders in
outputPath with your sample metadata.Run \(\rightarrow\) Run
(Ctrl + R / Cmd + R). Because
MeasurementExporter already loops over
getProject().getImageList(), a single
Run \(\rightarrow\) Run
exports all project images into your .csv file.Make sure the columnsToInclude array in the Groovy
script always starts with "Image" and
"Name":
Image: The full image name (including the series
number, e.g., (series 01)), which
string_parsing() uses to extract experimental
metadata.Name: The QuPath object classification assigned to each
segmented cell (for example, "PathCellObject",
"cCasp3", "EpCAM_E-Cadherin").string_parsing() splits the Image string on
underscores (_) and applies pattern matching for dates,
concentrations, and series numbers. Follow this template when naming
your microscopy files or QuPath project entries:
<PID>_<TISSUE>_<EXP_DATE>_DOC<SAMPLE_DATE>_<TREATMENT>_<CONC1>_<UNIT1>_<REP>_<MARKERS>_(series XX).tif
| Position / Pattern | Extracted Column | Description & Formatting Rules |
|---|---|---|
Field 1 (<PID>) |
PID |
Patient or model identifier (e.g., B39,
A8759). Avoid underscores inside the ID. |
Field 2 (<TISSUE>) |
Tissue |
Tissue source (e.g., Ascites,
p.wash, Spleen). |
YYYY-MM-DD or YYYY.MM.DD |
Date1 |
Date of imaging/experiment (e.g.,
2024-02-13 or 2023.11.10). |
DOC<YYYY-MM-DD> |
DOC |
Date of sample collection prefixed by DOC
(e.g., DOC2023-10-05). |
Field 5 (<TREATMENT>) |
Treatment |
Drug name, combination name, or control label
(Control, dmso, ctrl). |
<CONC1>_<UNIT1> |
Concentration1,
ConcentrationUnits1 |
Numeric dose followed by _ and unit
(uM, nM, mM,
pM). |
<CONC2>_<UNIT2> |
Concentration2,
ConcentrationUnits2 |
Second drug dose and unit (used only for two-drug combinations). |
Rep / Replica |
ReplicaOrNot |
Any token matching Rep or
Replica (case-insensitive) marks the row as
"Replica". |
series XX |
Image_number |
Confocal z-stack or field-of-view series identifier
(e.g., series 01). |
You can verify how drugsens will parse your filenames
before running a full batch import by passing a small test
data.frame to string_parsing():
For a single drug, use a single capitalized word (or lowercase) in
Field 5 followed by <CONC>_<UNIT>:
single_df <- data.frame(
Image = "B39_Ascites_2024-03-15_DOC2024-03-01_Niraparib_1000_nM_Rep_EpCAM_Ecad_cCasp3_(series 01).tif"
)
parsed_single <- string_parsing(single_df)
parsed_single[, c("PID", "Tissue", "Date1", "DOC", "Treatment",
"Concentration1", "ConcentrationUnits1", "Treatment_complete")]
#> PID Tissue Date1 DOC Treatment Concentration1
#> 1 B39 Ascites 2024-03-15 2024-03-01 Niraparib 1000
#> ConcentrationUnits1 Treatment_complete
#> 1 nM Niraparib1000nMCamelCase Convention)When testing a combination of two drugs, concatenate both drug names
in CamelCase in Field 5 (exactly two or more uppercase
letters, such as CarboplatinPaclitaxel or
GentamicinePaclitaxel), followed by
<CONC1>_<UNIT1>_<CONC2>_<UNIT2>:
Concentration1 (belongs to the first
drug)ConcentrationUnits1Concentration2 (belongs to the second
drug)ConcentrationUnits2combo_df <- data.frame(
Image = "B38_Ascites_2024-03-15_DOC2024-03-01_CarboplatinPaclitaxel_100_uM_10_nM_Rep_EpCAM_cCasp3_(series 02).tif"
)
parsed_combo <- string_parsing(combo_df)
parsed_combo[, c("PID", "Treatment", "Concentration1", "ConcentrationUnits1",
"Concentration2", "ConcentrationUnits2", "Treatment_complete")]
#> PID Treatment Concentration1 ConcentrationUnits1 Concentration2
#> 1 B38 CarboplatinPaclitaxel 100 uM 10
#> ConcentrationUnits2 Treatment_complete
#> 1 nM CarboplatinPaclitaxel100uM-10nMWhen Field 5 is "Control", "ctrl",
"dmso", or "original" (case-insensitive),
Treatment_complete is kept clean without appending
NA concentration strings:
ctrl_df <- data.frame(
Image = "B516_Ascites_2023-11-25_DOC2020-12-14_Control_rep_Ecad_cCasp3_(series 01).tif"
)
parsed_ctrl <- string_parsing(ctrl_df)
parsed_ctrl[, c("PID", "Tissue", "Treatment", "ReplicaOrNot", "Treatment_complete")]
#> PID Tissue Treatment ReplicaOrNot Treatment_complete
#> 1 B516 Ascites Control Replica Controlmake_run_config())QuPath classifiers often export raw object class names such as
"PathCellObject" (for cells positive only for nuclear DAPI)
or composite classifier strings like
"E-Cadherin: cCASP3".
make_run_config() creates a
config_drugsens.txt file in tempdir() (or
forcePath when provided) defining
list_of_relabeling, a named list mapping raw QuPath
Name strings to clean marker names, and loads it into the
package’s internal configuration environment without modifying
.GlobalEnv:
cfg_dir <- tempdir()
make_run_config(overwrite_config = TRUE, forcePath = cfg_dir)
cat(readLines(file.path(cfg_dir, "config_drugsens.txt")), sep = "\n")
#> # List of markers to relabel
#> list_of_relabeling =
#> list(
#> "PathCellObject" = "onlyDAPIPositve",
#> "cCasp3" = "cCASP3",
#> "E-Cadherin: cCASP3" = "E-Cadherin and cCASP3",
#> "EpCAM_E-Cadherin" = "E-Cadherin",
#> "EpCAM_E-Cadherin and cCASP3" = "E-Cadherin and cCASP3"
#> )To customize marker names for your own staining panel:
make_run_config(forcePath = "path/to/your/project").config_drugsens.txt in that directory to map your
QuPath class names to concise marker names.forcePath = "path/to/your/project" to
data_binding() so your custom relabeling map is applied
automatically as files are imported:# 1. Create a dedicated config directory and write a custom config_drugsens.txt
custom_cfg_dir <- file.path(tempdir(), "custom_project_config")
dir.create(custom_cfg_dir, showWarnings = FALSE, recursive = TRUE)
writeLines(
c(
"# Custom marker relabeling map",
"list_of_relabeling = list(",
' "PathCellObject" = "Stromal_DAPI_only",',
' "EpCAM_E-Cadherin: cCASP3" = "Early_Apoptotic_Tumor",',
' "EpCAM_E-Cadherin" = "Viable_Tumor",',
' "cCASP3" = "Late_Apoptotic"',
")"
),
con = file.path(custom_cfg_dir, "config_drugsens.txt")
)
# 2. Pass forcePath to data_binding() so your custom config is loaded automatically
example_dir <- system.file("extdata/to_merge/", package = "drugsens")
custom_bound <- data_binding(
path_to_the_projects_folder = example_dir,
files_extension_to_look_for = "csv",
forcePath = custom_cfg_dir
)
# 3. Verify that the custom marker names are now in the Name column
table(custom_bound$Name)
#>
#> Early_Apoptotic_Tumor Late_Apoptotic Stromal_DAPI_only
#> 1720 2659 3664
#> Viable_Tumor
#> 5247
# Restore default config for subsequent sessions
make_run_config(overwrite_config = TRUE)