SimFunctionSensitivity object

SimFunctionSensitivity object, subclass of SimFunction object

Description

The SimFunctionSensitivity object is a subclass of SimFunction object. It allows you to compute sensitivity.

Syntax

The SimFunctionSensitivity object shares all syntaxes of the SimFunction object. It has the following additional syntax.

[T,Y,SensMatrix] = F(___) returns T, a cell array of numeric vector, Y, a cell array of 2-D numeric matrices, and SensMatrix, a cell array of 3-D numeric matrix containing calculated sensitivities of model quantities. SensMatrix contains a matrix of size TimePoints x Outputs x Inputs. TimePoints is the total number of time points, Outputs is the total number of output factors, and Inputs is the total number of input factors.

If you specify a single output argument, the object returns an SimData object or array of SimData objects with sensitivity information.

Properties

The SimFunctionSensitivity object shares all properties of the SimFunction object. It has the following additional properties.

SensitivityOutputs	table with variables named: 'Name' 'Type' 'Units' (only if UnitConversion is turned on) This table contains information about model quantities (species or parameters) for which you want to compute the sensitivities. Sensitivity output factors are the numerators of time-dependent derivatives described in Sensitivity Analysis in SimBiology. This property is read only.
SensitivityInputs	table with variables named: 'Name' 'Type' 'Units' (only if UnitConversion is turned on) This table contains information about model quantities (species, compartments, or parameters) with respect to which you want to compute the sensitivities. Sensitivity input factors are the denominators of time-dependent derivatives described in Sensitivity Analysis in SimBiology. This property is read only.
SensitivityNormalization	Character vector specifying the normalization method for calculated sensitivities. The following examples show how sensitivities of a species x with respect to a parameter k are calculated for each normalization type. "Full" specifies that the data should be made dimensionless. $$\left(\frac{k}{x(t)}\right)\left(\frac{\partial x(t)}{\partial k}\right)$$ Use this option if you want to compute the relative change in a sensitivity output, x(t), with respect to the relative change in a sensitivity input, k. This option is useful to compare different sensitivities where the respective sensitivity inputs have different units and respective sensitivity outputs have different units as well. "Half" specifies normalization relative to the numerator (sensitivity output) only. $$\left(\frac{1}{x(t)}\right)\left(\frac{\partial x(t)}{\partial k}\right)$$ Use this option if you want to compute the relative change in a sensitivity output, x(t), with respect to the absolute change in a sensitivity input, k. This option is useful to compare different sensitivities when the sensitivity outputs have different units while the inputs have the same units. "None" specifies no normalization. $$\frac{\partial x(t)}{\partial k}$$ Use this option if you want to compute the absolute change in a sensitivity output, x(t), with respect to the absolute change in a sensitivity input, k. This option is useful to compare different sensitivities when all sensitivity inputs have the same units and all sensitivity outputs have the same units.

Examples

Calculate Local Sensitivities Using SimFunctionSensitivity Object

This example shows how to calculate the local sensitivities of some species in the Lotka-Volterra model using the SimFunctionSensitivity object.

Load the sample project.

sbioloadproject lotka;

Define the input parameters.

params = {'Reaction1.c1', 'Reaction2.c2'};

Define the observed species, which are the outputs of simulation.

observables  = {'y1', 'y2'};

Create a SimFunctionSensitivity object. Set the sensitivity output factors to all species (y1 and y2) specified in the observables argument and input factors to those in the params argument (c1 and c2) by setting the name-value pair argument to 'all'.

f = createSimFunction(m1,params,observables,[],'SensitivityOutputs','all','SensitivityInputs','all','SensitivityNormalization','Full')

f = 
SimFunction

Parameters:

          Name          Value        Type     
    ________________    _____    _____________

    {'Reaction1.c1'}      10     {'parameter'}
    {'Reaction2.c2'}    0.01     {'parameter'}

Observables: 

     Name        Type    
    ______    ___________

    {'y1'}    {'species'}
    {'y2'}    {'species'}

Dosed: None

Sensitivity Input Factors: 

          Name              Type     
    ________________    _____________

    {'Reaction1.c1'}    {'parameter'}
    {'Reaction2.c2'}    {'parameter'}

Sensitivity Output Factors: 

     Name        Type    
    ______    ___________

    {'y1'}    {'species'}
    {'y2'}    {'species'}

Sensitivity Normalization: 

Full

Calculate sensitivities by executing the object with c1 and c2 set to 10 and 0.1, respectively. Set the output times from 1 to 10. t contains time points, y contains simulation data, and sensMatrix is the sensitivity matrix containing sensitivities of y1 and y2 with respect to c1 and c2.

[t,y,sensMatrix] = f([10,0.1],[],[],1:10);

Retrieve the sensitivity information at time point 5.

temp = sensMatrix{:};
sensMatrix2 = temp(t{:}==5,:,:);
sensMatrix2 = squeeze(sensMatrix2)

sensMatrix2 = 2×2

   37.6987   -6.8447
  -40.2791    5.8225

The rows of sensMatrix2 represent the output factors (y1 and y2). The columns represent the input factors (c1 and c2).

$$sensMatrix2=\left[\begin{array}{cc}\begin{array}{c}\frac{\partial y1}{\partial c1}\\ \\ \frac{\partial y2}{\partial c1}\end{array}& \begin{array}{c}\frac{\partial y1}{\partial c2}\\ \\ \frac{\partial y2}{\partial c2}\end{array}\end{array}\right]$$

Set the stop time to 15, without specifying the output times. In this case, the output times are the solver time points by default.

sd = f([10,0.1],15);

Retrieve the calculated sensitivities from the SimData object sd.

[t,y,outputs,inputs] = getsensmatrix(sd);

Plot the sensitivities of species y1 and y2 with respect to c1.

figure;
plot(t,y(:,:,1));
legend(outputs);
title('Sensitivities of species y1 and y2 with respect to parameter c1');
xlabel('Time');
ylabel('Sensitivity');

Plot the sensitivities of species y1 and y2 with respect to c2.

figure;
plot(t,y(:,:,2));
legend(outputs);
title('Sensitivities of species y1 and y2 with respect to parameter c2');
xlabel('Time');
ylabel('Sensitivity');

Alternatively, you can use sbioplot.

sbioplot(sd);

You can also plot the sensitivity matrix using the time integral for the calculated sensitivities of y1 and y2. The plot indicates y1 and y2 are more sensitive to c1 than c2.

[~, in, out] = size(y);
result = zeros(in, out);
for i = 1:in
    for j = 1:out
        result(i,j) = trapz(t(:),abs(y(:,i,j)));
    end
end
figure;
hbar = bar(result);
haxes = hbar(1).Parent;
haxes.XTick = 1:length(outputs);
haxes.XTickLabel = outputs;
legend(inputs,'Location','NorthEastOutside');
ylabel('Sensitivity');

Version History

Introduced in R2015a