Metadata-Version: 2.1
Name: pymsprog
Version: 0.1.1
Summary: 
Author: noemi.montobbio
Author-email: noemi.montobbio@gmail.com
Requires-Python: >=3.7,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Description-Content-Type: text/markdown


# pymsprog: reproducible assessment of disability progression in MS

[![Python 3.7](https://img.shields.io/badge/python-3.7-blue.svg)](https://www.python.org/downloads/release/python-370/)

`pymsprog` provides tools for exhaustive and reproducible analysis of disability progression 
in multiple sclerosis (MS) from longitudinal data.

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

[//]: # (The package also provides two toy datasets for function testing:)

[//]: # ()
[//]: # (* `toydata_visits`: artificially generated EDSS and SDMT assessments for four patients;)

[//]: # (* `toydata_relapses`: artificially generated relapse dates associated with the patients in `toydata_visits`.)

A detailed tutorial in the form of a Jupyter Notebook (`pymsprog_tutorial.ipynb`) 
is available in the repo.

## Installation

You can install the latest release of `pymsprog`  with:
```commandline
pip install pymsprog
```
Alternatively, the development version can be downloaded from 
[GitHub](https://github.com/noemimontobbio/pymsprog).


## Usage

`MSprog` detects the events sequentially by scanning the outcome values in chronological order, 
and classifies progression events as relapse-associated or relapse-independent based on their 
relative timing with respect to the relapses [[1](#lublin2014), [2](#kappos2018), [3](#silent)]. 

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. 
These include the baseline scheme (fixed or roving), 
the events to be detected (first or multiple, progression and/or improvement), 
the length of the relapse influence window and of the event confirmation period(s) 
with the relative tolerance.

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

```{python}
from pymsprog import MSprog
import pandas as pd

# Load toy data
toydata_visits = pd.read_excel('MSprog_toydata.xlsx', sheet_name='visits')
toydata_relapses = pd.read_excel('MSprog_toydata.xlsx', sheet_name='relapses')


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


---
Outcome: EDSS
Confirmation at: [3]mm (-30dd, +30dd)
Baseline: roving
Relapse influence: 30dd
Events detected: multiple
---
Total subjects: 4
---
Progressed: 3 (PIRA: 3; RAW: 1)
Improved: 1
---
Progression events: 4 (PIRA: 3; RAW: 1)
Improved: 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  progression  RAW  PIRA  undefined_prog
           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 time2event conf3 sust_days sust_last
   1       1       PIRA        292     1       125         1
   2       1        RAW        198     1         0         0
   2       2       PIRA        257     1        90         1
   4       1       impr         77     1         0         0
   4       2       PIRA        129     1       204         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; `conf3` reports whether the event was 
confirmed; `sust_days` is the number of days for which the event was sustained *after confirmation*; 
`sust_last` reports whether the event was sustained until the last visit.

<br />

    
## References


<a id="lublin2014">[1]</a> 
Lublin FD, Reingold SC, Cohen JA, Cutter GR, Sørensen PS, Thompson
AJ, et al. Defining the clinical course of multiple sclerosis. Neurology
\[Internet\]. 2014;83:278–86. Available from:
<https://n.neurology.org/content/83/3/278>


<a id="kappos2018">[2]</a> 
Kappos L, Butzkueven H, Wiendl H, Spelman T, Pellegrini F, Chen Y,
et al. Greater sensitivity to multiple sclerosis disability worsening
and progression events using a roving versus a fixed reference value in
a prospective cohort study. Multiple Sclerosis Journal \[Internet\].
2018;24:963–73. Available from:
<https://doi.org/10.1177/1352458517709619>


<a id="silent">[3]</a> 
University of California SFM-ET, Cree BAC, Hollenbach JA, Bove R,
Kirkish G, Sacco S, et al. Silent progression in disease activity–free
relapsing multiple sclerosis. Annals of Neurology \[Internet\].
2019;85:653–66. Available from:
<https://onlinelibrary.wiley.com/doi/abs/10.1002/ana.25463>

