derive_var_nfrlt: Derive Nominal Relative Time from First Dose (NFRLT)

In admiral: ADaM in R Asset Library

Derive Nominal Relative Time from First Dose (NFRLT)

Description

Derives nominal/planned time from first dose in hours by combining visit day information with timepoint descriptions. The function converts timepoint strings to hours using convert_xxtpt_to_hours() and adds them to the day-based offset. Optionally creates a corresponding unit variable.

Usage

derive_var_nfrlt(
  dataset,
  new_var = NFRLT,
  new_var_unit = NULL,
  out_unit = "HOURS",
  tpt_var = NULL,
  visit_day,
  first_dose_day = 1,
  treatment_duration = 0,
  range_method = "midpoint",
  set_values_to_na = NULL
)

Arguments

dataset	Input dataset containing visit day variable and optionally timepoint variable.
new_var	Name of the new variable to create (unquoted). Default is NFRLT.
new_var_unit	Name of the unit variable to create (unquoted). If specified, a character variable will be created containing the unit of time exactly as provided in out_unit. Common CDISC variables are FRLTU (First Dose Relative Time Unit) or RRLTU (Reference Relative Time Unit). If not specified, no unit variable is created.
out_unit	Unit of time for the output variable. Options are: Days: "day", "days", "d" Hours: "hour", "hours", "hr", "hrs", "h" (default: "hours") Minutes: "minute", "minutes", "min", "mins" Weeks: "week", "weeks", "wk", "wks", "w" Case-insensitive. The internal calculation is performed in hours, then converted to the specified unit. If new_var_unit is specified, it will contain the value exactly as provided by the user.
tpt_var	Timepoint variable containing descriptions like "Pre-dose", "1H Post-dose", etc. (unquoted). If not provided or if the variable doesn't exist in the dataset, only the visit day offset is calculated (timepoint contribution is 0).
visit_day	Visit day variable (unquoted). This should be the planned/ nominal visit day (e.g., VISITDY). Records with NA in this variable will have NFRLT set to NA.
first_dose_day	The day number considered as the first dose day. Default is 1. For multiple-dose studies, this is typically Day 1.
treatment_duration	Duration of treatment in hours. Can be either: A numeric scalar (used for all records), or An unquoted variable name from the dataset (e.g., EXDUR) where each record can have a different treatment duration Passed to convert_xxtpt_to_hours(). Must be non-negative. Default is 0 hours (for instantaneous treatments like oral medications).
range_method	Method for converting time ranges to single values. Options are "midpoint" (default), "start", or "end". Passed to convert_xxtpt_to_hours(). For example, "0-6h" with midpoint returns 3, with start returns 0, with end returns 6.
set_values_to_na	An optional condition that marks derived NFRLT values as NA. For example, set_values_to_na = VISIT == "UNSCHEDULED" will set NFRLT to NA for all unscheduled visits. Can use any variables in the dataset. When new_var_unit is specified, the unit variable will also be set to NA for these records.

Details

The nominal relative time is calculated as:

NFRLT = (day_offset * 24 + timepoint_hours) * conversion_factor

Where:

• day_offset is calculated from visit_day and first_dose_day, accounting for the absence of Day 0 in clinical trial convention

• timepoint_hours is derived from the timepoint description using convert_xxtpt_to_hours(), or 0 if tpt_var is not provided

• conversion_factor is:

  • 1 for "hours" (default)

  • 1/24 for "days"

  • 1/168 for "weeks" (1/24/7)

  • 60 for "minutes"

If new_var_unit is specified, a character variable is created containing the value of out_unit exactly as provided by the user. For example:

• out_unit = "hours" creates unit variable with value "hours"

• out_unit = "HOURS" creates unit variable with value "HOURS"

• out_unit = "Days" creates unit variable with value "Days"

• NA when the corresponding time value is NA

This matches the behavior of derive_vars_duration() and allows consistency when deriving multiple time variables.

Handling "No Day 0":

In clinical trials, day numbering typically follows the convention: ..., Day -2, Day -1, Day 1, Day 2, ... (no Day 0). This function accounts for this by adjusting the day offset when visit_day is negative and first_dose_day is positive.

For example, with first_dose_day = 1 and different output units:

• Day -1, out_unit = "hours" -> -24 hours

• Day -1, out_unit = "days" -> -1 day

• Day -1, out_unit = "weeks" -> -0.1429 weeks

• Day -1, out_unit = "minutes" -> -1440 minutes

• Day -7 -> -168 hours, -7 days, -1 week, or -10080 minutes

• Day 1 -> 0 (in any unit, first dose day)

• Day 8 -> 168 hours, 7 days, 1 week, or 10080 minutes

With first_dose_day = 7:

• Day -1 -> -168 hours, -7 days, -1 week, or -10080 minutes

• Day 1 -> -144 hours, -6 days, -0.857 weeks, or -8640 minutes

• Day 6 -> -24 hours, -1 day, -0.143 weeks, or -1440 minutes

• Day 7 -> 0 (in any unit, first dose day)

Common Use Cases:

• Single dose study: Day 1 only, with samples at various timepoints (e.g., Pre-dose, 1H, 2H, 4H, 8H, 24H)

• Multiple dose study: Dosing on multiple days (e.g., Day 1, Day 8, Day 15) with samples around each dose

• Screening visits: Negative visit days (e.g., Day -14, Day -7) before first dose

• Steady state study: Multiple daily doses with sampling on specific days

• Oral medications: Use default treatment_duration = 0 for instantaneous absorption

• IV infusions: Specify treatment_duration as infusion duration in hours (scalar) or as a variable name containing duration per record

• Exposure records (EX): Can be called without tpt_var to derive NFRLT based only on visit day

• Unscheduled visits: Use set_values_to_na to set NFRLT to NA for unscheduled or early discontinuation visits

• Variable treatment durations: Use a variable name (e.g., EXDUR) when different subjects or visits have different treatment durations

• Hours output: Use out_unit = "hours" (default) for variables like NFRLT with FRLTU

• Days output: Use out_unit = "days" for variables like NFRLTDY with FRLTU

• Weeks output: Use out_unit = "weeks" for long-term studies with weekly dosing

• Minutes output: Use out_unit = "minutes" for very short-term PK studies or when minute precision is needed

• CDISC compliance: Use new_var_unit = FRLTU for first dose relative time or new_var_unit = RRLTU for reference relative time

• Consistency with duration: Use the same case for out_unit across derive_vars_duration() and derive_var_nfrlt() to ensure unit variables match

Important Notes:

• The function assumes visit_day represents the nominal/planned day, not the actual study day

• Day numbering follows clinical trial convention with no Day 0

• For timepoints that span multiple days (e.g., "24H Post-dose"), ensure visit_day is set to the day when the sample was taken. For example, if dosing occurs on Day 3, a "24H Post-dose" sample taken on Day 4 should have visit_day = 4.

• For crossover studies, consider deriving NFRLT separately per period

• NA values in visit_day will automatically result in NA for NFRLT (no need to use set_values_to_na for this case)

• NA values in tpt_var will result in NA for NFRLT

• NA values in the treatment_duration variable (if using a variable) will result in NA for NFRLT for those records

• Use set_values_to_na when you need to set NFRLT to NA based on other variables (e.g., VISIT == "UNSCHEDULED"), especially when visit_day is populated but should not be used for the NFRLT calculation

• If tpt_var is not provided or doesn't exist in the dataset, timepoint contribution is assumed to be 0 hours

• When using non-hour units, timepoint contributions are still calculated in hours first (e.g., "2H Post-dose" = 2 hours), then the entire result is converted to the specified unit

• The unit variable (if created) will contain the exact value provided in out_unit, preserving case and format

Setting Special Values:

If you need to set NFRLT to a specific value (e.g., 99999) for certain visits instead of NA, use set_values_to_na first to set them to NA, then use a subsequent mutate() call to replace those NA values:

dataset %>%
  derive_var_nfrlt(
    ...,
    set_values_to_na = VISIT == "UNSCHEDULED"
  ) %>%
  mutate(NFRLT = if_else(is.na(NFRLT) & VISIT == "UNSCHEDULED", 99999, NFRLT))

Value

The input dataset with the new nominal relative time variable added, and optionally the unit variable if new_var_unit is specified.

See Also

convert_xxtpt_to_hours(), derive_vars_duration()

BDS-Findings Functions that returns variable appended to dataset: derive_basetype_records(), derive_var_analysis_ratio(), derive_var_anrind(), derive_var_atoxgr(), derive_var_atoxgr_dir(), derive_var_base(), derive_var_chg(), derive_var_ontrtfl(), derive_var_pchg(), derive_var_shift(), derive_vars_crit_flag()

admiral documentation built on May 28, 2026, 9:08 a.m.