dsAnalyzeStudy

dsAnalyzeStudy - Apply an analysis function to DynaSim data, optionally saving data

 Apply the same user-specified analysis function to each element of data
 structure. intended for use with results from simulation studies varying some
 aspect of the model or inputs.

 Usage:
   [results,studyinfo]=dsAnalyzeStudy(data,func,'option1',value1)

 Inputs:
   - data: DynaSim data structure with one or more elements
     - also accepted: data file name, list of data files, studyinfo structure,
         study_dir, or studyinfo file
   - func: function handle pointing to analysis function (or cell array of
       function handles)
   - options: key/value pairs passed on to the analysis function

 Outputs:
   - results: array of structures returned by the analysis function

 TODO: annotate figures with data set-specific modifications

 See also: dsSimulate, dsCalcFR

 Author: Jason Sherfey, PhD <jssherfey@gmail.com>
 Copyright (C) 2016 Jason Sherfey, Boston University, USA

0001 function [results,studyinfo] = dsAnalyzeStudy(data,func,varargin)
0002 %dsAnalyzeStudy - Apply an analysis function to DynaSim data, optionally saving data
0003 %
0004 % Apply the same user-specified analysis function to each element of data
0005 % structure. intended for use with results from simulation studies varying some
0006 % aspect of the model or inputs.
0007 %
0008 % Usage:
0009 %   [results,studyinfo]=dsAnalyzeStudy(data,func,'option1',value1)
0010 %
0011 % Inputs:
0012 %   - data: DynaSim data structure with one or more elements
0013 %     - also accepted: data file name, list of data files, studyinfo structure,
0014 %         study_dir, or studyinfo file
0015 %   - func: function handle pointing to analysis function (or cell array of
0016 %       function handles)
0017 %   - options: key/value pairs passed on to the analysis function
0018 %
0019 % Outputs:
0020 %   - results: array of structures returned by the analysis function
0021 %
0022 % TODO: annotate figures with data set-specific modifications
0023 %
0024 % See also: dsSimulate, dsCalcFR
0025 %
0026 % Author: Jason Sherfey, PhD <jssherfey@gmail.com>
0027 % Copyright (C) 2016 Jason Sherfey, Boston University, USA
0028 
0029 % check inputs
0030 options=dsCheckOptions(varargin,{...
0031   'analysis_prefix','study_analysis',[],...
0032   'save_data_flag',0,{0,1},...
0033   'detailed_names_flag',0,{0,1},...
0034   'studyinfo',[],[],...
0035   'downsample_factor',1,[],...    % downsampling applied before analysis
0036   },false);
0037 
0038 % load data if input is not a DynaSim data structure
0039 if ~(isstruct(data) && isfield(data,'time'))
0040   % this is a data file, list of data files, studyinfo structure, study_dir, or studyinfo file
0041   [data,studyinfo]=dsImport(data,varargin{:}); % load all data in study
0042 else
0043   studyinfo=dsCheckStudyinfo([], varargin{:});
0044 end
0045 
0046 % studyinfo.base_simulator_options (contains study_dir, etc)
0047 % dsCreateBatch
0048 % dsSetupStudy
0049 
0050 if ~iscell(func)
0051   % convert func to cell array of function handles
0052   func={func};
0053 end
0054 for i=1:length(func)
0055   if ~isa(func{i},'function_handle')
0056     error('the second argument must be a function handle (or cell array of them) for the desired analysis function.');
0057   end
0058 end
0059 data=dsCheckData(data, varargin{:});
0060 
0061 % pass each element of data to the analysis function
0062 for i=1:length(data)
0063   for j=1:length(func)
0064   % apply analysis functions
0065     results(i)=feval(func{j},data(i),varargin{:});
0066   end
0067 end
0068 
0069 % NOTE: plots must display detailed info if not in filename.
0070 % loop over results (k):
0071 % if ishandle(results(k)) && options.detailed_names_flag==0
0072 %   % todo: add annotations if necessary
0073 % end
0074 
0075 % TODO: save results of analysis and/or plots
0076 if options.save_data_flag
0077   % possibly: get filename from studyinfo.analysis(k).data_file ...
0078   if options.detailed_names_flag % create filename with parameter info
0079     % outfile=... k<-options.studyinfo.base_data_files & options.studyinfo.simulations(k).modifications...)
0080   else
0081     % outfile=...
0082   end
0083   % save(outfile,'results','-v7.3');
0084 end