matlab-fit-simbiology-model

SimBiology モデルのフィッティング

fitproblem を使用してデータからパラメーターを推定し、NLME で母集団モデルをフィッティングし、 バーチャル患者を生成して、NCA 指標を計算します。

使用する場合

• モデルパラメーターを「フィッティング」「推定」「キャリブレーション」する場合
• 実験データ／観測データからパラメーターを推定する場合
• 母集団 PK/PD、NLME、混合効果、個体間変動
• バーチャル患者、バーチャルコホート
• NCA、AUC、Cmax、Tmax、半減期、クリアランス
• キーワード：「fit」「estimate」「calibrate」「population」「NCA」「AUC」

使用しない場合

• モデルの構築や図の作成（matlab-build-simbiology-model を使用）
• フィッティングを行わないシミュレーション（matlab-simulate-simbiology-model を使用）
• 感度解析（matlab-simulate-simbiology-model を使用）

必ず守るルール

1. パラメーター推定には fitproblem を使用する

sbiofit または sbiofitmixed を直接呼び出すのではなく、必ず fitproblem を使用してください。fitproblem は統一された宣言型インターフェースを提供します。

prob = fitproblem;
prob.Model = model;
prob.Data = data;
prob.ResponseMap = "Species = DataColumn";
prob.Estimated = estimatedInfo({'param'}, 'Bounds', [lo hi]);
results = fit(prob);

sbiofit(model, data, ...) や sbiofitmixed(model, data, ...) を直接呼び出さないでください。これらは位置引数のシグネチャでエラーが起きやすくなっています。

2. フィッティングには単なるテーブルではなく groupedData が必要

データは必ずラップしてください。

data = groupedData(table(...));
data.Properties.IndependentVariableName = 'Time';

3. ResponseMap はモデル出力とデータ列を対応付ける

形式は常に "ModelOutput = DataColumnName" です。

% Single compartment — use species name on the left
prob.ResponseMap = "Drug = DrugConc";

% Multi-compartment — use qualified name to disambiguate
prob.ResponseMap = "Central.Drug = DrugConc";

% When species name matches data column name, still use the = format
prob.ResponseMap = "Drug = Drug";

同じ区画内に同名の種が複数存在しない場合は、修飾なしの種名を使用してください（存在する場合は Compartment.Species で修飾します）。

4. 必ず境界値を設定する

非物理的な値（負の速度など）を防ぎます。

estimParams = estimatedInfo({'ke','ka'}, ...
    'InitialValue', [0.2, 1.0], ...
    'Bounds', [0.01 1; 0.1 5]);

5. 速度定数には対数変換を使用する

桁違いに値が変動するパラメーター（クリアランス、速度定数など）には、対数変換による推定が有効です。作成後に .Transform を設定してください。

ei = estimatedInfo({'ke','ka'}, 'InitialValue', [0.1, 0.5], 'Bounds', [0.01 1; 0.1 5]);
ei(1).Transform = 'log';
ei(2).Transform = 'log';

別の方法として、'log(param)' という名前の構文も使用できます（結果は同等です）。

ei = estimatedInfo({'log(ke)','log(ka)'}, 'InitialValue', [0.1, 0.5], 'Bounds', [0.01 1; 0.1 5]);

重要： InitialValue と Bounds は常に変換前（自然な値の範囲）で指定します。log(value) を渡さないでください。

使用できる変換：'log'、'logit'、'probit'

estimatedInfo コンストラクターに名前と値のペアとして 'Transform' を渡さないでください。エラーになります。必ず後から .Transform プロパティを設定してください。

6. 母集団フィッティングの誤差モデル

ノイズ構造に合った誤差モデルを選択してください。

• 'constant' — 一定の絶対ノイズ
• 'proportional' — ノイズが大きさに応じて変化（多くの PK データで使用）
• 'combined' — 一定ノイズと比例ノイズの両方
• 'exponential' — 対数正規残差

7. NCA には sbioncaoptions オブジェクトが必要

名前と値のペアは使用しないでください。列名にはキャメルケースを使用します。 EVDose 列では、投与量のない行に NaN を使用します。

判断表

シナリオ	方法
単一被験者または統合フィッティング	FitFunction="sbiofit" を指定した fitproblem
被験者ごとの個別フィッティング	Pooled=false を指定した fitproblem
母集団 NLME（IIV、ランダム効果）	FitFunction="sbiofitmixed" を指定した fitproblem
モデルに依存しない PK 指標	sbionca

fitproblem のワークフロー（推奨）

すべてのパラメーター推定に fitproblem を使用してください。sbiofit／sbiofitmixed の直接呼び出しに代わる、統一された宣言型インターフェースを提供します。

