pwGetDrivingFunctionsFromFile
stimuli = pwGetDrivingFunctionsFromFile(filename, inputType, colNameStimulusIDs,
colNameTime, colNameValues)
Reads a driving input function from a file or a data struct.
filename Either a string comprising the filename of an external xls or txt
file or a data struct returned by Data_ReadDataFile in order to
avoid multiple loading of the same file. See example below.
inputType 'steps', 'linear', 'injection', 'spline'. Compare pwAddU.
colNameStimulusIDs
Exact name of the column comprising the stimulus IDs which have
to start at 1 and must be contiguous. The stimulus ID
corresponds to a different experimental setting, e.g.
stimulation with a different dosage or a different patient.
colNameTime Exact name of the column comprising the time values.
colNameValues Exact name of the column comprising the values of the
driving input function (uValues).
Description
The shape of externally controlled variables is specified through
driving input functions (pwAddU). In an external xls or txt data file,
they are given in the MCode section using
pwGetDrivingFunction(uType, uTimes, uValues, u2Values)
(or, since PW 2.0.55, in a driving input section, compare pwAddData).
Example for an experiment consisting of two settings (stimuli) with
a continuous stimulation of 6 units and a pulsed stimulation of 7 units
and 5 minutes duration, both starting at t=0:
drivingFunctions(1).name = 'Drug';
drivingFunctions(1).stimuli(1) = pwGetDrivingFunction('steps', [-1 0], [0 6]);
drivingFunctions(1).stimuli(2) = pwGetDrivingFunction('steps', [-1 0 5], [0 7 0]);
In some cases, the external species can not be approximated by such a
parametrization, but is rather given by measured data-points.
Then, a linear or spline driving function can be used.
In order to avoid very long expressions like
drivingFunctions(i).stimuli(1) = pwGetDrivingFunction('linear', ...
[-1 0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0 1.1 1.2 1.3...], ...
to capture the whole measurement, the driving function may reside in a
separate file, say 'DrugInput.xls'. Since the file should contain the
information for all experimental settings, i.e. stimuli, we want to
extract the shape of the driving function for all stimuli at once.
It can be done via
drivingFunctions(1).name = 'Drug';
drivingFunctions(1).stimuli = pwGetDrivingFunctionsFromFile(...
'DrugInput.xls', 'linear', 'StimuliIDs', 'Time', 'DrugValues')
where 'DrugValues' is the name of the column in the file 'DrugInput.xls'
comprising the values of the external drug for the time-point and
stimuli number given in the columns 'Time' and 'StimuliIDs', respectively.
The specified column names are arbitrary but must match exactly the external
file column names. The file 'DrugInput.xls' could look like this:
StimuliIDs Time DrugValues
1 0 14.70
1 0.1 21.73
1 0.2 25.87
...
2 0 1.50
2 0.1 1.79
2 0.2 2.10
...
Terminology
Unfortunately, we are using the same plural 'driving functions' in two situations:
- Several species can be measured externally
- One species is measured under different settings, i.e. stimuli.
The plural 's' in 'pwGetDrivingFunctionsFromFile' refers to several
driving functions with the same name but for different stimuli.
Please see the example below.
Example
% In order to load data for different driving species, the function
% has to called several times, e.g.
drivingFunctions(1).name = 'Drug1';
drivingFunctions(1).stimuli = pwGetDrivingFunctionsFromFile(...
'DrugInput.xls', 'linear', 'StimuliIDs', 'Time', 'DrugValues1')
drivingFunctions(2).name = 'Drug2';
drivingFunctions(2).stimuli = pwGetDrivingFunctionsFromFile(...
'DrugInput.xls', 'linear', 'StimuliIDs', 'Time', 'DrugValues2')
% In order to avoid repeated reading of the external file, a data struct
% can be used:
dataStruct = Data_ReadDataFile('DrugInput.xls');
drivingFunctions(1).name = 'Drug1';
drivingFunctions(1).stimuli = pwGetDrivingFunctionFromFile(...
dataStruct, 'linear', 'StimuliIDs', 'Time', 'DrugValues1');
drivingFunctions(2).name = 'Drug2';
drivingFunctions(2).stimuli = pwGetDrivingFunctionFromFile(...
dataStruct, 'linear', 'StimuliIDs', 'Time', 'DrugValues2');
See also