Merge

LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2020 sbhattacharyay
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-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.
+MIT License
+
+Copyright (c) 2020 Shubhayu Bhattacharyay, Matthew Wang, Eshan Joshi, and Robert Stevens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

README.md

@@ -1,9 +1,63 @@
-# Decoding Quantitative Motor Features for Classification and Prediction in Severe Acquired Brain Injury
-
-Brain Injury Motion Sensing (BIMS) Project
-
-NOTE: Running MATLAB scripts will require installation of the Financial Toolbox.
-
-Johns Hopkins University
-
-This project is licensed under the terms of the MIT license.
+[![DOI](https://zenodo.org/badge/236843680.svg)](https://zenodo.org/badge/latestdoi/236843680)
+
+# Decoding accelerometry for classification and prediction of critically ill patients with severe brain injury
+A pilot study of the Neurological Injury Motion Sensing (NIMS) project
+
+Bhattacharyay, S., Rattray, J., Wang, M. _et al._ Decoding accelerometry for classification and prediction of critically ill patients with severe brain injury. _Sci Rep_ 11, 23654 (2021). https://doi.org/10.1038/s41598-021-02974-w
+
+## Contents
+
+- [Overview](#overview)
+- [Abstract](#abstract)
+- [Code](#code)
+- [License](./LICENSE)
+- [Citation](#citation)
+
+## Overview
+
+This repository contains the code underlying the article entitled **Decoding accelerometry for classification and prediction of critically ill patients with severe brain injury** from the Johns Hopkins University [Laboratory of Computational Intensive Care Medicine](https://lcicm.jhmi.edu/). In this file, we present the abstract, to outline the motivation for the work and the findings, and then a brief description of the code with which we generate these finding and achieve this objective.\
+\
+The code on this repository is commented throughout to provide a description of each step alongside the code which achieves it.
+
+## Abstract
+
+The goal of this research is to explore quantitative motor features in critically ill patients with severe brain injury (SBI). We hypothesized that computational decoding of these features would yield important information on underlying neurological states and clinical outcomes. Using wearable microsensors placed on all extremities, we recorded 1,701 hours of continuous, high-frequency accelerometry data from a prospective cohort of patients (n = 69) admitted to the ICU with SBI. Models were trained using time-, frequency-, and wavelet-domain motion features and levels of responsiveness and outcome as labels. The two primary tasks were detection of levels of responsiveness assessed by motor sub-score of the Glasgow Coma Scale (GCSm), and prediction of functional outcome at hospital discharge measured with the Glasgow Outcome Scale–Extended (GOSE). Detection models achieved significant (AUC: 0.70 [95% CI: 0.53–0.85]) and consistent (observation windows: 12 min – 9 hours) discrimination of SBI patients capable of purposeful movement (GCSm > 4). Prediction models accurately discriminated SBI patients of upper moderate disability or better (GOSE > 5) with 2–6 hours of observation (AUC: 0.82 [95% CI: 0.75–0.90]). Results suggest that computational analysis of time series motor activity in patients with SBI yields clinically important insights on underlying neurologic states and short-term clinical outcomes.
+
+## Code 
+All of the code used in this work can be found in the `./scripts` directory as MATLAB (`.m`) files, R (`.R`) files, or Jupyter notebooks (`.ipynb`). Moreover, generalised functions have been saved in the `./scripts/functions` sub-directory and `.py` scripts used to record accelerometry data from the bedside are available in the `./scripts/accel_recording_scripts` sub-directory.
+
+### 1. [Complete Motion Feature Extraction](scripts/01_motion_feature_extraction.m)
+In this `.m` script, we iterate through compiled triaxial accelerometry information from each patient, filter each axis with a high-pass (_f_c_ = 0.2 Hz) 4th-order Butterworth filter, and extract 7 different motion features from non-overlapping 5 second windows. Outputs are saved as `.csv` feature tables. We also plot short examples of the accelerometry processing pipeline for Figure 1 in this script.
+
+### 2. [Multiple Imputation of Missing Accelerometery Values](scripts/02_missing_feature_imputation.R)
+In this `.R` script, we apply our multiple missing feature imputation algorithm. In the event of totally missing recordings (_n_ = 10/483), we impute upper extremity recordings with linear regression from ipsilateral upper extremity sensors, we impute lower extremity recordings with linear regression from contralateral upper extremity sensors, and bed sensors are imputed with sampling with replacement from the total distribution of bed sensor values. Then, the large majority of missing values were imputed with multiple, normalized time-series imputation with the `Amelia II` package. We create 9 imputations, each stored in a separate `.csv` file.
+
+### 3. [Bed Motion Correction and Collection of Multiple Imputations](scripts/03_bed_movement_correction.R)
+In this `.R` script, we correct gross-external movements by properly adjusting for the motion features calculated from the sensor placed at the foot of each patient's bed. Based on a literature-sourced threshold of SMA for human dynamic activity, we define distributions for each feature correspodning to static activity, and correct bed sensoer feature values from extremity sensors accordingly. As a result, we have 9 bed-corrected, imputed feature sets, each stored in a separate `.csv` file.
+
+### 4. [Resampling of GCS data for classification](scripts/04_create_repeated_cv_folds.R)
+In this `.R` file, we create repeated cross-validation (5 repeats of 5-fold CV) for each tested observation window based on the available GCS observations for each observation window. We principally use the `createMultiFolds` function from the `caret` package to stratify folds by outcome labels. Folds for each observation window are stored in a `.csv` file in a newly created directory.
+
+### 5. [LOL embedding for dimensionality reduction](scripts/05_dim_reduction.R)
+In this `.R` file, we train Linear Optimal Low Rank Projections [(LOL)](https://neurodata.io/lol/) on model training sets and reduce both training and validation sets to low-dimensional spaces prior to model training. Prior to LOL, we normalize feature spaces per the distribution of feature type and sensor combinations. This enables us to use LOL coefficients to compare feature type and sensor significance. 
+
+### 6. [Train and evaluate prediction models and measure feature significance scores](scripts/06_prediction_models.R)
+In this `.R` file, we train and validate logistic regression models (GLM) for threshold-level GCSm detection, threshold-level GOSE at discharge prediction, and threshold-level GOSE at 12 months prediction. We train and evaluate models of varying observation windows and target dimensionalities. In this script, we also calculate our feature significance scores. This is equiavalent to the absolute LOL coefficient weighted by the trained linear coefficients of the corresponding logistic regression model.
+
+### 7. [Calculate bootstrapping bias-corrected cross-validation (BBC-CV) area under the receiver operating characteristic curve (AUC) and classification metrics](scripts/07_calculate_metrics.ipynb)
+In this `.ipynb` notebook, we calculate AUCs, ROC curves, and classification metrics for each observation window based on the validation set predictions returned by our models. We use bias-corrected bootstrapping for repeated cross-validation [(Repeated BBC-CV)](https://doi.org/10.1007/s10994-018-5714-4) to calculate 95% confidence intervals for the metrics and the ROC curve. This script is programmed to perform bootstrapping in parallel on 10 cores.
+
+### 8. [Calculate model calibration on validation set predictions](scripts/08_model_calibration_calculation.R)
+In this `.R` file, we calculate probability calibration curves and associated calibration metrics for each observation window based on the validation set predictions returned by our models. We use bias-corrected bootstrapping for repeated cross-validation [(Repeated BBC-CV)](https://doi.org/10.1007/s10994-018-5714-4) to calculate 95% confidence intervals for the metrics and the calibration curve. This script is programmed to perform bootstrapping in parallel on 10 cores.
+
+### 9. [Case study exploration](scripts/09_case_study_exploration.R)
+In this `.R` file, we retrospectively examine predictions of _Pr_(GCSm > 4) in patients (_n_ = 6) who experienced neurological transitions across this threshold to visually determine potential clinical utility of the accelerometry-based system. For each of the 6 patients, we train optimally discriminating detection models (one with a shorter observation window of 27 minutes and one with a longer observation window of 6 hours) on the remaining patient set and validate predictions on the case study patients specifically over a large, continuously overlapping observation window set. We bootstrap across imputations to produce 95% confidence intervals that account for variation due to imputation on the predictions. Then, we prepare the probability trajectories for plotting.
+
+### 10. [Create manuscript tables and perform statistical analyses](scripts/10_tables_and_statistics.R)
+In this `.R` file, we construct manuscript tables and perform miscellaneous statistical analyses for different parts (including figures) of the manuscript and supplementary materials. In addition to the classification metrics calculated in script no. 7, we also calculate classification accuracy with repeated BBC-CV in this script.
+
+### 11. [Plot figures for the manuscript](scripts/11_manuscript_figures.R)
+In this `.R` file, we produce the figures for the manuscript and the supplementary figures. The large majority of the quantitative figures in the manuscript are produced using the `ggplot` package.
+
+## Citation
+Bhattacharyay, S., Rattray, J., Wang, M. _et al._ Decoding accelerometry for classification and prediction of critically ill patients with severe brain injury. _Sci Rep_ 11, 23654 (2021). https://doi.org/10.1038/s41598-021-02974-w

accel_sensor_data/README.md

@@ -0,0 +1,37 @@
+# Unfiltered triaxial accelerometry (10 Hz) for NIMS
+
+## Data access instructions
+The data corresponding to this directory can be found at the following citation link:
+> Bhattacharyay, Shubhayu; Wang, Matthew; Rattray, John; Etienne-Cummings, Ralph; Kudela, Pawel; Stevens, Robert David, 2021, "Unfiltered triaxial accelerometry (10 Hz) for NIMS", https://doi.org/10.7910/DVN/SXNBGB, Harvard Dataverse, V1
+
+You will be asked to submit a request to access the data.
+
+## Description
+Raw accelerometry (10 Hz, unit: g) file names are formatted as: `‘accel_’ + unique patient identifier (UPI) + ‘.mat’`. For patients for whom we collected data too large to fit into one file, data is split into one file per sensor (7 sensors total), and file names are formatted as follows: `‘accel_’ + unique patient identifier (UPI) + ‘_C’ + sensor number (1 – 7) + ‘.mat’`.
+
+For complete `.mat` files, each file contains a MATLAB cell array (12 x 7) called `data`. The columns of this cell array correspond to the different sensors (in order: Bed [control sensor], Left Ankle, Left Elbow, Left Wrist, Right Ankle, Right Elbow, Right Wrist) and the rows of the cell array correspond to the different channels of the sensors. For this study, only rows 5-7 (x-,y-, and z-axes respectively) and row 12 (time of day stamps) are used, and thus rows 1-4 and 8-11 can be removed.
+
+For sensor-specific `.mat` files (ending in `_C#.mat`), each file contains a MATLAB cell array (1 x 12) called `C#`. This corresponds to the different channels of the sensor. For this study, only cells 5-7 (x-,y-, and z-axes respectively) and cell 12 (time of day stamps) are used, and thus cells 1-4 and 8-11 can be removed. The C# correspond to sensors as follows: C1 - Bed [control sensor], C2 - Left Ankle, C3 - Left Elbow, C4 - Left Wrist, C5 - Right Ankle, C6 - Right Elbow, and C7 - Right Wrist. To concatenate these channels into a 'data' cell array, as seen in complete `.mat` files, load all the `_C#.mat` for a specific patient, and run the following line of MATLAB code: `data = [C1;C2;C3;C4;C5;C6;C7]';`
+
+## Data format
+### For complete `.mat` files:
+`data` is a 12 x 7 cell array that can be labeled as follows:
+| Bed             | LA             | LE             | LW             | RA             | RE             | RW             |
+|-----------------|----------------|----------------|----------------|----------------|----------------|----------------|
+| Blank           | Blank          | Blank          | Blank          | Blank          | Blank          | Blank          |
+| Blank           | Blank          | Blank          | Blank          | Blank          | Blank          | Blank          |
+| Blank           | Blank          | Blank          | Blank          | Blank          | Blank          | Blank          |
+| Blank           | Blank          | Blank          | Blank          | Blank          | Blank          | Blank          |
+| x-axis (Bed)    | x-axis (LA)    | x-axis (LE)    | x-axis (LW)    | x-axis (RA)    | x-axis (RE)    | x-axis (RW)    |
+| y-axis (Bed)    | y-axis (LA)    | y-axis (LE)    | y-axis (LW)    | y-axis (RA)    | y-axis (RE)    | y-axis (RW)    |
+| z-axis (Bed)    | z-axis (LA)    | z-axis (LE)    | z-axis (LW)    | z-axis (RA)    | z-axis (RE)    | z-axis (RW)    |
+| Blank           | Blank          | Blank          | Blank          | Blank          | Blank          | Blank          |
+| Blank           | Blank          | Blank          | Blank          | Blank          | Blank          | Blank          |
+| Blank           | Blank          | Blank          | Blank          | Blank          | Blank          | Blank          |
+| Blank           | Blank          | Blank          | Blank          | Blank          | Blank          | Blank          |
+| TimeOfDay (Bed) | TimeOfDay (LA) | TimeOfDay (LE) | TimeOfDay (LW) | TimeOfDay (RA) | TimeOfDay (RE) | TimeOfDay (RW) |
+
+### For sensor-specific `.mat` files (ending in `_C#.mat`):
+`C#` is a 1 x 12 cell array that can be labeled as follows:
+| Blank             | Blank             | Blank             | Blank             | x-axis            | y-axis             | z-axis             | Blank             | Blank             | Blank             | Blank             | TimeOfDay             |
+|-----------------|----------------|----------------|----------------|----------------|----------------|----------------|----------------|----------------|----------------|----------------|----------------|