pymsprog package¶

Module contents¶

pymsprog.MSprog(data, subj_col, value_col, date_col, outcome, relapse=None, rsubj_col=None, rdate_col=None, subjects=None, delta_fun=None, worsening=None, valuedelta_col=None, event='firstCDW', RAW_PIRA=False, baseline='fixed', proceed_from='firstconf', sub_threshold_rebl='none', bl_geq=False, relapse_rebl=False, skip_local_extrema='none', validconf_col=None, conf_days=84, conf_tol_days=[7, 730.5], require_sust_days=0, check_intermediate=True, relapse_to_bl=30, relapse_to_event=0, relapse_to_conf=30, relapse_assoc=90, relapse_indep=None, impute_last_visit=0, date_format=None, include_dates=False, include_value=False, include_stable=True, return_unconfirmed=False, verbose=1)¶

The function detects and characterises the confirmed disability worsening (CDW) or improvement (CDI) events of an outcome measure (EDSS, NHPT, T25FW, or SDMT; or any custom outcome) for one or more subjects, 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.

Parameters:

data (pandas.DataFrame) – Longitudinal data containing subject ID, outcome value, date of visit.
subj_col (str) – Name of data column with subject ID.
value_col (str) – Name of data column with outcome value.
date_col (str) – Name of data column with date of visit.
outcome (str) –
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).
Outcome type determines a default direction of worsening (see worsening argument) and default definition of clinically meaningful change given the reference value (using the built-in function compute_delta()).
relapse (pandas.DataFrame) – Longitudinal data containing subject ID and relapse onset dates (if any).
rsubj_col (str) – Name of subject ID column for relapse data, if different from outcome data.
rdate_col (str) – Name of onset date column for relapse data, if different from outcome data.
subjects (array-like) – Subset of subject IDs to analyse. If none is specified, all subjects listed in data are included.
delta_fun (function) – 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. A custom delta function must be specified if outcome is set to ‘custom’ (see above). Otherwise, if none is specified, the built-in function compute_delta() is used internally.
worsening (str) – The direction of worsening (‘increase’ if higher values correspond to worse disease course, ‘decrease’ otherwise). This argument 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’.
valuedelta_col (str) –
Name of data column with alternative outcome value to use as baseline for delta function. It may be used, for instance, when analysing partial disability trajectories extracted using separate_ri_ra(). Example:

Original trajectory: EDSS = 3, 3.5, 5.5, 5, 5, 5.5, 6

Relapse-independent trajectory: RIEDSS = 3, 3.5, 3.5, 3.5, 3.5, 4, 4.5 (obtained using separate_ri_ra())

To extract progression events from the relapse-independent trajectory, the delta function should be referred to the original EDSS values (e.g., the worsening of 0.5 from 4 to 4.5 should be considered valid because the actual disability score of the patient went from 5.5 to 6). In such a case, MSprog() should be used with value_col='RIEDSS' and valuedelta_col='EDSS'.
event (str) –
Specifies which events to detect. Must be one of the following.
- ’firstCDW’ (first CDW, default)
- ’firstCDI’ (first CDI)
- ’first’ (only the very first confirmed event – CDI or CDW)
- ’firstPIRA’ (first PIRA)
- ’firstRAW’ (first RAW)
- ’multiple’ (all confirmed events in chronological order).
RAW_PIRA (bool) – 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 (str) –
Specifies the baseline scheme. Must be one of the following.
- ’fixed’: first valid outcome value, default;
- ’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 randomised data;
- ’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’);
- ’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’) – not recommended for randomised data.
proceed_from (str) –
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 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 (str) –
This argument is only used if baseline is not set to ‘fixed’. Must be one of the following.
- ’event’: any confirmed sub-threshold event (i.e., any confirmed change in the outcome measure, possibly below clinically meaningful threshold) can potentially trigger a re-baseline;
- ’improvement’: any confirmed sub-threshold improvement (i.e., any confirmed improvement in the outcome measure, possibly below clinically meaningful threshold) can potentially trigger a re-baseline;
- ’worsening’: any confirmed sub-threshold worsening (i.e., any confirmed worsening in the outcome measure, possibly below clinically meaningful threshold) can potentially trigger a re-baseline;
- ’none’: only use clinically meaningful confirmed changes for rebaseline.
See delta_fun argument and function compute_delta() for more details.
bl_geq (bool) – This argument is only used if the baseline is moved. 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 [Kappos JAMA Neurol 2020].
relapse_rebl (bool) – If True, re-baseline after every relapse.
skip_local_extrema (str) –
This argument is only used when moving the baseline. It controls re-baseline behaviour in the presence of local minima or maxima of the outcome trajectory. A visit i is a local minimum point for outcome if outcome[i+1]>outcome[i] and outcome[i-1]>outcome[i]; local maxima are defined similarly.

A visit i is a strict local minimum point for outcome if:

outcome[i+1]-outcome[i]>=delta_fun(outcome[i]);

outcome[i-1]-outcome[i]>=delta_fun(outcome[i]).

Strict local maxima are defined similarly.

When outcome[i]=outcome[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’: 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 (str) – Name of data column specifying which visits can (True) or cannot (False) be used as confirmation visits. The input data does not necessarily have to include such a column. If not specified (validconf_col=None), all visits are potentially used as confirmation visits.
conf_days (int, float, or array-like) – Period before confirmation (days). Can be a single value or array-like of any length if multiple windows are to be considered.
conf_tol_days (int, float, or array-like of length 1 or 2, or dict) – Tolerance window for confirmation visit (days); can be a single value (same tolerance on left and right) or array-like of length 2 (different tolerance on left and right). The right end of the interval can be set to float('inf') (confirmation window unbounded on the right – e.g., “confirmed over 12 or more weeks”). It can also be given as a dictionary with the values in conf_days as keys and different tolerance windows as values.
require_sust_days (int or float) – 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. Setting require_sust_days=float('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 (bool) – 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 (int, float, or array-like of length 1 or 2) – Minimum distance from a relapse (days) for a visit to be used as baseline. Can be a single value (minimum distance from last relapse) or array-like of length 2 (minimum distance from last relapse, minimum distance from next relapse). Note that setting the distance to zero means keeping the baseline where it is regardless of surrounding relapses. If the designated baseline does not respect this constraint, the baseline is moved to the next available visit.
relapse_to_event (int, float, or array-like of length 1 or 2) – Minimum distance from a relapse (days) for an event to be considered as such. Can be a single value (minimum distance from last relapse) or array-like of length 2 (minimum distance from last relapse, minimum distance from next relapse). Note that setting the distance to zero means retaining the event regardless of surrounding relapses.
relapse_to_conf (int, float, or array-like of length 1 or 2) – Minimum distance from a relapse (days) for a visit to be a valid confirmation visit. Can be a single value (minimum distance from last relapse) or array-like of length 2 (minimum distance from last relapse, minimum distance from next relapse). Note that setting the distance to zero means using any visit for confirmation regardless of surrounding relapses.
relapse_assoc (int, float, or array-like of length 1 or 2) – Maximum distance from a relapse (days) for a CDW event to be classified as RAW. Can be a single value (maximum distance from last relapse) or array-like of length 2 (maximum distance from last relapse, maximum distance from next relapse). The argument is ignored if RAW events are not detected (e.g., if event='firstCDW and RAW_PIRA=False).
relapse_indep (dict) –
Specifies relapse-free intervals for PIRA definition. Must be given in the form: {'prec': (p0, p1), 'event': (e0, e1), 'conf': (c0, c1)}. The dictionary specifies the intervals around (any subset of) the three checkpoints:
- ’prec’: a visit preceding the event – see below;
- ’event’: the disability worsening event onset;
- ’conf’: an eligible confirmation visit.
The dictionary can also optionally contain a key-value pair specifying how to choose ‘prec’:
- 'prec_type': 'baseline' → ‘prec’ is the current baseline;
- 'prec_type': 'last' → ‘prec’ is the last visit before event onset;
- 'prec_type': 'last_delta' → ‘prec’ is the last visit before event onset with a clinically meaningful score difference from the event score: i such that outcome[event] - outcome[i] >= delta_fun(outcome[i]) (if worsening='increase', the opposite otherwise) and same for the confirmation visit.
If ‘prec_type’ is not in the dictionary keys, ‘prec’ is assumed to be the current baseline.

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 None (e.g., “between baseline and event onset”: p1=None and e0=None).

The relapse_indep argument is ignored if PIRA events are not detected (e.g., if event='firstCDW and RAW_PIRA=False).
impute_last_visit (float or int) – Imputation probability for worsening events occurring at last 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 (str) –
Format of dates in the input data. Can be:
- ’day’ if dates 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.
- Standard format for dates (e.g., "%d-%m-%Y"; see datetime.strftime() docs for correct syntax).
If not specified, function pandas.to_datetime() will try to infer it automatically.
include_dates (bool) –
If True, the results DataFrame will include the dates of:
- event onset (“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_value (bool) –
If True, the results DataFrame will include the outcome value at:
- event onset (“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 (bool) – If True, subjects with no confirmed events are included in the results DataFrame, with ‘time2event’ = total follow up.
return_unconfirmed (bool) – If True, return an additional DataFrame including unconfirmed changes.
verbose (int) – One of: 0 (print no info); 1 (print concise info, default); 2 (print extended info).

Returns:

summary – Event sequence and counts for each subject (one row per subject). It includes the following columns:

event_sequencestr: Sequence of detected events (if any), in chronological order.
CDIint: Count of confirmed disability improvement (CDI) events.
CDWint: Count of confirmed disability worsening (CDW) events.
RAWint: Count of relapse-associated worsening (RAW) events.
PIRAint: Count of progression independent of relapse activity (PIRA) events.

Notes

Depending on computation settings, some of the above columns may be absent (e.g., no CDI column if event='firstCDW').

Return type:

pandas.DataFrame

resultspandas.DataFrame

Extended information on each detected event for all subjects, including the following columns:

<subj_col>str: Subject ID.
neventint: Cumulative count of events for the subject.
event_typestr: Type of event (e.g., CDI or CDW).
CDW_typestr: Type of CDW (PIRA, RAW, undefined).
total_fufloat: Total follow-up duration (days).
time2eventfloat: Days from start of follow-up to event onset.
bl2eventfloat: Days from baseline to event onset.
datedatetime-like, or float if date_format='day': Date of event onset.
valuefloat: Outcome value at event onset.
bl_datedatetime-like, or float if date_format='day': Baseline date for the event.
bl_valuefloat: Outcome value at baseline.
last_delta_datedatetime-like, or float if date_format='day': Date of last visit before event onset at a clinically meaningful score distance.
last_delta_valuefloat: Outcome value at that visit.
conf<conf_days>_datedatetime-like, or float if date_format='day': Date of the <conf_days>-day confirmation visit.
conf<conf_days>_valuefloat: Outcome value at the <conf_days>-day confirmation visit.
PIRA_conf<conf_days>_datedatetime-like, or float if date_format='day': When relevant, date of <conf_days>-day confirmation visit for PIRA (may differ from CDW confirmation if the PIRA definition includes confirmation-related constraints on relapses).
PIRA_conf<conf_days>_valuefloat: When relevant, voutcome value at <conf_days>-day confirmation visit for PIRA (may differ from CDW confirmation if the PIRA definition includes confirmation-related constraints on relapses).
sust_daysfloat: Number of days the event was sustained.
sust_lastbool: Whether the event was sustained until end of follow-up.

Some columns may be absent depending on computation settings (e.g., no date columns if include_dates=False).

unconfirmedpandas.DataFrame

Info on unconfirmed outcome changes (only returned if return_unconfirmed=True), including the following columns:

<subj_col>str: Subject ID.
datedatetime-like, or float if date_format='day': Date of initial outcome change.
valuefloat: Outcome value at initial outcome change.
bl_datedatetime-like, or float if date_format='day': Date of baseline.
bl_valuefloat: Outcome value at baseline.
closest_rel-float: Distance in days from the last relapse before the outcome change (if any).
closest_rel+float: Distance in days from the next relapse after the outcome change (if any).

In first-event scenarios (e.g., event='firstCDW'), the event search stops as soon as the first confirmed event is found – in this case, the unconfirmed data frame only reports unconfirmed outcome changes occurring before detecting a confirmed event.

Raises:: ValueError – If the arguments are incorrectly specified.

Examples

>>> toydata_visits, toydata_relapses = load_toy_data()
>>> # 1. EDSS course
>>> summary, results = MSprog(toydata_visits, relapse=toydata_relapses, subj_col='id', value_col='EDSS', date_col='date', outcome='edss')
>>> # 1. SDMT course
>>> summary, results = MSprog(toydata_visits, relapse=toydata_relapses, subj_col='id', value_col='EDSS', date_col='date', outcome='sdmt')

pymsprog.compute_delta(baseline, outcome='edss')¶

Definition of default minimum clinically meaningful shift for different scales (EDSS, NHPT, T25FW, or SDMT).

Parameters:

baseline (float) – Baseline value.
outcome (str) – Type of test (‘edss’[default], ‘nhpt’, ‘t25fw’, or ‘sdmt’)

Returns:

Minimum clinically meaningful change from the provided baseline value. Specifically:

EDSS: 1.5 if baseline = 0, 1 if 0 < baseline <= 5.0, 0.5 if baseline > 5.0.
NHPT and T25FW: 20% of baseline.
SDMT: either 3 points or 10% of baseline.

Return type:

float

Notes

Default thresholds are meant to apply to all versions of each test (e.g., dominant or non-dominant hand for NHPT, best time or median of two trials, etc.).

pymsprog.is_event(x, baseline, type, outcome, worsening=None, sub_threshold=False, delta_fun=None, baseline_delta=None)¶

Check for change from baseline.

Parameters:

x (float) – New value.
baseline (float) – Baseline value.
type (str) – ‘wors’ or ‘impr’ or ‘change’.
outcome (str) – Outcome type (one of: ‘edss’, ‘nhpt’, ‘t25fw’, ‘sdmt’, ‘custom’). Outcome type (if not ‘custom’) determines a default direction of worsening (see worsening argument) and default definition of clinically meaningful change given the reference value (using the built-in function compute_delta()).
worsening (str) – ‘increase’ or ‘decrease’. If outcome is not ‘custom’, the argument is ignored and the direction of worsening is automatically assigned (‘increase’ for edss, nhpt, t25fw; ‘decrease’ for sdmt)
sub_threshold (bool) – Whether to retain events below the clinically meaningful change from baseline.
delta_fun (function) – 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. A custom delta function must be specified if outcome is set to ‘custom’ (see above). Otherwise, if none is specified, the built-in function compute_delta() is used internally. The argument is ignored if sub_threshold=True.
baseline_delta (float) – Baseline value to use to compute clinically meaningful change, if different from baseline.

Returns:

Whether x is an event with respect to baseline.

Return type:

bool

pymsprog.load_toy_data()¶

Load the example longitudinal MS dataset provided with pymsprog.

This toy dataset is intended for testing and demonstration purposes. It provides artificially generated Extended Disability Status Scale (EDSS) and Symbol Digit Modalities Test (SDMT) longidutinal scores, visit dates, and relapse onset dates in a small cohort of example patients to illustrate the use of the package.

Returns:

visits (pandas.DataFrame) – Longitudinal disability info, including the following columns:

id: str
Subject identifier.

date: datetime-like
Visit date.

EDSS: float
EDSS score.

SDMT: float
SDMT score.
relapses (pandas.DataFrame) – Relapse info, including the following columns:

id: str
Subject identifier.

date: datetime-like
Relapse date.

Notes

The dataset is loaded from two .csv files (MSprog_toydata_visits.csv and MSprog_toydata_relapses.csv) bundled within the package.

Examples

>>> visits, relapses = load_toy_data()
>>> visits.head()
>>> relapses.head()

pymsprog.separate_ri_ra(data, subj_col, value_col, date_col, outcome, relapse, rsubj_col=None, rdate_col=None, delta_fun=None, worsening=None, sub_threshold=False, validconf_col=None, conf_days=84, conf_tol_days=[7, 730.5], sust_raw_days=180, relapse_to_bl=30, relapse_to_conf=30, relapse_assoc=90, impute_last_visit=0, subtract_bl=False, date_format=None, include_rel_num=False, include_bl=True, include_raw_dates=False, verbose=0)¶

Given longitudinal disability assessments and relapse dates, decompose the disability trajectory into a relapse-associated component (RAC) and a relapse-independent component (RIC). The RAC is split into a “sustained” component and a “transient” component (see below).

Parameters:

data (pandas.DataFrame) – Longitudinal data containing subject ID, outcome value, date of visit.
subj_col (str) – Name of data column with subject ID.
value_col (str) – Name of data column with outcome value.
date_col (str) – Name of data column with date of visit.
outcome (str) –
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)
- None (only accepted when specifying custom delta_fun and worsening)
Outcome type determines a default direction of worsening (see worsening argument) and default definition of clinically meaningful change given the reference value (using the built-in function compute_delta()).
relapse (pandas.DataFrame) – Longitudinal data containing subject ID and relapse date.
rsubj_col (str) – Name of subject ID column for relapse data, if different from outcome data.
rdate_col (str) – Name of onset date column for relapse data, if different from outcome data.
delta_fun (function) – 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. If none is specified (default), the user must provide a non-None value for the outcome argument (see above) in order to use the built-in function compute_delta().
worsening (str) – The direction of worsening (‘increase’ if higher values correspond to worse disease course, ‘decrease’ otherwise). This argument is only used when outcome is set to None. Otherwise, worsening is automatically set to ‘increase’ if outcome is set to ‘edss’, ‘nhpt’, ‘t25fw’, and to ‘decrease’ if outcome is set to ‘sdmt’.
sub_threshold (bool) – If True, delta_fun is ignored and any change in the outcome measure can potentially trigger a contribution to the RAC.
validconf_col (str) – Name of data column specifying which visits can (True) or cannot (False) be used as confirmation visits. The input data does not necessarily have to include such a column. If not specified (validconf_col=None), all visits are potentially used as confirmation visits.
conf_days (int, float, or array-like) – Period before confirmation (days). Can be a single value or array-like of any length if multiple windows are to be considered.
conf_tol_days (int, float, or array-like of length 1 or 2) – Tolerance window for confirmation visit (days); can be a single value (same tolerance on left and right) or array-like of length 2 (different tolerance on left and right). The right end of the interval can be set to float('inf') (confirmation window unbounded on the right – e.g., “confirmed over 12 or more weeks”).
sust_raw_days (int or float) – Minimum number of days over which a confirmed RAW event must be maintained (i.e., confirmed at all visits occurring in the specified period) to be considered as “sustained RAW”. Events confirmed for the remainder of the follow-up period are always considered sustained even if follow-up duration is shorter than sust_raw_days. Setting sust_raw_days=float('inf'), events are considered sustained only if the change is maintained for the remainder of the follow-up period.
relapse_to_bl (int, float, or array-like of length 1 or 2) – Minimum distance from a relapse (days) for a visit to be used as baseline. Can be a single value (minimum distance from last relapse) or array-like of length 2 (minimum distance from last relapse, minimum distance from next relapse). Note that setting the distance to zero means keeping the baseline where it is regardless of surrounding relapses. If the designated baseline does not respect this constraint, the baseline is moved to the next available visit.
relapse_to_conf (int, float, or array-like of length 1 or 2) – Minimum distance from a relapse (days) for a visit to be a valid confirmation visit. Can be a single value (minimum distance from last relapse) or array-like of length 2 (minimum distance from last relapse, minimum distance from next relapse). Note that setting the distance to zero means using any visit for confirmation regardless of surrounding relapses.
relapse_assoc (int, float, or array-like of length 1 or 2) – Maximum distance from a relapse (days) for a CDW event to be classified as RAW. Can be a single value (maximum distance from last relapse) or array-like of length 2 (maximum distance from last relapse, maximum distance from next relapse).
impute_last_visit (float or int) – Imputation probability for RAW events occurring at last 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).
subtract_bl (bool) – If True, the returned DataFrame will also include (f'{value_col}-bl' column) the overall change in score from baseline (simply obtained by subtracting the overall baseline from data[value_col]).
date_format (str) –
Format of dates in the input data. Can be:
- ’day’ if dates 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.
- Standard format for dates (e.g., "%d-%m-%Y"; see datetime.strftime() docs for correct syntax).
If not specified, function pandas.to_datetime() will try to infer it automatically.
include_rel_num (bool) – If True, the returned DataFrame will include the cumulative number of relapses (‘relapse_num’ column) at all visits of each subject.
include_bl (bool) – If True, the returned DataFrame will include the baseline outcome value (f'bl{value_col}' column) for each subject.
include_raw_dates (bool) – If True, an additional DataFrame is returned containing the dates of detected RAW events for each subject.
verbose (int) – One of: 0 (print no info); 1 (print concise info, default); 2 (print extended info).

Returns:

data_sep (pandas.DataFrame) – The original DataFrame (data) with the addition of the following columns:

ric_<value_col>: float
Cumulative relapse-independent change from baseline.

srac_<value_col>: float
Cumulative sustained relapse-associated change.

trac_<value_col>: float
Transient relapse-associated changes (“bumps”).

bl_<value_col>: float
Baseline score (if include_bl=True).

relapse_num: int
Cumulative relapse number (if include_rel_num=True).
raw_events (pandas.DataFrame) – Dates of detected RAW events for each subject (only returned if include_raw_dates=True), including columns:

<subj_col>: str
Subject ID.

<date_col>: datetime-like, or float if date_format='day'.
Date of RAW event.

Notes

For each subject, the function analyses the disability assessments surrounding each relapse to look for a confirmed worsening in the disability score within the influence period of the relapse (as per relapse_assoc[0]) with respect to the last visit preceding the relapse (at a distance specified by relapse_assoc[1]). If such a worsening is found, it is labelled as a relapse-associated worsening (RAW) event.

The change in score resulting from each RAW event is subtracted from the overall trajectory to isolate PIRA. If a RAW event is sustained for a specified period of time (as per sust_raw_days argument), the accumulation of disability is considered permanent and the change is subtracted from all subsequent visits. The change is computed as the minimum score over the sustained period; any temporary worsening exceeding the change is considered as a “bump”, and is only subtracted from the score of the current assessment. If a RAW event is transient (not sustained), the change is only subtracted from all scores up to the confirmation visit. Three sub-trajectories are obtained:

SRAC (“sustained RAC”): permanent accumulation of disability from sustained RAW.
TRAC (“transient RAC”): temporary disability worsening from transient RAW (“bumps”).
RIC: disability accumulation due to PIRA, obtained as the trajectory of disability worsening deprived of all sustained and transient relapse-associated contributions.

All sub-trajectories are expressed as deltas relative to the baseline value, as the disability already accumulated at the beginning of the follow-up period cannot be attributed to relapse-associated or relapse-independent CDW with the available data.

Raises:: ValueError – If the arguments are incorrectly specified.

pymsprog.value_milestone(data, milestone, subj_col, value_col, date_col, outcome, relapse=None, rsubj_col=None, rdate_col=None, worsening=None, validconf_col=None, conf_days=84, conf_tol_days=[7, 730.5], require_sust_days=0, relapse_to_event=0, relapse_to_conf=30, impute_last_visit=0, date_format=None, verbose=0)¶

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

Parameters:

data (pandas.DataFrame) – Longitudinal data containing subject ID, outcome value, date of visit.
milestone (float) – Disability milestone (outcome value to check data against).
subj_col (str) – Name of data column with subject ID.
value_col (str) – Name of data column with outcome value.
date_col (str) – Name of data column with date of visit.
outcome (str) –
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)
- None (only accepted when specifying a custom worsening).
Outcome type determines a default direction of worsening (see worsening argument).
relapse (pandas.DataFrame) – Longitudinal data containing subject ID and relapse date (can be omitted).
rsubj_col (str) – Name of subject ID column for relapse data, if different from outcome data.
rdate_col (str) – Name of onset date column for relapse data, if different from outcome data.
worsening (str) – The direction of worsening (‘increase’ if higher values correspond to worse disease course, ‘decrease’ otherwise). This argument is only used when outcome is set to None. Otherwise, worsening is automatically set to ‘increase’ if outcome is set to ‘edss’, ‘nhpt’, ‘t25fw’, and to ‘decrease’ if outcome is set to ‘sdmt’.
validconf_col (str) – Name of data column specifying which visits can (True) or cannot (False) be used as confirmation visits. The input data does not necessarily have to include such a column. If not specified (validconf_col=None), all visits are potentially used as confirmation visits.
conf_days (int, float, or array-like) – Period before confirmation (days). Can be a single value or array-like of any length if multiple windows are to be considered.
conf_tol_days (int, float, or array-like of length 1 or 2) – Tolerance window for confirmation visit (days); can be a single value (same tolerance on left and right) or array-like of length 2 (different tolerance on left and right). The right end of the interval can be set to float('inf') (confirmation window unbounded on the right – e.g., “confirmed over 12 or more weeks”).
require_sust_days (int or float) – Minimum number of days over which the milestone must be sustained. (i.e., confirmed at all visits occurring in the specified period) to be retained. If the milestone is sustained for the remainder of the follow-up period, it is always considered reached regardless of follow-up duration. If require_sust_days=float('inf'), milestone is considered reached only when sustained for the remainder of the follow-up period.
relapse_to_event (int, float, or array-like of length 1 or 2) – Minimum distance from a relapse (days) for an event to be considered as such. Can be a single value (minimum distance from last relapse) or array-like of length 2 (minimum distance from last relapse, minimum distance from next relapse). Note that setting the distance to zero means retaining the event regardless of surrounding relapses.
relapse_to_conf (int, float, or array-like of length 1 or 2) – Minimum distance from a relapse (days) for a visit to be a valid confirmation visit. Can be a single value (minimum distance from last relapse) or array-like of length 2 (minimum distance from last relapse, minimum distance from next relapse). Note that setting the distance to zero means using any visit for confirmation regardless of surrounding relapses.
impute_last_visit (float or int) – Imputation probability for milestone reached at last visit (i.e. with no confirmation). If impute_last_visit=0, milestone is never imputed (i.e., considered reached) if the value is attained at the last visit; if impute_last_visit=1, it is always imputed; if impute_last_visit=p, 0<p<1, it is imputed with probability p. If a value N>1 is passed, milestone is imputed only if occurring within N days of follow-up (e.g., in case of early discontinuation).
date_format (str) –
Format of dates in the input data. Can be:
- ’day’ if dates 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.
- Standard format for dates (e.g., "%d-%m-%Y"; see datetime.strftime() docs for correct syntax).
If not specified, function pandas.to_datetime() will try to infer it automatically.
verbose (int) – One of: 0 (print no info); 1 (print concise info); 1 (print extended info).

Returns:

results – A DataFrame including the following columns:

<date_col>: datetime-like, or int if date_format='day: Date of first reaching or exceeding the milestone (or last date of follow-up if milestone is not reached).
<value_col>: float: First value reaching or exceeding the milestone, if present.
time2event: int: The time taken to reach or exceed the milestone (or total follow-up length if milestone is not reached).
observed: bool: Whether the milestone was reached (True) or not (False).

Return type:

pandas.DataFrame

Notes

“Reaching or exceeding” the milestone means either value <= milestone or value >= milestone, depending on the outcome measure (see arguments outcome and worsening).
An event is only retained if confirmed, i.e., if all values up to the confirmation visit reach or exceed the milestone.

Raises:: ValueError – If the arguments are incorrectly specified.