{
"cells": [
{
"cell_type": "markdown",
"id": "9fc532f7",
"metadata": {},
"source": [
"# Analysing disability course in MS\n",
"\n",
"This tutorial illustrates how to use the `pymsprog` 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](#input-data) needed, and by giving a [minimal working example](#minimal-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."
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "aea06648",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"1.0.5\n",
"/opt/anaconda3/envs/pymsprog-env/bin/python\n",
"/opt/anaconda3/envs/pymsprog-env\n",
"1.0.5\n",
"/opt/anaconda3/envs/pymsprog-env/lib/python3.11/site-packages/pymsprog/__init__.py\n"
]
}
],
"source": [
"import pymsprog\n",
"print(pymsprog.__version__)"
]
},
{
"cell_type": "markdown",
"id": "1b116555",
"metadata": {},
"source": [
"(input-data)=\n",
"## Input data\n",
"\n",
"The data must be organised in a pandas DataFrame containing (at least) the following columns:\n",
"\n",
"* Subject IDs\n",
"* Visit dates\n",
"* Outcome values.\n",
"\n",
"The visits should be listed in chronological order (if they are not, `MSprog()` will sort them automatically before analysing them).\n",
"\n",
"For relapsing-remitting MS patients, an additional DataFrame with the dates of relapses is needed to correctly assess progression and characterise progression events as relapse-associated or relapse-independent. The dataset should contain (at least) the following columns:\n",
"\n",
"* Subject IDs\n",
"* Visit dates."
]
},
{
"cell_type": "markdown",
"id": "5fa16693",
"metadata": {},
"source": [
"In this tutorial, we will use toy data with artificially generated EDSS and SDMT assessments and relapse dates for a few hypothetical patients:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "cf6a6216",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"Visits:\n",
" id date visit_day EDSS SDMT\n",
"0 1 2021-09-23 0 5.5 54\n",
"1 1 2021-11-03 41 5.5 54\n",
"2 1 2022-01-19 118 5.5 57\n",
"3 1 2022-04-27 216 5.5 55\n",
"4 1 2022-07-12 292 6.0 57\n",
"\n",
"Relapses:\n",
" id date visit_day\n",
"0 2 2021-06-12 198\n",
"1 2 2022-10-25 698\n",
"2 3 2022-12-01 409\n",
"3 6 2022-12-18 426\n",
"4 7 2021-09-11 185\n"
]
}
],
"source": [
"from pymsprog import load_toy_data\n",
"toydata_visits, toydata_relapses = load_toy_data()\n",
"\n",
"print('\\nVisits:')\n",
"print(toydata_visits.head())\n",
"print('\\nRelapses:')\n",
"print(toydata_relapses.head())"
]
},
{
"cell_type": "markdown",
"id": "50731f52-e892-497b-99fa-1a920ec2bd99",
"metadata": {},
"source": [
"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."
]
},
{
"cell_type": "markdown",
"id": "920efc13",
"metadata": {},
"source": [
"(minimal-example)=\n",
"## Minimal example\n",
"\n",
"The core block of `pymsprog` is the `MSprog()` function. Given data on visits and relapses 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) {cite:p}`lublin2014,kappos2020`.\n",
"\n",
"By default, `MSprog()` detects the first CDW. \n",
"\n",
"We can test it on the EDSS toy data..."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "5b6b1783",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"---\n",
"Outcome: edss\n",
"Confirmation over: 84 (-7, +730.5) days\n",
"Baseline: fixed\n",
"Relapse influence (baseline): [30, 0] days\n",
"Relapse influence (event): [0, 0] days\n",
"Relapse influence (confirmation): [30, 0] days\n",
"Events detected: firstCDW\n",
"---\n",
"Total subjects: 7\n",
"---\n",
"Subjects with CDW: 4 (PIRA: 3; RAW: 1)\n"
]
}
],
"source": [
"from pymsprog import MSprog\n",
"summary_edss, results_edss = MSprog(toydata_visits, # data on visits\n",
" subj_col='id', value_col='EDSS', date_col='date', # specify column names\n",
" outcome='edss', # specify outcome type <--- EDSS\n",
" relapse=toydata_relapses) # data on relapses"
]
},
{
"cell_type": "markdown",
"id": "a22c75a4-645d-466b-9afb-3918451257f3",
"metadata": {},
"source": [
"
\n",
"...or on the SDMT toy data:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "c89027c3-8982-450a-9c07-92282fc4657c",
"metadata": {
"scrolled": true
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"---\n",
"Outcome: sdmt\n",
"Confirmation over: 84 (-7, +730.5) days\n",
"Baseline: fixed\n",
"Relapse influence (baseline): [30, 0] days\n",
"Relapse influence (event): [0, 0] days\n",
"Relapse influence (confirmation): [30, 0] days\n",
"Events detected: firstCDW\n",
"---\n",
"Total subjects: 7\n",
"---\n",
"Subjects with CDW: 1 (PIRA: 1; RAW: 0)\n"
]
}
],
"source": [
"summary_sdmt, results_sdmt = MSprog(toydata_visits, # data on visits\n",
" subj_col='id', value_col='EDSS', date_col='visit_day', # specify column names\n",
" outcome='sdmt', # specify outcome type <--- SDMT\n",
" relapse=toydata_relapses, # data on relapses\n",
" date_format='day') # specify that dates are given as days"
]
},
{
"cell_type": "markdown",
"id": "2d860cc9",
"metadata": {},
"source": [
"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).\n",
"\n",
"The function prints concise info (the `verbose` argument can be used to control the amount of info printed out -- see [Printing progress info](#printing-progress-info) section below), and generates the following two DataFrames.\n",
"\n",
"
\n",
"\n",
"**1. Detailed info on each event for all subjects:**"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "68a401bc",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" id nevent event_type CDW_type total_fu time2event bl2event sust_days \\\n",
"0 1 1 CDW PIRA 534.0 292.0 292.0 242.0 \n",
"1 2 1 CDW RAW 730.0 198.0 198.0 84.0 \n",
"2 3 0 491.0 491.0 NaN 0.0 \n",
"3 4 0 586.0 586.0 NaN 0.0 \n",
"4 5 1 CDW PIRA 637.0 140.0 140.0 497.0 \n",
"5 6 0 491.0 491.0 NaN 0.0 \n",
"6 7 1 CDW PIRA 779.0 372.0 372.0 407.0 \n",
"\n",
" sust_last \n",
"0 1.0 \n",
"1 0.0 \n",
"2 0.0 \n",
"3 0.0 \n",
"4 1.0 \n",
"5 0.0 \n",
"6 1.0 \n"
]
}
],
"source": [
"print(results_edss)"
]
},
{
"cell_type": "markdown",
"id": "4adbc475",
"metadata": {},
"source": [
"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(*); `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.\n",
"\n",
"(*): For subjects with no confirmed events, `time2event` is the total follow-up length. To omit these subjects, set `include_stable=False` in `MSprog()`.\n",
"\n",
"
\n",
"\n",
"**2. Event count for each subject:** "
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "2c8920cd",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" event_sequence CDW RAW PIRA\n",
"1 PIRA 1 0 1\n",
"2 RAW 1 1 0\n",
"3 0 0 0\n",
"4 0 0 0\n",
"5 PIRA 1 0 1\n",
"6 0 0 0\n",
"7 PIRA 1 0 1\n"
]
}
],
"source": [
"print(summary_edss)"
]
},
{
"cell_type": "markdown",
"id": "beb685cf",
"metadata": {},
"source": [
"**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, \n",
"\n",
"1. in `results_edss`, `nevent` can only be 0 or 1.\n",
"2. in `summary_edss`, CDW count can only be 0 or 1, and CDI column is omitted.\n",
"\n",
"In a multiple-event setting (`event='multiple'`), more than one event per subject can be detected, and the event-count DataFrame also includes the event sequence for each subject. See [the relevant section](#multiple-events).\n",
"\n",
"
\n",
"\n",
"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. In the following sections we will go into more detail about usage and best practices for the different options. Please refer to the documentation for a complete illustration of each of the function arguments and their default values."
]
},
{
"cell_type": "markdown",
"id": "43af745c",
"metadata": {},
"source": [
"(outcome)=\n",
"## Outcome\n",
"\n",
"In `MSprog()`, outcome type is specified via the mandatory argument `outcome`. This triggers:\n",
"\n",
"* Value range checks (e.g., EDSS in the 0-10 range)\n",
"* Direction of worsening (e.g., for EDSS, \"higher values = worse\")\n",
"* Outcome-specific **\"minimum clinically relevant change\"**.\n",
"\n",
"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 `pymsprog` for the most used disability scales {cite:p}`lorscheider2016,bosma2010,kalinowski2022,strober2019`:\n",
"\n",
"* `outcome='edss'`: Expanded Disability Status Scale (EDSS). $\\delta(x)=\\begin{cases} 1.5 \\quad \\text{ if } x=0\\\\1 \\quad\\;\\;\\; \\text{ if } 0 < x \\leq 5\\\\0.5 \\quad \\text{ if } x>5\\end{cases}$;\n",
"\n",
"* `outcome='nhpt'`: Nine-Hole Peg Test (NHPT), for either the dominant or the non-dominant hand. $\\delta=$ 20% of reference score;\n",
"\n",
"* `outcome='t25fw'`: Timed 25-Foot Walk (T25FW). $\\delta=$ 20% of reference score;\n",
"\n",
"* `outcome='sdmt'`: Symbol Digit Modalities Test (SDMT). $\\delta=$ either 4 points or 20% of reference score.\n",
"\n",
"These default options are internally implemented by the `compute_delta()` function. For example, if the baseline EDSS score is 4, a valid worsening will correspond to an increase by (at least):"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "30f23689",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"1.0\n"
]
}
],
"source": [
"from pymsprog import compute_delta\n",
"print(compute_delta(4)) # default outcome measure is 'edss'"
]
},
{
"cell_type": "markdown",
"id": "b4f2739c-e8ed-4a28-81cc-f39a48c9ea7d",
"metadata": {},
"source": [
"If the baseline T25FW score is 10, the minimum shift that is considered as a valid change will be:"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "95b590ff-291c-4e24-a8fa-5b11b3d3ae5f",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"2.0\n"
]
}
],
"source": [
"print(compute_delta(10, outcome='t25fw'))"
]
},
{
"cell_type": "markdown",
"id": "5acc2795",
"metadata": {},
"source": [
"### Custom threshold values\n",
"\n",
"The user can provide their own function to customise the computation of the threshold values, using the `delta_fun` argument of `MSprog()`. The provided function must take the baseline value as argument, and return the corresponding threshold. This applies to two scenarios.\n",
"\n",
"
\n",
"\n",
"**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:"
]
},
{
"cell_type": "code",
"execution_count": 17,
"id": "bf126b27",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"- CUSTOM minimum valid change from baseline SDMT=50: 3\n",
"- DEFAULT minimum valid change from baseline SDMT=50: 4\n"
]
}
],
"source": [
"def my_sdmt_delta(x):\n",
" return min(3, x/10)\n",
"print('- CUSTOM minimum valid change from baseline SDMT=50: ', my_sdmt_delta(50)) # my delta\n",
"print('- DEFAULT minimum valid change from baseline SDMT=50: ', compute_delta(50, outcome='sdmt')) # default delta"
]
},
{
"cell_type": "markdown",
"id": "20448ef7",
"metadata": {},
"source": [
"To use our custom function, we can then set `delta_fun=my_sdmt_delta` in `MSprog()` when computing the disability events.\n",
"\n",
"
\n",
"\n",
"**2. The outcome of interest is not among the ones listed above.** In this case, we set `outcome=None`, and `delta_fun` as our desired custom-defined function. By default, higher values of a custom outcome are interpreted as a worsening. If the opposite direction of worsening is desired, set the `worsening` argument to `'decrease'`. Note that the `worsening` argument is only used by `MSprog()` 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'`.\n"
]
},
{
"cell_type": "markdown",
"id": "f83ff0e6",
"metadata": {},
"source": [
"(baseline-scheme)=\n",
"## Baseline scheme\n",
"\n",
"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.\n",
"\n",
"* *Fixed baseline* (`baseline='fixed'`, default): the baseline visit is set to be the first available assessment.\n",
"\n",
"* *Roving baseline* (`baseline='roving'`): the baseline visit is initially set as the first available assessment, then updated after each event. This scheme is recommended in a **\"multiple events\" setting** {cite:p}`kappos2018` (see example below), but **not recommended for clinical trial data** as it may break the randomisation.\n",
"\n",
"* *Improvement-based roving baseline* (`baseline='roving_impr'`): the baseline visit is initially set as the first available assessment, then updated after each confirmed improvement. This scheme is suitable for a **first-CDW setting** to discard fluctuations around the baseline {cite:p}`muller2023`, but **not recommended for clinical trial data** as it may break the randomisation. \n",
"\n",
"* *Worsening-based roving baseline* (`baseline='roving_wors'`): the baseline visit is initially set as the first available assessment, then updated after each confirmed worsening. This scheme is suitable when the endpoint of interest is **a specific type of CDW**: for instance, when searching specifically for PIRA events, the reference should be moved after any previous RAW event; when searching specifically for RAW events, the reference should be moved after any previous PIRA event. \n",
"\n",
"**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).\n",
"\n",
"\n",
"### Additional options\n",
"\n",
"* For roving baseline schemes, the re-baseline procedure can be made finer through the `sub_threshold_rebl` argument in `MSprog()`: setting `sub_threshold_rebl='event'`, for instance, rebaseline can be triggered by *any* confirmed change, even if below [the clinically meaningful threshold](#outcome). In this case, the sub-threshold improvement events are used to move the baseline, but not listed in the event sequence.\n",
"\n",
"* When a roving baseline is used, the reference is moved after a previously detected event. The new reference may be set at the date of the previous event (`proceed_from='event'`), or at the first confirmation visit of such event (`proceed_from='firstconf'`, default).\n",
"\n",
"* If the baseline visit occurs in the vicinity of a clinical relapse, the reference value may be overestimated. The `relapse_to_bl` argument allows to specify the minimum accepted distance (in days) of the baseline visit from the onset of a previous relapse. For instance, if `baseline='fixed'` and `relapse_to_bl=30`, the baseline visit is chosen as the first available visit satisfying the requirement of \"no relapses within the preceding 30 days\". If two values are provided, they are interpreted as intervals before *and after* the event -- e.g., `relapse_to_bl=[30, 2]` implements the constraint of \"no relapses within the preceding 30 days or within the following 2 days\". If relapse **end dates** are available (may be provided as an additional column in the relapse file whose name is specified by argument `renddate_col` in `MSprog()`), the first value of `relapse_to_bl` is overwritten by the relapse duration, unless it was set to 0 (in which case it stays 0 and the baseline is **not** moved based on the influence of previous relapses). If the `baseline` argument is set to a roving scheme, all the above applies to every baseline change as well. \n",
"\n",
"* On top of the chosen baseline scheme, *post-relapse re-baseline* {cite:p}`kappos2020` can be applied by setting `relapse_rebl=True` in `MSprog()`. If this is enabled, the onset of each relapse prompts a re-baseline to the next available visit following the relapse and out of its influence (as per `relapse_to_bl`). As an additional constraint, an updated baseline can be forced to have a score greater than or equal to the previous baseline by setting `bl_geq=True` in `MSprog()`.\n",
"\n",
"* Due to fluctuations in the data, the new reference value following a re-baseline may fall at a local minimum or maximum of the disability trajectory. These may be excluded for consideration as baseline visits using the `skip_local_extrema` argument in `MSprog()`.\n",
"\n",
"
\n",
"\n",
"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).**\n",
"\n",
"\n",
"(multiple-events)=\n",
"### Multiple events\n",
"\n",
"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.\n",
"\n",
"For example, extracting multiple EDSS events for subject `4` from `toydata_visits` with a **fixed** baseline would result in the following."
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "09dd60e2",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"Data:\n",
" date EDSS\n",
"0 2021-09-18 4.5\n",
"1 2021-12-04 3.5\n",
"2 2022-03-12 3.5\n",
"3 2022-07-19 5.0\n",
"4 2022-10-05 5.0\n",
"5 2023-01-16 5.5\n",
"6 2023-04-27 5.0\n",
"\n",
"---Results with fixed baseline:---\n",
"nevent 1\n",
"event_type CDI\n",
"CDW_type \n",
"total_fu 586.0\n",
"time2event 77.0\n",
"bl2event 77.0\n",
"sust_days 98.0\n",
"sust_last 0.0\n"
]
}
],
"source": [
"print('\\nData:')\n",
"print(toydata_visits.loc[toydata_visits['id']==4, ['date', 'EDSS']].reset_index(drop=True)) # EDSS visits\n",
"\n",
"_, results = MSprog(toydata_visits, 'id', 'EDSS', 'date', outcome='edss',\n",
" relapse=toydata_relapses, \n",
" subjects=[4],\n",
" conf_days=12 * 7, \n",
" event='multiple', baseline='fixed', # <---\n",
" verbose=0)\n",
"print('\\n---Results with fixed baseline:---')\n",
"print(results.drop(columns='id').set_index('nevent', drop=True).T) # results"
]
},