CHECKSTUDYINFO - Standardize studyinfo structure and auto-populate missing fields
Usage:
studyinfo=dsCheckStudyinfo(studyinfo)
Input: DynaSim studyinfo structure
Output:
- DynaSim studyinfo structure (standardized)
studyinfo.study_id (unique identifier, cannot be set by user; may be
useful in future for recovering results that are moved)
studyinfo.study_dir
studyinfo.time_created
studyinfo.last_modified
studyinfo.base_model (=[]): original model from which a set of simulations was derived
studyinfo.base_simulator_options (=[])
studyinfo.base_solve_file (='')
studyinfo.simulations(k) (=[])
.simulations(k).sim_id: unique identifier in study
.simulations(k).modifications: modifications made to the base
model during this simulation
.simulations(k).stop_time
.simulations(k).duration
.simulations(k).status: {'started', 'failed', 'finished'}
.simulations(k).data_file: full filename of eventual output file
.simulations(k).batch_dir (=[]): directory where cluster jobs were
saved (if cluster_flag=1)
.simulations(k).job_file (=[]): m-file cluster job that runs this
simulation (if cluster_flag=1)
.simulations(k).error_log (='')
.simulations(k).machine_info
.machine_info.host_name
.machine_info.total_memory
.machine_info.CPU_type
.machine_info.CPU_cache
.machine_info.num_cores
.machine_info.operating_system
.machine_info.kernel
.machine_info.home_dir
.simulations(k).modified_model_file
.simulations(k).simulator_options
.simulations(k).solve_file
.simulations(k).result_files (={}): cell array of result files
(including saved plots)
.simulations(k).result_functions (={}): cell array of names of
functions producing results
stored in result_files
(including plot functions)
.simulations(k).result_options (={}): cell array of option
structures for result_functions
studyinfo.base_data_files{k}: these are the base data files analyses are
applied to. for simulated data, this equals
{simulations.datafile}
studyinfo.analysis(j)(=[]): metadata for one batch (analysis applied to all
files = {studyinfo.simulations.data_file})
.analysis(j).analysis_id
.analysis(j).function
.analysis(j).analysis_options
.analysis(j).stop_time
.analysis(j).duration
.analysis(j).status
.analysis(j).batch_dir (=[])
.analysis(j).job_file (=[])
.analysis(j).error_log (='')
.analysis(j).machine_info (same as studyinfo.simulations.machine_info)
.analyses(j).derived_result_file: full file names of derived data sets
studyinfo.matlab_version
studyinfo.dynasim_hash
studyinfo.user_name
studyinfo.paths (=[])
studyinfo.project_id (=[])
Examples:
- Example 1: obtain empty studyinfo structure with all fields
studyinfo=dsCheckStudyinfo([])
- Example 2: standardize existing studyinfo
studyinfo=dsCheckStudyinfo(studyinfo)
See also: dsSetupStudy, dsSimulate, dsCreateBatch, dsImport, dsAnalyzeStudy
Author: Jason Sherfey, PhD <jssherfey@gmail.com>
Copyright (C) 2016 Jason Sherfey, Boston University, USA0001 function studyinfo = dsCheckStudyinfo(studyinfo, varargin) 0002 %CHECKSTUDYINFO - Standardize studyinfo structure and auto-populate missing fields 0003 % 0004 % Usage: 0005 % studyinfo=dsCheckStudyinfo(studyinfo) 0006 % 0007 % Input: DynaSim studyinfo structure 0008 % 0009 % Output: 0010 % - DynaSim studyinfo structure (standardized) 0011 % studyinfo.study_id (unique identifier, cannot be set by user; may be 0012 % useful in future for recovering results that are moved) 0013 % studyinfo.study_dir 0014 % studyinfo.time_created 0015 % studyinfo.last_modified 0016 % studyinfo.base_model (=[]): original model from which a set of simulations was derived 0017 % studyinfo.base_simulator_options (=[]) 0018 % studyinfo.base_solve_file (='') 0019 % studyinfo.simulations(k) (=[]) 0020 % .simulations(k).sim_id: unique identifier in study 0021 % .simulations(k).modifications: modifications made to the base 0022 % model during this simulation 0023 % .simulations(k).stop_time 0024 % .simulations(k).duration 0025 % .simulations(k).status: {'started', 'failed', 'finished'} 0026 % .simulations(k).data_file: full filename of eventual output file 0027 % .simulations(k).batch_dir (=[]): directory where cluster jobs were 0028 % saved (if cluster_flag=1) 0029 % .simulations(k).job_file (=[]): m-file cluster job that runs this 0030 % simulation (if cluster_flag=1) 0031 % .simulations(k).error_log (='') 0032 % .simulations(k).machine_info 0033 % .machine_info.host_name 0034 % .machine_info.total_memory 0035 % .machine_info.CPU_type 0036 % .machine_info.CPU_cache 0037 % .machine_info.num_cores 0038 % .machine_info.operating_system 0039 % .machine_info.kernel 0040 % .machine_info.home_dir 0041 % .simulations(k).modified_model_file 0042 % .simulations(k).simulator_options 0043 % .simulations(k).solve_file 0044 % .simulations(k).result_files (={}): cell array of result files 0045 % (including saved plots) 0046 % .simulations(k).result_functions (={}): cell array of names of 0047 % functions producing results 0048 % stored in result_files 0049 % (including plot functions) 0050 % .simulations(k).result_options (={}): cell array of option 0051 % structures for result_functions 0052 % studyinfo.base_data_files{k}: these are the base data files analyses are 0053 % applied to. for simulated data, this equals 0054 % {simulations.datafile} 0055 % studyinfo.analysis(j)(=[]): metadata for one batch (analysis applied to all 0056 % files = {studyinfo.simulations.data_file}) 0057 % .analysis(j).analysis_id 0058 % .analysis(j).function 0059 % .analysis(j).analysis_options 0060 % .analysis(j).stop_time 0061 % .analysis(j).duration 0062 % .analysis(j).status 0063 % .analysis(j).batch_dir (=[]) 0064 % .analysis(j).job_file (=[]) 0065 % .analysis(j).error_log (='') 0066 % .analysis(j).machine_info (same as studyinfo.simulations.machine_info) 0067 % .analyses(j).derived_result_file: full file names of derived data sets 0068 % studyinfo.matlab_version 0069 % studyinfo.dynasim_hash 0070 % studyinfo.user_name 0071 % studyinfo.paths (=[]) 0072 % studyinfo.project_id (=[]) 0073 % 0074 % Examples: 0075 % - Example 1: obtain empty studyinfo structure with all fields 0076 % studyinfo=dsCheckStudyinfo([]) 0077 % 0078 % - Example 2: standardize existing studyinfo 0079 % studyinfo=dsCheckStudyinfo(studyinfo) 0080 % 0081 % See also: dsSetupStudy, dsSimulate, dsCreateBatch, dsImport, dsAnalyzeStudy 0082 % 0083 % Author: Jason Sherfey, PhD <jssherfey@gmail.com> 0084 % Copyright (C) 2016 Jason Sherfey, Boston University, USA 0085 0086 options=dsCheckOptions(varargin,{... 0087 'verbose_flag',0,{0,1},... 0088 'process_id',[],[],... % process identifier for loading studyinfo if necessary 0089 'auto_gen_test_data_flag',0,{0,1},... 0090 },false); 0091 0092 if options.auto_gen_test_data_flag 0093 varargs = varargin; 0094 varargs{find(strcmp(varargs, 'auto_gen_test_data_flag'))+1} = 0; 0095 varargs(end+1:end+2) = {'unit_test_flag',1}; 0096 argin = [{studyinfo}, varargs]; % specific to this function 0097 end 0098 0099 studyinfo_field_order={'study_id','study_dir','time_created','last_modified',... 0100 'base_model','base_simulator_options','base_solve_file','simulations','base_data_files',... 0101 'analysis','matlab_version','dynasim_hash','user_name','paths','project_id'}; 0102 0103 sim_field_order={'sim_id','modifications','stop_time','duration','status',... 0104 'data_file','batch_dir','job_file','error_log','machine_info','modified_model_file',... 0105 'simulator_options','solve_file','result_files','result_functions','result_options'}; 0106 0107 % todo: implement analysis standardization 0108 analysis_field_order={'analysis_id','function','analysis_options','stop_time','duration',... 0109 'status','batch_dir','job_file','error_log','machine_info','derived_result_file'}; 0110 0111 % check if input is string with filename, studyinfo structure, or [] 0112 % prepare studyinfo structure for standardization 0113 study_dir=pwd; 0114 0115 % check if study_dir was provided 0116 if ischar(studyinfo) && isdir(studyinfo) 0117 study_dir=studyinfo; 0118 studyinfo=fullfile(study_dir,'studyinfo.mat'); 0119 end 0120 0121 % check if studyinfo.mat was provided (or derived from input study_dir) 0122 if ischar(studyinfo) && exist(studyinfo,'file') 0123 study_dir=fileparts2(studyinfo); 0124 studyinfo=dsStudyinfoIO([],study_dir,options.process_id,options.verbose_flag); 0125 elseif isnumeric(studyinfo) && isempty(studyinfo) % [], created dummy studyinfo 0126 % set some default studyinfo fields 0127 studyinfo.time_created=datestr(now); 0128 studyinfo.last_modified=studyinfo.time_created; 0129 elseif isstruct(studyinfo) 0130 % do nothing here. already ready for standardization of structure. 0131 else 0132 error('studyinfo data type not recognized. input should be existing studyinfo file name, structure, or []'); 0133 end 0134 0135 % check for presence of each field and set defaults if missing 0136 if ~isfield(studyinfo,'study_id') 0137 studyinfo.study_id=now; 0138 end 0139 if ~isfield(studyinfo,'study_dir') 0140 studyinfo.study_dir=study_dir; 0141 end 0142 if ~isfield(studyinfo,'time_created') 0143 studyinfo.time_created=datestr(now); 0144 end 0145 if ~isfield(studyinfo,'last_modified') 0146 studyinfo.last_modified=datestr(now); 0147 end 0148 if ~isfield(studyinfo,'base_model') 0149 studyinfo.base_model=[]; 0150 end 0151 if ~isfield(studyinfo,'base_simulator_options') 0152 studyinfo.base_simulator_options=[]; 0153 end 0154 if ~isfield(studyinfo,'base_solve_file') 0155 studyinfo.base_solve_file=''; 0156 end 0157 if ~isfield(studyinfo,'base_data_files') 0158 studyinfo.base_data_files={}; 0159 end 0160 if ~isfield(studyinfo,'matlab_version') 0161 studyinfo.matlab_version=version; 0162 end 0163 if ~isfield(studyinfo,'dynasim_hash') 0164 % record current directory 0165 cwd=pwd; 0166 % move to dynasim directory 0167 cd(dsGetRootPath()); 0168 % get git hash 0169 [a,b]=system('git rev-parse HEAD'); 0170 studyinfo.dynasim_hash=strtrim(b); 0171 % return to original directory 0172 cd(cwd); 0173 end 0174 if ~isfield(studyinfo,'user_name') 0175 try 0176 user_name = getenv('USER'); 0177 catch 0178 user_name = ''; 0179 end 0180 studyinfo.user_name=user_name; 0181 end 0182 if ~isfield(studyinfo,'project_id') 0183 studyinfo.project_id=[]; % no project by default 0184 end 0185 if ~isfield(studyinfo,'paths') 0186 studyinfo.paths=[]; 0187 end 0188 0189 % check substructure studyinfo.simulations: 0190 if ~isfield(studyinfo,'simulations') 0191 studyinfo.simulations=[]; 0192 elseif isstruct(studyinfo.simulations) 0193 % standardize simulations substructure 0194 if ~isfield(studyinfo.simulations,'sim_id') 0195 studyinfo.simulations.sim_id=1; 0196 end 0197 if ~isfield(studyinfo.simulations,'modifications') 0198 studyinfo.simulations.modifications={}; 0199 end 0200 if ~isfield(studyinfo.simulations,'stop_time') 0201 studyinfo.simulations.stop_time=[]; 0202 end 0203 if ~isfield(studyinfo.simulations,'duration') 0204 studyinfo.simulations.duration=[]; 0205 end 0206 if ~isfield(studyinfo.simulations,'status') 0207 studyinfo.simulations.status=''; 0208 end 0209 if ~isfield(studyinfo.simulations,'data_file') 0210 studyinfo.simulations.data_file={}; 0211 end 0212 if ~isfield(studyinfo.simulations,'batch_dir') 0213 studyinfo.simulations.batch_dir=[]; 0214 end 0215 if ~isfield(studyinfo.simulations,'job_file') 0216 studyinfo.simulations.job_file=[]; 0217 end 0218 if ~isfield(studyinfo.simulations,'error_log') 0219 studyinfo.simulations.error_log=''; 0220 end 0221 if ~isfield(studyinfo.simulations,'machine_info') 0222 studyinfo.simulations.machine_info=[]; 0223 end 0224 if ~isfield(studyinfo.simulations,'modified_model_file') 0225 studyinfo.simulations.modified_model_file=[]; 0226 end 0227 if ~isfield(studyinfo.simulations,'simulator_options') 0228 studyinfo.simulations.simulator_options=[]; 0229 end 0230 if ~isfield(studyinfo.simulations,'solve_file') 0231 studyinfo.simulations.solve_file=''; 0232 end 0233 if ~isfield(studyinfo.simulations,'result_files') 0234 studyinfo.simulations.result_files={}; 0235 end 0236 if ~isfield(studyinfo.simulations,'result_functions') 0237 studyinfo.simulations.result_functions={}; 0238 end 0239 if ~isfield(studyinfo.simulations,'result_options') 0240 studyinfo.simulations.result_options={}; 0241 end 0242 end 0243 0244 % check substructure studyinfo.analysis: 0245 if ~isfield(studyinfo,'analysis') 0246 studyinfo.analysis=[]; 0247 elseif isstruct(studyinfo.analysis) 0248 % standardize analysis substructure 0249 if ~isfield(studyinfo.analysis,'analysis_id') 0250 % ... 0251 end 0252 % ... 0253 end 0254 0255 % 3.0 sort fields 0256 % remove extra fields 0257 otherfields=setdiff(fieldnames(studyinfo),studyinfo_field_order); 0258 studyinfo=rmfield(studyinfo,otherfields); 0259 0260 % sort standardized fields 0261 studyinfo=orderfields(studyinfo,studyinfo_field_order); 0262 0263 % repeat for studyinfo.simulations 0264 if isstruct(studyinfo.simulations) 0265 otherfields=setdiff(fieldnames(studyinfo.simulations),sim_field_order); 0266 studyinfo.simulations=rmfield(studyinfo.simulations,otherfields); 0267 studyinfo.simulations=orderfields(studyinfo.simulations,sim_field_order); 0268 end 0269 0270 % repeat for studyinfo.analysis 0271 if isstruct(studyinfo.analysis) 0272 otherfields=setdiff(fieldnames(studyinfo.analysis),analysis_field_order); 0273 studyinfo.analysis=rmfield(studyinfo.analysis,otherfields); 0274 studyinfo.analysis=orderfields(studyinfo.analysis,analysis_field_order); 0275 end 0276 0277 %% auto_gen_test_data_flag argout 0278 if options.auto_gen_test_data_flag 0279 argout = {studyinfo}; % specific to this function 0280 0281 % dsUnitSaveAutoGenTestData(argin, argout); 0282 end