StartBatch - Start a new batch job.
Batch processing is useful if you need to repeatedly perform a given analysis
on different data sets. Using batch processing is easier and more reliable
than writing a simple 'for' loop:
* You must only supply the code to run the analysis on one data set,
and a text file listing the data sets, including specific parameters
* Running the batch on a subset of the data is as easy as commenting
out the appropriate lines in this file
* Batch processing will not be interrupted when the analysis of one
particular data set generates an error
* Errors can be logged to disk
* Processing can be delayed to a later time (e.g. during the night)
Results can either be kept in memory using the batch output variable, or
stored in a central database. The latter is the recommended solution, as it
is far more powerful and reliable. See EXAMPLES below.
During batch processing, figures are typically hidden so they do not keep
popping up as the user is performing other tasks as the batch is running in
the background (although this is configurable). In order to keep figures
hidden, batch functions should not use figure(h) or axes(a) which make the
figure visible. Two helper functions, <a href="matlab:help scf">scf</a> and <a href="matlab:help sca">sca</a>, can be used instead
to set the current figure or axes without making the figure visible.
USAGE
batch = StartBatch(mfile,bfile,<options>)
mfile batch function (M-file name or function handle)
bfile batch file listing the parameters for each iteration
<options> optional list of property-value pairs (see table below)
=========================================================================
Properties Values
-------------------------------------------------------------------------
'delay' delay (in minutes) before execution starts
'hide' by default, new figures are hidden to speed up batch
processing (use 'off' to cancel this behavior)
'log' progress/error log file (default = none) (see NOTE below)
=========================================================================
NOTE
Log file names can include wildcards to indicate current date and time:
%y year
%m month
%d day
%t time
EXAMPLE 1 - RESULTS KEPT IN BATCH OUTPUT VARIABLE
This is the simpler solution, but it is not as reliable (e.g. the results
can be lost if Matlab crashes) and powerful (e.g. the results cannot be
shared between users) as using a database. See EXAMPLE 2 below.
Suppose you wish to count the number of 'ripples' in a set of sleep
sessions recorded from different rats. You could create the file
'batch.txt', where you would list the session files to process, as
well as the LFP channel to use in each case to detect ripples:
Rat-01-20100915-01-sleep 5
Rat-01-20100920-01-sleep 5
Rat-02-20101001-01-sleep 3
Rat-01-20101005-04-rest 1
...
The function used to process the data would look like:
function n = CountRipples(session,channel)
SetCurrentSession(session);
lfp = GetLFP(channel);
fil = FilterLFP(lfp,'bandpass','ripples');
ripples = FindRipples(fil);
n = size(ripples,1);
To start processing the data in one hour, you would then call:
b = StartBatch(@CountRipples,'batch.txt','delay',60);
To get the results:
n = GetBatch(b);
To log progress and errors:
b = StartBatch(@CountRipples,'batch.txt','log','Errors-%y%m%d.log');
LIMITATIONS
For technical reasons, the batch function must have a fixed number of output
parameters, e.g. it cannot have 'varargout' as one of its output parameters.
It is possible to circumvent this limitation if you know in advance the number
of output parameters that the batch function would actually return in your
particular case. Assuming this function is called 'VariableProcess', takes two
inputs and will always return three outputs for your data, you could define:
function [x,y,z] = FixedProcess(u,v)
[x,y,z] = VariableProcess(u,v);
and then use this as the batch function.
EXAMPLE 2 - RESULTS STORED IN CENTRAL DATABASE
Let us rewrite the previous example using a central database. First, we need
to create the database:
% This assumes your login/password are stored
% in a configuration file in your home directory
DBConnect;
DBCreate('Ripples_%y%m%d');
The function used to process the data would now look like:
function CountRipples(session,channel)
SetCurrentSession(session);
lfp = GetLFP(channel);
fil = FilterLFP(lfp,'bandpass','ripples');
ripples = FindRipples(fil);
n = size(ripples,1);
eid = [session '-' num2str(channel)];
DBAddVariable(n,eid,'Ripple Count','','',{'CountRipples'});
This would store the number of ripples for each session, as well as useful
information such as who stored these data, when, using which function (the
actual code, not just the function name, is stored in the database).
To get the results:
n = DBGetValues;
SEE
See also Database, GetBatch, BatchInfo, CancelBatch, CleanBatches, Store,
Recall, Hide, sca, scf.0001 function batch = StartBatch(mfile,bfile,varargin) 0002 0003 %StartBatch - Start a new batch job. 0004 % 0005 % Batch processing is useful if you need to repeatedly perform a given analysis 0006 % on different data sets. Using batch processing is easier and more reliable 0007 % than writing a simple 'for' loop: 0008 % 0009 % * You must only supply the code to run the analysis on one data set, 0010 % and a text file listing the data sets, including specific parameters 0011 % 0012 % * Running the batch on a subset of the data is as easy as commenting 0013 % out the appropriate lines in this file 0014 % 0015 % * Batch processing will not be interrupted when the analysis of one 0016 % particular data set generates an error 0017 % 0018 % * Errors can be logged to disk 0019 % 0020 % * Processing can be delayed to a later time (e.g. during the night) 0021 % 0022 % Results can either be kept in memory using the batch output variable, or 0023 % stored in a central database. The latter is the recommended solution, as it 0024 % is far more powerful and reliable. See EXAMPLES below. 0025 % 0026 % During batch processing, figures are typically hidden so they do not keep 0027 % popping up as the user is performing other tasks as the batch is running in 0028 % the background (although this is configurable). In order to keep figures 0029 % hidden, batch functions should not use figure(h) or axes(a) which make the 0030 % figure visible. Two helper functions, <a href="matlab:help scf">scf</a> and <a href="matlab:help sca">sca</a>, can be used instead 0031 % to set the current figure or axes without making the figure visible. 0032 % 0033 % USAGE 0034 % 0035 % batch = StartBatch(mfile,bfile,<options>) 0036 % 0037 % mfile batch function (M-file name or function handle) 0038 % bfile batch file listing the parameters for each iteration 0039 % <options> optional list of property-value pairs (see table below) 0040 % 0041 % ========================================================================= 0042 % Properties Values 0043 % ------------------------------------------------------------------------- 0044 % 'delay' delay (in minutes) before execution starts 0045 % 'hide' by default, new figures are hidden to speed up batch 0046 % processing (use 'off' to cancel this behavior) 0047 % 'log' progress/error log file (default = none) (see NOTE below) 0048 % ========================================================================= 0049 % 0050 % NOTE 0051 % 0052 % Log file names can include wildcards to indicate current date and time: 0053 % 0054 % %y year 0055 % %m month 0056 % %d day 0057 % %t time 0058 % 0059 % EXAMPLE 1 - RESULTS KEPT IN BATCH OUTPUT VARIABLE 0060 % 0061 % This is the simpler solution, but it is not as reliable (e.g. the results 0062 % can be lost if Matlab crashes) and powerful (e.g. the results cannot be 0063 % shared between users) as using a database. See EXAMPLE 2 below. 0064 % 0065 % Suppose you wish to count the number of 'ripples' in a set of sleep 0066 % sessions recorded from different rats. You could create the file 0067 % 'batch.txt', where you would list the session files to process, as 0068 % well as the LFP channel to use in each case to detect ripples: 0069 % 0070 % Rat-01-20100915-01-sleep 5 0071 % Rat-01-20100920-01-sleep 5 0072 % Rat-02-20101001-01-sleep 3 0073 % Rat-01-20101005-04-rest 1 0074 % ... 0075 % 0076 % The function used to process the data would look like: 0077 % 0078 % function n = CountRipples(session,channel) 0079 % 0080 % SetCurrentSession(session); 0081 % lfp = GetLFP(channel); 0082 % fil = FilterLFP(lfp,'bandpass','ripples'); 0083 % ripples = FindRipples(fil); 0084 % n = size(ripples,1); 0085 % 0086 % To start processing the data in one hour, you would then call: 0087 % 0088 % b = StartBatch(@CountRipples,'batch.txt','delay',60); 0089 % 0090 % To get the results: 0091 % 0092 % n = GetBatch(b); 0093 % 0094 % To log progress and errors: 0095 % 0096 % b = StartBatch(@CountRipples,'batch.txt','log','Errors-%y%m%d.log'); 0097 % 0098 % LIMITATIONS 0099 % 0100 % For technical reasons, the batch function must have a fixed number of output 0101 % parameters, e.g. it cannot have 'varargout' as one of its output parameters. 0102 % It is possible to circumvent this limitation if you know in advance the number 0103 % of output parameters that the batch function would actually return in your 0104 % particular case. Assuming this function is called 'VariableProcess', takes two 0105 % inputs and will always return three outputs for your data, you could define: 0106 % 0107 % function [x,y,z] = FixedProcess(u,v) 0108 % 0109 % [x,y,z] = VariableProcess(u,v); 0110 % 0111 % and then use this as the batch function. 0112 % 0113 % EXAMPLE 2 - RESULTS STORED IN CENTRAL DATABASE 0114 % 0115 % Let us rewrite the previous example using a central database. First, we need 0116 % to create the database: 0117 % 0118 % % This assumes your login/password are stored 0119 % % in a configuration file in your home directory 0120 % DBConnect; 0121 % DBCreate('Ripples_%y%m%d'); 0122 % 0123 % The function used to process the data would now look like: 0124 % 0125 % function CountRipples(session,channel) 0126 % 0127 % SetCurrentSession(session); 0128 % lfp = GetLFP(channel); 0129 % fil = FilterLFP(lfp,'bandpass','ripples'); 0130 % ripples = FindRipples(fil); 0131 % n = size(ripples,1); 0132 % eid = [session '-' num2str(channel)]; 0133 % DBAddVariable(n,eid,'Ripple Count','','',{'CountRipples'}); 0134 % 0135 % This would store the number of ripples for each session, as well as useful 0136 % information such as who stored these data, when, using which function (the 0137 % actual code, not just the function name, is stored in the database). 0138 % 0139 % To get the results: 0140 % 0141 % n = DBGetValues; 0142 % 0143 % SEE 0144 % 0145 % See also Database, GetBatch, BatchInfo, CancelBatch, CleanBatches, Store, 0146 % Recall, Hide, sca, scf. 0147 % 0148 0149 % Copyright (C) 2007-2013 by Michaël Zugaro 0150 % 0151 % This program is free software; you can redistribute it and/or modify 0152 % it under the terms of the GNU General Public License as published by 0153 % the Free Software Foundation; either version 3 of the License, or 0154 % (at your option) any later version. 0155 0156 % Default values 0157 delay = 0; 0158 hide = 'on'; 0159 log = ''; 0160 0161 % Check number of parameters 0162 if nargin < 2, 0163 error('Incorrect number of parameters (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details).'); 0164 end 0165 0166 % Parse parameter list 0167 for i = 1:2:length(varargin), 0168 if ~ischar(varargin{i}), 0169 error(['Parameter ' num2str(i+1) ' is not a property (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details).']); 0170 end 0171 switch(lower(varargin{i})), 0172 case 'delay', 0173 delay = varargin{i+1}; 0174 if ~isiscalar(delay,'>0'), 0175 error('Incorrect value for property ''delay'' (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details).'); 0176 end 0177 case 'hide', 0178 hide = lower(varargin{i+1}); 0179 if ~isastring(hide,'on','off'), 0180 error('Incorrect value for property ''hide'' (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details).'); 0181 end 0182 case 'log', 0183 log = varargin{i+1}; 0184 if ~isastring(log), 0185 error('Incorrect value for property ''log'' (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details).'); 0186 end 0187 otherwise, 0188 error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details).']); 0189 end 0190 end 0191 0192 % Compatibility with previous versions: reverse parameter order if necessary 0193 if isa(bfile,'function_handle') || (isastring(mfile) && isempty(which(mfile))), 0194 tmp = bfile; 0195 bfile = mfile; 0196 mfile = tmp; 0197 end 0198 0199 % Batch function name 0200 if isa(mfile,'function_handle'), 0201 mfileName = func2str(mfile); 0202 else 0203 mfileName = mfile; 0204 end 0205 0206 % Check batch file and function are valid 0207 if ~isastring(bfile) || ~exist(bfile,'file'), 0208 error('Batch file not found (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details).'); 0209 end 0210 if isempty(which(mfileName)), 0211 error('Batch function not found (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details).'); 0212 end 0213 0214 % Make sure M-file has a defined number of output parameters 0215 if nargout(mfile) == -1, 0216 error(['''' mfileName ''' has a variable number of output arguments (type ''help <a href="matlab:help StartBatch">StartBatch</a>'' for details). ']); 0217 end 0218 0219 % Open batch file 0220 f = fopen(bfile,'r'); 0221 if f == -1, error(['Could not open file ''' bfile '''.']); end 0222 0223 % Parse batch file 0224 b = ParseBatch(bfile); 0225 0226 % Open log file 0227 b.log = -1; 0228 if ~isempty(log), 0229 % Insert date 0230 log = InsertDate(log); 0231 b.log = fopen(log,'w'); 0232 if b.log == -1, error(['Could not open log file ''' log '''.']); end 0233 end 0234 0235 % Set batch function 0236 [~,mfile] = fileparts(mfileName); 0237 b.mfile = mfile; 0238 0239 b.hide = strcmp(hide,'on'); 0240 if b.hide, 0241 warning('Figures will be hidden (type ''help <a href="matlab:help Hide">Hide</a>'' for details).'); 0242 end 0243 0244 % Start timer 0245 batch = timer('TimerFcn',{@RunBatch,b},'StartDelay',delay*60,'Tag','BatchJob'); 0246 start(batch);