QuPath Setup and Filename Metadata Conventions

Overview

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:

  1. Generating the QuPath Groovy export script (generate_qupath_script()).
  2. Structuring image filenames for single drugs, drug combinations, and vehicle controls.
  3. Testing filename metadata extraction directly in R (string_parsing()).
  4. Configuring cell marker relabeling (make_run_config()).

1. Generating and Running the QuPath Groovy Scripts

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.class

How to Add and Run Scripts in QuPath (v0.4 / v0.5+)

  1. Open the Script Editor: In QuPath’s top menu bar, select Automate \(\rightarrow\) Show script editor (Ctrl + [ on Windows/Linux, Cmd + [ on macOS).
  2. Step A — Cell Detection & Classification Script:
    • Click 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 it across all images in your project via Run \(\rightarrow\) Run for project in the Script Editor menu.
  3. Step B — Measurement Export Script (script_for_qupath.txt):
    • In the Script Editor, click 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).
    • Replace the <...> placeholders in outputPath with your sample metadata.
    • Click 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.

Required Columns in QuPath Export

Make sure the columnsToInclude array in the Groovy script always starts with "Image" and "Name":


2. Filename Naming Convention

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).

3. Examples: Single Drugs, Combinations, and Controls

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():

Single-Drug Treatment

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    Niraparib1000nM

Two-Drug Combination (CamelCase 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>:

combo_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-10nM

Vehicle / Untreated Controls

When 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            Control

4. Customizing Marker Relabeling (make_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:

  1. Run make_run_config(forcePath = "path/to/your/project").
  2. Edit config_drugsens.txt in that directory to map your QuPath class names to concise marker names.
  3. Pass 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)