sbioelementaryeffects

Выполните глобальный анализ чувствительности (GSA) путем вычисления элементарных эффектов

    Описание

    пример

    elementaryEffectsResults = sbioelementaryeffects(modelObj,params,observables) выполняет глобальный анализ чувствительности модели SimBiology modelObj путем вычисления элементарных эффектов observables относительно отдельных количеств модели или параметров, заданных в params.

    пример

    elementaryEffectsResults = sbioelementaryeffects(modelObj,params,observables,Name=Value) дополнительные опции использования заданы одними или несколькими аргументами name-value.

    Примеры

    свернуть все

    Загрузите модель роста опухоли.

    sbioloadproject tumor_growth_vpop_sa.sbproj

    Заставьте вариант предполагаемыми параметрами и дозой применяться к модели.

    v = getvariant(m1);
    d = getdose(m1,'interval_dose');

    Получите активный configset и установите вес опухоли как ответ.

    cs = getconfigset(m1);
    cs.RuntimeOptions.StatesToLog = 'tumor_weight';

    Симулируйте модель и постройте профиль роста опухоли.

    sbioplot(sbiosimulate(m1,cs,v,d));

    Figure contains an axes object. The axes object with title States versus Time contains an object of type line. This object represents tumor_weight.

    Выполните глобальный анализ чувствительности (GSA) на модели, чтобы найти параметры модели, к которым рост опухоли чувствителен.

    Во-первых, задайте параметры модели интереса, которые вовлечены в фармакодинамику роста опухоли. Задайте ответ модели как вес опухоли.

    modelParamNames = {'L0','L1','w0','k1'};
    outputName = 'tumor_weight';

    Затем выполните GSA путем вычисления элементарных эффектов с помощью sbioelementaryeffects. Используйте 100 как количество отсчетов и набор ShowWaitBar к true показать прогресс симуляции.

    rng('default');
    eeResults = sbioelementaryeffects(m1,modelParamNames,outputName,Variants=v,Doses=d,NumberSamples=100,ShowWaitbar=true);

    Покажите средний ответ модели, результаты симуляции и теневую область, покрывающую 90% результатов симуляции.

    plotData(eeResults,ShowMedian=true,ShowMean=false);

    Figure contains an axes object. The axes object contains 12 objects of type line, patch. These objects represent model simulation, 90.0% region, median value.

    Можно настроить область квантиля к различному проценту путем определения Alphas для более низких и верхних квантилей всех ответов модели. Например, alpha значение 0,1 графиков теневая область между 100*alpha и 100*(1-alpha) квантили всех симулированных ответов модели.

    plotData(eeResults,Alphas=0.1,ShowMedian=true,ShowMean=false);

    Figure contains an axes object. The axes object contains 12 objects of type line, patch. These objects represent model simulation, 80.0% region, median value.

    Постройте курс времени средних значений и стандартные отклонения элементарных эффектов.

    h = plot(eeResults);
    % Resize the figure.
    h.Position(:) = [100 100 1280 800];

    Figure contains 8 axes objects. Axes object 1 with title sensitivity output [Tumor Growth Model].tumor_weight contains an object of type line. Axes object 2 with title sensitivity output [Tumor Growth Model].tumor_weight contains an object of type line. Axes object 3 contains an object of type line. Axes object 4 contains an object of type line. Axes object 5 contains an object of type line. Axes object 6 contains an object of type line. Axes object 7 contains an object of type line. Axes object 8 contains an object of type line.

    Среднее значение эффектов объясняет, оказывают ли изменения входных значений параметров какое-либо влияние на ответ веса опухоли. Стандартное отклонение эффектов объясняет, зависит ли изменение чувствительности от местоположения в области параметра.

    От среднего значения графиков эффектов, параметры L1 и w0 кажется, самые чувствительные параметры к весу опухоли, прежде чем доза будет применена в t = 7. Но, после того, как доза применяется, k1 и L0 станьте более чувствительными параметрами и способствуйте больше всего дозируемому после того, как этапу веса опухоли. Графики стандартного отклонения эффектов показывают больше отклонений для больших значений параметров на более позднем этапе (t> 35), чем для этапа прежде-чем-дозы роста опухоли.

    Можно также отобразить величины чувствительности в столбиковой диаграмме. Каждая цветная штриховка представляет гистограмму, представляющую значения в разное время. Более темные цвета означают, что те значения происходят чаще по курсу всего времени.

    bar(eeResults);

    Figure contains an axes object. The axes object with title sensitivity output [Tumor Growth Model].tumor_weight contains 18 objects of type patch, line. These objects represent mean, standard deviation.

    Можно также построить сетки параметра, и выборки использовались для расчета элементарных эффектов.

    plotGrid(eeResults)

    Figure contains 6 axes objects. Axes object 1 contains 200 objects of type line. Axes object 2 contains 200 objects of type line. Axes object 3 contains 200 objects of type line. Axes object 4 contains 200 objects of type line. Axes object 5 contains 200 objects of type line. Axes object 6 contains 200 objects of type line.

    Можно задать больше выборок, чтобы увеличить точность элементарных эффектов, но симуляция может занять больше времени, чтобы закончиться. Используйте addsamples добавить больше выборок.

    eeResults2 = addsamples(eeResults,200);

    SimulationInfo свойство объекта результата содержит различную информацию для вычисления элементарных эффектов. Например, данные о симуляции модели (SimData) для каждой симуляции с помощью набора выборок параметра хранятся в SimData поле свойства. Это поле является массивом SimData объекты.

    eeResults2.SimulationInfo.SimData
     
       SimBiology SimData Array : 1500-by-1
     
       Index:    Name:         ModelName:         DataCount: 
       1           -           Tumor Growth Model 1          
       2           -           Tumor Growth Model 1          
       3           -           Tumor Growth Model 1          
       ...                                                   
       1500        -           Tumor Growth Model 1          
     
    

    Можно узнать, перестала ли какая-либо симуляция модели работать во время расчета путем проверки ValidSample поле SimulationInfo. В этом примере поле не показывает не пройдено запусков симуляции.

    all(eeResults2.SimulationInfo.ValidSample)
    ans = logical
       1
    
    

    Можно добавить пользовательские выражения как observables и вычислить элементарные эффекты добавленного observables. Например, можно вычислить эффекты для максимального веса опухоли путем определения пользовательского выражения можно следующим образом.

    % Suppress an information warning that is issued.
    warnSettings = warning('off', 'SimBiology:sbservices:SB_DIMANALYSISNOTDONE_MATLABFCN_UCON');
    % Add the observable expression.
    eeObs = addobservable(eeResults2,'Maximum tumor_weight','max(tumor_weight)','Units','gram');

    Постройте вычисленные результаты симуляции, показывающие 90%-ю область квантиля.

    h2 = plotData(eeObs);
    h2.Position(:) = [100 100 1500 800];

    Figure contains 2 axes objects. Axes object 1 contains 12 objects of type line, patch. These objects represent model simulation, 90.0% region, mean value. Axes object 2 contains 12 objects of type line, patch. These objects represent model simulation, 90.0% region, mean value.

    Можно также удалить заметное путем определения его имени.

    eeNoObs = removeobservable(eeObs,'Maximum tumor_weight');

    Восстановите настройки предупреждения.

    warning(warnSettings);

    Входные параметры

    свернуть все

    Модель SimBiology в виде SimBiology model object.

    Имена параметров модели, разновидностей или отсеков в виде вектора символов, строки, представляют в виде строки вектор или массив ячеек из символьных векторов.

    Пример: ["k1","k2"]

    Типы данных: char | string | cell

    Ответы модели в виде вектора символов, строки, представляют в виде строки вектор или массив ячеек из символьных векторов. Задайте имена разновидностей, параметров, отсеков или observables.

    Пример: "tumor_growth"

    Типы данных: char | string | cell

    Аргументы name-value

    Задайте дополнительные пары аргументов как Name1=Value1,...,NameN=ValueN, где Name имя аргумента и Value соответствующее значение. Аргументы name-value должны появиться после других аргументов, но порядок пар не имеет значения.

    Пример: eeResults = sbioelementaryeffects(modelObj,params,observables,StopTime=10) задает, чтобы использовать время остановки 10.

    Параметр ограничивает в виде числовой матрицы с двумя столбцами. Первый столбец содержит нижние границы, и второй столбец содержит верхние границы. Количество строк должно быть равно количеству параметров в params.

    Если параметр имеет ненулевое значение, границы по умолчанию составляют ±10% значения. Если значение параметров является нулем, границами по умолчанию является [0 1].

    Пример: [0.5 5]

    Типы данных: double

    Дозы, чтобы использовать во время симуляций модели в виде ScheduleDose или RepeatDose возразите или вектор из объектов дозы.

    Варианты, чтобы применяться перед симуляциями модели в виде различного объекта или вектора из различных объектов.

    Когда вы задаете несколько вариантов с дублирующимися техническими требованиями для значения свойства, последнее вхождение для значения свойства в массиве вариантов используется в процессе моделирования.

    Количество отсчетов, чтобы вычислить элементарные эффекты в виде положительного целого числа. Функция требует (количество входа params + 1) * NumberSamples симуляции модели, чтобы вычислить элементарные эффекты.

    Типы данных: double

    Метод, чтобы выбрать точки выборки, чтобы вычислить элементарные эффекты в виде "chain" или "radial". "chain" укажите, что выбор использует метод Морриса [1]. "radial" укажите, что выбор использует метод Sohier [2]. Для получения дополнительной информации смотрите Элементарные Эффекты для Глобального Анализа чувствительности.

    Типы данных: char | string

    Уровень дискретизации области параметра в виде положительного даже целое число. Этот параметр задает сетку равноотстоящих точек в области параметра, где каждая размерность дискретизируется с помощью Gridlevel+1 'points'. Следующий рисунок показывает пример сетки для параметров p1 и p2 в данных границах параметра.

    Grid of points

    Для получения дополнительной информации смотрите Элементарные Эффекты для Глобального Анализа чувствительности.

    Типы данных: double

    Размер шага для вычисления элементарных эффектов в виде положительного целого числа между 1 и GridLevel. Размер шага измеряется в терминах узлов решетки между соседними точками. Следующий рисунок показывает примеры различных значений дельты сетки.

    Two grids of points, one with red lines showing a GridDelta of one and the other showing a GridDelta of three.

    Для получения дополнительной информации смотрите Элементарные Эффекты для Глобального Анализа чувствительности.

    Типы данных: double

    Отметьте, чтобы использовать абсолютные значения элементарных эффектов в виде true или false. По умолчанию функция использует абсолютные значения элементарных эффектов. Используя неабсолютные значения может составить в среднем при вычислении среднего значения. Для получения дополнительной информации смотрите Элементарные Эффекты для Глобального Анализа чувствительности.

    Типы данных: логический

    Метод, чтобы сгенерировать выборки параметра в виде одного из следующего:

    • "lhs" — Используйте латинские выборки гиперкуба низкого несоответствия.

    • "random" — Используйте равномерно распределенные случайные выборки.

    Функция выбирает сгенерированные выборки параметра путем выборки узлов решетки.

    Время остановки симуляции в виде неотрицательного скаляра. Если вы не задаете никакой StopTime ни OutputTimes, функция использует время остановки от активной конфигурации модели модели. Вы не можете задать оба StopTime и OutputTimes.

    Типы данных: double

    Simulation времена выхода в виде числового вектора. Функция вычисляет элементарные эффекты в этих выходных моментах времени. Вы не можете задать оба StopTime и OutputTimes. По умолчанию функция использует моменты времени, о которых сообщают, первой симуляции модели.

    Пример: [0 1 2 3.5 4 5 5.5]

    Типы данных: double

    Отметьте, чтобы запустить симуляции модели параллельно в виде true или false. Когда значением является true и Parallel Computing Toolbox™ доступен, функциональные параллельные симуляции запусков.

    Типы данных: логический

    Отметьте, чтобы включить ускорение модели в виде true или false.

    Типы данных: логический

    Метод для интерполяции ответов модели на единый набор выходных времен в виде вектора символов или строки. Допустимые опции следуют.

    • "interp1q" — Используйте interp1q функция.

    • Используйте interp1 функция путем определения одного из следующих методов:

      • "nearest"

      • "linear"

      • "spline"

      • "pchip"

      • "v5cubic"

    • "zoh" — Укажите, что нулевой порядок содержит.

    Типы данных: char | string

    Отметьте, чтобы показать прогресс симуляций модели путем отображения панели ожидания в виде true или false. По умолчанию никакие не ожидают, панель отображена.

    Типы данных: логический

    Выходные аргументы

    свернуть все

    Результаты, содержащие средние значения и стандартные отклонения элементарных эффектов, возвращенных как SimBiology.gsa.ElementaryEffects объект. Объект включает информацию, такую как среднее и стандартное отклонение элементарных эффектов, а также выборок параметра, и симуляции модели использовались для расчета элементарных эффектов.

    Больше о

    свернуть все

    Элементарные эффекты для глобального анализа чувствительности

    sbioelementaryeffects позволяет вам оценить глобальную чувствительность ответа модели относительно изменений параметров модели.

    Считайте простой случай одним входным параметром чувствительности P. Элементарный EE эффекта P относительно ответа модели R определяется следующим образом.

    EEP(x)=R(x)R(x+delta)

    Здесь, EEP(x) является элементарным эффектом P. R(x) и R(x+delta) являются ответами модели в определенное время или значения observables, оцененного для значений параметров x и x+delta.

    В общем случае входных параметров чувствительности k x является вектором из различных значений параметров, x = [v1,v2,v3,…,vk]. Элементарный эффект i th параметр вычисляется можно следующим образом.

    EEPi(x)=R(v1,v2,v3,...,vi,...,vk)R(v1,v2,v3,...,vi+deltai,...,vk)=R(x)R(x+ei×deltai)

    Здесь, ei является i th канонический единичный вектор. Таким образом, вычисляя элементарные эффекты всех параметров P1,P2,P3,…,Pk требует k+1 симуляции модели.

    Функция предоставляет два метода ('PointSelection') выбрать набор k+1 точки, требуемые вычислить эти элементарные эффекты.

    • radial — Этот метод [2] использование точки k, x±e1×delta1,x±e2×delta2,...,x±ek×deltak, это располагается вокруг одной центральной точки x, чтобы вычислить элементарные эффекты для каждого из параметров k.

      Central point connected by lines to other points surrounding it. Points are labeled X, X+e1*delta1, and so on.

    • chain — Этот метод [1] цепи использования точек, вместо радиально расположенных точек вокруг центральные точки:

      x+i=1nei×deltai,гдеn=0,1,...,k

      Series of points connected by lines in a staircase pattern. Points are labeled X, X+e1*delta1+e2*delta2, and so on.

    Чтобы получить среднее и стандартное отклонение элементарных эффектов, функция вычисляет N ('NumberSamples') элементарные эффекты на параметр, который требует N*(k+1) симуляции. По умолчанию функция сообщает о среднем и стандартном отклонении абсолютных элементарных эффектов каждого параметра P1,P2,P3,…,Pk.

    Среднее значениеизEEPi=среднее значение(|EEPi|) Стандартное отклонение  EEPi=станд(|EEPi|)

    • Среднее значение элементарных эффектов объясняет, оказывают ли изменения параметра P какое-либо влияние на ответ R в среднем.

    • Стандартное отклонение объясняет, зависит ли изменение чувствительности от местоположения в области параметра.

    Функция использует абсолютные элементарные эффекты по умолчанию, потому что элементарные эффекты могут составить в среднем при вычислении среднего значения в противном случае. Опционально, можно установить 'AbsoluteEffects' аргумент значения имени к false получить средние значения и стандартные отклонения неабсолютных элементарных эффектов.

    Функция сообщает, что точки использовались для расчета элементарных эффектов в ParameterSamples свойство возвращенного объекта результатов. Каждый блок k+1 строки в таблице ParameterSamples соответствует k+1 радиальным или цепочечным точкам, использовался для расчета элементарных эффектов. SimulationInfo.SimData свойство объекта результатов содержит соответствующие симуляции модели. Функциональные выборки точки от сетки параметра заданы 'GridLevel' и 'GridDelta'. Следующая фигура иллюстрирует простой случай с двумя входными параметрами чувствительности (y1 и y2) с 'NumberSamples' = 2 использования chain 'PointSelection' метод.

    Two chains of points on a grid, with associated elementary effects shown.

    Ссылки

    [1] Моррис, Макс Д. “Планы Выборки факториала относительно Предварительных Вычислительных Экспериментов”. Технометрики 33, № 2 (май 1991): 161–74.

    [2] Sohier, Анри, Жан-Лу Фарг и Хелене Пит-Ланир. “Улучшение Представительности Метода Морриса для Воздушного Запуска, чтобы вращаться вокруг Разделения”. Объемы Продолжений IFAC 47, № 3 (2014): 7954–59.

    Введенный в R2021b
    Для просмотра документации необходимо авторизоваться на сайте