QuPath Setup and Filename Metadata Conventions
Source:vignettes/qupath-and-metadata.Rmd
qupath-and-metadata.RmdOverview
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:
- Generating the QuPath Groovy export script
(
generate_qupath_script()). - Structuring image filenames for single drugs, drug combinations, and vehicle controls.
- Testing filename metadata extraction directly in R
(
string_parsing()). - 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.classHow to Add and Run Scripts in QuPath (v0.4 / v0.5+)
-
Open the Script Editor: In QuPath’s top menu bar,
select
AutomateShow script editor(Ctrl + [on Windows/Linux,Cmd + [on macOS). -
Step A — Cell Detection & Classification
Script:
- Click
FileNewin the Script Editor and paste the cell detection & object classification script from the package README (or save it in your project’sscripts/folder so it appears underAutomateProject scripts). - Run it across all images in your project via
RunRun for projectin the Script Editor menu.
- Click
-
Step B — Measurement Export Script
(
script_for_qupath.txt):- In the Script Editor, click
FileOpen...and select thescript_for_qupath.txtfile generated bygenerate_qupath_script()(or paste it into a new tab viaFileNew). - Replace the
<...>placeholders inoutputPathwith your sample metadata. - Click
RunRun(Ctrl + R/Cmd + R). BecauseMeasurementExporteralready loops overgetProject().getImageList(), a singleRunRunexports all project images into your.csvfile.
- In the Script Editor, click
Required Columns in QuPath Export
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)), whichstring_parsing()uses to extract experimental metadata. -
Name: The QuPath object classification assigned to each segmented cell (for example,"PathCellObject","cCasp3","EpCAM_E-Cadherin").
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 Niraparib1000nMTwo-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>:
- Field 6 =
Concentration1(belongs to the first drug) - Field 7 =
ConcentrationUnits1 - Field 8 =
Concentration2(belongs to the second drug) - Field 9 =
ConcentrationUnits2
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-10nMVehicle / 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 Control4. 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:
- Run
make_run_config(forcePath = "path/to/your/project"). - Edit
config_drugsens.txtin that directory to map your QuPath class names to concise marker names. - Pass
forcePath = "path/to/your/project"todata_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)