---
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
<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>`:

```{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 `<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`

```{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)
```
