Uploaded files

Author: noxtoby

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Neil Oxtoby
+Copyright (c) 2023 Neil Oxtoby
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -0,0 +1,54 @@
+# Goldilocks DPM
+
+A Disease Progression Modelling (DPM) implementation of the Goldilocks framework for data-driven model configuration.
+
+Goldilocks (conference paper: [Oxtoby, AAIC 2024](https://doi.org/10.1002/alz.092363)) is a framework for helping users ensure that their data-driven model of choice is configured "just right" for the available data. Conceptually, Goldilocks informs on feature selection and hyperparameter tuning, with respect to signal in the data. This complements work in the field of explainable AI.
+
+![Goldilocks Zone for synthetic ADNI-like data](./in_the_zone.png)
+
+## Contents
+
+1. [goldilocks\_dpm](goldilocks_dpm): python module for implementing the Goldilocks framework within data-driven DPM.
+    1. [demos](goldilocks_dpm/demos): folder containing demo implementations of various DPMs.
+        1. [README](goldilocks_dpm/demos/README.md): describes the `goldilocks-dpm` workflow
+        1. [goldilocks-pysustain.py](goldilocks_dpm/demos/goldilocks-pysustain.py): **Su**btype and **Sta**ge **In**ference
+        1. Calls [plot\_SuStaIn\_model\_arbitrarycolours.py](goldilocks_dpm/demos/plot_SuStaIn_model_arbitrarycolours.py) which demos how to use arbitrary colours in SuStaIn model plotting (thanks to Alex Young for help with this).
+    1. **TODO**. [goldilocks\_ebm.py](): Event-Based Model (GMM, KDE, Ordinal Scored Events)
+1. [ADNIMERGE2023_synthetic.csv](goldilocks_dpm/demos/ADNIMERGE2023_synthetic.csv): Data mimicking [ADNI](https://adni.loni.usc.edu) data based on ADNIMERGE.csv downloaded in May 2023.
+    1. [synthetic_data.ipynb](goldilocks_dpm/demos/synthetic_data.ipynb): Jupyter notebook for generating the above, FYI (don't try to run it unless you have an ADNIMERGE CSV to feed into it).
+
+
+## Workflow
+
+See [goldilocks-pysustain.py](goldilocks_dpm/demos/goldilocks-pysustain.py) for a worked example using ZScoreSustain.
+
+```
+## 1. Prepare your data
+
+## 2. Create a Goldilocks DPM object and run the framework
+
+## ZScoreSuStaIn
+from goldilocks_dpm import goldilocks_ZscoreSustain
+
+gdpm = goldilocks_ZscoreSustain(
+    classes = y,
+    dpmData = X,
+    output_folder = "path/to/output_folder",
+    robust_zscores = False,
+    case_label = 1,
+    ctrl_label = 0, 
+    direction_abnormal = direction_abnormal,
+    biomarker_labels = biomarkers
+)
+
+gdpm.run_goldilocks()
+
+## 3. Interrogate the resulting output.
+print(gdpm.Z_vals)
+print(gdpm.Z_max)
+
+```
+
+## Licence
+
+MIT.

goldilocks_dpm/__init__.py

@@ -0,0 +1,5 @@
+# Authors: Neil Oxtoby <github:noxtoby>
+# License: MIT
+
+from .goldilocks_dpm import *
+from .goldilocks_ZscoreSustain import *

goldilocks_dpm/demos/ADNIMERGE2023_synthetic.csv

@@ -0,0 +1,60 @@
+# Goldilocks DPM Demos
+
+Demonstrations of the [Goldilocks-DPM](../) framework for data-driven **D**isease **P**rogression **M**odel configuration.
+
+## Contents
+
+1. [goldilocks-pysustain.py](./goldilocks-pysustain.py): **Su**btype and **Sta**ge **In**ference ([Young et al., Nature Communications 2018](https://doi.org/10.1038/s41467-018-05892-0))
+1. Future feature (**TODO**): [goldilocks-ebm.py](): Event-Based Model ([Fonteijn, et al., NeuroImage 2012](https://doi.org/10.1016/j.neuroimage.2012.01.062))
+
+### Workflow for Z-Score SuStaIn
+
+See [goldilocks-pysustain.py](./goldilocks-pysustain.py) for a worked example, but here's a conceptual overview.
+
+* Import the module:
+
+```
+from goldilocks_dpm import goldilocks_ZscoreSustain
+```
+
+<br/>
+
+* Prepare your data.
+   - SuStaIn: see examples in [pySuStaIn](https://github.com/ucl-pond/pySuStaIn) for inspiration and guidance.
+   - EBM: see [kde_ebm](https://github.com/ucl-pond/kde_ebm) and [disease-progression-modelling.github.io](https://disease-progression-modelling.github.io) for inspiration and guidance. 
+
+<br/>
+
+* Create a goldilocks ZScoreSustaIn object including your data matrix `X` and vector `y` labelling cases and controls (controls are used to z-score your data):
+
+```
+output_folder = Path.cwd() # or wherever you want the output to go
+
+gdpm = goldilocks_ZscoreSustain(
+    dpmData = X,
+    classes = y,
+    output_folder = output_folder,
+    robust_zscores = False,
+    case_label = 1,
+    ctrl_label = 0, 
+    direction_abnormal = direction_abnormal,
+    biomarker_labels = biomarkers
+)
+```
+
+<br/>
+
+* Run the goldilocks zone calculation
+
+```
+gdpm.run_goldilocks(
+    plot = True,
+    plot_format = "png",
+    verbose = False
+)
+```
+
+<br/>
+
+* Your `goldilocks_ZscoreSustain` object will now contain the z-scored X data, and goldilocks-suggested pySuStaIn hyperparameters `Z_vals` and `Z_max`
+

goldilocks_dpm/demos/README.md

@@ -0,0 +1,5 @@
+# Authors: Neil Oxtoby <github:noxtoby>
+# License: MIT
+
+from .goldilocks_dpm import *
+from .goldilocks_ZscoreSustain import *