pymsprog 1.0.0

No project description provided

pymsprog: reproducible assessment of disability progression in MS

📖 Documentation

pymsprog is a Python package providing tools for exhaustive and reproducible analysis of disability course in multiple sclerosis (MS) from longitudinal data. An R version of the library is available as well.

Its core function, MSprog(), detects and characterises the evolution of an outcome measure (EDSS, NHPT, T25FW, SDMT; or any custom outcome measure) for one or more subjects, based on repeated assessments through time and on the dates of acute episodes (if any).

The package also provides a small toy dataset for testing and demonstration purposes. The dataset contains 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.

Please refer to the documentation for function usage and data structure. Detailed tutorials providing examples and best-practice tips are also available.

If you use this package in your work, please cite the following work:
Montobbio N, Carmisciano L, Signori A, et al. Creating an automated tool for a consistent and repeatable evaluation of disability progression in clinical studies for multiple sclerosis. Mult Scler. 2024;30(9):1185-1192. doi:10.1177/13524585241243157

For any questions, requests for new features, or bug reporting, please contact: [e-mail]. Any feedback is highly appreciated!

Installation

You can install the latest release of pymsprog with:

pip install pymsprog

Alternatively, the development version can be downloaded from GitHub.

Usage

MSprog() detects disability events sequentially by scanning the outcome values in chronological order.

Several qualitative and quantitative options for event detection are given as arguments that can be set by the user and reported as a complement to the results to ensure reproducibility.

The example below illustrates the function's usage and output:

from pymsprog import MSprog, load_toy_data
import pandas as pd

# Load toy data
toydata_visits, toydata_relapses = load_toy_data()

# Detect events
summary, results = MSprog(toydata_visits,                          # insert data on visits
                 relapse=toydata_relapses,                         # insert data on relapses
                 subj_col='id', value_col='EDSS', date_col='date', # specify column names 
                 outcome='edss',                                   # specify outcome type
                 event='multiple', baseline='roving')              # modify default options on event detection)

---
Outcome: EDSS
Confirmation over: [84] days (-7 days, +730.5 days)
Baseline: roving
Relapse influence (baseline): [30, 0] days
Relapse influence (event): [0, 0] days
Relapse influence (confirmation): [30, 0] days
Events detected: multiple
        
---
Total subjects: 4
---
Progressed: 3 (PIRA: 3; RAW: 1)
Improved: 1
---
CDW events: 4 (PIRA: 3; RAW: 1)
Improvement events: 1

The function prints out a concise report of the results, as well as the specific set of options used to obtain them. Complete results are stored in two pandas.DataFrame objects generated by the function call:

1. A summary table providing the event count for each subject and event type:

  event_sequence  improvement  CDW  RAW  PIRA  undefined_CDW
            PIRA            0    1    0     1              0
       RAW, PIRA            0    2    1     1              0
                            0    0    0     0              0
      impr, PIRA            1    1    0     1              0

where: event_sequence specifies the order of the events; the other columns count the events of each type.

2. Extended info on each event for all subjects:

   id  nevent event_type total_fu time2event conf84  PIRA_conf84 sust_days sust_last
    1       1       PIRA      534        292      1            1       242         1
    2       1        RAW      730        198      1          None        84         0
    2       2       PIRA      730        539      1             1       191         1
    3       0       None      491        491   None          None      None      None
    4       1       impr      586         77      1          None        98         0
    4       2       PIRA      586        304      1             1       282         1

where: nevent is the cumulative event count for each subject; event_type characterises the event; time2event is the number of days from baseline to event; conf84 reports whether the event was confirmed over 84 days (12 weeks); 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.