Add protosleepnet-gagliardi and protosleeptransformer-gagliardi (multi-dataset PSN/PST)

README.md

@@ -24,6 +24,10 @@ All models follow the AASM 5-class standard: **W, N1, N2, N3, REM**.
 | `seqsleepnet-phan` | BiLSTM + Attention | Sleep-EDF | 0.810 | 0.758 | 0.742 | 659K | Phan et al. 2019 |
 | `chambon2018` | Braindecode CNN | MASS SS3 | 0.826 | 0.731 | 0.736 | 29K | Chambon et al. 2018 |
 | `tsinalis-2016` | 2-layer CNN | Sleep-EDF | 0.773 | 0.661 | 0.683 | 145K | Tsinalis et al. 2016 |
+| `protosleeptransformer-gagliardi` | Prototype-based Transformer | 28 sites (multi-dataset) | 0.880 | 0.797 | 0.829 | 4.0M | Gagliardi et al. |
+| `protosleepnet-gagliardi` | Prototype-based BiLSTM + Attention | 28 sites (multi-dataset) | 0.872 | 0.780 | 0.818 | 792K | Gagliardi et al. |
+
+The two `*-gagliardi` models are trained jointly on 28 sites; ACC / F1 / κ in this table are on the SHHS test subjects (842). Per-site test metrics for every training site are in each model folder (`metrics.json`) and on the [documentation page](https://guidogagl.github.io/physioex/pages/train/networks/protosleepnet.html). These sites were seen in training (other subjects), so the numbers are not an external validation.
 
 ## Usage
 
@@ -37,6 +41,15 @@ from physioex.models import load_embeddings
 path = load_embeddings("sleeptransformer-phan", "hmc", verbose=True)
 ```
 
+### ProtoSleepNet and ProtoSleepTransformer
+
+```python
+model = load_from_pretrained("protosleeptransformer-gagliardi", verbose=True)   # L=21; "protosleepnet-gagliardi" has L=20
+# input (batch, L, 3, 29, 129): log-power spectrograms of EEG, EOG, EMG; output (batch, L, 5) logits W/N1/N2/N3/REM
+```
+
+Interpretable, prototype-based sleep staging ([paper and code](https://github.com/guidogagl/protosleepnet), npj Digital Medicine). These checkpoints are the multi-dataset models; they contain no prototype codebook (`quantize=True` needs one learned after training, see the paper repository). Research use only; not a medical device.
+
 ## Pre-extracted Embeddings
 
 | Model | HuggingFace Repo | Datasets |

protosleepnet-gagliardi/config.json

@@ -0,0 +1,67 @@
+{
+  "model_class": "physioex.models.protosleepnet:ProtoSleepNet",
+  "factory": "from_seq_sleep_net",
+  "factory_kwargs": {
+    "n_channels": 3,
+    "use_channel_mixer": true,
+    "cdropout": 0.5,
+    "cm_n_heads": 4,
+    "cm_d_ff": 256,
+    "cm_n_layers": 1
+  },
+  "training": {
+    "backbone": "seq",
+    "dataset": "multi-dataset",
+    "sites": [
+      "alzheimers_hc",
+      "dcsm",
+      "hmc",
+      "hpap",
+      "mass_ss01",
+      "mass_ss02",
+      "mass_ss03",
+      "mass_ss04",
+      "mass_ss05",
+      "mesa",
+      "mros",
+      "parkinsons_night_hoa",
+      "shhs",
+      "sleepedf",
+      "stages_BOGN",
+      "stages_GSBB",
+      "stages_GSDV",
+      "stages_GSLH",
+      "stages_GSSA",
+      "stages_GSSW",
+      "stages_MSMI",
+      "stages_MSNF",
+      "stages_MSQW",
+      "stages_MSTH",
+      "stages_MSTR",
+      "stages_STLK",
+      "stages_STNF",
+      "wsc"
+    ],
+    "channels": [
+      "EEG",
+      "EOG",
+      "EMG"
+    ],
+    "pipeline_preset": "seqsleepnet",
+    "sequence_length": 20,
+    "step": 161500,
+    "epoch": 17,
+    "max_epochs": 20,
+    "epoch_size": 300000,
+    "batch_size": 32,
+    "lr": 0.0001,
+    "weight_decay": 0.0,
+    "cdropout": 0.5,
+    "scheduler": "plateau",
+    "seed": 42,
+    "val_subjects_per_site": 30,
+    "n_parameters": 792843,
+    "model_pt_sha256": "1156a3fe18d3bc8a83a775bcc8e1a1ba08c0c4624b3415a4fc07982e907136db"
+  },
+  "reference": "Gagliardi et al. - Prototype-based interpretable sleep staging with physiologically meaningful sub-stage pattern discovery (npj Digital Medicine); ProtoSleepNet with a SeqSleepNet epoch encoder"
+}

protosleepnet-gagliardi/metrics.json

@@ -0,0 +1,158 @@
+{
+  "dcsm": {
+    "accuracy": 0.8669193387031555,
+    "f1_score": 0.7735686242580414,
+    "cohen_kappa": 0.8085136413574219,
+    "n_subjects": 26
+  },
+  "hmc": {
+    "accuracy": 0.8137681484222412,
+    "f1_score": 0.7843350291252136,
+    "cohen_kappa": 0.754386842250824,
+    "n_subjects": 15
+  },
+  "hpap": {
+    "accuracy": 0.847312867641449,
+    "f1_score": 0.8011698484420776,
+    "cohen_kappa": 0.790353536605835,
+    "n_subjects": 25
+  },
+  "mass_ss01": {
+    "accuracy": 0.8113972544670105,
+    "f1_score": 0.760994303226471,
+    "cohen_kappa": 0.7239391803741455,
+    "n_subjects": 5
+  },
+  "mass_ss02": {
+    "accuracy": 0.9103608727455139,
+    "f1_score": 0.8373631477355957,
+    "cohen_kappa": 0.8577286601066589,
+    "n_subjects": 2
+  },
+  "mass_ss03": {
+    "accuracy": 0.8884488344192505,
+    "f1_score": 0.8440731763839722,
+    "cohen_kappa": 0.8354583382606506,
+    "n_subjects": 6
+  },
+  "mass_ss04": {
+    "accuracy": 0.8713385462760925,
+    "f1_score": 0.8337583422660828,
+    "cohen_kappa": 0.8140228390693665,
+    "n_subjects": 4
+  },
+  "mass_ss05": {
+    "accuracy": 0.8910866379737854,
+    "f1_score": 0.8205164313316345,
+    "cohen_kappa": 0.8412991166114807,
+    "n_subjects": 3
+  },
+  "mesa": {
+    "accuracy": 0.8415964245796204,
+    "f1_score": 0.7709669828414917,
+    "cohen_kappa": 0.7755186557769775,
+    "n_subjects": 206
+  },
+  "mros": {
+    "accuracy": 0.8590859174728394,
+    "f1_score": 0.7569057703018188,
+    "cohen_kappa": 0.7947317361831665,
+    "n_subjects": 219
+  },
+  "shhs": {
+    "accuracy": 0.8721997737884521,
+    "f1_score": 0.7802436530590058,
+    "cohen_kappa": 0.8181514143943787,
+    "n_subjects": 842
+  },
+  "sleepedf": {
+    "accuracy": 0.8423321843147278,
+    "f1_score": 0.7936996340751648,
+    "cohen_kappa": 0.7777798175811768,
+    "n_subjects": 15
+  },
+  "stages_BOGN": {
+    "accuracy": 0.8653397560119629,
+    "f1_score": 0.8055032849311828,
+    "cohen_kappa": 0.7999787330627441,
+    "n_subjects": 8
+  },
+  "stages_GSBB": {
+    "accuracy": 0.8141167759895325,
+    "f1_score": 0.6905997812747955,
+    "cohen_kappa": 0.7291826605796814,
+    "n_subjects": 3
+  },
+  "stages_GSDV": {
+    "accuracy": 0.8038463592529297,
+    "f1_score": 0.6973017871379852,
+    "cohen_kappa": 0.6794775724411011,
+    "n_subjects": 19
+  },
+  "stages_GSLH": {
+    "accuracy": 0.8122743964195251,
+    "f1_score": 0.7400574326515198,
+    "cohen_kappa": 0.7323593497276306,
+    "n_subjects": 3
+  },
+  "stages_GSSA": {
+    "accuracy": 0.8259979486465454,
+    "f1_score": 0.6725034892559052,
+    "cohen_kappa": 0.6955694556236267,
+    "n_subjects": 5
+  },
+  "stages_GSSW": {
+    "accuracy": 0.8364912271499634,
+    "f1_score": 0.7105811983346939,
+    "cohen_kappa": 0.7221176028251648,
+    "n_subjects": 8
+  },
+  "stages_MSMI": {
+    "accuracy": 0.8399351239204407,
+    "f1_score": 0.7874741137027741,
+    "cohen_kappa": 0.764193058013916,
+    "n_subjects": 6
+  },
+  "stages_MSNF": {
+    "accuracy": 0.8536977767944336,
+    "f1_score": 0.7420601010322571,
+    "cohen_kappa": 0.7350186705589294,
+    "n_subjects": 4
+  },
+  "stages_MSQW": {
+    "accuracy": 0.8049342632293701,
+    "f1_score": 0.7340189278125763,
+    "cohen_kappa": 0.7112038135528564,
+    "n_subjects": 15
+  },
+  "stages_MSTH": {
+    "accuracy": 0.8230452537536621,
+    "f1_score": 0.7710439085960388,
+    "cohen_kappa": 0.7448060512542725,
+    "n_subjects": 3
+  },
+  "stages_MSTR": {
+    "accuracy": 0.8494215607643127,
+    "f1_score": 0.7995543360710144,
+    "cohen_kappa": 0.7792340517044067,
+    "n_subjects": 29
+  },
+  "stages_STLK": {
+    "accuracy": 0.8020937442779541,
+    "f1_score": 0.7044362127780914,
+    "cohen_kappa": 0.7082521319389343,
+    "n_subjects": 16
+  },
+  "stages_STNF": {
+    "accuracy": 0.6911861300468445,
+    "f1_score": 0.6302476167678833,
+    "cohen_kappa": 0.5907843112945557,
+    "n_subjects": 49
+  },
+  "wsc": {
+    "accuracy": 0.8327528834342957,
+    "f1_score": 0.7292141616344452,
+    "cohen_kappa": 0.7345144748687744,
+    "n_subjects": 235
+  }
+}

protosleepnet-gagliardi/model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1156a3fe18d3bc8a83a775bcc8e1a1ba08c0c4624b3415a4fc07982e907136db
+size 3185744

protosleeptransformer-gagliardi/config.json

@@ -0,0 +1,67 @@
+{
+  "model_class": "physioex.models.protosleepnet:ProtoSleepNet",
+  "factory": "from_sleep_transformer",
+  "factory_kwargs": {
+    "n_channels": 3,
+    "use_channel_mixer": true,
+    "cdropout": 0.5,
+    "cm_n_heads": 4,
+    "cm_d_ff": 256,
+    "cm_n_layers": 1
+  },
+  "training": {
+    "backbone": "st",
+    "dataset": "multi-dataset",
+    "sites": [
+      "alzheimers_hc",
+      "dcsm",
+      "hmc",
+      "hpap",
+      "mass_ss01",
+      "mass_ss02",
+      "mass_ss03",
+      "mass_ss04",
+      "mass_ss05",
+      "mesa",
+      "mros",
+      "parkinsons_night_hoa",
+      "shhs",
+      "sleepedf",
+      "stages_BOGN",
+      "stages_GSBB",
+      "stages_GSDV",
+      "stages_GSLH",
+      "stages_GSSA",
+      "stages_GSSW",
+      "stages_MSMI",
+      "stages_MSNF",
+      "stages_MSQW",
+      "stages_MSTH",
+      "stages_MSTR",
+      "stages_STLK",
+      "stages_STNF",
+      "wsc"
+    ],
+    "channels": [
+      "EEG",
+      "EOG",
+      "EMG"
+    ],
+    "pipeline_preset": "seqsleepnet",
+    "sequence_length": 21,
+    "step": 129000,
+    "epoch": 13,
+    "max_epochs": 20,
+    "epoch_size": 300000,
+    "batch_size": 32,
+    "lr": 0.0001,
+    "weight_decay": 0.0,
+    "cdropout": 0.5,
+    "scheduler": "plateau",
+    "seed": 42,
+    "val_subjects_per_site": 30,
+    "n_parameters": 3975947,
+    "model_pt_sha256": "08d0fbc806fc08dc7d0167e1c2b81b0e2b4f5495bad2c1e5dda6bde14972e603"
+  },
+  "reference": "Gagliardi et al. - Prototype-based interpretable sleep staging with physiologically meaningful sub-stage pattern discovery (npj Digital Medicine); ProtoSleepNet with a SleepTransformer epoch encoder (ProtoSleepTransformer)"
+}

protosleeptransformer-gagliardi/metrics.json

@@ -0,0 +1,158 @@
+{
+  "dcsm": {
+    "accuracy": 0.8702830672264099,
+    "f1_score": 0.7813203930854797,
+    "cohen_kappa": 0.814110517501831,
+    "n_subjects": 26
+  },
+  "hmc": {
+    "accuracy": 0.8149487376213074,
+    "f1_score": 0.7894913554191589,
+    "cohen_kappa": 0.7542371153831482,
+    "n_subjects": 15
+  },
+  "hpap": {
+    "accuracy": 0.8568612933158875,
+    "f1_score": 0.8123102903366088,
+    "cohen_kappa": 0.8033641576766968,
+    "n_subjects": 25
+  },
+  "mass_ss01": {
+    "accuracy": 0.8099777102470398,
+    "f1_score": 0.7662928938865662,
+    "cohen_kappa": 0.7229146361351013,
+    "n_subjects": 5
+  },
+  "mass_ss02": {
+    "accuracy": 0.899495542049408,
+    "f1_score": 0.8326705098152161,
+    "cohen_kappa": 0.8409970998764038,
+    "n_subjects": 2
+  },
+  "mass_ss03": {
+    "accuracy": 0.8935643434524536,
+    "f1_score": 0.8462500929832458,
+    "cohen_kappa": 0.8430709838867188,
+    "n_subjects": 6
+  },
+  "mass_ss04": {
+    "accuracy": 0.8704115748405457,
+    "f1_score": 0.8285602331161499,
+    "cohen_kappa": 0.8123855590820312,
+    "n_subjects": 4
+  },
+  "mass_ss05": {
+    "accuracy": 0.8880821466445923,
+    "f1_score": 0.8241837739944458,
+    "cohen_kappa": 0.8376818895339966,
+    "n_subjects": 3
+  },
+  "mesa": {
+    "accuracy": 0.8423029184341431,
+    "f1_score": 0.7783137679100036,
+    "cohen_kappa": 0.7777889370918274,
+    "n_subjects": 206
+  },
+  "mros": {
+    "accuracy": 0.8716872930526733,
+    "f1_score": 0.76549391746521,
+    "cohen_kappa": 0.8110989928245544,
+    "n_subjects": 219
+  },
+  "shhs": {
+    "accuracy": 0.8797802329063416,
+    "f1_score": 0.7969330906867981,
+    "cohen_kappa": 0.8292210102081299,
+    "n_subjects": 842
+  },
+  "sleepedf": {
+    "accuracy": 0.8419311046600342,
+    "f1_score": 0.7802790582180024,
+    "cohen_kappa": 0.7753002047538757,
+    "n_subjects": 15
+  },
+  "stages_BOGN": {
+    "accuracy": 0.8734385967254639,
+    "f1_score": 0.8174633622169495,
+    "cohen_kappa": 0.8110359311103821,
+    "n_subjects": 8
+  },
+  "stages_GSBB": {
+    "accuracy": 0.8277900815010071,
+    "f1_score": 0.7078808963298797,
+    "cohen_kappa": 0.7492383718490601,
+    "n_subjects": 3
+  },
+  "stages_GSDV": {
+    "accuracy": 0.7771223187446594,
+    "f1_score": 0.6878511548042298,
+    "cohen_kappa": 0.6485589742660522,
+    "n_subjects": 19
+  },
+  "stages_GSLH": {
+    "accuracy": 0.7902125716209412,
+    "f1_score": 0.6977275252342224,
+    "cohen_kappa": 0.699348509311676,
+    "n_subjects": 3
+  },
+  "stages_GSSA": {
+    "accuracy": 0.8213919997215271,
+    "f1_score": 0.6764142096042634,
+    "cohen_kappa": 0.6922687292098999,
+    "n_subjects": 5
+  },
+  "stages_GSSW": {
+    "accuracy": 0.812491238117218,
+    "f1_score": 0.6743945777416229,
+    "cohen_kappa": 0.6745665073394775,
+    "n_subjects": 8
+  },
+  "stages_MSMI": {
+    "accuracy": 0.8343757390975952,
+    "f1_score": 0.7943509340286254,
+    "cohen_kappa": 0.7625976800918579,
+    "n_subjects": 6
+  },
+  "stages_MSNF": {
+    "accuracy": 0.8530546426773071,
+    "f1_score": 0.7574287533760071,
+    "cohen_kappa": 0.742588996887207,
+    "n_subjects": 4
+  },
+  "stages_MSQW": {
+    "accuracy": 0.8185931444168091,
+    "f1_score": 0.7487448275089263,
+    "cohen_kappa": 0.7301760315895081,
+    "n_subjects": 15
+  },
+  "stages_MSTH": {
+    "accuracy": 0.8234567642211914,
+    "f1_score": 0.762702202796936,
+    "cohen_kappa": 0.743338942527771,
+    "n_subjects": 3
+  },
+  "stages_MSTR": {
+    "accuracy": 0.8437274098396301,
+    "f1_score": 0.795867669582367,
+    "cohen_kappa": 0.7728587985038757,
+    "n_subjects": 29
+  },
+  "stages_STLK": {
+    "accuracy": 0.8119391798973083,
+    "f1_score": 0.7170879185199738,
+    "cohen_kappa": 0.7238086462020874,
+    "n_subjects": 16
+  },
+  "stages_STNF": {
+    "accuracy": 0.7204012274742126,
+    "f1_score": 0.67246994972229,
+    "cohen_kappa": 0.6321213245391846,
+    "n_subjects": 49
+  },
+  "wsc": {
+    "accuracy": 0.8454704284667969,
+    "f1_score": 0.7394338309764862,
+    "cohen_kappa": 0.7503787875175476,
+    "n_subjects": 235
+  }
+}

protosleeptransformer-gagliardi/model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08d0fbc806fc08dc7d0167e1c2b81b0e2b4f5495bad2c1e5dda6bde14972e603
+size 15935623