% 1. Prepare data
data = groupedData(table(tSample, yData, 'VariableNames', {'Time','Drug'}));
data.Properties.IndependentVariableName = 'Time';

% 2. Define parameters with bounds
estimParams = estimatedInfo({'ke','ka'}, ...
    'InitialValue', [0.2, 1.0], ...
    'Bounds', [0.01 1; 0.1 5]);

% 3. Build the fit problem
prob = fitproblem;
prob.Model = model;
prob.Data = data;
prob.ResponseMap = "Drug = Drug";
prob.Estimated = estimParams;
prob.Doses = dose;                  % optional
prob.FunctionName = 'scattersearch';
prob.ProgressPlot = true;           % show live progress

% 4. Fit
results = fit(prob);

% 5. Inspect
disp(results.ParameterEstimates);
plot(results);

fitproblemの主なプロパティ

プロパティ	目的
Model	SimBiologyモデルオブジェクト
Data	groupedDataテーブル
Estimated	estimatedInfoオブジェクト（EstimatedParametersではありません）
ResponseMap	モデルの種をデータ列に対応付けます
Doses	用量オブジェクト（複数可）（Doseではありません）
FitFunction	"sbiofit"（デフォルト）または"sbiofitmixed"
FunctionName	アルゴリズム：'scattersearch'、'nlinfit'、'fminsearch'、'lsqnonlin'、'particleswarm'
ProgressPlot	フィッティングの進行状況をリアルタイムで表示する場合はtrue
UseParallel	並列評価を行う場合はtrue
Pooled	true／false／"auto"（sbiofitのみ）
ErrorModel	"constant"、"proportional"、"combined"、"exponential"
Variants	フィッティング中に適用するバリアント

よくあるプロパティ名の間違い： prob.Estimated（EstimatedParametersではありません）、 prob.Doses（Doseではありません）、prob.FunctionName（AlgorithmやMethodではありません）。

推定アルゴリズム

メソッド	使用例
'scattersearch'	組み込みのグローバル探索。追加のツールボックスは不要です — まずはこちらをお試しください
'nlinfit'	デフォルトの局所探索。滑らかな問題に適しています
'lsqnonlin'	境界付き最小二乗法（Optimization Toolbox）
'fminsearch'	導関数不要。単純な問題に適しています
'particleswarm'	グローバル探索（Global Optimization Toolbox）

複数被験者データからの投与

被験者ごとに異なる用量を投与する場合は、createDosesを使用してデータから被験者ごとの用量オブジェクトを抽出します。用量列では、投与しない行をNaNにする必要があります。

% Data format: dose amount only at administration time, NaN elsewhere
%   ID  Time  Dose  DrugConc  Group
%   1   0     50    0         LowDose
%   1   1     NaN   2.05      LowDose
%   ...
%   3   0     200   0         HighDose

% Create template dose targeting the depot species
tempDose = sbiodose('StudyDose');
tempDose.TargetName = 'Depot.Drug';   % match your model's dose target

% Extract per-subject doses from groupedData
doseArray = createDoses(gData, 'Dose', '', tempDose);

% Pass to fitproblem
prob.Doses = doseArray;

重要： 投与時点だけでなく、すべての行に用量値がある場合、createDosesはすべての行を投与イベントとして扱います。投与しない行にはNaNを使用してください。

母集団フィッティング（プールまたは個別）

data.Properties.GroupVariableName = 'SubjectID';

% Pooled — one parameter set for all
prob.Pooled = true;

% Individual — separate per subject
prob.Pooled = false;

カテゴリベースのプーリング（グループごとの推定値）

カテゴリごと（例：用量グループ）にパラメーターを個別に推定するには、fitproblemやsbiofitではなく、estimatedInfoオブジェクトでCategoryVariableNameを使用します。

estimParams = estimatedInfo({'ke'}, 'InitialValue', 0.1, 'Bounds', [0.01 1]);
estimParams.CategoryVariableName = 'DoseGroup';  % column in data table
% Do NOT set prob.Pooled — leave it at the default

警告： CategoryVariableNameを使用する場合は、prob.Pooledを設定しないでください。Pooled=falseを設定すると、被験者ごとの個別フィッティングが実行され、CategoryVariableNameは無視されます（MATLABから警告が表示されます）。カテゴリベースのプーリングが正しく機能するよう、Pooledは未設定のままにしてください。

NLME母集団フィッティング

個体間変動とランダム効果を推定するには、FitFunctionを"sbiofitmixed"に設定します。

% 1. Load & tag grouped data
data = groupedData(readtable('pop_pk_data.csv'));
data.Properties.IndependentVariableName = 'Time';
data.Properties.GroupVariableName = 'SubjectID';

% 2. Define parameters (Bounds ignored by sbiofitmixed — use InitialValue only)
estimParams = estimatedInfo({'CL','Vd','ka'}, ...
    'InitialValue', [5, 50, 1.2]);

