admiral

Name: admiral
Author: RConsortium

88stars20forks

How to install admiral?

rconsortium/pharma-skills/admiral

$npx -y skills add RConsortium/pharma-skills --skill admiral

Installs into the current project.

Summary

Parent skill for the admiral ADaM derivation family. Covers shared conventions used across all admiral child skills: library setup, pipe style, date derivation rules, flag variable conventions, and QC patterns. Route to a child skill for dataset-specific derivation workflows.

Files · 1

View on GitHub

SKILL.md

1	# admiral (parent skill)
2
3	This skill defines the shared conventions that apply across all admiral ADaM
4	derivation skills in this family. When a child skill is loaded, this parent
5	provides the foundation — child skills reference these conventions rather than
6	repeating them.
7
8	---
9
10	## Skill Routing
11
12	Choose the child skill that matches the target ADaM dataset type:
13
14	\| Dataset type \| Child skill \| Description \|
15	\|---\|---\|---\|
16	\| ADSL — Subject-Level \| `admiral/admiral-adsl` \| Treatment dates, disposition, population flags \|
17	\| BDS — Findings (ADVS, ADLB) \| `admiral/admiral-bds` \| Parameters, baseline, change from baseline \|
18	\| OCCDS — Adverse Events \| `admiral/admiral-adae` \| (planned) \|
19	\| TTE — Time to Event \| `admiral/admiral-adtte` \| (planned) \|
20
21	ADSL must be derived before any BDS or OCCDS dataset — population flags and
22	treatment variables from ADSL are merged into all downstream datasets.
23
24	---
25
26	## Shared Library Setup
27
28	Every admiral derivation script begins with this setup block. Add dataset-specific
29	libraries (e.g. `metatools`, `tfrmt`) per child skill requirements.
30
31	```r
32	library(admiral)
33	library(dplyr)
34	library(lubridate)
35
36	# For submission-ready output
37	library(metacore)
38	library(xportr)
39
40	# For benchmark reproducibility
41	library(pharmaversesdtm)
42	library(pharmaverseadam)
43	```
44
45	---
46
47	## Pipe and Expression Style
48
49	Always use the native pipe `\|>` — not the magrittr pipe `%>%`. admiral
50	functions accept `\|>` and it is the pharmaverse standard for new code.
51
52	Always use `exprs()` for admiral verb arguments that accept variable lists.
53	The `exprs()` wrapper is required for `by_vars`, `new_vars`, `order`, and
54	`source_vars` arguments in admiral functions. Bare variable names or character
55	strings will not work.
56
57	```r
58	# CORRECT
59	derive_vars_merged(
60	by_vars = exprs(STUDYID, USUBJID),
61	new_vars = exprs(TRTSDT = EXSTDT),
62	order = exprs(EXSTDT)
63	)
64
65	# WRONG — does not work with admiral
66	derive_vars_merged(
67	by_vars = c("STUDYID", "USUBJID"),
68	new_vars = c(TRTSDT = EXSTDT)
69	)
70	```
71
72	---
73
74	## Date Derivation Rules
75
76	**Never use `as.Date()`, `as.POSIXct()`, or `convert_dtc_to_date()` directly
77	on `--DTC` variables.** These silently return `NA` for partial dates (e.g.
78	`"2023-06"`, `"2023"`) without any warning.
79
80	Always use the admiral date functions:
81
82	\| Goal \| Function \|
83	\|---\|---\|
84	\| `--DTC` → Date variable \| `derive_vars_dt()` \|
85	\| `--DTC` → Datetime variable \| `derive_vars_dtm()` \|
86	\| Study day from dates \| `derive_vars_dy()` \|
87	\| Treatment duration \| `derive_var_trtdurd()` \|
88
89	### Imputation direction
90
91	\| Date type \| Rule \| admiral argument \|
92	\|---\|---\|---\|
93	\| Start dates (TRTSDT, ADT for start events) \| Impute to earliest \| `date_imputation = "first"` \|
94	\| End dates (TRTEDT, EOSDT) \| Impute to latest \| `date_imputation = "last"` \|
95	\| Time when absent — start \| `"00:00:00"` \| `time_imputation = "first"` \|
96	\| Time when absent — end \| `"23:59:59"` \| `time_imputation = "last"` \|
97
98	Always use `flag_imputation = "auto"` — this auto-generates `--DTF` and
99	`--TMF` imputation flag variables. Never suppress imputation flags.
100
101	```r
102	# Correct date derivation pattern
103	source_dt <- source_domain \|>
104	derive_vars_dt(
105	dtc = XXDTC,
106	new_vars_prefix = "XX",
107	date_imputation = "first",
108	flag_imputation = "auto"
109	)
110	```
111
112	### Study day convention
113
114	CDISC study day: Day 1 is the reference date; there is no Day 0. Always use
115	`derive_vars_dy()`. Never compute manually with `date2 - date1`.
116
117	---
118
119	## Flag Variable Convention
120
121	Flag variables must be `"Y"` or `NA` — never `"N"`.
122
123	This applies to all flag types: population flags (`--FL`), baseline flags
124	(`ABLFL`), analysis flags (`ANL01FL`), and any other indicator variable.
125
126	```r
127	# CORRECT
128	mutate(SAFFL = if_else(has_dose, "Y", NA_character_))
129
130	# WRONG — violates CDISC ADaM convention
131	mutate(SAFFL = if_else(has_dose, "Y", "N"))
132	```
133
134	When using `derive_var_merged_exist_flag()`, always set both:
135	- `true_value = "Y"`
136	- `false_value = NA_character_`
137	- `missing_value = NA_character_`
138
139	---
140
141	## DOMAIN Variable Removal
142
143	Remove `DOMAIN` from source datasets before passing to `derive_vars_merged()`.
144	admiral errors if a variable exists in both the input dataset and the source.
145
146	```r
147	# Pattern for ADSL and all BDS derivations
148	adsl <- adsl \|>
149	derive_vars_merged(
150	dataset_add = select(ex, -DOMAIN),
151	by_vars = exprs(STUDYID, USUBJID),
152	...
153	)
154	```
155
156	This applies to all SDTM source domains — EX, DS, VS, LB, AE, etc.
157
158	---
159
160	## QC Patterns
161
162	### Uniqueness assertions
163
164	Use `stopifnot()` to assert structural assumptions before proceeding. These
165	catch data quality issues earl

People who liked this also viewed

6 picks

Type

admiral

88stars20forks

View on GitHub

How to install admiral?

rconsortium/pharma-skills/admiral

$npx -y skills add RConsortium/pharma-skills --skill admiral

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# admiral (parent skill)
2
3	This skill defines the shared conventions that apply across all admiral ADaM
4	derivation skills in this family. When a child skill is loaded, this parent
5	provides the foundation — child skills reference these conventions rather than
6	repeating them.
7
8	---
9
10	## Skill Routing
11
12	Choose the child skill that matches the target ADaM dataset type:
13
14	\| Dataset type \| Child skill \| Description \|
15	\|---\|---\|---\|
16	\| ADSL — Subject-Level \| `admiral/admiral-adsl` \| Treatment dates, disposition, population flags \|
17	\| BDS — Findings (ADVS, ADLB) \| `admiral/admiral-bds` \| Parameters, baseline, change from baseline \|
18	\| OCCDS — Adverse Events \| `admiral/admiral-adae` \| (planned) \|
19	\| TTE — Time to Event \| `admiral/admiral-adtte` \| (planned) \|
20
21	ADSL must be derived before any BDS or OCCDS dataset — population flags and
22	treatment variables from ADSL are merged into all downstream datasets.
23
24	---
25
26	## Shared Library Setup
27
28	Every admiral derivation script begins with this setup block. Add dataset-specific
29	libraries (e.g. `metatools`, `tfrmt`) per child skill requirements.
30
31	```r
32	library(admiral)
33	library(dplyr)
34	library(lubridate)
35
36	# For submission-ready output
37	library(metacore)
38	library(xportr)
39
40	# For benchmark reproducibility
41	library(pharmaversesdtm)
42	library(pharmaverseadam)
43	```
44
45	---
46
47	## Pipe and Expression Style
48
49	Always use the native pipe `\|>` — not the magrittr pipe `%>%`. admiral
50	functions accept `\|>` and it is the pharmaverse standard for new code.
51
52	Always use `exprs()` for admiral verb arguments that accept variable lists.
53	The `exprs()` wrapper is required for `by_vars`, `new_vars`, `order`, and
54	`source_vars` arguments in admiral functions. Bare variable names or character
55	strings will not work.
56
57	```r
58	# CORRECT
59	derive_vars_merged(
60	by_vars = exprs(STUDYID, USUBJID),
61	new_vars = exprs(TRTSDT = EXSTDT),
62	order = exprs(EXSTDT)
63	)
64
65	# WRONG — does not work with admiral
66	derive_vars_merged(
67	by_vars = c("STUDYID", "USUBJID"),
68	new_vars = c(TRTSDT = EXSTDT)
69	)
70	```
71
72	---
73
74	## Date Derivation Rules
75
76	**Never use `as.Date()`, `as.POSIXct()`, or `convert_dtc_to_date()` directly
77	on `--DTC` variables.** These silently return `NA` for partial dates (e.g.
78	`"2023-06"`, `"2023"`) without any warning.
79
80	Always use the admiral date functions:
81
82	\| Goal \| Function \|
83	\|---\|---\|
84	\| `--DTC` → Date variable \| `derive_vars_dt()` \|
85	\| `--DTC` → Datetime variable \| `derive_vars_dtm()` \|
86	\| Study day from dates \| `derive_vars_dy()` \|
87	\| Treatment duration \| `derive_var_trtdurd()` \|
88
89	### Imputation direction
90
91	\| Date type \| Rule \| admiral argument \|
92	\|---\|---\|---\|
93	\| Start dates (TRTSDT, ADT for start events) \| Impute to earliest \| `date_imputation = "first"` \|
94	\| End dates (TRTEDT, EOSDT) \| Impute to latest \| `date_imputation = "last"` \|
95	\| Time when absent — start \| `"00:00:00"` \| `time_imputation = "first"` \|
96	\| Time when absent — end \| `"23:59:59"` \| `time_imputation = "last"` \|
97
98	Always use `flag_imputation = "auto"` — this auto-generates `--DTF` and
99	`--TMF` imputation flag variables. Never suppress imputation flags.
100
101	```r
102	# Correct date derivation pattern
103	source_dt <- source_domain \|>
104	derive_vars_dt(
105	dtc = XXDTC,
106	new_vars_prefix = "XX",
107	date_imputation = "first",
108	flag_imputation = "auto"
109	)
110	```
111
112	### Study day convention
113
114	CDISC study day: Day 1 is the reference date; there is no Day 0. Always use
115	`derive_vars_dy()`. Never compute manually with `date2 - date1`.
116
117	---
118
119	## Flag Variable Convention
120
121	Flag variables must be `"Y"` or `NA` — never `"N"`.
122
123	This applies to all flag types: population flags (`--FL`), baseline flags
124	(`ABLFL`), analysis flags (`ANL01FL`), and any other indicator variable.
125
126	```r
127	# CORRECT
128	mutate(SAFFL = if_else(has_dose, "Y", NA_character_))
129
130	# WRONG — violates CDISC ADaM convention
131	mutate(SAFFL = if_else(has_dose, "Y", "N"))
132	```
133
134	When using `derive_var_merged_exist_flag()`, always set both:
135	- `true_value = "Y"`
136	- `false_value = NA_character_`
137	- `missing_value = NA_character_`
138
139	---
140
141	## DOMAIN Variable Removal
142
143	Remove `DOMAIN` from source datasets before passing to `derive_vars_merged()`.
144	admiral errors if a variable exists in both the input dataset and the source.
145
146	```r
147	# Pattern for ADSL and all BDS derivations
148	adsl <- adsl \|>
149	derive_vars_merged(
150	dataset_add = select(ex, -DOMAIN),
151	by_vars = exprs(STUDYID, USUBJID),
152	...
153	)
154	```
155
156	This applies to all SDTM source domains — EX, DS, VS, LB, AE, etc.
157
158	---
159
160	## QC Patterns
161
162	### Uniqueness assertions
163
164	Use `stopifnot()` to assert structural assumptions before proceeding. These
165	catch data quality issues earl

People who liked this also viewed

6 picks

Type