function [results,studyinfo]=AnalyzeStudy(data,func,varargin)
%% [results,studyinfo]=AnalyzeStudy(data,func,varargin)
% purpose: 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.
% 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: SimulateModel, CalcFR

% check inputs
options=CheckOptions(varargin,{...
  'prefix','study_analysis',[],...
  'save_data_flag',0,{0,1},...
  'detailed_names_flag',0,{0,1},...
  'studyinfo',[],[],...
  'downsample_factor',1,[],...    % downsampling applied before analysis
  },false);

% load data if input is not a DynaSim data structure
if ~(isstruct(data) && isfield(data,'time'))
  % this is a data file, list of data files, studyinfo structure, study_dir, or studyinfo file
  [data,studyinfo]=ImportData(data,varargin{:}); % load all data in study
else
  studyinfo=CheckStudyinfo([]);
end

% studyinfo.base_simulator_options (contains study_dir, etc)
% CreateBatch
% SetupStudy

if ~iscell(func)
  % convert func to cell array of function handles
  func={func};
end
for i=1:length(func)
  if ~isa(func{i},'function_handle')
    error('the second argument must be a function handle (or cell array of them) for the desired analysis function.');
  end
end
data=CheckData(data);

% pass each element of data to the analysis function
for i=1:length(data)
  for j=1:length(func)
  % apply analysis functions
    results(i)=feval(func{j},data(i),varargin{:});
  end
end

% NOTE: plots must display detailed info if not in filename.
% loop over results (k):
% if ishandle(results(k)) && options.detailed_names_flag==0
%   % todo: add annotations if necessary
% end

% todo: save results of analysis and/or plots
if options.save_data_flag
  % possibly: get filename from studyinfo.analysis(k).data_file ...
  if options.detailed_names_flag % create filename with parameter info
    % outfile=... k<-options.studyinfo.base_data_files & options.studyinfo.simulations(k).modifications...)
  else
    % outfile=...
  end
  % save(outfile,'results','-v7.3');
end