Metadata-Version: 2.3
Name: pymsprog
Version: 1.0.0
Summary: 
Author: noemi.montobbio
Author-email: noemi.montobbio@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: numpy (>=1.26,<2.0)
Requires-Dist: pandas (>=2.3.0,<3.0.0)
Description-Content-Type: text/markdown


# pymsprog: reproducible assessment of disability progression in MS

![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)

[📖 Documentation](https://pymsprog.readthedocs.io)

`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](https://github.com/noemimontobbio/msprog) 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](https://pymsprog.readthedocs.io) 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:**<br />
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: **noemi.montobbio@unige.it**. Any feedback is highly
appreciated!

## 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 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:

```{python}
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.


