├── .gitignore ├── .gitattributes ├── README.md ├── Model fitting and prediction ├── computeAccuracy.m ├── performForwardPrediction.m ├── performOneStepAheadPrediction.m └── fitIOModel.m └── LICENSE.md /.gitignore: -------------------------------------------------------------------------------- 1 | # psb log files 2 | *.o* 3 | *.o* 4 | 5 | # Atom editor files 6 | .idea* 7 | 8 | 9 | # Zip files 10 | *.zip 11 | 12 | 13 | # Windows default autosave extension 14 | *.asv 15 | 16 | # OSX / *nix default autosave extension 17 | *.m~ 18 | 19 | # Compiled MEX binaries (all platforms) 20 | *.mex* 21 | 22 | # Simulink Code Generation 23 | slprj/ 24 | 25 | # Session info 26 | octave-workspace -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | *.mlx -crlf -diff -merge 2 | *.mat -crlf -diff -merge 3 | *.fig -crlf -diff -merge 4 | *.p -crlf -diff -merge 5 | *.slx -crlf -diff -merge 6 | *.mdl -crlf -diff -merge 7 | 8 | *.mdlp -crlf -diff -merge 9 | *.slxp -crlf -diff -merge 10 | *.sldd -crlf -diff -merge 11 | *.mexa64 -crlf -diff -merge 12 | *.mexw64 -crlf -diff -merge 13 | *.mexmaci64 -crlf -diff -merge 14 | *.xlsx -crlf -diff -merge 15 | *.docx -crlf -diff -merge 16 | *.pdf -crlf -diff -merge 17 | *.jpg -crlf -diff -merge 18 | *.png -crlf -diff -merge -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Dynamic modeling of stimulation 2 | This repository hosts the code for the following publication: 3 | ## Publication: 4 | Yuxiao Yang, Shaoyu Qiao, Omid G. Sani, J. Isaac Sedillo, Breonna Ferrentino, Bijan Pesaran, and Maryam M. Shanechi. *Modelling and Prediction of the Dynamic Responses of Large-Scale Brain Networks during Direct Electrical Stimulation*. Nature Biomedical Engineering (2021). https://doi.org/10.1038/s41551-020-00666-w 5 | 6 | # Code structure 7 | The LSSM fitting and prediction functions are included under [./Model fitting and prediction](<./Model fitting and prediction>) 8 | 9 | # Licence 10 | Copyright (c) 2020 University of Southern California 11 | See full notice in [LICENSE.md](LICENSE.md) 12 | Yuxiao Yang and Maryam Shanechi 13 | Shanechi Lab, University of Southern California 14 | -------------------------------------------------------------------------------- /Model fitting and prediction/computeAccuracy.m: -------------------------------------------------------------------------------- 1 | % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2 | % Copyright (c) 2021 University of Southern California 3 | % See full notice in LICENSE.md 4 | % Yuxiao Yang, Maryam Shanechi 5 | % Shanechi Lab, University of Southern California 6 | % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 7 | 8 | function [CC, EV] = computeAccuracy(y, y_predict) 9 | % This function computes the prediction accuracy measures 10 | % Input: 11 | % 1. y, true data (time by dimension vector) 12 | % 2. y_predict, prediction of the data (time by dimension vector) 13 | % Output: 14 | % 1. CC: correlation coefficient between prediction and ground-truth, one 15 | % value for each outoput dimension 16 | % 2. EV: explained variacne between prediction and ground-truth, one 17 | % value for each outoput dimension 18 | 19 | %%%%% compute CC between prediction and ground-truth 20 | CC = zeros(size(y,2),1); 21 | EV = zeros(size(y,2),1); 22 | for k = 1 : size(y,2) 23 | CC(k) = corr(y(:,k), y_predict(:,k)); 24 | EV(k) = (1 - mean((y(:,k)-y_predict(:,k)).^2) / var(y(:,k)) )*100; 25 | end 26 | 27 | end 28 | -------------------------------------------------------------------------------- /Model fitting and prediction/performForwardPrediction.m: -------------------------------------------------------------------------------- 1 | % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2 | % Copyright (c) 2021 University of Southern California 3 | % See full notice in LICENSE.md 4 | % Yuxiao Yang, Maryam Shanechi 5 | % Shanechi Lab, University of Southern California 6 | % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 7 | 8 | function [y_predict] = performForwardPrediction(u,LSSM) 9 | % This function uses the fitted LSSM to forward predict the outputin test 10 | % data 11 | % Detailed explanation goes here 12 | % Input: 13 | % 1. u, time by dimension vector representing the input in test data 14 | % 2. LSSM, fitted LSSM in training data 15 | % order selection 16 | % Output: 17 | % 1. y_predict, time by dimension vector representing the forward-predicted 18 | % output 19 | 20 | % Disable warnings (compare throws unimportant warnings): 21 | warningSettingBackup = warning; 22 | warning('off'); 23 | 24 | %%%%%% organize input and output into system identification datastructure 25 | TestData = iddata([],u,1); % 1 represent discrete-time system 26 | 27 | %%%%% forward prediction, only use past input to predict current output 28 | opt = compareOptions; 29 | opt.InitialCondition = 'zero'; % zero initialization 30 | [PredictData,~,~] = compare(TestData, LSSM, opt); 31 | % NOTE: here we do not provide the "prediction_step_ahead" input to the 32 | % compare function to perform forward prediction. 33 | y_predict = PredictData.y; 34 | 35 | warning(warningSettingBackup); % Restore original warning settings 36 | -------------------------------------------------------------------------------- /Model fitting and prediction/performOneStepAheadPrediction.m: -------------------------------------------------------------------------------- 1 | % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2 | % Copyright (c) 2021 University of Southern California 3 | % See full notice in LICENSE.md 4 | % Yuxiao Yang, Maryam Shanechi 5 | % Shanechi Lab, University of Southern California 6 | % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 7 | 8 | function [y_predict] = performOneStepAheadPrediction(y,u,LSSM) 9 | % This function uses the fitted LSSM to one-step-ahead predict the outputin test 10 | % data 11 | % Detailed explanation goes here 12 | % Input: 13 | % 1. y, time by dimension vector representing the output in test data 14 | % 2. u, time by dimension vector representing the input in test data 15 | % 3. LSSM, fitted LSSM in training data 16 | % order selection 17 | % Output: 18 | % 1. y_predict, time by dimension vector representing the forward-predicted 19 | % output 20 | 21 | %%%%%% organize input and output into system identification datastructure 22 | TestData = iddata(y,u,1); % 1 represent discrete-time system 23 | 24 | %%%%% one step ahead prediction, use past input and past output to predict current output 25 | opt = compareOptions; 26 | opt.InitialCondition = 'zero'; % zero initialization 27 | prediction_step_ahead = 1; % 1 step ahead prediction 28 | [PredictData,~,~] = compare(TestData, LSSM, prediction_step_ahead, opt); 29 | % NOTE: here we do provide "prediction_step_ahead" of 1 to the 30 | % compare function to perform one-step ahead prediction. 31 | y_predict = PredictData.y; 32 | 33 | end 34 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | This software is Copyright © 2020 The University of Southern California. All Rights Reserved. 2 | 3 | Permission to use, copy, modify, and distribute this software and its documentation for educational, research 4 | and non-profit purposes, without fee, and without a written agreement is hereby granted, provided that the 5 | above copyright notice, this paragraph and the following three paragraphs appear in all copies. 6 | 7 | Permission to make commercial use of this software may be obtained by contacting: 8 | USC Stevens Center for Innovation 9 | University of Southern California 10 | 1150 S. Olive Street, Suite 2300 11 | Los Angeles, CA 90115, USA 12 | 13 | This software program and documentation are copyrighted by The University of Southern California. The software 14 | program and documentation are supplied "as is", without any accompanying services from USC. USC does not warrant 15 | that the operation of the program will be uninterrupted or error-free. The end-user understands that the program 16 | was developed for research purposes and is advised not to rely exclusively on the program for any reason. 17 | 18 | IN NO EVENT SHALL THE UNIVERSITY OF SOUTHERN CALIFORNIA BE LIABLE TO ANY PARTY FOR 19 | DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST 20 | PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE 21 | UNIVERSITY OF SOUTHERN CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 22 | DAMAGE. THE UNIVERSITY OF SOUTHERN CALIFORNIA SPECIFICALLY DISCLAIMS ANY 23 | WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 24 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED 25 | HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF SOUTHERN CALIFORNIA HAS NO 26 | OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR 27 | MODIFICATIONS. 28 | -------------------------------------------------------------------------------- /Model fitting and prediction/fitIOModel.m: -------------------------------------------------------------------------------- 1 | % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2 | % Copyright (c) 2021 University of Southern California 3 | % See full notice in LICENSE.md 4 | % Yuxiao Yang, Maryam Shanechi 5 | % Shanechi Lab, University of Southern California 6 | % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 7 | 8 | function [LSSM] = fitIOModel(y,u,searchorder) 9 | % This function fits the LSSM using training data 10 | % Detailed explanation goes here 11 | % Input: 12 | % 1. y, time by dimension vector representing the output 13 | % 2. u, time by dimension vector representing the input 14 | % 3. searchorder, vector representing the model order to be searched during model 15 | % order selection 16 | % Output: 17 | % 1. LSSM, the fitted LSSM, a data structure. See MATLAB system 18 | % identification toolbox for the definition of this data structure 19 | 20 | %%%%%% organize input and output into system identification datastructure 21 | TrainingData = iddata(y,u,1); % 1 represent discrete-time system 22 | 23 | %%%%% set model fitting setting using the system identification toolbox, please see MATLAB system identification toolbox for details 24 | N4SID_opt = n4sidOptions('N4Weight', 'MOESP', 'Focus', 'simulation', 'EnforceStability', true); % setting for initial subspace idetification 25 | PEM_opt = ssestOptions('Focus', 'simulation', 'InitialState', 'zero', 'EnforceStability', true); % setting for the PEM refinement 26 | 27 | %%%%% do order selection in the training set, either with AIC or with inner-level cross-validation; here AIC is provided as an example. 28 | AIC_values = zeros(length(searchorder),1); 29 | for k = 1 : length(searchorder) 30 | %%% sweep model order 31 | modelorder_here = searchorder(k); 32 | %%% use subspace identification to fit initial LSSM 33 | Initial_LSSM = n4sid(TrainingData, modelorder_here, 'Feedthrough', false, 'DisturbanceModel', 'estimate', N4SID_opt); 34 | %%% use PEM to refine the fit 35 | Refined_LSSM = pem(TrainingData, Initial_LSSM, PEM_opt); 36 | %%% get AIC of the fitted model 37 | AIC_values(k) = aic(Refined_LSSM, 'AICc'); 38 | end 39 | [~, ind] = min(AIC_values); 40 | Selected_modelorder = searchorder(ind); 41 | 42 | %%%% fit final model with selected model order 43 | %%% use subspace identification to fit initial LSSM 44 | Initial_LSSM_selected = n4sid(TrainingData,Selected_modelorder, 'Feedthrough', false, 'DisturbanceModel', 'estimate', N4SID_opt); 45 | %%% use PEM to refine the fit 46 | LSSM = pem(TrainingData, Initial_LSSM_selected, PEM_opt); 47 | 48 | end 49 | --------------------------------------------------------------------------------