msprog
Reproducible Assessment of Disability Course in Multiple Sclerosis

Package index
Search the msprog package
Vignettes
Functions
15
Source code
10
Man pages
9
Home
/
CRAN
/
msprog
/
Analysing disability course in MS

Analysing disability course in MS
In msprog: Reproducible Assessment of Disability Course in Multiple Sclerosis 

knitr::opts_chunk$set(
  collapse=TRUE,
  comment="#>"
)

library(knitr)
hook_output = knit_hooks$get("output")
knit_hooks$set(output = function(x, options) {
  # this hook is used only when the linewidth option is not NULL
  if (!is.null(n <- options$linewidth)) {
    x = xfun::split_lines(x) #substring(x, 4, nchar(x)))
    # any lines wider than n should be wrapped
    if (any(nchar(x) > n)) x = strwrap(x, width = n)
    x = paste0(paste(x, collapse = "\n#> "), "\n")
  }
  hook_output(x, options)
})

This vignette illustrates how to use the msprog package to analyse the evolution of disability in multiple sclerosis (MS) based on repeated assessments through time of an outcome measure (EDSS, NHPT, T25FW, SDMT; or any custom outcome measure). We'll start by illustrating the type of input data needed, and by giving a minimal working example to introduce the main function and facilitate the reading of the document. We'll then move on to a more detailed description of the different parameter configurations.

library(msprog)

