--- name: admiral-adrs description: > Derives an ADaM Tumor Response Analysis Dataset (ADRS) using the {admiral} and {admiralonco} R packages. Use when a user needs to create ADRS from SDTM RS domain data, derive RECIST 1.1 response parameters (overall response, confirmed response, best overall response, clinical benefit), or generate QC-ready R code following CDISC ADaM and oncology conventions. Requires SDTM RS input data, ADSL with randomization and treatment dates, and an ADaM ADRS specification. license: MIT metadata: author: Navitas Data Sciences version: "0.1" pharmaverse: "true" parent: admiral compatibility: > Requires R with admiral, admiralonco, dplyr, lubridate, and pharmaversesdtm installed. Requires a completed ADSL dataset with RANDDT and TRTSDT. Designed for use in a GxP-compliant oncology trial environment with access to SDTM RS domain data and an ADaM ADRS specification. ---

# admiral-adrs

> Shared conventions (library setup, pipe style, date rules, flag convention, > `# REVIEW:` annotations, `stopifnot()` patterns) are defined in the parent > [`../SKILL.md`](../SKILL.md). The workflow below is ADRS-specific.

Derives a CDISC-conformant ADRS tumor response dataset using {admiral} and {admiralonco}. Outputs executable, QC-ready R code covering RECIST 1.1 response parameters with full derivation traceability.

The primary design challenge in ADRS is the **confirmation logic**: CR and PR must be supported by a second qualifying assessment ≥28 days later. Best Overall Response (BOR) follows a strict hierarchy (CR > PR > SD > NON-CR/NON-PD > PD > NE) and handles NE propagation in ways that manual `case_when()` or `slice_min()` cannot replicate correctly. Always use `admiralonco` functions — never manual derivations.

---

## Inputs

Before generating code, confirm the following are available or explicitly noted as absent:

| Input | Required | Notes | |---|---|---| | RS | Yes | One record per tumor assessment per subject; RSSTRESC contains the response category (CR/PR/SD/PD/NE) | | ADSL | Yes | Provides TRTSDT, RANDDT, treatment labels, population flags | | ADaM ADRS spec | Yes | Parameter list, PARAMCD/PARAM mapping, confirmation window, clinical benefit definition | | Study context | Yes | RECIST version (1.0 vs 1.1), assessor (investigator vs BICR), confirmation window, clinical benefit anchor date |

If RS or ADSL are absent, stop and request them.

**Note on pharmaversesdtm test data:** The `pharmaversesdtm` package no longer exports a plain `rs` object. Use `pharmaversesdtm::rs_onco_recist` for test or benchmark runs. When working with real study data, load RS from the study's SDTM package or file path.

---

## Workflow

Follow these steps in order. Generate code section by section, not as a single block.

### Step 1 — Setup and domain loading

```r library(admiral) library(admiralonco) library(dplyr) library(lubridate) library(pharmaversesdtm)

# Load RS domain # For pharmaversesdtm test data: use rs_onco_recist (plain `rs` no longer exported) rs <- pharmaversesdtm::rs_onco_recist adsl <- adsl # assumed derived upstream; replace with path/load as needed

# Confirm RS has at least one record stopifnot(nrow(rs) > 0) ```

### Step 2 — DOMAIN removal

Remove DOMAIN from RS **before** any `derive_param_*()` or `derive_vars_merged()` calls. admiral errors when DOMAIN exists in both the dataset and a source dataset passed to these functions.

```r rs <- rs |> select(-DOMAIN) ```

### Step 3 — Merge ADSL backbone variables

Bring required ADSL variables into the RS dataset before parameter derivation. At minimum: RANDDT and TRTSDT (clinical benefit anchor and study day reference), treatment labels, and population flags.

```r # REVIEW: Confirm which ADSL variables are required by the ADaM ADRS spec. # RANDDT is the conventional clinical benefit anchor date; TRTSDT is required # for ADY derivation. Add or remove population flags per the spec. adrs <- rs |> derive_vars_merged( dataset_add = adsl, by_vars = exprs(STUDYID, USUBJID), new_vars = exprs(RANDDT, TRTSDT, TRT01P, TRT01PN, TRT01A, TRT01AN, ITTFL, SAFFL) ) ```

### Step 4 — Date derivation (ADT, ADTF, ADY)

Derive the analysis date from RSDTC. This must happen **before** any `derive_param_*()` call — admiralonco response functions use ADT internally for confirmation window comparisons.

```r adrs <- adrs |> derive_vars_dt( dtc = RSDTC, new_vars_prefix = "A", date_imputation = "first", flag_imputation = "auto" ) |> derive_vars_dy( reference_date = TRTSDT, source_vars = exprs(ADT) ) ```

### Step 5 — Analysis value (AVALC, AVAL)

Set AVALC from RSSTRESC and derive the numeric AVAL using the admiralonco helper `aval_resp()`. This function maps response categories to a monotone numeric scale: CR=1, PR=2, SD=3, NON-CR/NON-PD=4, PD=5, NE=6.

```r # REVIEW: Confirm that RSSTRESC values in this study's RS domain align with the # RECIST 1.1 CT expected by aval_resp(). Non-standard categories (e.g. # "NON-CR/NON-PD" in lymphoma, iRECIST response categories) require a custom # lookup if aval_resp() does not map them — do not suppress the resulting NA. adrs <- adrs |> mutate( AVALC = RSSTRESC, AVAL = aval_resp(AVALC) ) ```

### Step 6 — Overall response parameter (OVRLRESP)

Add OVRLRESP records — one per subject per assessment timepoint. This parameter carries the verbatim response at each visit; it is not confirmation-adjusted.

```r # REVIEW: PARAMCD and PARAM values must match the ADaM ADRS spec exactly. # Adjust filter_source if the study uses a different assessor # (BICR: RSEVAL == "INDEPENDENT ASSESSOR") or a different RECIST version. adrs <- adrs |> derive_param_response( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, set_values_to = exprs( PARAMCD = "OVRLRESP", PARAM = "Overall Response by Investigator" ) ) ```

