Required Packages

The examples of this vignette require the following packages.

library(admiral)
library(admiralneuro)
library(pharmaversesdtm)
library(dplyr)
library(lubridate)
library(stringr)

Read in Data

To start, all data frames needed for the creation of ADNV should be loaded into the global environment. Reading data will usually be a company specific process, however, for the purpose of this vignette, we will use example data from {pharmaversesdtm} and {admiralneuro}. We will utilize NV and ADSL for the basis of the Nervous System Analysis dataset.

nv <- pharmaversesdtm::nv_neuro %>%
  convert_blanks_to_na()

adsl <- admiralneuro::adsl_neuro %>%
  convert_blanks_to_na()

Initial Setup

The following steps are used to merge ADSL variables with the source data NV, followed with filtering to retain only UPSIT records. Common analysis variables such as Analysis Date (ADT) and Relative Analysis Day (ADY) can also be derived during this process. Note that only the sections relevant to this vignette are included in the steps below. To get detailed guidance on all the steps, refer to the {admiral} Creating a BDS Finding ADaM vignette.

adsl_vars <- exprs(AGE, SEX, TRTSDT, TRTEDT, TRT01A, TRT01P)

adnv <- nv %>%
  derive_vars_merged(
    dataset_add = adsl,
    new_vars = adsl_vars,
    by_vars = exprs(STUDYID, USUBJID)
  ) %>%
  filter(NVTESTCD == "UPSIT") %>%
  derive_vars_dt(
    new_vars_prefix = "A",
    dtc = NVDTC
  ) %>%
  derive_vars_dy(reference_date = TRTSDT, source_vars = exprs(ADT))

param_lookup <- tibble::tribble(
  ~NVTESTCD, ~NVCAT, ~PARAMCD, ~PARAM, ~PARAMN,
  "UPSIT", "OLFACTORY FUNCTION", "UPSITTS", "UPSIT Combined Score from 40 Odorant", 1
)

adnv <- adnv %>%
  derive_vars_merged_lookup(
    dataset_add = param_lookup,
    new_vars = exprs(PARAMCD, PARAM, PARAMN),
    by_vars = exprs(NVTESTCD, NVCAT)
  )

adnv <- adnv %>%
  mutate(
    AVAL = NVSTRESN,
    AVALC = if_else(
      is.na(NVSTRESN) | as.character(NVSTRESN) != NVSTRESC,
      NVSTRESC,
      NA
    )
  )

if (all(is.na(adnv$AVALC))) {
  adnv <- adnv %>% select(-AVALC)
}

Convert UPSIT Score to Percentile

The UPSIT (University of Pennsylvania Smell Identification Test) is a standardized test that measures olfactory function using 40 odor identification items. The raw UPSIT score ranges from 0 to 40, with higher scores indicating better olfactory function.

To enable meaningful interpretation across different age and sex groups, raw UPSIT scores can be converted to percentiles based on normative data. These percentiles represent where an individual’s performance ranks relative to age- and sex-matched peers.

In the following steps, we will incorporate the conversion from UPSIT total score to percentile using the function admiralneuro::compute_upsit_percentile().

1. Define the Source Variables

The first step is to define keep_vars, which lists the source variables to retain and copy into newly derived records in the next step; all other variables will remain in the dataset but will be set to NA in those derived rows.

2. Convert UPSIT Score to Percentile

The second step creates new analysis records in which the original UPSITTS values are converted into percentiles using admiralneuro::compute_upsit_percentile(). The conversion is based on the patient’s sex and age at the time of assessment.

The new parameter values which include AVAL, PARAMCD, PARAM, and PARAMN are assigned for the percentile parameter.

keep_vars <- c(
  get_admiral_option("subject_keys"),
  adsl_vars,
  exprs(ADT, ADY, VISIT)
)

# Prepare derived rows
upsit_percentile <- adnv %>%
  filter(PARAMCD == "UPSITTS") %>%
  mutate(
    AVAL = compute_upsit_percentile(
      sex = SEX,
      age = AGE,
      upsit_score = AVAL
    ),
    PARAMCD = "UPSITPC",
    PARAM = "Percentile derived from UPSIT total score",
    PARAMN = 2,
    AVALU = NA
  )

# Bind with original dataset
adnv <- bind_rows(adnv, upsit_percentile)

# Drop AVALU because it contains no non-missing values
if (all(is.na(adnv$AVALU))) {
  adnv <- adnv %>% select(-AVALU)
}

This is how the parameters and newly converted parameters will look like:

adnv <- adnv %>%
  restrict_derivation(
    derivation = derive_vars_crit_flag,
    args = params(
      crit_nr = 1,
      condition = if_else(PARAMCD == "UPSITPC", AVAL <= 10, NA),
      description = "UPSITPC <= 10",
      values_yn = TRUE # To get "Y", "N", and NA for the flag
    ),
    filter = PARAMCD == "UPSITPC"
  )

Remaining Analysis Dataset Set-up

The {admiral} Creating a BDS Finding ADaM vignette covers all the steps that are not shown here, such as merging the timing variables, analysis flags, baseline derivations, change from baseline calculations, etc.

References

University of Pennsylvania Smell Identification Test. (n.d.). In Wikipedia. Retrieved from https://en.wikipedia.org/wiki/University_of_Pennsylvania_Smell_Identification_Test

Brumm, M. C. et al. (2023). Updated Percentiles for the University of Pennsylvania Smell Identification Test in Adults 50 Years of Age and Older. Neurology, 100(16), e1691–e1701.

Mastenbroek, S. E. et al. (2025). Two-step detection of Lewy body pathology via smell-function testing and CSF α-synuclein seed amplification. Nature Communications, 16, 7182.