
{
"cell_type": "markdown",
"id": "2b9b341b",
"metadata": {},
"source": [
"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:"
]
},
{
"cell_type": "code",
"execution_count": 11,
"id": "29497d72",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"---Results with roving baseline:---\n",
"nevent 1 2\n",
"event_type CDI CDW\n",
"CDW_type PIRA\n",
"total_fu 586.0 586.0\n",
"time2event 77.0 304.0\n",
"bl2event 77.0 129.0\n",
"sust_days 98.0 282.0\n",
"sust_last 0.0 1.0\n"
]
}
],
"source": [
"_, results = MSprog(toydata_visits, 'id', 'EDSS', 'date', outcome='edss',\n",
" relapse=toydata_relapses, \n",
" subjects=[4],\n",
" conf_days=12 * 7, \n",
" event='multiple', baseline='roving', # <-----\n",
" verbose=0)\n",
"print('\\n---Results with roving baseline:---')\n",
"print(results.drop(columns='id').set_index('nevent', drop=True).T) # results"
]
},
{
"cell_type": "markdown",
"id": "e0390511",
"metadata": {},
"source": [
"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 (PIRA) event is detected at visit 4 (EDSS=5), confirmed at visit 5.\n",
"
\n",
"\n",
"Other valid values for the `event` argument are:\n",
"\n",
"* `'first'`: only the very first confirmed event -- CDI or CDW\n",
"* `'firstCDI'`: first CDI event\n",
"* `'firstPIRA'`: first PIRA event\n",
"* `'firstRAW'`: first RAW event.\n",
"\n",
"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.\n",
"\n",
"\n",
"\n",
"(event-confirmation)=\n",
"## Event confirmation\n",
"\n",
"An event is only validated if the change in the outcome value from the current baseline is maintained **up to**(\\*) a subsequent *confirmation visit* at a pre-specified distance from the event {cite:p}`ontaneda2017`. The event is confirmed if the difference in the outcome value from the baseline score remains above-[threshold](#outcome) 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.\n",
"\n",
"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 (left and right tolerance)(\\**). 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.\n",
"\n",
"i. A common setting for **clinical trial data** would be: `conf_days=7*12`, `conf_tol_days=[0, np.inf]`, \n",
"i.e., \"confirmation over 12 or more weeks\".\n",
"\n",
"ii. A common setting for **observational data** would be: `conf_days=7*24`, `conf_tol_days=[0, 7*12]`, \n",
"i.e., the confirmation visit must lie between 24 weeks after the event, and 36 weeks after the event.\n",
"\n",
"**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.\n",
"\n",
"### Additional options\n",
"\n",
"* If `conf_days` is specified as a sequence of values (e.g., `conf_days=[7*12, 7*24]`), events are retained if confirmed by *at least one visit* falling within any of the specified periods (here, 12 **or** 24 weeks with their relative tolerance interval)(\\***). Confirmation dates/values at *all* specified values will be included in the results table (if `include_dates=True` / `include_values=True` in `MSprog()`).\n",
"\n",
"* If the confirmation visit occurs in the vicinity of a clinical relapse, it is typically considered invalid. The `relapse_to_conf` argument allows to specify the minimum accepted distance (in days) of a confirmation visit from the onset of a previous relapse. For example, `relapse_to_conf=30` implements the constraint \"no relapses within the preceding 30 days\" for a visit to be used as confirmation. If two values are provided, they are interpreted as intervals before *and after* the event -- e.g., `relapse_to_conf=[30, 2]` implements the constraint \"no relapses within the preceding 30 days or within the following 2 days\". If relapse **end dates** are available (may be provided as an additional column in the relapse file whose name is specified by argument `renddate_col` in `MSprog()`), the first value of `relapse_to_conf` is overwritten by the relapse duration, unless it was set to 0 (in which case it stays 0 and confirmation visits are **not** discarded based on the influence of previous relapses).\n",
"\n",
"* By default, a disability worsening occurring at the last available assessment is ignored by `MSprog()`. This behaviour can be changed using the `impute_last_visit` argument. If set to `TRUE`, any disability worsening occurring at the last visit is retained even though unconfirmed. If set to a numeric value N, unconfirmed worsening events are included only if occurring within N days of follow up (e.g., in case of early discontinuation).\n",
"\n",
"* In scenarios (e.g., a clinical trial) where disability course is compared between two cohorts with different relapse rates, there may be an imbalance in visit frequency between the two groups, due to unscheduled visits after relapses. This implies a higher probability of detecting outcome changes in the group with more assessments. Such issue is sometimes addressed by only using scheduled visits as confirmation visits {cite:p}`hauser2017`. It is possible to implement this with `MSprog()` by including an additional column in the longitudinal data, specifying which visits can (`True`) or cannot (`False`) be used as confirmation visits. The name of such column must be specified using the `validconf_col` argument -- for example, if the database contains a column `'scheduled'` tracking scheduled visits, unscheduled visits can be excluded from consideration as confirmation visits by setting `validconf_col='scheduled'`in `MSprog()`.\n",
"\n",
"\n",
"(\\*) 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.\n",
"\n",
"(\\**) `conf_tol_days` can also be specified as a single integer if the same tolerance on left and right is desired.\n",
"\n",
"(\\***) 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 but not over 12 weeks* if there are no valid confirmation visits falling within the 12-week window (unless `check_intermediate=FALSE`).\n",
"\n",
"### Sustained CDW or CDI\n",
"\n",
"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.\n",
"\n",
"The `require_sust_days` argument may be of use in the following scenarios.\n",
"\n",
"* Suppose the maximum follow-up in the population is 96 weeks excluding the baseline visit. If one wants to detect CDWs sustained over the whole follow-up, coding it as \"worsening confirmed over 96 weeks or more\" (`conf_days=7*96`, `conf_tol_days=c(0, Inf)`) would discard CDWs of patients whose follow-up is shorter than 96 weeks. In a scenario where patients have different follow-up lengths, the `require_sust_days` argument offers a more reliable way of implementing this, e.g., as \"worsening confirmed over 12 weeks or more and sustained for the whole follow-up period\" (`conf_days=7*12`, `conf_tol_days=c(0, Inf)`, `require_sust_days=Inf`). \n",
"\n",
"* In observational data with coarsely- and unevenly-spaced visits, the `require_sust_days` argument may be used to detect sustained CDW (e.g., `require_sust_days=7*96`) while still requiring the presence of a confirmation visit within a specified interval from the event (e.g., `conf_days=7*12`, `conf_tol_days=c(0,7*12)`). \n",
"\n",
"* Sustained disability worsening can be required to exclude transient RAW events.\n"
]
},
{
"cell_type": "markdown",
"id": "ea6ee00d",
"metadata": {},
"source": [
"## Relapse-based classification of CDW events\n",
"\n",
"Detected CDW events may be further categorised based on their timing with respect to relapses (\\*) 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.\n",
"\n",
"(\\*) 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 section [Input data](#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`.\n",
"\n",
"(raw)=\n",
"### RAW\n",
"\n",
"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:\n",
"\n",
"* `relapse_assoc=90` (equivalent to `relapse_assoc=[90, 0]`): RAW = \"a CDW event occurring within 90 days after the onset of a relapse\";\n",
"* `relapse_assoc=[90, 7]`: RAW = \"a CDW event occurring no more than 90 days after and no more than 7 days before the onset of a relapse\".\n",
"\n",
"(pira)=\n",
"### PIRA\n",
"\n",
"In the literature, PIRA is typically defined by requiring an absence of relapses within appropriate intervals anchored to the dates of the baseline visit, the worsening event, and the confirmation visit {cite:p}`kappos2020,cagol2022,muller2023`. \n",
"\n",
"The `relapse_indep` argument in `MSprog()` allows to specify custom relapse-free intervals. The argument must be provided in the form of a dictionary as follows:\n",
"\n",
"`{'prec': (p0, p1), 'event': (e0, e1), 'conf': (c0, c1)}`.\n",
" \n",
"The dictionary specifies the intervals \\[`p0`, `p1`\\], \\[`e0`, `e1`\\], and \\[`c0`, `c1`\\] around (any subset of) the three checkpoints:\n",
"\n",
"- `'prec'`: a visit preceding the event -- see below;\n",
"- `'event'`: the disability worsening event;\n",
"- `'conf'`: the first available confirmation visit.\n",
"\n",
"The dictionary can also optionally contain a key-value pair specifying how to choose `'prec'`:\n",
"\n",
"- `'prec_type': 'baseline'` → `'prec'` is the current baseline;\n",
"- `'prec_type': 'last'` → `'prec'` is the last visit before the event;\n",
"- `'prec_type': 'last_lower'` → `'prec'` is the last visit before event onset with a clinically meaningful score difference from it:\n",
" `i` such that `outcome[event] - outcome[i] >= delta_fun(outcome[i])` (if `worsening='increase'`, the opposite otherwise)\n",
" and same for the confirmation visit.\n",
"\n",
"If `'prec_type'` is not in the dictionary keys, it will be automatically assigned as `'baseline'`.\n",
"\n",
"If both ends of an interval are 0 (e.g., if both `p0=0` and `p1=0`), the checkpoint is ignored.\n",
"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`).\n",
"\n",
"For example, in {cite:t}`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 the confirmation visit 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 the reference visit and the confirmation visit, which is implemented by setting: `p0 = 0`, `p1 = None`, `e0 = None`, `e1 = None`, `c0 = None`, `c1 = 0`. \n",
"\n",
"### Example\n",
"\n",
"The following code detects multiple events with the `RAW_PIRA` flag enabled."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "fc2d4e9b-ff07-4f07-bb29-853bf036f0f8",
"metadata": {},
"outputs": [],
"source": [
"summary, results = MSprog(data=toydata_visits,\n",
" subj_col='id', value_col='EDSS', date_col='date', outcome='edss', \n",
" event='multiple', RAW_PIRA=True, baseline='roving', \n",
" relapse=toydata_relapses) \n"
]
},
{
"cell_type": "markdown",
"id": "e63250e6-1d52-4f9e-be3c-9be5bd7277ae",
"metadata": {},
"source": [
"The `summary` DataFrame (and the info printed out by the function) now includes RAW and PIRA counts."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "de8d50e6-28c7-4320-9efa-875e042a1444",
"metadata": {},
"outputs": [],
"source": [
"print(summary)"
]
},
{
"cell_type": "markdown",
"id": "e2543ad1-23da-4ec2-8df5-b99f1d70992e",
"metadata": {},
"source": [
"In the `results` DataFrame, each CDW event is now further characterised by a `CDW_type` column:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a0e400e1-13da-4f8e-8743-b42e5e93359c",
"metadata": {},
"outputs": [],
"source": [
"print(results)"
]
},
{
"cell_type": "markdown",
"id": "f2e52ef3-37fc-48ec-af8b-af88ec7cbd02",
"metadata": {},
"source": [
"## `MSprog()` outputs\n",
"\n",
"### What to include in results\n",
"\n",
"The results DataFrame provides extended info on each event for all subjects. The following arguments can be used to control the information included.\n",
"\n",
"* `include_dates`: if `True`, the results will include the dates of: event onset; baseline; last visit before event onset at clinically meaningful score difference from it; confirmation visit.\n",
"* `include_value`: if `True`, the results will include the outcome value at: event onset; baseline; last visit before event onset at clinically meaningful score difference from it; confirmation visit.\n",
"* `include_stable`: if `True`, subjects with no confirmed events are included in the results, with `time2event` = total follow up.\n",
"\n",
"\n",
"For example:"
]
},
{
"cell_type": "code",
"execution_count": 19,
"id": "7aacb0ca-9395-4648-bf32-b5f4523df33d",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" 0 1 \\\n",
"id 1 2 \n",
"nevent 1 1 \n",
"event_type CDW CDW \n",
"CDW_type PIRA RAW \n",
"bl_date 2021-09-23 00:00:00 2020-11-26 00:00:00 \n",
"bl_value 5.5 4.0 \n",
"date 2022-07-12 00:00:00 2021-06-12 00:00:00 \n",
"value 6.0 5.5 \n",
"total_fu 534.0 730.0 \n",
"time2event 292.0 198.0 \n",
"bl2event 292.0 198.0 \n",
"conf84_date 2022-11-06 00:00:00 2021-09-04 00:00:00 \n",
"conf84_value 6.0 5.0 \n",
"PIRA_conf84_date 2022-11-06 00:00:00 NaT \n",
"PIRA_conf84_value 6.0 NaN \n",
"sust_days 242.0 84.0 \n",
"sust_last 1.0 0.0 \n",
"\n",
" 2 3 \n",
"id 5 7 \n",
"nevent 1 1 \n",
"event_type CDW CDW \n",
"CDW_type PIRA PIRA \n",
"bl_date 2021-06-14 00:00:00 2021-03-10 00:00:00 \n",
"bl_value 4.0 3.5 \n",
"date 2021-11-01 00:00:00 2022-03-17 00:00:00 \n",
"value 5.0 4.5 \n",
"total_fu 637.0 779.0 \n",
"time2event 140.0 372.0 \n",
"bl2event 140.0 372.0 \n",
"conf84_date 2022-01-17 00:00:00 2022-07-22 00:00:00 \n",
"conf84_value 5.5 4.5 \n",
"PIRA_conf84_date 2022-01-17 00:00:00 2022-07-22 00:00:00 \n",
"PIRA_conf84_value 5.5 4.5 \n",
"sust_days 497.0 407.0 \n",
"sust_last 1.0 1.0 \n"
]
}
],
"source": [
"summary, results = MSprog(toydata_visits,\n",
" subj_col='id', value_col='EDSS', date_col='date',\n",
" outcome='edss',\n",
" relapse=toydata_relapses,\n",
" include_dates=True, include_value=True, include_stable=False,\n",
" verbose=0)\n",
"print(results.T)"
]
},
{
"cell_type": "markdown",
"id": "7d38d52e-ad84-4319-b4c2-2257ae43ec60",
"metadata": {},
"source": [
"(printing-progress-info)=\n",
"### Printing progress info\n",
"\n",
"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. \n",
"\n",
"For further insight into the event detection process, the `return_unconfirmed` argument allows to also return all score changes from baseline that were not identified as valid events (e.g., not confirmed).\n",
"\n",
"See the example below."
]
},
{
"cell_type": "code",
"execution_count": 13,
"id": "69f67e8b-805f-4536-b2c6-487507177a8e",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"Subject #1: 8 visits, 0 relapses\n",
"Baseline at visit no.1\n",
"Searching for events from visit no.2 on\n",
"EDSS change at visit no.5 (2022-07-12); potential confirmation visits available: no.6, 7, 8\n",
"Found EDSS-CDW (PIRA) (visit no.5, 2022-07-12) confirmed at 84 weeks, sustained up to visit no.8 (2023-03-11)\n",
"Baseline at visit no.6\n",
"Searching for events from visit no.7 on\n",
"No EDSS change in any subsequent visit: end process\n",
"Event sequence: PIRA\n",
"\n",
"Subject #2: 10 visits, 2 relapses\n",
"Baseline at visit no.1\n",
"Searching for events from visit no.2 on\n",
"EDSS change at visit no.4 (2021-06-12); potential confirmation visits available: no.5, 6, 7, 8, 9, 10\n",
"Found EDSS-CDW (RAW) (visit no.4, 2021-06-12) confirmed at 84 weeks, sustained up to visit no.5 (2021-09-04)\n",
"Baseline at visit no.5\n",
"Searching for events from visit no.6 on\n",
"EDSS change at visit no.8 (2022-05-19); potential confirmation visits available: no.9, 10\n",
"Found EDSS-CDW (PIRA) (visit no.8, 2022-05-19) confirmed at 84 weeks, sustained up to visit no.10 (2022-11-26)\n",
"Baseline at visit no.9\n",
"Searching for events from visit no.10 on\n",
"No EDSS change in any subsequent visit: end process\n",
"Event sequence: RAW, PIRA\n",
"\n",
"Subject #3: 7 visits, 1 relapse\n",
"Baseline at visit no.1\n",
"Searching for events from visit no.2 on\n",
"EDSS change at visit no.2 (2021-12-01); potential confirmation visits available: no.4, 5, 7\n",
"Change not confirmed: proceed with search\n",
"Searching for events from visit no.3 on\n",
"No EDSS change in any subsequent visit: end process\n",
"Event sequence: -\n",
"\n",
"Subject #4: 7 visits, 0 relapses\n",
"Baseline at visit no.1\n",
"Searching for events from visit no.2 on\n",
"EDSS change at visit no.2 (2021-12-04); potential confirmation visits available: no.3, 4, 5, 6, 7\n",
"Found EDSS-CDI (visit no.2, 2021-12-04) confirmed at 84 weeks, sustained up to visit no.3 (2022-03-12)\n",
"Baseline at visit no.3\n",
"Searching for events from visit no.4 on\n",
"EDSS change at visit no.4 (2022-07-19); potential confirmation visits available: no.5, 6, 7\n",
"Found EDSS-CDW (PIRA) (visit no.4, 2022-07-19) confirmed at 84 weeks, sustained up to visit no.7 (2023-04-27)\n",
"Baseline at visit no.5\n",
"Searching for events from visit no.6 on\n",
"No EDSS change in any subsequent visit: end process\n",
"Event sequence: CDI, PIRA\n",
"\n",
"Subject #5: 9 visits, 0 relapses\n",
"Baseline at visit no.1\n",
"Searching for events from visit no.2 on\n",
"EDSS change at visit no.3 (2021-11-01); potential confirmation visits available: no.4, 5, 6, 7, 8, 9\n",
"Found EDSS-CDW (PIRA) (visit no.3, 2021-11-01) confirmed at 84 weeks, sustained up to visit no.9 (2023-03-13)\n",
"Baseline at visit no.4\n",
"Searching for events from visit no.5 on\n",
"EDSS change at visit no.5 (2022-04-30); potential confirmation visits available: no.7, 8, 9\n",
"Change not confirmed: proceed with search\n",
"Searching for events from visit no.6 on\n",
"EDSS change at visit no.8 (2022-12-15); potential confirmation visits available: no.9\n",
"Change not confirmed: proceed with search\n",
"Searching for events from visit no.9 on\n",
"No EDSS change in any subsequent visit: end process\n",
"Event sequence: PIRA\n",
"\n",
"Subject #6: 7 visits, 1 relapse\n",
"Baseline at visit no.1\n",
"Searching for events from visit no.2 on\n",
"EDSS change at visit no.3 (2022-02-15); potential confirmation visits available: no.4, 5, 7\n",
"Found EDSS-CDI (visit no.3, 2022-02-15) confirmed at 84 weeks, sustained up to visit no.5 (2022-10-05)\n",
"Baseline at visit no.4\n",
"Searching for events from visit no.5 on\n",
"EDSS change at visit no.6 (2022-12-22); potential confirmation visits available: no.\n",
"Change not confirmed: proceed with search\n",
"Searching for events from visit no.7 on\n",
"EDSS change at visit no.7 (2023-02-21); potential confirmation visits available: no.\n",
"Change not confirmed: proceed with search\n",
"Searching for events from visit no.- on\n",
"No EDSS change in any subsequent visit: end process\n",
"Event sequence: CDI\n",
"\n",
"Subject #7: 9 visits, 1 relapse\n",
"Baseline at visit no.1\n",
"Searching for events from visit no.2 on\n",
"EDSS change at visit no.3 (2021-09-11); potential confirmation visits available: no.4, 5, 6, 7, 8, 9\n",
"Change not confirmed: proceed with search\n",
"Searching for events from visit no.4 on\n",
"EDSS change at visit no.5 (2022-03-17); potential confirmation visits available: no.6, 7, 8, 9\n",
"Found EDSS-CDW (PIRA) (visit no.5, 2022-03-17) confirmed at 84 weeks, sustained up to visit no.9 (2023-04-28)\n",
"Baseline at visit no.6\n",
"Searching for events from visit no.7 on\n",
"No EDSS change in any subsequent visit: end process\n",
"Event sequence: PIRA\n",
"\n",
"---\n",
"Outcome: edss\n",
"Confirmation over: 84 (-7, +730.5) days\n",
"Baseline: roving\n",
"Relapse influence (baseline): [30, 0] days\n",
"Relapse influence (event): [0, 0] days\n",
"Relapse influence (confirmation): [30, 0] days\n",
"Events detected: multiple\n",
"---\n",
"Total subjects: 7\n",
"---\n",
"Subjects with CDW: 5 (PIRA: 5; RAW: 1)\n",
"Subjects with CDI: 2\n",
"---\n",
"CDW events: 6 (PIRA: 5; RAW: 1)\n",
"CDI events: 2\n"
]
}
],
"source": [
"summary, results, unconfirmed = MSprog(toydata_visits,\n",
" subj_col='id', value_col='EDSS', date_col='date',\n",
" outcome='edss',\n",
" event='multiple', baseline='roving',\n",
" relapse=toydata_relapses,\n",
" return_unconfirmed=True, # <---\n",
" verbose=2) # <---"
]
},