Input data {#input}

The data must be organised in a data frame object containing (at least) the following columns:

The visits should be listed in chronological order (if they are not, msprog::MSprog() will sort them automatically before analysing them).

The msprog package provides a toy dataset toydata_visits with artificially generated EDSS and SDMT assessments for a small cohort of patients.

head(toydata_visits)


For relapsing MS patients, an additional data frame object with the onset dates of relapses is needed to correctly assess disease course (and possibly to characterise worsening events as relapse-associated or relapse-independent). The dataset should contain (at least) the following columns:

The package provides a toy dataset with artificially generated relapse onset dates associated with the patients in toydata_visits:

head(toydata_relapses)

Dates are interpreted as calendar days (e.g., YYYY-mm-dd) by default, but can optionally be provided as number of days "from start" (starting point can be different across subjects -- e.g., days from randomisation in a clinical trial): see "visit_day" column in the toy datasets, and SDMT example below. Disability assessment dates and relapse dates must be given in the same format.

Minimal example {#example}

The core block of msprog is the MSprog() function. Given data on visits and relapses[^rnames] in the form specified above, MSprog() detects the confirmed disability worsening (CDW) or improvement (CDI) events for each subject for the outcome of interest. If specified, CDW events can be further classified based on their timing with respect to relapses and identified as relapse-associated worsening (RAW) or progression independent of relapse activity (PIRA, see [@lublin2014; @kappos2018; @silent2019]).

[^rnames]: If the names of columns with subject ID and date in the relapse database are different from the main database, they must be specified using arguments rsubj_col and rdate_col.

By default, MSprog() only detects the first CDW. We can test it on the EDSS toy data...

output_edss <- MSprog(data=toydata_visits, # data on visits
                 subj_col="id", value_col="EDSS", date_col="date", # specify column names
                 outcome="edss", # specify outcome type
                 relapse=toydata_relapses) # data on relapses

...or on the SDMT toy data:

output_sdmt <- MSprog(data=toydata_visits, # data on visits
                 subj_col="id", value_col="SDMT", date_col="visit_day", # specify column names
                 outcome="sdmt", # specify outcome type
                 relapse=toydata_relapses, # data on relapses
                 date_format="day") # specify that dates are given as days

Note that, in the SDMT example, "visit_day" is used as date column. For the MSprog() function to interpret it correctly, we need to specify date_format="day" (note that this also applies to relapse dates).

The function prints out concise info (the verbose argument can be used to control the amount of info printed out -- see the relevant section).

Full tabulation of the results can be accessed via the following attributes of the function output.

  1. results: detailed info on each event for all subjects. In our example:
# print(output_edss$results, row.names=FALSE)
DT::datatable(output_edss$results, rownames=F,
              options = list(dom="t", scrollX=T, scrollY=F, paging = FALSE)
              )

where: `nevent` is the cumulative event count for each subject; `event_type` characterises the event; `total_fu` is the number of days from start to end of follow-up; `time2event` is the number of days from start of follow-up to event[^timeto]; `bl2event` is the number of days from current baseline to event; `sust_days` is the number of days for which the event was sustained; `sust_last` reports whether the event was sustained until the last visit.
  1. event_count: a data frame summarising event counts for each subject. Here's what it looks like for the EDSS-based computation above:
# print(output_edss$event_count)
DT::datatable(output_edss$event_count,
              options = list(dom="t", scrollX=T, scrollY=F, paging = FALSE)
              )

Note. In this example, we called MSprog() without specifying the event argument - which defaults to firstCDW (only detect the first CDW event). For this reason,

  1. In output_edss$results, nevent can only be 0 or 1.
  2. In output_edss$event_count, CDW count can only be 0 or 1, and CDI column is omitted.

In a multiple-event setting (event="multiple"), more than one event per subject can be detected, and event_count also includes the event sequence for each subject. See the relevant section.


Additionally, by applying the print method to the MSprog() output, the user can print out the full list of function arguments, as well as a short paragraph describing the complete set of applied criteria, to be reported to ensure complete reproducibility. In our example:

print(output_edss)

[^timeto]: For subjects with no confirmed events, time2event is the total follow-up length. To omit these subjects, set include_stable=FALSE in MSprog().


Several qualitative and quantitative options for analysing disability evolution are given as optional arguments of MSprog() that can be set by the user. In order to ensure reproducibility, the results should always be complemented by the set of criteria used to obtain them (e.g., using the print method mentioned above). In the following sections we will go into more detail about usage and best practices for the different options. Please refer to the documentation (by typing ?MSprog) for a complete illustration of each of the function arguments and their default values.

Outcome {#outcome}

In MSprog(), outcome type is specified via the mandatory argument outcome. This triggers:

Outcome values are scanned in chronological order, and tested for their difference from the current reference value. Such difference is typically required to be larger than a clinically meaningful threshold $\delta$, depending on the reference value $x$. Default settings are implemented in msprog for the most used disability scales (see [@lorscheider2016; @bosma2010; @kalinowski2022; @strober2019]):

These default options are internally implemented by the compute_delta() function. For example, if the baseline EDSS score is 4, by default a clinically meaningful EDSS worsening will correspond to an increase by (at least):

print(compute_delta(4, outcome="edss"))

If the baseline T25FW score is 10, the minimum clinically relevant change will be:

print(compute_delta(10, outcome="t25fw"))

Customising "clinically relevant change"

The user can provide their own function to customise the computation of clinically relevant thresholds, using the delta_fun argument of MSprog(). The user-defined function must take the baseline value as argument, and return the corresponding threshold. This applies to two scenarios.

  1. The outcome of interest is among the ones listed above, but we want to define the thresholds differently. For example, we want to change the minimum $\delta$ for SDMT to, say, "either 3 points or 10% of the reference value". In this case, we would define: r my_sdmt_delta <- function(x) {min(c(x/10, 3))} Let's compute the minimum clinically relevant change in SDMT score starting from a baseline of 50 using our custom function, and compare it with the default function: r print(my_sdmt_delta(50)) # my delta print(compute_delta(50, outcome="sdmt")) # default delta We can then compute: {r, eval=FALSE} output <- MSprog(... outcome="sdmt", delta_fun=my_sdmt_delta, ...) Specifying outcome="sdmt", the outcomes values will be checked internally to verify that they are in the correct range for SDMT.

  2. The outcome of interest is not among the ones listed above. In this case, we set outcome="custom", and delta_fun as our desired custom-defined function. For custom outcomes, the direction of worsening must be specified as well (i.e., whether increasing or decreasing values of the outcome are interpreted as a worsening). This can be done by setting the worsening argument to either "increase" or "decrease". Note that the provided worsening argument is only used by MSprog() 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".

Baseline scheme

The assessment of the disability evolution strongly depends on the choices made in defining the starting point, i.e., the baseline. Different behaviours are appropriate in different contexts. This aspect is controlled by the baseline argument in MSprog(). The following alternative baseline schemes can be adopted.

Note. If the baseline data is stored in a separate file, the user should merge it with the main data frame containing longitudinal visit data. This can be done by inserting the baseline date and outcome value for each subject at the beginning of the data frame (not necessarily next to the other visits from the same subject -- they will be grouped by subject ID).

Additional options


As already mentioned above, extra caution should be used when applying any re-baseline scheme to randomised data, as moving the reference value based on post-randomisation events can introduce bias (especially if the occurrence of these events is influenced by the treatment). For clinical trial data, general recommendation is to use a fixed baseline (at the time of randomisation).

Multiple events {#multiple}

The event argument allows to specify which events to detect. By default, it is set to "firstCDW" (only detect the first CDW event). It can be set to "multiple" to sequentially detect all CDW or CDI events.

For example, extracting multiple EDSS events for subject 4 from toydata_visits with a fixed baseline would result in the following.

print(toydata_visits[toydata_visits$id==4, c("date", "EDSS")]) # EDSS visits

output <- MSprog(data=toydata_visits, 
                 subj_col="id", value_col="EDSS", date_col="date", outcome="edss", 
                 subjects=4,
                 relapse=toydata_relapses, 
                 event="multiple", baseline="fixed",  # <---
                 verbose=0)
# print(output$results, row.names=FALSE) # results
DT::datatable(output$results, rownames=F,
              options = list(dom="t", scrollX=T, scrollY=F, paging = FALSE)
              )

With these settings, the EDSS improvement at visit 2 (EDSS=3.5, confirmed at visit 3) does not trigger a re-baseline. The algorithm keeps searching for events from after the confirmation visit, evaluating the changes relative to the original baseline (EDSS=4.5). The subsequent EDSS worsening is therefore not detected. On the other hand, adopting a roving baseline scheme we get:

output <- MSprog(data=toydata_visits, 
                 subj_col="id", value_col="EDSS", date_col="date", outcome="edss", 
                 subjects=4,
                 relapse=toydata_relapses, 
                 event="multiple", baseline="roving",  # <---
                 verbose=0)
# print(output$results, row.names=FALSE) # results
DT::datatable(output$results, rownames=F,
              options = list(dom="t", scrollX=T, scrollY=F, paging = FALSE)
              )

The baseline has now been moved to the confirmation visit of the first CDI event (visit 3, EDSS=3.5). With respect to this baseline, a subsequent CDW event is detected at visit 4 (EDSS=5), confirmed at visit 5.


Other valid values for the event argument are:

Note. if, for example, "event=firstPIRA", all non-PIRA events preceding the first PIRA are actually detected -- although not reported. This allows to combine this scenario with a roving baseline scheme, where the baseline is moved after every confirmed non-PIRA event. For instance, if a RAW event occurs first, the subsequent worsening would be counted from the re-baselined outcome value after the RAW.

Event confirmation

An event is only validated if the change in the outcome value from the current baseline is maintained up to[^upto] a subsequent confirmation visit at a pre-specified distance from the event [@ontaneda2017]. The event is confirmed if the difference in the outcome value from the baseline score remains above-threshold at all assessments up to the confirmation visit. For example, with the default EDSS thresholds, an increase in EDSS from 4 points to 6 points is confirmed if EDSS=5 at all subsequent visits; it is not confirmed if EDSS=4.5 at all subsequent visits.

[^upto]: The value change from baseline must also be maintained at all intermediate visits between the event and the confirmation visit. This behaviour may be changed by setting the check_intermediate argument to FALSE (in this case, the change only needs to be confirmed at the designated confirmation visit). We do not recommend this, as it may lead to including random fluctuations as events. We included this option to provide the possibility of replicating the results from previous studies that used this rationale.

The chosen confirmation period depends on the type of study and on the frequency of visits, and can be set in MSprog() by using the conf_days argument. A tolerance interval around conf_days can be specified using the conf_tol_days argument, given as a sequence of two integers (lower and upper tolerance)[^lrtol]. Setting the right end of the interval to Inf allows event confirmation to occur at any visit after conf_days. Let's see two examples.

i. A common setting for clinical trial data would be: conf_days=7*12, conf_tol_days=c(0, Inf), i.e., "confirmation over 12 or more weeks".

ii. A common setting for observational data would be: conf_days=7*24, conf_tol_days=c(0,7*12), i.e., the confirmation visit must lie between 24 weeks after the event, and 36 weeks after the event.

[^lrtol]: conf_tol_days can also be specified as a single integer if symmetric lower and upper tolerance is desired.

Note. "Confirmed over 12 or more weeks" (i.e., no upper bound) $\neq$ "sustained over the whole follow up".
Setting no upper bound to the confirmation interval means that the first visit at least 12 weeks after the initial change is selected as confirmation visit. The confirmation window is then defined as the interval between the initial worsening and that confirmation visit, and scores are checked therein.

Additional options

[^1224]: An event is only confirmed if the value change from baseline is maintained at all visits up to the confirmation visit. So an event can only be "confirmed over 24 weeks" and not "confirmed over 12 weeks" if there are no valid confirmation visits falling within the 12-week window (unless check_intermediate=FALSE).

Sustained CDW or CDI {#sustained}

In addition to event confirmation, some studies require events to be sustained for a specified period of time. The require_sust_days argument allows to specify, if desired, the length of such period. For example, if require_sust_days=7*48, an event is only retained if the change in the outcome measure from the current baseline is confirmed at all visits falling within the following 48 weeks. If the event is sustained for the entire follow-up, it is retained even if the follow-up period ends <48 weeks after the event. Setting require_sust_days=Inf, events are retained only when sustained for the entire follow-up duration.

The require_sust_days argument may be of use in the following scenarios.

Relapse-based classification of CDW events {#rawpira}

Detected CDW events may be further categorised based on their timing with respect to relapses[^reldata] and identified as RAW or PIRA. This has to be explicitly enabled by setting the flag RAW_PIRA=TRUE in MSprog() (unless the endpoint of interest is already firstPIRA or firstRAW). On top of that, the definitions used to label a CDW as RAW or as PIRA are controlled by arguments relapse_assoc and relapse_indep, as detailed below.

[^reldata]: Relapse data is to be provided using the optional relapse argument in MSprog(). It should be given as a data frame containing subject IDs and relapse onset dates (see "Input data"). If the names of columns with subject IDs and dates in the relapse database are different from the main database, they must be specified using arguments rsubj_col and rdate_col.

Relapse-associated worsening (RAW) {#raw}

RAW events are typically defined as CDW events occurring within a specified interval from the onset of a relapse. The length (in days) of such interval can be specified using the relapse_assoc argument in MSprog(). Common values are 30 or 90 days. Additionally, one may also provide a maximum distance from relapses whose onset is after the event. The logic is that the reported onset date of a relapse may be slightly delayed. The examples below illustrate the usage of the relapse_assoc argument:

Progression independent of relapse activity (PIRA) {#pira}

In the literature, PIRA is generally defined as CDW occurring in the absence of relapses within predefined intervals. In most cases (see, e.g., [@kappos2020; @cagol2022; @muller2023]), relapse-free intervals are anchored to (possibly a subset of):

The relapse_indep argument in MSprog() allows to specify custom relapse-free intervals. The auxiliary function relapse_indep_from_bounds() organises the given interval bounds into a named list to be given to MSprog() through the relapse_indep argument. ``` {r, eval=FALSE} output <- MSprog(... relapse_indep=relapse_indep_from_bounds(p0, p1, e0, e1, c0, c1), ...)

where: `p0` and `p1` specify the interval around a visit preceding the event (can be the current reference, the last visit before event onset, or the last visit before event onset with a clinically meaningful score difference from it [^pira]); `e0` and `e1` specify the interval around the event; `c0` and `c1` specify the interval around the confirmation visit; see Figure 1. If both ends of an interval are 0 (e.g., if both `p0=0` and `p1=0`), the checkpoint is ignored. To merge two intervals together, set both the right end of the first interval and the left end of the second interval to `NULL` (e.g., "between baseline and event onset": `p1=NULL` and `e0=NULL`). 

```r
knitr::include_graphics("./relapse_indep_def.png")

For example, in @muller2023, the authors recommend an absence of relapses during the 90 days before and 30 days after the event, and during the 90 days before and 30 days after confirmation for a CDW event to be considered as PIRA. This translates into: p0<-0, p1<-0, e0<-90, e1<-30, c0<-90, c1<-30. When a high specificity is desired, they recommend an absence of relapses in the whole period between reference and confirmation, which is implemented by setting: p0<-0, p1<-NULL, e0<-NULL, e1<-NULL, c0<-NULL, c1<-0.


For more details and examples on PIRA computation, please refer to the dedicated package vignette Assessing progression independent of relapse activity (PIRA) in MS.

Example

The following code detects multiple events with the RAW_PIRA flag enabled. 

output <- MSprog(data=toydata_visits,
                 subj_col="id", value_col="EDSS", date_col="date", outcome="edss", 
                 event="multiple", RAW_PIRA=TRUE, baseline="roving", 
                 relapse=toydata_relapses)


The output$event_count data frame (and the summary printed out by the function) now includes RAW and PIRA counts:

# print(output$event_count)
DT::datatable(output$event_count, 
              options = list(dom="t", scrollX=T, scrollY=F, paging = FALSE)
              )


In the output$results data frame, each CDW event is now further characterised by a CDW_type column:

# print(output$results, row.names=FALSE)
DT::datatable(output$results, rownames=F,
              options = list(dom="t", scrollX=T, scrollY=F, paging = FALSE)
              )


MSprog() outputs

What to include in results

The results attribute provides extended info on each event for all subjects. The following arguments can be used to control the information included.

For example:

output <- MSprog(data=toydata_visits, 
                      subj_col="id", value_col="EDSS", date_col="date", 
                      outcome="edss", relapse=toydata_relapses, verbose=0,
                      include_dates=T, include_value=T, include_stable=F) # <---- !

# print(output$results, row.names=FALSE)
DT::datatable(output$results, rownames=F,
              options = list(dom="t", scrollX=T, scrollY=F, paging = FALSE)
              )

Printing progress info {#progressinfo}

The verbose argument controls the amount of info printed out by the MSprog() function. When setting verbose=0, the function prints no info. When setting verbose=1 (default), the function only prints out concise info. When setting verbose=2, the function prints out an extended log of the ongoing computations. See the example below.

output <- MSprog(data=toydata_visits, 
                 subj_col="id", value_col="EDSS", date_col="date", outcome="edss",
                 event="multiple", baseline="roving", 
                 relapse=toydata_relapses, verbose=2)

For further insight into the event detection process, all score changes from baseline that were not identified as valid events (e.g., not confirmed) are stored in output$unconfirmed. In this example, this looks like:

# print(output$unconfirmed, row.names=FALSE)
DT::datatable(output$unconfirmed, rownames=F,
              options = list(dom="t", scrollX=T, scrollY=F, paging = FALSE)
              )

Time to disability milestone

Instead of studying disability course with respect to a baseline value, one can focus on the time taken to reach a specific disability milestone (e.g., EDSS $\geq$ 6). This can be computed using another function from the msprog package, value_milestone().

The following code detects the time to EDSS $\geq$ 6 for each subject in the toy data. 

vm <- value_milestone(toydata_visits, milestone=6,
                 subj_col="id", value_col="EDSS", date_col="date",
                 outcome="edss", relapse=toydata_relapses,
                 verbose=0)

The function returns a data frame indexed by subject IDs:

print(vm)

where: "date" contains the date of the first confirmed EDSS $\geq$ 6 (or last date of follow-up if milestone is not reached or not confirmed); "EDSS" contains the first EDSS value $\geq$ 6, if present, otherwise no value; "time2event" contains the time to reach EDSS $\geq$ 6 (or total follow-up length if not reached or not confirmed); "observed" indicates whether EDSS $\geq$ 6 was reached (1) or not (0).

Several arguments controlling the behaviour of the MSprog() function are also available for the value_milestone() function (e.g., require_sust_days, impute_last_visit...). Please refer to the documentation (by typing ?value_milestone) for a complete illustration of each of the function arguments and their default values.

For more examples on the usage of the value_milestone() function, please refer to the package vignette Time to event.

References



Try the msprog package in your browser

Any scripts or data that you put into this service are public.

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

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close