--- title: "QuPath Setup and Filename Metadata Conventions" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{QuPath Setup and Filename Metadata Conventions} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", message = FALSE, warning = FALSE ) ``` ## 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`): ```{r generate-script} 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") ) ``` ### 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](https://github.com/flalom/drugsens#qupath-scripts) (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"`: - `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"`). --- ## 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: ```text ___DOC______(series XX).tif ``` | Position / Pattern | Extracted Column | Description & Formatting Rules | | :--- | :--- | :--- | | Field 1 (``) | `PID` | Patient or model identifier (e.g., `B39`, `A8759`). Avoid underscores inside the ID. | | Field 2 (``) | `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` | `DOC` | Date of sample collection prefixed by `DOC` (e.g., `DOC2023-10-05`). | | Field 5 (``) | `Treatment` | Drug name, combination name, or control label (`Control`, `dmso`, `ctrl`). | | `_` | `Concentration1`, `ConcentrationUnits1` | Numeric dose followed by `_` and unit (`uM`, `nM`, `mM`, `pM`). | | `_` | `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 `_`: ```{r single-drug} 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")] ``` ### 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 `___`: - Field 6 = `Concentration1` (belongs to the first drug) - Field 7 = `ConcentrationUnits1` - Field 8 = `Concentration2` (belongs to the second drug) - Field 9 = `ConcentrationUnits2` ```{r combo-drug} 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")] ``` ### Vehicle / Untreated Controls When Field 5 is `"Control"`, `"ctrl"`, `"dmso"`, or `"original"` (case-insensitive), `Treatment_complete` is kept clean without appending `NA` concentration strings: ```{r control-drug} 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")] ``` --- ## 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`: ```{r config-example} cfg_dir <- tempdir() make_run_config(overwrite_config = TRUE, forcePath = cfg_dir) cat(readLines(file.path(cfg_dir, "config_drugsens.txt")), sep = "\n") ``` 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: ```{r custom-config-binding} # 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) # Restore default config for subsequent sessions make_run_config(overwrite_config = TRUE) ```