
{
"cell_type": "markdown",
"id": "6d45ce0d-750d-467b-9c35-60e640fecea9",
"metadata": {},
"source": [
"
\n",
"\n",
"Let's visualise the unconfirmed events:"
]
},
{
"cell_type": "code",
"execution_count": 14,
"id": "31173e42-8e2b-4f02-a7d1-16e64958db0a",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"---Unconfirmed events:---\n",
" id date value bl_date bl_value closest_rel- closest_rel+\n",
"0 3 2021-12-01 4.5 2021-10-18 3.5 inf 365.0\n",
"1 5 2022-04-30 5.0 2022-01-17 5.5 inf inf\n",
"2 5 2022-12-15 5.0 2022-01-17 5.5 inf inf\n",
"3 6 2022-12-22 6.0 2022-09-03 4.5 4.0 inf\n",
"4 6 2023-02-21 6.0 2022-09-03 4.5 65.0 inf\n",
"5 7 2021-09-11 5.0 2021-03-10 3.5 -0.0 0.0\n"
]
}
],
"source": [
"print('---Unconfirmed events:---')\n",
"print(unconfirmed)"
]
},
{
"cell_type": "markdown",
"id": "8b574c2c",
"metadata": {},
"source": [
"## Time to disability milestone\n",
"\n",
"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.0). This can be computed using function `pymsprog.value_milestone()`.\n",
"\n",
"The following code detects the time to EDSS $\\geq$ 6.0 for each subject in the toy data. "
]
},
{
"cell_type": "code",
"execution_count": 15,
"id": "f41e582f",
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/Users/nmontobbio/code/MSprog/py-MSprog/pymsprog/docs/source/tutorials/../../../pymsprog/__init__.py:1860: FutureWarning: Setting an item of incompatible dtype is deprecated and will raise an error in a future version of pandas. Value '2022-07-12' has dtype incompatible with datetime64[ns], please explicitly cast to a compatible dtype first.\n",
" results.at[subjid, date_col] = display_date(data_id.loc[milestone_idx, date_col], global_start) #_d_# #data_id.loc[milestone_idx,date_col]\n"
]
}
],
"source": [
"from pymsprog import value_milestone\n",
"\n",
"vm = value_milestone(toydata_visits, milestone=6,\n",
" subj_col='id', value_col='EDSS', date_col='date', outcome='edss',\n",
" relapse=toydata_relapses,\n",
" verbose=0)"
]
},
{
"cell_type": "markdown",
"id": "221f2d04-c688-45a6-b570-13f472721195",
"metadata": {},
"source": [
"The function returns a DataFrame indexed by subject IDs:"
]
},
{
"cell_type": "code",
"execution_count": 16,
"id": "95a5bec9",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" date EDSS time2event observed\n",
"1 2022-07-12 6.0 292.0 1\n",
"2 2022-05-19 6.0 539.0 1\n",
"3 2023-02-21 NaN 491.0 0\n",
"4 2023-04-27 NaN 586.0 0\n",
"5 2023-03-13 NaN 637.0 0\n",
"6 2023-02-21 NaN 491.0 0\n",
"7 2023-04-28 NaN 779.0 0\n"
]
}
],
"source": [
"print(vm)"
]
},
{
"cell_type": "markdown",
"id": "53abb650",
"metadata": {},
"source": [
"where: `'date'` contains the date of the first confirmed EDSS $\\geq$ 6.0 (or last date of follow-up if milestone is not reached or not confirmed); `'EDSS'` contains the first EDSS value $\\geq$ 6.0, if present, otherwise no value; `'time2event'` contains the time to reach EDSS $\\geq$ 6.0 (or total follow-up length if not reached or not confirmed); `'observed'` indicates whether EDSS $\\geq$ 6.0 was reached (1) or not (0).\n",
"\n",
"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 for a complete illustration of each of the function arguments and their default values."
]
},
{
"cell_type": "markdown",
"id": "e94cc210-b90c-4ea8-881a-44e78d90b728",
"metadata": {},
"source": [
"## References\n",
"```{bibliography}\n",
":style: plain\n",
":filter: cited\n",
"```"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f009d2d6-e4e2-4b85-9a6b-384ecbadb3bf",
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.13"
}
},
"nbformat": 4,
"nbformat_minor": 5
}