dsSetupStudy

SETUPSTUDY - Initialize DynaSim studyinfo structure, prepare list of output file names, and create output directories

 TODO: break up this function into smaller functions

 See also: dsSimulate, dsUpdateStudy

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

0001 function [studyinfo,options] = dsSetupStudy(base_model,varargin)
0002 %SETUPSTUDY - Initialize DynaSim studyinfo structure, prepare list of output file names, and create output directories
0003 %
0004 % TODO: break up this function into smaller functions
0005 %
0006 % See also: dsSimulate, dsUpdateStudy
0007 %
0008 % Author: Jason Sherfey, PhD <jssherfey@gmail.com>
0009 % Copyright (C) 2016 Jason Sherfey, Boston University, USA
0010 
0011 % Check inputs
0012 opts=dsCheckOptions(varargin,{...
0013   'modifications_set',[],[],... % search space
0014   'simulator_options',[],[],... % options from dsSimulate
0015   'process_id',[],[],... % process identifier for loading studyinfo if necessary
0016   },false);
0017 
0018 if isempty(opts.simulator_options)
0019   error('dsSetupStudy must be given a simulator_options structure from dsSimulate');
0020 end
0021 
0022 modifications_set = opts.modifications_set;
0023 process_id = opts.process_id;
0024 options = opts.simulator_options;
0025 
0026 % Setup Study
0027 if options.verbose_flag
0028   fprintf('PREPARING STUDY:\n');
0029 end
0030 
0031 if options.save_data_flag || options.save_results_flag || options.parallel_flag
0032   % If in parallel mode, need to calculate
0033   % studyinfo regardless of whether or not
0034   % are saving data.
0035 
0036   % set default study_dir if necessary
0037   if isempty(options.study_dir)
0038     if ~options.auto_gen_test_data_flag && ~options.unit_test_flag
0039       % format: <study_dir> = <project_dir>/<prefix>_<timestamp>
0040       options.study_dir=fullfile(options.project_dir,[options.prefix '_' datestr(now,'yyyymmddHHMMSS')]);
0041     else
0042       options.study_dir=fullfile(options.project_dir,[options.prefix '_unitTest']);
0043     end
0044   end
0045 
0046   % make sure we have the full path and access rights
0047   options.study_dir = getAbsolutePath(options.study_dir);
0048 
0049   % create study_dir if it doesn't exist
0050   if ~isdir(options.study_dir)
0051     if options.verbose_flag
0052       fprintf('Creating study directory: %s\n',options.study_dir);
0053     end
0054     mkdir(options.study_dir);
0055   end
0056 
0057   % set solve_file name for this study
0058   if isempty(options.solve_file)
0059     % set default solve_file for this study
0060     [~,fname]=fileparts(options.study_dir);
0061     fname=['solve_ode_' fname];
0062 
0063     % replace non-word characters by underscores so that matlab can execute
0064     % the file as a Matlab function:
0065     fname=regexprep(fname,'[^\w]','_');
0066 
0067     % store the solve file
0068     options.solve_file = fullfile(options.study_dir,'solve',[fname '.m']);
0069   end
0070 
0071   % initialize studyinfo if not already initialized
0072   if ischar(options.study_dir) && isdir(options.study_dir) && exist(fullfile(options.study_dir,'studyinfo.mat'),'file')
0073     % studyinfo file already exists
0074     studyinfo=dsCheckStudyinfo(options.study_dir,'process_id',process_id, varargin{:});
0075     orig_studyinfo=studyinfo;
0076   else
0077     orig_studyinfo=[];
0078 
0079     % studyinfo file does not exist; initialize new studyinfo structure
0080     if ~isempty(base_model)
0081       warning off; %warning('off','MATLAB:warn_r14_stucture_assignment')
0082       studyinfo.simulations.sim_id = 1; % set up dummy simulations sub-structure
0083       warning on;
0084     else
0085       studyinfo = [];
0086     end
0087 
0088     studyinfo=dsCheckStudyinfo(studyinfo,'process_id',process_id, varargin{:}); % auto-fill all fields
0089   end
0090 
0091   % set basic metadata for this study
0092   studyinfo.study_dir = options.study_dir;
0093   studyinfo.project_id = [];%options.project_id; % <-- placeholder for future feature
0094   if isempty(studyinfo.base_model)
0095     studyinfo.base_model = base_model;
0096   end
0097 
0098   if isempty(studyinfo.base_simulator_options)
0099     studyinfo.base_simulator_options = options;
0100   end
0101 
0102   if isempty(studyinfo.base_solve_file)
0103     studyinfo.base_solve_file = options.solve_file;
0104   end
0105 
0106   if isempty(studyinfo.base_data_files)
0107     studyinfo.base_data_files = {};%options.base_data_files; % <-- placeholder for future feature (analysis stream)
0108   end
0109 
0110   % create study_dir if it doesn't exist
0111   if ~isdir(options.study_dir)
0112     if options.verbose_flag
0113       fprintf('Creating study directory: %s\n',options.study_dir);
0114     end
0115     mkdir(options.study_dir);
0116   end
0117 
0118   % create models dir if it doesn't exist and saving model
0119 %   models_dir = fullfile(options.study_dir,'models');
0120 %   if ~isdir(models_dir)
0121 %     if options.verbose_flag
0122 %       fprintf('creating models directory: %s\n',models_dir);
0123 %     end
0124 %     mkdir(models_dir);
0125 %   end
0126 
0127   % create data dir if it doesn't exist and saving model
0128   data_dir = fullfile(options.study_dir,'data');
0129   if ~isdir(data_dir)
0130     if options.verbose_flag
0131       fprintf('Creating data directory: %s\n',data_dir);
0132     end
0133     mkdir(data_dir);
0134   end
0135 
0136   % create figure dir if it doesn't exist and is needed
0137   if ~isempty(options.plot_functions)
0138     plot_dir = fullfile(options.study_dir,'plots');
0139     if ~isdir(plot_dir)
0140       if options.verbose_flag
0141         fprintf('Creating plot directory: %s\n',plot_dir);
0142       end
0143       mkdir(plot_dir);
0144     end
0145   end
0146 
0147   % set single-simulation metadata (studyinfo.simulation(k))
0148   % create list of output file names (use modifications_set to loop sims)
0149   for k = 1:length(modifications_set)
0150     if length(studyinfo.simulations)<k || isempty(studyinfo.simulations(k).status)
0151       studyinfo.simulations(k).sim_id=k;
0152       studyinfo.simulations(k).modifications=modifications_set{k};
0153       fname=[options.prefix '_sim' num2str(k) '_data.mat'];
0154       studyinfo.simulations(k).data_file=fullfile(data_dir,fname);
0155       fname=[options.prefix '_sim' num2str(k) '_model.mat'];
0156       %studyinfo.simulations(k).modified_model_file=fullfile(models_dir,fname);
0157       studyinfo.simulations(k).status='initialized';
0158 
0159       % set file names for analysis results
0160       for kk = 1:length(options.analysis_functions)
0161         studyinfo.simulations(k).result_functions{end+1} = options.analysis_functions{kk};
0162         studyinfo.simulations(k).result_options{end+1} = options.analysis_options{kk};
0163 
0164         fname = [options.prefix '_sim' num2str(k) '_analysis' num2str(kk) '_' func2str(options.analysis_functions{kk}) '.mat'];
0165         studyinfo.simulations(k).result_files{end+1} = fullfile(data_dir,fname);
0166       end
0167 
0168       % set files names for saved plots (in plot_dir)
0169       for kk=1:length(options.plot_functions)
0170         studyinfo.simulations(k).result_functions{end+1}=options.plot_functions{kk};
0171         studyinfo.simulations(k).result_options{end+1}=options.plot_options{kk};
0172         fname=[options.prefix '_sim' num2str(k) '_plot' num2str(kk) '_' func2str(options.plot_functions{kk})];
0173         % note: extension will depend on output format (jpg,png,eps,svg)
0174         % and be set in dsAnalyze().
0175         studyinfo.simulations(k).result_files{end+1}=fullfile(plot_dir,fname);
0176       end
0177 
0178       % TODO: add options.detailed_names_flag (see dsAnalyzeStudy())
0179       % ...
0180     end
0181   end
0182   % TODO: set single-analysis metadata (studyinfo.analysis(k))
0183   % ...
0184 
0185   % save studyinfo if it has changed
0186   if ~isequal(orig_studyinfo,studyinfo)
0187     % save studyinfo structure to disk
0188     study_file=fullfile(options.study_dir,'studyinfo.mat');
0189     dsStudyinfoIO(studyinfo,study_file,process_id,options.verbose_flag);
0190   end
0191 else
0192   % set defaults for not saving anything
0193   if isempty(options.study_dir)
0194     % if not saving data, store solvers in current directory
0195     options.study_dir = pwd; % this is where /solve/solve_ode.m will be created
0196   end
0197 
0198   if ~isdir(options.study_dir) % in case user provides different location to save solvers
0199     if options.verbose_flag
0200       fprintf('Creating study directory: %s\n',options.study_dir);
0201     end
0202 
0203     mkdir(options.study_dir);
0204   end
0205 
0206   studyinfo=[];
0207 end