MSprog: Assess multiple sclerosis disability course from longitudinal...

In msprog: Reproducible Assessment of Disability Course in Multiple Sclerosis

Assess multiple sclerosis disability course from longitudinal data.

Description

Detect and characterise confirmed disability worsening (CDW) or improvement (CDI) events of an outcome measure (EDSS, NHPT, T25FW, or SDMT; or any custom outcome) based on repeated assessments through time (and on the dates of acute episodes, if any). The events are detected sequentially by scanning the outcome values in chronological order. Several qualitative and quantitative options are given as arguments that can be set by the user and reported as a complement to the results to ensure reproducibility.

Usage

MSprog(
  data,
  subj_col,
  value_col,
  date_col,
  outcome,
  relapse = NULL,
  rsubj_col = NULL,
  rdate_col = NULL,
  renddate_col = NULL,
  subjects = NULL,
  delta_fun = NULL,
  worsening = NULL,
  event = c("firstCDW", "firstCDI", "multiple", "firstPIRA", "firstRAW", "first"),
  RAW_PIRA = FALSE,
  baseline = c("fixed", "roving", "roving_impr", "roving_wors"),
  proceed_from = c("firstconf", "event"),
  sub_threshold_rebl = c("none", "change", "improvement", "worsening"),
  bl_geq = FALSE,
  relapse_rebl = FALSE,
  skip_local_extrema = c("none", "strict", "all"),
  validconf_col = NULL,
  conf_days = 12 * 7,
  conf_tol_days = c(7, 2 * 365.25),
  require_sust_days = 0,
  check_intermediate = TRUE,
  relapse_to_bl = 30,
  relapse_to_event = 0,
  relapse_to_conf = 30,
  relapse_assoc = 90,
  relapse_indep = NULL,
  impute_last_visit = 0,
  date_format = NULL,
  include_dates = FALSE,
  include_values = FALSE,
  include_stable = TRUE,
  verbose = 1
)

Arguments

