value_milestone: Time to disability milestone.

In msprog: Reproducible Assessment of Disability Course in Multiple Sclerosis

Time to disability milestone.

Description

Scan the visits in chronological order to detect the first outcome value reaching or exceeding a specified disability milestone (e.g., EDSS>=6), with confirmation.

Usage

value_milestone(
  data,
  milestone,
  subj_col,
  value_col,
  date_col,
  outcome,
  worsening = NULL,
  relapse = NULL,
  rsubj_col = NULL,
  rdate_col = NULL,
  validconf_col = NULL,
  conf_days = 12 * 7,
  conf_tol_days = c(7, 2 * 365.25),
  require_sust_days = 0,
  relapse_to_event = 0,
  relapse_to_conf = 30,
  impute_last_visit = 0,
  date_format = NULL,
  verbose = 0
)

Arguments

data	Data frame containing longitudinal data, including: subject IDs, outcome values, visit dates.
milestone	Disability milestone (outcome value to check data against).
subj_col	Name of data column with subject IDs.
value_col	Name of data column with outcome values.
date_col	Name of data column with visit dates.
outcome	Specifies the outcome type. Must be one of the following: "edss" (Expanded Disability Status Scale) "nhpt" (Nine-Hole Peg Test) "t25fw" (Timed 25-Foot Walk) "sdmt" (Symbol Digit Modalities Test) "custom" (only accepted when specifying argument worsening). When it's not set to "custom", outcome type triggers internal checks on value range and determines the direction of worsening (see worsening argument).
worsening	The direction of worsening ("increase" if higher values correspond to worse disease course, "decrease" otherwise). The given value is only used when outcome is set to "custom". Otherwise, worsening is automatically set to "increase" if outcome is set to "edss", "nhpt", "t25fw", and to "decrease" if outcome is set to "sdmt".
relapse	Optional data frame containing longitudinal data, including subject IDs and relapse onset dates.
rsubj_col	Name of subject ID column in the relapse data frame, if different from the one in data.
rdate_col	Name of date column in the relapse data frame, if different from the date column in data.
validconf_col	Name of data column, if any, specifying which visits can (TRUE) or cannot (FALSE) be used as confirmation visits. If not specified (validconf_col=NULL), all visits are potentially used as confirmation visits.
conf_days	Period before confirmation (days). Can be a single value, or vector of any length if considering multiple windows. If length(conf_days) > 1 (e.g., conf_days=c(12*7, 24*7)), the function retains milestones confirmed at either time point (e.g., "confirmed over 12 or 24 weeks") with their relative tolerance (as per conf_tol_days).
conf_tol_days	Tolerance window for confirmation visit (days); can be an integer (equal lower and upper tolerance) or vector of length 2 (different lower and upper tolerance). The right end of the interval can be set to Inf (confirmation window unbounded on the right – e.g., "confirmed over 12 or more weeks").
require_sust_days	Minimum number of days over which the milestone must be sustained (i.e., confirmed at all visits occurring in the specified period). If the milestone is sustained for the remainder of the follow-up period, it is considered reached regardless of follow-up duration. If require_sust_days=Inf, values are retained only when sustained for the remainder of the follow-up period.
relapse_to_event	Minimum distance (days) from the onset of a relapse for the milestone to be considered reached. Can be an integer (minimum distance from last relapse onset) or vector of length 2 (minimum distance from last relapse onset, minimum distance from next relapse onset). Note that setting the distance to zero means retaining the event regardless of surrounding relapses.
relapse_to_conf	Minimum distance (days) from the onset of a relapse for a visit to be a valid confirmation visit. Can be an integer (minimum distance from last relapse onset) or vector of length 2 (minimum distance from last relapse onset, minimum distance from next relapse onset). Note that setting the distance to zero means using any visit for confirmation regardless of surrounding relapses.
impute_last_visit	Imputation probability when the milestone is reached at the last available visit (i.e., with no confirmation). Unconfirmed values exceeding the milestone at the last visit are never imputed if impute_last_visit=0; they are always imputed if impute_last_visit=1; they are imputed with probability p, ⁠0<p<1⁠, if impute_last_visit=p. If a value N>1 is passed, unconfirmed values exceeding the milestone are imputed only if occurring within N days of follow-up (e.g., in case of early discontinuation).
date_format	Format of dates in the date_col and rdate_col columns of the input data. Can be specified as: Standard format for dates (e.g., "%d-%m-%Y"; see strptime() docs for correct syntax). "day" if dates in are given as "days from start" (the starting point can be different for each subject – e.g., days from randomisation in a clinical trial); negative values are accepted. If not specified, function as.Date() will try to infer it automatically.
verbose	One of: 0 (print no info) 1 (print concise info, default) 2 (print extended info).

Details

• "Reaching or exceeding" means either value>=milestone or value<=milestone, depending on the direction of worsening (see arguments outcome and worsening).

• An event is only considered "observed" if confirmed, i.e., if all values up to the confirmation visit reach or exceed the milestone.

Value

A data frame containing the following columns:

• ⁠<date_col>⁠: the date of first reaching or exceeding the milestone with confirmation (or last date of follow-up if milestone is not reached or not confirmed).

• ⁠<value_col⁠: the first value reaching or exceeding the milestone with confirmation, if present, otherwise no value.

• "time2event": the time taken to reach or exceed the milestone (or total follow-up length if milestone is not reached or not confirmed).

• "observed": whether the milestone was reached with confirmation (1) or not (0).

msprog documentation built on Sept. 4, 2026, 5:08 p.m.