ADMIT documentation: ADMITprocessData

ADMITprocessData

ADMITprocessData processes the raw (experimental) data adding tolerances
and intermediate bounds based on qualitative constraints

OPTDATA = ADMITprocessData(OPTDATA,[OPTIONS])
  Processes input raw data from OPTDATA without any modifications,
  copying every entry of the type 'Raw' and setting its type to
  'Processed'.

OPTDATA = ADMITprocessData(OPTDATA,VAR_NAMES,TIME,[OPTIONS])
  Generates bounds on variables VAR_NAMES at time instances TIME from the
  raw data on these variables found in OPTDATA. Intermediate bounds are
  calculated using two raw data bounds enclosing current time point
     intermediate_lowerbound = min(left_lowerbound,right_lowerbound)
     intermediate_upperbound = min(left_upperbound,right_upperbound)
  (for more details see Examples section)
  For time invariant variables the TIME input should be empty ([])

OPTDATA = ADMITprocessData(OPTDATA,VAR_NAMES,TIME,RELTOL,[OPTIONS])
  Same as previous function, but before the intermediate bounds are
  calculated, relative tolerance of size RELTOL is added to the input raw
  data. Relative tolerance is calculated as
     value_lowerbound*(1-RELTOL)
     value_upperbound*(1+RELTOL)

OPTDATA = ADMITprocessData(OPTDATA,VAR_NAMES,TIME,...
                           RELTOL,ABSTOL,[OPTIONS])
  Same as previous function, but absolute tolerance ABSTOL is added after
  the relative tolerance. With both tolerances the values look like
     value_lowerbound*(1-RELTOL)-ABSTOL
     value_upperbound*(1+RELTOL)+ABSTOL

OPTDATA = ADMITprocessData(OPTDATA,VAR_NAMES,TIME,...
                           RELTOL,ABSTOL,INTERBOUNDS,[OPTIONS])
  Same as previous function, but rules for calculating intermediate
  bounds can be specified. Possible rules are
     'minmax'      - used by default, "worst case bounds"
     'decrease'    - measurements are considered monotonicaly decreasing
                     over the whole time horizon TIME
     'increase'    - measurements are considered monotonicaly increasing
                     over the whole time horizon TIME
     'interpolate' - bounds on the intermediate measurements are
                     interpolated linearly according to the TIME values
  For details on differences of these rules please refer to the Examples
  section below.

Inputs
  [...]        : square brackets notify that input is optional.
  OPTDATA      : valid ADMITdata object with the experimental data of
                 type 'Raw' to be processed. If you wish to process data
                 of different type, call ADMITimportData first.
  VAR_NAMES    : string with the name of the variable or cell array of
                 strings for several variable names.
  TIME         : time vector or ADMITtime object for which intermediate
                 bounds are to be added. Should be empty ([]) for time
                 invariant variables.
  RELTOL       : relative tolerances on the species. Can be given as a
                 single value (used for all species), or defined as a
                 vector of the same length as the number of species in
                 the VAR_NAMES. 0 is the default value.
  ABSTOL       : absolute tolerances on the species. Provided in the same
                 form as relative tolerance.
  INTERBOUNDS  : interpolation method/type used to derive bounds at the
                 time points TIME for variables in VAR_NAMES. Possible
                 values are:
                 - 'minmax'
                 - 'decreasing'/'decrease'
                 - 'increasing'/'increase'  
                 - 'interpolate'
                 Can be given as a single string (this mode will be used
                 for all the variables) or as a cell array of strings of
                 the same length as VAR_NAMES. 'minmax' is the default
                 value.
  OPTIONS      : ADMIToptions object, that contains options and
                 preferences. Default options are used if this input is
                 not provided.

Returns
 OPTDATA       : generated ADMITdata objects of the type 'Processed'. 
                 Input OPTDATA will also be included in it.

Examples

% Add data stored in matrices
% (note: you can use csvread,xlsread,... and other MatLab-functions to
% read data from CSV,EXCEL,... files!)
dataMean     = [1.5,1.9,1.3,1.7,2,1.6];
dataVariance = [0.15,0.2,0.15,0.1,0.15,0.1];
dataTime     = [0,1,2,3,4,5];
% assume lower/upper bounds to correspond to -/+ standard-deviation
dataLB       = dataMean - sqrt(dataVariance);
dataUB       = dataMean + sqrt(dataVariance);
% import
OPTDATA = ADMITimportData('x1',dataTime,dataLB,dataUB)
ADMITplot(OPTDATA,'x1')

% First process this data with no agruments.
% The result is then exactly the same as the 'Raw' data.
OPTDATA1 = ADMITprocessData(OPTDATA);
ADMITplot(OPTDATA1,'x1','Processed')

% Next, add tolerances to the measurement data and intermediate steps.
% The time points that are close enough to some 'Raw' timepoint of the
% input (<1% of the minimal input stepsize) are taken as exact timepoints,
% all the rest are treated as intermediate. For intermediate time points
% two closest 'Raw' points enclosing it are taken as reference and the
% bounds are then calculated according to specified method. If this method
% is not set explicitly (see further), the intermediate bounds are the
% worst of the two reference bounds. I.e. if the bounds are, say, [1,2]
% and [3,4], the intermediate will be [1,4].
OPTDATA2 = ADMITprocessData(OPTDATA,'x1',0:.2:5,.05,.025);
ADMITplot(OPTDATA2,'x1')

% To show how to treat multiple variables at once, we create a second set
% of 'Raw' data.
dataLB2   = 3 - dataMean - sqrt(dataVariance);
dataUB2   = 3 - dataMean + sqrt(dataVariance);
% We can attach new data to the existing object by providing it as the
% first input of ADMITimportData.
OPTDATAx2 = ADMITimportData(OPTDATA, 'x2',dataTime,dataLB2,dataUB2);
ADMITplot(OPTDATAx2,{'x1','x2'})

% We can only process data for the same time window, but the tolerances
% and intermediate bounds methods can be different for different
% variables. Here we specify relative and absolute tolerance values for
% the variables, but set intermediate bounds method same for both.
% The intermediate bounds method 'decrease' or 'decreasing' is creating
% bounds in a way that only monotonically decreasing functions can fit.
% The overall result can be tighter than the initial 'Raw' bounds even
% with added tolerances.
OPTDATA3 = ADMITprocessData(OPTDATAx2,{'x1','x2'},0:.2:5,...
                            [0.05 0.075],[0.025,0],'decrease');
ADMITplot(OPTDATA3,{'x1','x2'})

% The intermediate bounds method 'increase' or 'increasing' is similar
% to the 'decreasing' method, but only monotonically increasing functions
% are considered for it.
% The method 'interpolate' generates bounds that allow functions that
% are linear between any two neighboring 'Raw' input data points.
OPTDATA4 = ADMITprocessData(OPTDATAx2,{'x1','x2'},0:.2:5,...
                            0,0,{'increase','interpolate'});
ADMITplot(OPTDATA4,{'x1','x2'})

% The bounds can be created for different time intervals with different
% options, as shown next. Pay attention, though, that if the time
% intervals will overlap, this can cause problems, as the corresponding
% bounds will be intersected when adding them to the ADMITproject
OPTDATA5 = ADMITprocessData(OPTDATAx2,'x1',0:.2:2,0,0,'decrease');
OPTDATA5 = ADMITprocessData(OPTDATA5,'x1',2.2:.2:5,0,0,'increase');
ADMITplot(OPTDATA5,'x1')