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:

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 Calculation. 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 Calculation. This property is read only.

SensitivityNormalizationCharacter 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.
  • 'None' — No normalization.

    x(t)k

  • 'Half' — Normalization relative to the numerator only.

    (1x(t))(x(t)k)

  • 'Full' — Full dedimensionalization

    (kx(t))(x(t)k)

Examples

collapse all

This example shows how to calculate 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 using the keyword '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 simulation time = 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 output factors (y1 and y2). The columns represent the input factors (c1 and c2).

sensMatrix2=[y1c1y2c1y1c2y2c2]

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. Expand Run1 to select which simulation or sensitivity data to display.

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 the parameter 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');

Introduced in R2015a