data	Data frame containing longitudinal data, including: subject IDs, outcome values, visit dates.
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 custom delta_fun and worsening). When it's not set to "custom", outcome type triggers internal checks on value range, determines the direction of worsening (see worsening argument), and selects the default definition of clinically meaningful change given the reference value (using the built-in function compute_delta()). The latter can be replaced by a custom function using the delta_fun argument.
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 relapse onset date column in the relapse data frame, if different from the date column in data.
renddate_col	Name of relapse end date column in the relapse data frame (if applicable).
subjects	Subset of subjects (a vector or list of IDs). If none is specified, all subjects listed in data are included.
delta_fun	Custom function specifying the minimum clinically meaningful change in the outcome measure from the provided reference value. The function provided must take a numeric value (reference score) as input, and return a numeric value corresponding to the minimum shift from baseline, see example below. If outcome is set to "custom", a custom delta function must be specified by the user. For other values of outcome, if no delta_fun is specified, the built-in function compute_delta() is used internally.
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".
event	Character string specifying which events to detect. Must be one of the following. "firstCDW" (first CDW, default). "firstCDI" (first CDI). "multiple" (all confirmed events in chronological order). "firstPIRA" (first progression independent of relapse activity, PIRA). "firstRAW" (first relapse-associated worsening, RAW). "first" (only the very first confirmed event – CDI or CDW).
RAW_PIRA	If TRUE, further classify CDW events based on their timing with respect to relapses (RAW, PIRA). The argument is ignored if event is set to "firstCDI" (not relevant) or to "firstRAW"/"firstPIRA" (always enabled).
baseline	Specifies the baseline scheme. Must be one of the following. "fixed": first eligible outcome value; recommended for randomised data (default). "roving": updated after each CDI or CDW event to the visit determined by proceed_from; suitable for a multiple-event setting (i.e., when event is set to "multiple") or when searching for a specific type of CDW (i.e., when event is set to "firstPIRA" or "firstRAW"). "roving_impr": updated after every CDI (to the visit determined by proceed_from); suitable for a first-CDW setting to discard fluctuations around baseline; not recommended for multiple events. "roving_wors": updated after every CDW (to the visit determined by proceed_from); suitable when searching for a specific type of CDW (i.e., when event is set to "firstPIRA" or "firstRAW").
proceed_from	After detecting a confirmed disability event, continue searching: from the next visit after the first qualifying confirmation visit if proceed_from="firstconf" from the next visit after the event onset if proceed_from="event". If baseline is set to "roving", "roving_impr", or "roving_wors", when rebaselining after a confirmed disability event, the baseline is moved to: the first qualifying confirmation visit if proceed_from="firstconf" the event visit if proceed_from="event".
sub_threshold_rebl	This argument is only used if baseline is not set to "fixed". It controls whether and which "sub-threshold" events (i.e., confirmed changes in the outcome measure below the clinically meaningful threshold) can trigger a re-baseline. Must be one of the following. "none" (default): only use clinically meaningful confirmed changes for re-baseline. "change": any confirmed sub-threshold change can potentially trigger a re-baseline. "improvement": any confirmed sub-threshold improvement can potentially trigger a re-baseline. "worsening": any confirmed sub-threshold worsening can potentially trigger a re-baseline. See delta_fun argument and compute_delta() function for more details.
bl_geq	This argument is only used if relapse-based re-baseline is enabled (relapse_rebl=TRUE). If TRUE, the new reference value must always be greater or equal than the previous one; when it is not, the old reference value is assigned to it [2].
relapse_rebl	If TRUE, re-baseline after every relapse [2].
skip_local_extrema	This argument is only used if the baseline is moved. It controls re-baseline behaviour in the presence of local minima or maxima. A visit i is a local minimum point for outcome x if x[i+1]>x[i] and x[i-1]>x[i]. Local maxima are defined similarly. A visit i is a strict local minimum point for outcome x if x[i+1]-x[i]>=delta_fun(x[i]); x[i-1]-x[i]>=delta_fun(x[i]). Strict local maxima are defined similarly. When x[i]=x[i-2], visit i is not considered a local extremum point even if the above conditions hold. This controls for cases where the outcome has an undulating course. The following argument values are accepted. "none" (default): local extrema are always accepted as valid baseline values. "strict": the baseline cannot be placed at a strict local minimum or maximum. "all": the baseline cannot be placed at a local minimum or maximum.
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 detects events 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 (upper tolerance) may 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 a confirmed change must be sustained (i.e., confirmed at all visits occurring in the specified period) to be retained as an event. Events sustained for the remainder of the follow-up period are always retained regardless of follow-up duration. If require_sust_days=Inf, events are retained only when sustained for the remainder of the follow-up period. (Warning: if check_intermediate is set to FALSE, sustained change will be established based only on the end of the specified period.)
check_intermediate	If TRUE (default), events are confirmed over all intermediate visits up to the confirmation visit. If set to FALSE (not recommended in most cases, as it may discard meaningful fluctuations), events will be confirmed only at the specified confirmation visit (and only at the end of the period defined by require_sust_days, if any).
relapse_to_bl	Minimum distance (days) from the onset of a relapse for a visit to be used as baseline. 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 keeping the baseline where it is regardless of surrounding relapses. If relapse end dates are available (renddate_col), the minimum distance from last relapse onset is automatically set to the specific relapse duration, unless relapse_to_bl (or relapse_to_bl[1]) is zero (in which case relapse timing does not affect baseline placement). If the designated baseline does not satisfy this constraint, the baseline is moved to the next available visit.
relapse_to_event	Minimum distance (days) from the onset of a relapse for an event to be considered as such. 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. If relapse end dates are available (renddate_col), the minimum distance from last relapse onset is automatically set to the specific relapse duration, unless relapse_to_event (or relapse_to_event[1]) is zero (in which case relapse timing does not affect event validation).
relapse_to_conf	Minimum distance (days) from the onset of a relapse for a visit to be an eligible 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. If relapse end dates are available (renddate_col), the minimum distance from last relapse onset is automatically set to the specific relapse duration, unless relapse_to_conf (or relapse_to_conf[1]) is zero (in which case relapse timing does not affect selection of confirmation visits).
relapse_assoc	Maximum distance (days) from the onset of a relapse for a CDW event to be classified as RAW. Can be an integer (maximum distance from last relapse onset) or vector of length 2 (maximum distance from last relapse onset, maximum distance from next relapse onset). If relapse end dates are available (renddate_col), the maximum distance from last relapse is automatically set to the specific relapse duration. The argument is ignored if RAW events are not detected (e.g., if event="firstCDW" and RAW_PIRA=FALSE).
relapse_indep	Specifies relapse-free intervals for PIRA definition. Must be a named list list(prec=list(p0, p1), event=list(e0, e1), conf=list(c0, c1)) specifying the intervals around (any subset of) three checkpoints: a preceding visit, e.g., baseline or last visit before the worsening (p0 and p1) the event onset (e0 and e1) an eligible confirmation visit (c0 and c1). The auxiliary function relapse_indep_from_bounds() can be used to organise interval bounds into a named list correctly, by calling: relapse_indep_from_bounds(p0, p1, e0, e1, c0, c1) See relapse_indep_from_bounds() function docs for more details on how to define the intervals. If relapse end dates are available (renddate_col), it is possible to also define PIRA based on those by setting use_end_dates=TRUE in relapse_indep_from_bounds(). The argument is ignored if PIRA events are not detected (e.g., if event="firstCDW" and RAW_PIRA=FALSE).
impute_last_visit	Imputation probability for worsening events occurring at the last available visit (i.e., with no confirmation). Unconfirmed worsening events occurring 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 worsening events 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.
include_dates	If TRUE, output$results will include the dates of: event onset ("date" column) the initial baseline ("initial_bl_date" column) the current baseline ("bl_date" column) the last visit before event onset with a clinically meaningful score difference from it ("last_delta_date" column) the confirmation visit(s) ("conf<c>_date" column and, when relevant, "PIRA_conf<c>_date" column for each c in conf_days)
include_values	If TRUE, output$results will include the outcome value at: event onset ("value" column) the initial baseline ("initial_bl_value" column) the current baseline ("bl_value" column) the last visit before event onset with a clinically meaningful score difference from it ("last_delta_value" column) the confirmation visit(s) ("conf<c>_value" column and, when relevant, "PIRA_conf<c>_value" column for each c in conf_days)
include_stable	If TRUE, subjects with no confirmed events are included in output$results, with time2event = total follow up.
verbose	One of: 0 (print no info); 1 (print concise info, default); 2 (print extended info).

Value

An object of class MSprogOutput with the following attributes:

• event_count: a data frame containing event counts for each subject (and the event sequence in case of multiple events).

• results: a data frame with extended info on each event for all subjects.

• settings: a list containing all the arguments used to compute the output.

• unconfirmed: a data frame with info on unconfirmed events (initial change from baseline, but no confirmation) for all subjects.

For a detailed description of output data frames, see ?MSprogOutput.

References

[1] Müller J, Cagol A, Lorscheider J, Tsagkas C, Benkert P, Yaldizli Ö, et al. Harmonizing definitions for progression independent of relapse activity in multiple sclerosis: A systematic review. JAMA Neurol. 2023;80:1232–45.

[2] Kappos L, Wolinsky JS, Giovannoni G, Arnold DL, Wang Q, Bernasconi C, et al. Contribution of relapse-independent progression vs relapse-associated worsening to overall confirmed disability accumulation in typical relapsing multiple sclerosis in a pooled analysis of 2 randomized clinical trials. JAMA Neurol. 2020;77:1132–40.

Examples

# 1. EDSS course
output <- MSprog(toydata_visits, subj_col="id", value_col="EDSS", date_col="date", outcome="edss",
    relapse=toydata_relapses, conf_days=12*7, conf_tol_days=30,
    event="multiple", baseline="roving", verbose=1)
print(output$results) # extended info on each event for all subjects
print(output$event_count) # event counts for each subject
# 2. SDMT course
output <- MSprog(toydata_visits, subj_col="id", value_col="SDMT", date_col="date", outcome="sdmt",
    relapse=toydata_relapses, conf_days=12*7, conf_tol_days=30,
    event="multiple", baseline="roving", verbose=1)
print(output$results) # extended info on each event for all subjects
print(output$event_count) # event counts for each subject
# 3. SDMT course, with a custom delta function
my_sdmt_delta <- function(reference_value) {min(c(reference_value/10, 3))}
output <- MSprog(toydata_visits, subj_col="id", value_col="SDMT", date_col="date", outcome="sdmt",
    delta_fun=my_sdmt_delta,
    relapse=toydata_relapses, conf_days=12*7, conf_tol_days=30,
    event="multiple", baseline="roving", verbose=1)
print(output$results) # extended info on each event for all subjects
print(output$event_count) # event counts for each subject

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