% 3. Build the fit problem
prob = fitproblem;
prob.Model = model;
prob.Data = data;
prob.ResponseMap = "DrugConc = Concentration";
prob.Estimated = estimParams;
prob.FitFunction = "sbiofitmixed";
prob.ErrorModel = "proportional";
prob.ProgressPlot = true;

% 4. Fit
results = fit(prob);

% 5. Inspect
results.FixedEffects
results.RandomEffectCovarianceMatrix
results.IndividualParameterEstimates

NLMEとsbiofitの使い分け

基準	FitFunction="sbiofit"	FitFunction="sbiofitmixed"
被験者が1人	はい
複数の被験者、IIVなし	はい（プール）
個体間変動		はい
ランダム効果の推定		はい
共変量モデリング		はい
小規模なデータセット（被験者5人未満）	はい	収束しない場合があります
パラメーターの境界	はい（適用されます）	無視されます — 代わりに適切なInitialValueを使用してください

共変量を含むNLME（CovariateModel）

共変量（例：体重、年齢）がパラメーターに影響する場合は、estimatedInfoの代わりにCovariateModelを使用します。

covModel = CovariateModel;
covModel.Expression = {
    'CL = theta1 + theta2*WT + eta1'
    'Vd = theta3 + theta4*WT + eta2'
    'ka = theta5 + eta3'
};
initVals = covModel.constructDefaultFixedEffectValues;
initVals.theta1 = 5; initVals.theta2 = 0.1;
initVals.theta3 = 50; initVals.theta4 = 0.5;
initVals.theta5 = 1.2;
covModel.FixedEffectValues = initVals;

prob = fitproblem;
prob.Model = model;
prob.Data = data;  % groupedData with WT column
prob.ResponseMap = "DrugConc = Concentration";
prob.FitFunction = "sbiofitmixed";
prob.Estimated = covModel;
prob.ErrorModel = "proportional";
results = fit(prob);

使い分け：

• estimatedInfo — 共変量を含まないNLME（よりシンプルで、パラメーター数が少ない）
• CovariateModel — 共変量を含むNLME（パラメーターと共変量の関係）

式のルール： 固定効果にはthetaプレフィックス、ランダム効果にはetaを使用します。1つの式で使用できるランダム効果は最大1つです。フィッティング前にverify(covModel)を使用して構文を検証してください。

仮想患者の生成

仮定した分布から生成する（Scenarios）

makedistとともにSimBiology.Scenariosを使用します — 行列を手動で構築する必要がありません。

sc = SimBiology.Scenarios;
add(sc, 'elementwise', 'ke', makedist('Lognormal', 'mu', log(0.1), 'sigma', 0.3), 'Number', 100);
add(sc, 'elementwise', 'ka', makedist('Lognormal', 'mu', log(0.5), 'sigma', 0.25), 'Number', 100);

simfun = createSimFunction(model, sc, {'Drug'}, []);
results = simfun(sc, 24);

NLMEの結果から生成する（sbiosampleparameters）

sbiosampleparametersを使用して、フィッティング済みの母集団パラメーターからサンプリングします — 共変量モデルのパラメーター化が自動的に反映されます。

% Extract from NLME results
covModel = covariateModel(nlmeResults);
thetas = nlmeResults.FixedEffects;
omega = nlmeResults.RandomEffectCovarianceMatrix;

% Sample 200 virtual patients
nVP = 200;
vpParams = sbiosampleparameters(covModel.Expression, thetas, omega, nVP);

% Simulate
simfun = createSimFunction(model, {'CL','Vd','ka'}, {'Cp'}, []);
vpSim = simfun(vpParams, 48);

非コンパートメント解析（NCA）

シミュレーション出力から解析する

NCAで十分な時間分解能を確保するため、明示的なOutputTimesを使用します（デフォルトのソルバー出力では、Cmax付近の点が少なすぎる場合があります）。

cs = getconfigset(m, 'active');
cs.SolverOptions.OutputTimes = linspace(0, 24, 200);

[t, x, names] = sbiosimulate(m);
drugIdx = find(strcmp(names, 'Drug'));
Vd = sbioselect(m, 'Type', 'parameter', 'Name', 'Vd');
conc = x(:, drugIdx) ./ Vd.Value;
evDose = NaN(size(t)); evDose(1) = 100;
data = table(t, conc, evDose, 'VariableNames', {'Time','Concentration','EVDose'});

opt = sbioncaoptions;
opt.concentrationColumnName = 'Concentration';
opt.timeColumnName = 'Time';
opt.EVDoseColumnName = 'EVDose';
opt.AdministrationRoute = 'ExtraVascular';
ncaResults = sbionca(data, opt);