### Step 7 — Unconfirmed response flag (RSP)

Add RSP records — one per subject, indicating whether any CR or PR was observed (unconfirmed). Retained alongside CONFIRMED to enable the ORR verification check in Step 11.

```r adrs <- adrs |> derive_param_response( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, resp_val = c("CR", "PR"), set_values_to = exprs( PARAMCD = "RSP", PARAM = "Response (Unconfirmed)" ) ) ```

### Step 8 — Confirmed response (CONFIRMED)

A CR or PR is confirmed when a second qualifying assessment ≥ `ref_confirm` days after the first also shows CR or PR. CONFIRMED = "Y" if the subject has at least one confirmed CR or PR; "N" otherwise.

**Flag convention note:** CONFIRMED uses `"Y"`/`"N"`, not `"Y"`/`NA` — this is the documented admiralonco contract. See [Flag convention exception](#flag-convention-exception-for-confirmed-and-cbrespfl) below. Do not recode `"N"` to `NA`.

```r # REVIEW: ref_confirm = 28 is the RECIST 1.1 standard for CR/PR confirmation. # Confirm this value against the study protocol and SAP — some programs specify # 21 days, and regulatory precedent exists for other windows. A wrong value # silently inflates or deflates confirmed ORR. adrs <- adrs |> derive_param_confirmed_resp( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, ref_confirm = 28, # PLACEHOLDER — confirm from SAP set_values_to = exprs( PARAMCD = "CONFIRMED", PARAM = "Confirmed Response" ) ) ```

### Step 9 — Best overall response (BESTRESP)

BOR applies the RECIST 1.1 hierarchy across all assessments for each subject. `derive_param_confirmed_bor()` handles confirmation requirements, the NE propagation rule, and the hierarchy correctly. Never substitute `slice_min(AVAL)` or manual `case_when()` — these cannot replicate the NE propagation logic.

```r # REVIEW: missing_as_ne controls how missing assessments are treated in BOR. # FALSE (default): missing assessments are ignored (excluded from BOR). # TRUE: missing assessments count as NE, which can worsen BOR for subjects # with gaps in the assessment schedule. # Confirm the per-protocol analysis population definition with the # statistical reviewer before committing to either value. adrs <- adrs |> derive_param_confirmed_bor( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, ref_confirm = 28, # must match Step 8 missing_as_ne = FALSE, # PLACEHOLDER — confirm from SAP set_values_to = exprs( PARAMCD = "BESTRESP", PARAM = "Best Overall Response (Confirmed)" ) ) ```

### Step 10 — Clinical benefit (CBRESPFL)

Clinical benefit is a durable non-progressive response: CR, PR, or SD sustained for ≥ `ref_start_window` days from `reference_date`. CBRESPFL = "Y" if criteria are met; "N" otherwise.

**Flag convention note:** CBRESPFL uses `"Y"`/`"N"`, not `"Y"`/`NA`. Same admiralonco contract as CONFIRMED — do not recode.

```r # REVIEW: Two protocol-specific decisions are required here and must both be # confirmed from the protocol and SAP before use: # # (1) reference_date — RANDDT is the conventional anchor. Some protocols # instead define the 42-day window from the date of the first qualifying # response (first SD, PR, or CR). If the protocol means "from first # qualifying assessment", compute per-subject first-assessment dates # and pass them as reference_date rather than a fixed ADSL variable. # # (2) ref_start_window = 42 — RECIST standard for SD duration. Some studies # use 35 or 56 days. Confirm from the protocol. adrs <- adrs |> derive_param_clinbenefit( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, reference_date = RANDDT, # PLACEHOLDER — confirm anchor from protocol ref_start_window = 42, # PLACEHOLDER — confirm from protocol set_values_to = exprs( PARAMCD = "CBRESPFL", PARAM = "Clinical Benefit" ) ) ```

### Step 11 — Verification: confirmed vs unconfirmed ORR

Print response counts side-by-side and assert that confirmed ORR cannot exceed unconfirmed ORR. A confirmed count greater than unconfirmed count signals a configuration error in the confirmation window.

```r # Print response parameter summary for QC — include in script output log response_summary <- adrs |> filter(PARAMCD %in% c("RSP", "CONFIRMED", "CBRESPFL")) |> count(PARAMCD, AVALC) print(response_summary)

# Confirmed ORR must not exceed unconfirmed ORR n_confirmed <- sum(adrs$PARAMCD == "CONFIRMED" & adrs$AVALC == "Y", na.rm = TRUE) n_unconfirmed <- sum(adrs$PARAMCD == "RSP" & adrs$AVALC == "Y", na.rm = TRUE) stopifnot(n_confirmed <= n_unconfirmed)

# PD is never a confirmed response stopifnot(!any( adrs$PARAMCD == "CONFIRMED" & adrs$AVALC == "Y" & adrs$AVAL == aval_resp("PD"), na.rm = TRUE )) ```

### Step 12 — Final checks

```r # Required parameter coverage required_params <- c("OVRLRESP", "RSP", "CONFIRMED", "BESTRESP", "CBRESPFL") missing_params <- setdiff(required_params, unique(adrs$PARAMCD)) if (length(missing_params) > 0) { stop("Missing required ADRS parameters: ", paste(missing_params, collapse = ", ")) }

# Uniqueness: one record per subject per subject-level parameter dup_check <- adrs |> filter(PARAMCD %in% c("BESTRESP", "CONFIRMED", "RSP", "CBRESPFL")) |> count(STUDYID, USUBJID, PARAMCD) |> filter(n > 1) if (nrow(dup_check) > 0) { stop("Duplicate subject-level parameter records found:\n", paste(paste(dup_check$USUBJID, dup_check$PARAMCD), collapse = "\n")) }

# Required variable presence check required_vars <- c( "STUDYID", "USUBJID"

--- name: admiral-adrs description: > Derives an ADaM Tumor Response Analysis Dataset (ADRS) using the {admiral} and {admiralonco} R packages. Use when a user needs to create ADRS from SDTM RS domain data, derive RECIST 1.1 response parameters (overall response, confirmed response, best overall response, clinical benefit), or generate QC-ready R code following CDISC ADaM and oncology conventions. Requires SDTM RS input data, ADSL with randomization and treatment dates, and an ADaM ADRS specification. license: MIT metadata: author: Navitas Data Sciences version: "0.1" pharmaverse: "true" parent: admiral compatibility: > Requires R with admiral, admiralonco, dplyr, lubridate, and pharmaversesdtm installed. Requires a completed ADSL dataset with RANDDT and TRTSDT. Designed for use in a GxP-compliant oncology trial environment with access to SDTM RS domain data and an ADaM ADRS specification. ---

# admiral-adrs

> Shared conventions (library setup, pipe style, date rules, flag convention, > `# REVIEW:` annotations, `stopifnot()` patterns) are defined in the parent > [`../SKILL.md`](../SKILL.md). The workflow below is ADRS-specific.

Derives a CDISC-conformant ADRS tumor response dataset using {admiral} and {admiralonco}. Outputs executable, QC-ready R code covering RECIST 1.1 response parameters with full derivation traceability.

The primary design challenge in ADRS is the **confirmation logic**: CR and PR must be supported by a second qualifying assessment ≥28 days later. Best Overall Response (BOR) follows a strict hierarchy (CR > PR > SD > NON-CR/NON-PD > PD > NE) and handles NE propagation in ways that manual `case_when()` or `slice_min()` cannot replicate correctly. Always use `admiralonco` functions — never manual derivations.

---

## Inputs

Before generating code, confirm the following are available or explicitly noted as absent:

| Input | Required | Notes | |---|---|---| | RS | Yes | One record per tumor assessment per subject; RSSTRESC contains the response category (CR/PR/SD/PD/NE) | | ADSL | Yes | Provides TRTSDT, RANDDT, treatment labels, population flags | | ADaM ADRS spec | Yes | Parameter list, PARAMCD/PARAM mapping, confirmation window, clinical benefit definition | | Study context | Yes | RECIST version (1.0 vs 1.1), assessor (investigator vs BICR), confirmation window, clinical benefit anchor date |

If RS or ADSL are absent, stop and request them.

**Note on pharmaversesdtm test data:** The `pharmaversesdtm` package no longer exports a plain `rs` object. Use `pharmaversesdtm::rs_onco_recist` for test or benchmark runs. When working with real study data, load RS from the study's SDTM package or file path.

---

## Workflow

Follow these steps in order. Generate code section by section, not as a single block.

### Step 1 — Setup and domain loading

```r library(admiral) library(admiralonco) library(dplyr) library(lubridate) library(pharmaversesdtm)

# Load RS domain # For pharmaversesdtm test data: use rs_onco_recist (plain `rs` no longer exported) rs <- pharmaversesdtm::rs_onco_recist adsl <- adsl # assumed derived upstream; replace with path/load as needed

# Confirm RS has at least one record stopifnot(nrow(rs) > 0) ```

### Step 2 — DOMAIN removal

Remove DOMAIN from RS **before** any `derive_param_*()` or `derive_vars_merged()` calls. admiral errors when DOMAIN exists in both the dataset and a source dataset passed to these functions.

```r rs <- rs |> select(-DOMAIN) ```

### Step 3 — Merge ADSL backbone variables

Bring required ADSL variables into the RS dataset before parameter derivation. At minimum: RANDDT and TRTSDT (clinical benefit anchor and study day reference), treatment labels, and population flags.

```r # REVIEW: Confirm which ADSL variables are required by the ADaM ADRS spec. # RANDDT is the conventional clinical benefit anchor date; TRTSDT is required # for ADY derivation. Add or remove population flags per the spec. adrs <- rs |> derive_vars_merged( dataset_add = adsl, by_vars = exprs(STUDYID, USUBJID), new_vars = exprs(RANDDT, TRTSDT, TRT01P, TRT01PN, TRT01A, TRT01AN, ITTFL, SAFFL) ) ```

### Step 4 — Date derivation (ADT, ADTF, ADY)

Derive the analysis date from RSDTC. This must happen **before** any `derive_param_*()` call — admiralonco response functions use ADT internally for confirmation window comparisons.

```r adrs <- adrs |> derive_vars_dt( dtc = RSDTC, new_vars_prefix = "A", date_imputation = "first", flag_imputation = "auto" ) |> derive_vars_dy( reference_date = TRTSDT, source_vars = exprs(ADT) ) ```

### Step 5 — Analysis value (AVALC, AVAL)

Set AVALC from RSSTRESC and derive the numeric AVAL using the admiralonco helper `aval_resp()`. This function maps response categories to a monotone numeric scale: CR=1, PR=2, SD=3, NON-CR/NON-PD=4, PD=5, NE=6.

```r # REVIEW: Confirm that RSSTRESC values in this study's RS domain align with the # RECIST 1.1 CT expected by aval_resp(). Non-standard categories (e.g. # "NON-CR/NON-PD" in lymphoma, iRECIST response categories) require a custom # lookup if aval_resp() does not map them — do not suppress the resulting NA. adrs <- adrs |> mutate( AVALC = RSSTRESC, AVAL = aval_resp(AVALC) ) ```

### Step 6 — Overall response parameter (OVRLRESP)

Add OVRLRESP records — one per subject per assessment timepoint. This parameter carries the verbatim response at each visit; it is not confirmation-adjusted.

```r # REVIEW: PARAMCD and PARAM values must match the ADaM ADRS spec exactly. # Adjust filter_source if the study uses a different assessor # (BICR: RSEVAL == "INDEPENDENT ASSESSOR") or a different RECIST version. adrs <- adrs |> derive_param_response( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, set_values_to = exprs( PARAMCD = "OVRLRESP", PARAM = "Overall Response by Investigator" ) ) ```

### Step 7 — Unconfirmed response flag (RSP)

Add RSP records — one per subject, indicating whether any CR or PR was observed (unconfirmed). Retained alongside CONFIRMED to enable the ORR verification check in Step 11.

```r adrs <- adrs |> derive_param_response( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, resp_val = c("CR", "PR"), set_values_to = exprs( PARAMCD = "RSP", PARAM = "Response (Unconfirmed)" ) ) ```

### Step 8 — Confirmed response (CONFIRMED)

A CR or PR is confirmed when a second qualifying assessment ≥ `ref_confirm` days after the first also shows CR or PR. CONFIRMED = "Y" if the subject has at least one confirmed CR or PR; "N" otherwise.

**Flag convention note:** CONFIRMED uses `"Y"`/`"N"`, not `"Y"`/`NA` — this is the documented admiralonco contract. See [Flag convention exception](#flag-convention-exception-for-confirmed-and-cbrespfl) below. Do not recode `"N"` to `NA`.

```r # REVIEW: ref_confirm = 28 is the RECIST 1.1 standard for CR/PR confirmation. # Confirm this value against the study protocol and SAP — some programs specify # 21 days, and regulatory precedent exists for other windows. A wrong value # silently inflates or deflates confirmed ORR. adrs <- adrs |> derive_param_confirmed_resp( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, ref_confirm = 28, # PLACEHOLDER — confirm from SAP set_values_to = exprs( PARAMCD = "CONFIRMED", PARAM = "Confirmed Response" ) ) ```

### Step 9 — Best overall response (BESTRESP)

BOR applies the RECIST 1.1 hierarchy across all assessments for each subject. `derive_param_confirmed_bor()` handles confirmation requirements, the NE propagation rule, and the hierarchy correctly. Never substitute `slice_min(AVAL)` or manual `case_when()` — these cannot replicate the NE propagation logic.

```r # REVIEW: missing_as_ne controls how missing assessments are treated in BOR. # FALSE (default): missing assessments are ignored (excluded from BOR). # TRUE: missing assessments count as NE, which can worsen BOR for subjects # with gaps in the assessment schedule. # Confirm the per-protocol analysis population definition with the # statistical reviewer before committing to either value. adrs <- adrs |> derive_param_confirmed_bor( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, ref_confirm = 28, # must match Step 8 missing_as_ne = FALSE, # PLACEHOLDER — confirm from SAP set_values_to = exprs( PARAMCD = "BESTRESP", PARAM = "Best Overall Response (Confirmed)" ) ) ```

### Step 10 — Clinical benefit (CBRESPFL)

Clinical benefit is a durable non-progressive response: CR, PR, or SD sustained for ≥ `ref_start_window` days from `reference_date`. CBRESPFL = "Y" if criteria are met; "N" otherwise.

**Flag convention note:** CBRESPFL uses `"Y"`/`"N"`, not `"Y"`/`NA`. Same admiralonco contract as CONFIRMED — do not recode.

```r # REVIEW: Two protocol-specific decisions are required here and must both be # confirmed from the protocol and SAP before use: # # (1) reference_date — RANDDT is the conventional anchor. Some protocols # instead define the 42-day window from the date of the first qualifying # response (first SD, PR, or CR). If the protocol means "from first # qualifying assessment", compute per-subject first-assessment dates # and pass them as reference_date rather than a fixed ADSL variable. # # (2) ref_start_window = 42 — RECIST standard for SD duration. Some studies # use 35 or 56 days. Confirm from the protocol. adrs <- adrs |> derive_param_clinbenefit( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, reference_date = RANDDT, # PLACEHOLDER — confirm anchor from protocol ref_start_window = 42, # PLACEHOLDER — confirm from protocol set_values_to = exprs( PARAMCD = "CBRESPFL", PARAM = "Clinical Benefit" ) ) ```

### Step 11 — Verification: confirmed vs unconfirmed ORR

Print response counts side-by-side and assert that confirmed ORR cannot exceed unconfirmed ORR. A confirmed count greater than unconfirmed count signals a configuration error in the confirmation window.

```r # Print response parameter summary for QC — include in script output log response_summary <- adrs |> filter(PARAMCD %in% c("RSP", "CONFIRMED", "CBRESPFL")) |> count(PARAMCD, AVALC) print(response_summary)

# Confirmed ORR must not exceed unconfirmed ORR n_confirmed <- sum(adrs$PARAMCD == "CONFIRMED" & adrs$AVALC == "Y", na.rm = TRUE) n_unconfirmed <- sum(adrs$PARAMCD == "RSP" & adrs$AVALC == "Y", na.rm = TRUE) stopifnot(n_confirmed <= n_unconfirmed)

# PD is never a confirmed response stopifnot(!any( adrs$PARAMCD == "CONFIRMED" & adrs$AVALC == "Y" & adrs$AVAL == aval_resp("PD"), na.rm = TRUE )) ```

### Step 12 — Final checks

```r # Required parameter coverage required_params <- c("OVRLRESP", "RSP", "CONFIRMED", "BESTRESP", "CBRESPFL") missing_params <- setdiff(required_params, unique(adrs$PARAMCD)) if (length(missing_params) > 0) { stop("Missing required ADRS parameters: ", paste(missing_params, collapse = ", ")) }

# Uniqueness: one record per subject per subject-level parameter dup_check <- adrs |> filter(PARAMCD %in% c("BESTRESP", "CONFIRMED", "RSP", "CBRESPFL")) |> count(STUDYID, USUBJID, PARAMCD) |> filter(n > 1) if (nrow(dup_check) > 0) { stop("Duplicate subject-level parameter records found:\n", paste(paste(dup_check$USUBJID, dup_check$PARAMCD), collapse = "\n")) }

# Required variable presence check required_vars <- c( "STUDYID", "USUBJID"

--- name: admiral-adrs description: > Derives an ADaM Tumor Response Analysis Dataset (ADRS) using the {admiral} and {admiralonco} R packages. Use when a user needs to create ADRS from SDTM RS domain data, derive RECIST 1.1 response parameters (overall response, confirmed response, best overall response, clinical benefit), or generate QC-ready R code following CDISC ADaM and oncology conventions. Requires SDTM RS input data, ADSL with randomization and treatment dates, and an ADaM ADRS specification. license: MIT metadata: author: Navitas Data Sciences version: "0.1" pharmaverse: "true" parent: admiral compatibility: > Requires R with admiral, admiralonco, dplyr, lubridate, and pharmaversesdtm installed. Requires a completed ADSL dataset with RANDDT and TRTSDT. Designed for use in a GxP-compliant oncology trial environment with access to SDTM RS domain data and an ADaM ADRS specification. ---

# admiral-adrs

> Shared conventions (library setup, pipe style, date rules, flag convention, > `# REVIEW:` annotations, `stopifnot()` patterns) are defined in the parent > [`../SKILL.md`](../SKILL.md). The workflow below is ADRS-specific.

Derives a CDISC-conformant ADRS tumor response dataset using {admiral} and {admiralonco}. Outputs executable, QC-ready R code covering RECIST 1.1 response parameters with full derivation traceability.

The primary design challenge in ADRS is the **confirmation logic**: CR and PR must be supported by a second qualifying assessment ≥28 days later. Best Overall Response (BOR) follows a strict hierarchy (CR > PR > SD > NON-CR/NON-PD > PD > NE) and handles NE propagation in ways that manual `case_when()` or `slice_min()` cannot replicate correctly. Always use `admiralonco` functions — never manual derivations.

---

## Inputs

Before generating code, confirm the following are available or explicitly noted as absent:

| Input | Required | Notes | |---|---|---| | RS | Yes | One record per tumor assessment per subject; RSSTRESC contains the response category (CR/PR/SD/PD/NE) | | ADSL | Yes | Provides TRTSDT, RANDDT, treatment labels, population flags | | ADaM ADRS spec | Yes | Parameter list, PARAMCD/PARAM mapping, confirmation window, clinical benefit definition | | Study context | Yes | RECIST version (1.0 vs 1.1), assessor (investigator vs BICR), confirmation window, clinical benefit anchor date |

If RS or ADSL are absent, stop and request them.

**Note on pharmaversesdtm test data:** The `pharmaversesdtm` package no longer exports a plain `rs` object. Use `pharmaversesdtm::rs_onco_recist` for test or benchmark runs. When working with real study data, load RS from the study's SDTM package or file path.

---

## Workflow

Follow these steps in order. Generate code section by section, not as a single block.

### Step 1 — Setup and domain loading

```r library(admiral) library(admiralonco) library(dplyr) library(lubridate) library(pharmaversesdtm)

# Load RS domain # For pharmaversesdtm test data: use rs_onco_recist (plain `rs` no longer exported) rs <- pharmaversesdtm::rs_onco_recist adsl <- adsl # assumed derived upstream; replace with path/load as needed

# Confirm RS has at least one record stopifnot(nrow(rs) > 0) ```

### Step 2 — DOMAIN removal

Remove DOMAIN from RS **before** any `derive_param_*()` or `derive_vars_merged()` calls. admiral errors when DOMAIN exists in both the dataset and a source dataset passed to these functions.

```r rs <- rs |> select(-DOMAIN) ```

### Step 3 — Merge ADSL backbone variables

Bring required ADSL variables into the RS dataset before parameter derivation. At minimum: RANDDT and TRTSDT (clinical benefit anchor and study day reference), treatment labels, and population flags.

```r # REVIEW: Confirm which ADSL variables are required by the ADaM ADRS spec. # RANDDT is the conventional clinical benefit anchor date; TRTSDT is required # for ADY derivation. Add or remove population flags per the spec. adrs <- rs |> derive_vars_merged( dataset_add = adsl, by_vars = exprs(STUDYID, USUBJID), new_vars = exprs(RANDDT, TRTSDT, TRT01P, TRT01PN, TRT01A, TRT01AN, ITTFL, SAFFL) ) ```

### Step 4 — Date derivation (ADT, ADTF, ADY)

Derive the analysis date from RSDTC. This must happen **before** any `derive_param_*()` call — admiralonco response functions use ADT internally for confirmation window comparisons.

```r adrs <- adrs |> derive_vars_dt( dtc = RSDTC, new_vars_prefix = "A", date_imputation = "first", flag_imputation = "auto" ) |> derive_vars_dy( reference_date = TRTSDT, source_vars = exprs(ADT) ) ```

### Step 5 — Analysis value (AVALC, AVAL)

Set AVALC from RSSTRESC and derive the numeric AVAL using the admiralonco helper `aval_resp()`. This function maps response categories to a monotone numeric scale: CR=1, PR=2, SD=3, NON-CR/NON-PD=4, PD=5, NE=6.

```r # REVIEW: Confirm that RSSTRESC values in this study's RS domain align with the # RECIST 1.1 CT expected by aval_resp(). Non-standard categories (e.g. # "NON-CR/NON-PD" in lymphoma, iRECIST response categories) require a custom # lookup if aval_resp() does not map them — do not suppress the resulting NA. adrs <- adrs |> mutate( AVALC = RSSTRESC, AVAL = aval_resp(AVALC) ) ```

### Step 6 — Overall response parameter (OVRLRESP)

Add OVRLRESP records — one per subject per assessment timepoint. This parameter carries the verbatim response at each visit; it is not confirmation-adjusted.

```r # REVIEW: PARAMCD and PARAM values must match the ADaM ADRS spec exactly. # Adjust filter_source if the study uses a different assessor # (BICR: RSEVAL == "INDEPENDENT ASSESSOR") or a different RECIST version. adrs <- adrs |> derive_param_response( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, set_values_to = exprs( PARAMCD = "OVRLRESP", PARAM = "Overall Response by Investigator" ) ) ```

### Step 7 — Unconfirmed response flag (RSP)

Add RSP records — one per subject, indicating whether any CR or PR was observed (unconfirmed). Retained alongside CONFIRMED to enable the ORR verification check in Step 11.

```r adrs <- adrs |> derive_param_response( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, resp_val = c("CR", "PR"), set_values_to = exprs( PARAMCD = "RSP", PARAM = "Response (Unconfirmed)" ) ) ```

### Step 8 — Confirmed response (CONFIRMED)

A CR or PR is confirmed when a second qualifying assessment ≥ `ref_confirm` days after the first also shows CR or PR. CONFIRMED = "Y" if the subject has at least one confirmed CR or PR; "N" otherwise.

**Flag convention note:** CONFIRMED uses `"Y"`/`"N"`, not `"Y"`/`NA` — this is the documented admiralonco contract. See [Flag convention exception](#flag-convention-exception-for-confirmed-and-cbrespfl) below. Do not recode `"N"` to `NA`.

```r # REVIEW: ref_confirm = 28 is the RECIST 1.1 standard for CR/PR confirmation. # Confirm this value against the study protocol and SAP — some programs specify # 21 days, and regulatory precedent exists for other windows. A wrong value # silently inflates or deflates confirmed ORR. adrs <- adrs |> derive_param_confirmed_resp( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, ref_confirm = 28, # PLACEHOLDER — confirm from SAP set_values_to = exprs( PARAMCD = "CONFIRMED", PARAM = "Confirmed Response" ) ) ```

### Step 9 — Best overall response (BESTRESP)

BOR applies the RECIST 1.1 hierarchy across all assessments for each subject. `derive_param_confirmed_bor()` handles confirmation requirements, the NE propagation rule, and the hierarchy correctly. Never substitute `slice_min(AVAL)` or manual `case_when()` — these cannot replicate the NE propagation logic.

```r # REVIEW: missing_as_ne controls how missing assessments are treated in BOR. # FALSE (default): missing assessments are ignored (excluded from BOR). # TRUE: missing assessments count as NE, which can worsen BOR for subjects # with gaps in the assessment schedule. # Confirm the per-protocol analysis population definition with the # statistical reviewer before committing to either value. adrs <- adrs |> derive_param_confirmed_bor( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, ref_confirm = 28, # must match Step 8 missing_as_ne = FALSE, # PLACEHOLDER — confirm from SAP set_values_to = exprs( PARAMCD = "BESTRESP", PARAM = "Best Overall Response (Confirmed)" ) ) ```

### Step 10 — Clinical benefit (CBRESPFL)

Clinical benefit is a durable non-progressive response: CR, PR, or SD sustained for ≥ `ref_start_window` days from `reference_date`. CBRESPFL = "Y" if criteria are met; "N" otherwise.

**Flag convention note:** CBRESPFL uses `"Y"`/`"N"`, not `"Y"`/`NA`. Same admiralonco contract as CONFIRMED — do not recode.

```r # REVIEW: Two protocol-specific decisions are required here and must both be # confirmed from the protocol and SAP before use: # # (1) reference_date — RANDDT is the conventional anchor. Some protocols # instead define the 42-day window from the date of the first qualifying # response (first SD, PR, or CR). If the protocol means "from first # qualifying assessment", compute per-subject first-assessment dates # and pass them as reference_date rather than a fixed ADSL variable. # # (2) ref_start_window = 42 — RECIST standard for SD duration. Some studies # use 35 or 56 days. Confirm from the protocol. adrs <- adrs |> derive_param_clinbenefit( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, reference_date = RANDDT, # PLACEHOLDER — confirm anchor from protocol ref_start_window = 42, # PLACEHOLDER — confirm from protocol set_values_to = exprs( PARAMCD = "CBRESPFL", PARAM = "Clinical Benefit" ) ) ```

### Step 11 — Verification: confirmed vs unconfirmed ORR

Print response counts side-by-side and assert that confirmed ORR cannot exceed unconfirmed ORR. A confirmed count greater than unconfirmed count signals a configuration error in the confirmation window.

```r # Print response parameter summary for QC — include in script output log response_summary <- adrs |> filter(PARAMCD %in% c("RSP", "CONFIRMED", "CBRESPFL")) |> count(PARAMCD, AVALC) print(response_summary)

# Confirmed ORR must not exceed unconfirmed ORR n_confirmed <- sum(adrs$PARAMCD == "CONFIRMED" & adrs$AVALC == "Y", na.rm = TRUE) n_unconfirmed <- sum(adrs$PARAMCD == "RSP" & adrs$AVALC == "Y", na.rm = TRUE) stopifnot(n_confirmed <= n_unconfirmed)

# PD is never a confirmed response stopifnot(!any( adrs$PARAMCD == "CONFIRMED" & adrs$AVALC == "Y" & adrs$AVAL == aval_resp("PD"), na.rm = TRUE )) ```

### Step 12 — Final checks

```r # Required parameter coverage required_params <- c("OVRLRESP", "RSP", "CONFIRMED", "BESTRESP", "CBRESPFL") missing_params <- setdiff(required_params, unique(adrs$PARAMCD)) if (length(missing_params) > 0) { stop("Missing required ADRS parameters: ", paste(missing_params, collapse = ", ")) }

# Uniqueness: one record per subject per subject-level parameter dup_check <- adrs |> filter(PARAMCD %in% c("BESTRESP", "CONFIRMED", "RSP", "CBRESPFL")) |> count(STUDYID, USUBJID, PARAMCD) |> filter(n > 1) if (nrow(dup_check) > 0) { stop("Duplicate subject-level parameter records found:\n", paste(paste(dup_check$USUBJID, dup_check$PARAMCD), collapse = "\n")) }

# Required variable presence check required_vars <- c( "STUDYID", "USUBJID"

--- name: admiral-adrs description: > Derives an ADaM Tumor Response Analysis Dataset (ADRS) using the {admiral} and {admiralonco} R packages. Use when a user needs to create ADRS from SDTM RS domain data, derive RECIST 1.1 response parameters (overall response, confirmed response, best overall response, clinical benefit), or generate QC-ready R code following CDISC ADaM and oncology conventions. Requires SDTM RS input data, ADSL with randomization and treatment dates, and an ADaM ADRS specification. license: MIT metadata: author: Navitas Data Sciences version: "0.1" pharmaverse: "true" parent: admiral compatibility: > Requires R with admiral, admiralonco, dplyr, lubridate, and pharmaversesdtm installed. Requires a completed ADSL dataset with RANDDT and TRTSDT. Designed for use in a GxP-compliant oncology trial environment with access to SDTM RS domain data and an ADaM ADRS specification. ---

# admiral-adrs

> Shared conventions (library setup, pipe style, date rules, flag convention, > `# REVIEW:` annotations, `stopifnot()` patterns) are defined in the parent > [`../SKILL.md`](../SKILL.md). The workflow below is ADRS-specific.

Derives a CDISC-conformant ADRS tumor response dataset using {admiral} and {admiralonco}. Outputs executable, QC-ready R code covering RECIST 1.1 response parameters with full derivation traceability.

The primary design challenge in ADRS is the **confirmation logic**: CR and PR must be supported by a second qualifying assessment ≥28 days later. Best Overall Response (BOR) follows a strict hierarchy (CR > PR > SD > NON-CR/NON-PD > PD > NE) and handles NE propagation in ways that manual `case_when()` or `slice_min()` cannot replicate correctly. Always use `admiralonco` functions — never manual derivations.

---

## Inputs

Before generating code, confirm the following are available or explicitly noted as absent:

| Input | Required | Notes | |---|---|---| | RS | Yes | One record per tumor assessment per subject; RSSTRESC contains the response category (CR/PR/SD/PD/NE) | | ADSL | Yes | Provides TRTSDT, RANDDT, treatment labels, population flags | | ADaM ADRS spec | Yes | Parameter list, PARAMCD/PARAM mapping, confirmation window, clinical benefit definition | | Study context | Yes | RECIST version (1.0 vs 1.1), assessor (investigator vs BICR), confirmation window, clinical benefit anchor date |

If RS or ADSL are absent, stop and request them.

**Note on pharmaversesdtm test data:** The `pharmaversesdtm` package no longer exports a plain `rs` object. Use `pharmaversesdtm::rs_onco_recist` for test or benchmark runs. When working with real study data, load RS from the study's SDTM package or file path.

---

## Workflow

Follow these steps in order. Generate code section by section, not as a single block.

### Step 1 — Setup and domain loading

```r library(admiral) library(admiralonco) library(dplyr) library(lubridate) library(pharmaversesdtm)

# Load RS domain # For pharmaversesdtm test data: use rs_onco_recist (plain `rs` no longer exported) rs <- pharmaversesdtm::rs_onco_recist adsl <- adsl # assumed derived upstream; replace with path/load as needed

# Confirm RS has at least one record stopifnot(nrow(rs) > 0) ```

### Step 2 — DOMAIN removal

Remove DOMAIN from RS **before** any `derive_param_*()` or `derive_vars_merged()` calls. admiral errors when DOMAIN exists in both the dataset and a source dataset passed to these functions.

```r rs <- rs |> select(-DOMAIN) ```

### Step 3 — Merge ADSL backbone variables

Bring required ADSL variables into the RS dataset before parameter derivation. At minimum: RANDDT and TRTSDT (clinical benefit anchor and study day reference), treatment labels, and population flags.

```r # REVIEW: Confirm which ADSL variables are required by the ADaM ADRS spec. # RANDDT is the conventional clinical benefit anchor date; TRTSDT is required # for ADY derivation. Add or remove population flags per the spec. adrs <- rs |> derive_vars_merged( dataset_add = adsl, by_vars = exprs(STUDYID, USUBJID), new_vars = exprs(RANDDT, TRTSDT, TRT01P, TRT01PN, TRT01A, TRT01AN, ITTFL, SAFFL) ) ```

### Step 4 — Date derivation (ADT, ADTF, ADY)

Derive the analysis date from RSDTC. This must happen **before** any `derive_param_*()` call — admiralonco response functions use ADT internally for confirmation window comparisons.

```r adrs <- adrs |> derive_vars_dt( dtc = RSDTC, new_vars_prefix = "A", date_imputation = "first", flag_imputation = "auto" ) |> derive_vars_dy( reference_date = TRTSDT, source_vars = exprs(ADT) ) ```

### Step 5 — Analysis value (AVALC, AVAL)

Set AVALC from RSSTRESC and derive the numeric AVAL using the admiralonco helper `aval_resp()`. This function maps response categories to a monotone numeric scale: CR=1, PR=2, SD=3, NON-CR/NON-PD=4, PD=5, NE=6.

```r # REVIEW: Confirm that RSSTRESC values in this study's RS domain align with the # RECIST 1.1 CT expected by aval_resp(). Non-standard categories (e.g. # "NON-CR/NON-PD" in lymphoma, iRECIST response categories) require a custom # lookup if aval_resp() does not map them — do not suppress the resulting NA. adrs <- adrs |> mutate( AVALC = RSSTRESC, AVAL = aval_resp(AVALC) ) ```

### Step 6 — Overall response parameter (OVRLRESP)

Add OVRLRESP records — one per subject per assessment timepoint. This parameter carries the verbatim response at each visit; it is not confirmation-adjusted.

```r # REVIEW: PARAMCD and PARAM values must match the ADaM ADRS spec exactly. # Adjust filter_source if the study uses a different assessor # (BICR: RSEVAL == "INDEPENDENT ASSESSOR") or a different RECIST version. adrs <- adrs |> derive_param_response( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, set_values_to = exprs( PARAMCD = "OVRLRESP", PARAM = "Overall Response by Investigator" ) ) ```

### Step 7 — Unconfirmed response flag (RSP)

Add RSP records — one per subject, indicating whether any CR or PR was observed (unconfirmed). Retained alongside CONFIRMED to enable the ORR verification check in Step 11.

```r adrs <- adrs |> derive_param_response( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, resp_val = c("CR", "PR"), set_values_to = exprs( PARAMCD = "RSP", PARAM = "Response (Unconfirmed)" ) ) ```

### Step 8 — Confirmed response (CONFIRMED)

A CR or PR is confirmed when a second qualifying assessment ≥ `ref_confirm` days after the first also shows CR or PR. CONFIRMED = "Y" if the subject has at least one confirmed CR or PR; "N" otherwise.

**Flag convention note:** CONFIRMED uses `"Y"`/`"N"`, not `"Y"`/`NA` — this is the documented admiralonco contract. See [Flag convention exception](#flag-convention-exception-for-confirmed-and-cbrespfl) below. Do not recode `"N"` to `NA`.

```r # REVIEW: ref_confirm = 28 is the RECIST 1.1 standard for CR/PR confirmation. # Confirm this value against the study protocol and SAP — some programs specify # 21 days, and regulatory precedent exists for other windows. A wrong value # silently inflates or deflates confirmed ORR. adrs <- adrs |> derive_param_confirmed_resp( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, ref_confirm = 28, # PLACEHOLDER — confirm from SAP set_values_to = exprs( PARAMCD = "CONFIRMED", PARAM = "Confirmed Response" ) ) ```

### Step 9 — Best overall response (BESTRESP)

BOR applies the RECIST 1.1 hierarchy across all assessments for each subject. `derive_param_confirmed_bor()` handles confirmation requirements, the NE propagation rule, and the hierarchy correctly. Never substitute `slice_min(AVAL)` or manual `case_when()` — these cannot replicate the NE propagation logic.

```r # REVIEW: missing_as_ne controls how missing assessments are treated in BOR. # FALSE (default): missing assessments are ignored (excluded from BOR). # TRUE: missing assessments count as NE, which can worsen BOR for subjects # with gaps in the assessment schedule. # Confirm the per-protocol analysis population definition with the # statistical reviewer before committing to either value. adrs <- adrs |> derive_param_confirmed_bor( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, ref_confirm = 28, # must match Step 8 missing_as_ne = FALSE, # PLACEHOLDER — confirm from SAP set_values_to = exprs( PARAMCD = "BESTRESP", PARAM = "Best Overall Response (Confirmed)" ) ) ```

### Step 10 — Clinical benefit (CBRESPFL)

Clinical benefit is a durable non-progressive response: CR, PR, or SD sustained for ≥ `ref_start_window` days from `reference_date`. CBRESPFL = "Y" if criteria are met; "N" otherwise.

**Flag convention note:** CBRESPFL uses `"Y"`/`"N"`, not `"Y"`/`NA`. Same admiralonco contract as CONFIRMED — do not recode.

```r # REVIEW: Two protocol-specific decisions are required here and must both be # confirmed from the protocol and SAP before use: # # (1) reference_date — RANDDT is the conventional anchor. Some protocols # instead define the 42-day window from the date of the first qualifying # response (first SD, PR, or CR). If the protocol means "from first # qualifying assessment", compute per-subject first-assessment dates # and pass them as reference_date rather than a fixed ADSL variable. # # (2) ref_start_window = 42 — RECIST standard for SD duration. Some studies # use 35 or 56 days. Confirm from the protocol. adrs <- adrs |> derive_param_clinbenefit( dataset_adsl = adsl, filter_source = RSEVAL == "INVESTIGATOR" & RSEVALID == "RECIST 1.1", source_var = RSSTRESC, reference_date = RANDDT, # PLACEHOLDER — confirm anchor from protocol ref_start_window = 42, # PLACEHOLDER — confirm from protocol set_values_to = exprs( PARAMCD = "CBRESPFL", PARAM = "Clinical Benefit" ) ) ```

### Step 11 — Verification: confirmed vs unconfirmed ORR

Print response counts side-by-side and assert that confirmed ORR cannot exceed unconfirmed ORR. A confirmed count greater than unconfirmed count signals a configuration error in the confirmation window.

```r # Print response parameter summary for QC — include in script output log response_summary <- adrs |> filter(PARAMCD %in% c("RSP", "CONFIRMED", "CBRESPFL")) |> count(PARAMCD, AVALC) print(response_summary)

# Confirmed ORR must not exceed unconfirmed ORR n_confirmed <- sum(adrs$PARAMCD == "CONFIRMED" & adrs$AVALC == "Y", na.rm = TRUE) n_unconfirmed <- sum(adrs$PARAMCD == "RSP" & adrs$AVALC == "Y", na.rm = TRUE) stopifnot(n_confirmed <= n_unconfirmed)

# PD is never a confirmed response stopifnot(!any( adrs$PARAMCD == "CONFIRMED" & adrs$AVALC == "Y" & adrs$AVAL == aval_resp("PD"), na.rm = TRUE )) ```

### Step 12 — Final checks

```r # Required parameter coverage required_params <- c("OVRLRESP", "RSP", "CONFIRMED", "BESTRESP", "CBRESPFL") missing_params <- setdiff(required_params, unique(adrs$PARAMCD)) if (length(missing_params) > 0) { stop("Missing required ADRS parameters: ", paste(missing_params, collapse = ", ")) }

# Uniqueness: one record per subject per subject-level parameter dup_check <- adrs |> filter(PARAMCD %in% c("BESTRESP", "CONFIRMED", "RSP", "CBRESPFL")) |> count(STUDYID, USUBJID, PARAMCD) |> filter(n > 1) if (nrow(dup_check) > 0) { stop("Duplicate subject-level parameter records found:\n", paste(paste(dup_check$USUBJID, dup_check$PARAMCD), collapse = "\n")) }

# Required variable presence check required_vars <- c( "STUDYID", "USUBJID"