投与経路

経路	用量列	追加設定
'ExtraVascular'	opt.EVDoseColumnName	—
'IVBolus'	opt.IVDoseColumnName	—
'IVInfusion'	opt.IVDoseColumnName	opt.infusionRateColumnName

主な NCA 指標

すべての指標名にはアンダースコアを使用します（例：Cmax ではなく C_max）。

指標	説明
AUC_0_last	曲線下面積（0 から最終時点まで）
AUC_infinity	無限大まで外挿した AUC
C_max	観測された最大濃度
T_max	Cmax の時刻
T_half	終末相の消失半減期
CL	クリアランス（用量 / AUC）
V_z	分布容積（終末相）
MRT	平均滞留時間

複数被験者の NCA

data.Properties.GroupVariableName = 'SubjectID';
opt.groupColumnName = 'SubjectID';
ncaResults = sbionca(data, opt);

信頼区間とプロファイル尤度

制限事項： sbioparameterci は、非線形回帰（sbiofit）の結果に対してのみ動作します。NLME の結果（sbiofitmixed）には対応していません。

sbiofit によるフィッティング後に、信頼区間を計算します。

ガウス（漸近）CI — 高速、デフォルト

ciResults = sbioparameterci(fitResults);
disp(ciResults.Results);  % table: Name (cell), Estimate, Bounds, ConfidenceInterval (Nx2 double), Status (categorical)
plot(ciResults);

.Results テーブルの列の型：

• Name — char のセル配列（Results.Name{i}）
• ConfidenceInterval — Nx2 の double 行列（Results.ConfidenceInterval(i,:)）
• Status — categorical（Results.Status(i)、{i} ではありません）

プロファイル尤度 CI — 非線形モデルでより高精度

ciPL = sbioparameterci(fitResults, 'Type', 'ProfileLikelihood');
plot(ciPL);  % shows profile likelihood curves with CI bounds
% Custom confidence level: 'Alpha', 0.10 for 90% CI

種類	速度	使用する状況
'Gaussian'（デフォルト）	高速	簡易確認、問題の挙動が良好な場合
'ProfileLikelihood'	低速	最終結果、パラメーターの識別可能性

規則

• 種名はコンパートメント名と異なる必要があります。 異なる名前を使用してください。例：コンパートメントに Depot、種に DrugDepot を指定します（コンパートメント Depot 内の種に Depot を指定するのではありません）。
• コンパートメントの体積の単位： コンパートメントの体積には常に単位を指定してください（例：'liter'）。DimensionalAnalysis = true と groupedData の VariableUnits を設定します。純粋な量ベースのモデルでは、Value = 1 を設定し、単位は省略します。
• .sbproj の読み込み： proj = sbioloadproject('f.sbproj'); model = proj.(fieldnames(proj){1});
• データの抽出： 特定の変数には selectbyname(sbiosimulate(m), 'Drug')、特定の時刻には resample(sd, tSample, 'linear') を使用します。
• パラメーターの探索空間が不明な場合は、'scattersearch' から始めます。
• 桁違いの範囲にわたるパラメーターには 'log' 変換を使用します（ルール 5 を参照）。
• フィッティングの前に sbioaccelerate(model) を呼び出さないでください。効果がなく、時間を浪費します。
• cs.MaximumWallClock = 60 を設定すると、不適切な初期値によるシミュレーションのハングを停止できます。
• 実行時間の長いフィッティングでは、prob.ProgressPlot = true を設定します。

フィッティング品質の評価

plot(results);                      % observed vs predicted overlay
plotResiduals(results);             % residuals vs time
plotResidualDistribution(results);  % histogram — should be ~normal
plotActualVersusPredicted(results); % identity line check

results.LogLikelihood  % higher = better
results.AIC            % lower = better (penalizes complexity)
results.BIC            % lower = better (stronger penalty)
results.MSE            % mean squared error

モデル比較： BIC で比較します。deltaBIC < -10 は複雑なモデルを強く支持し、deltaBIC > 0 はより単純なモデルが望ましいことを示します。

NLME に移行するタイミング： 複数の被験者でパラメーター値が異なる場合、被験者固有の残差パターンが系統的に見られる場合、個体間変動の定量化が必要な場合、または共変量で差異を説明できる可能性がある場合です。

• フィッティング関数には UUID 文字列ではなく、モデルオブジェクトを渡します。
• sbiofit／sbiofitmixed／sbionlmefit を直接呼び出さないでください。fitproblem を使用します。

参考資料

詳細なガイダンスは必要に応じて読み込んでください。

• references/nca-analysis-guidance.md — NCA のパターン、IV 点滴、指標の解釈に関する詳細

---

Copyright 2026 The MathWorks, Inc.

---