Communitygithub.com

pkpd-modeling

藥物動力學與藥效學建模與模擬:非房室分析、房室模型與群體 PK、PK/PD 與暴露-反應、TMDD、PBPK 導向、生體相等性、異速增長與首次人體劑量、藥物交互作用預測及貝氏治療藥物監測。用於分析濃度-時間數據、推導暴露指標、擬合 PK 或 PD 模型,或評估給藥方案。

pkpd-modeling 是什麼?

此技能是一套全面的藥物動力學與藥效學 (PK/PD) 建模與模擬命令列工具組,專為支援藥物開發與臨床藥理學工作流程而設計。它涵蓋從非房室分析 (NCA) 和房室模型擬合,到群體 PK 資料集檢查、暴露-反應分析、生體相等性、異速增長與首次人體劑量計算、藥物交互作用預測以及貝氏治療藥物監測等功能。每個腳本都會在結果旁醒目地呈現診斷性發現(例如:擬合參數的可識別性不佳、外插比例過高),幫助使用者避免數據解讀中的常見陷阱。所有腳本都支援結構化輸出格式 (table/tsv/json),可無縫整合到自動化工作流程中。此工具集設計為一種計算與診斷輔助工具,最終的監管或臨床決策仍應由合格專家做出。支援的語言是 Python,透過命令列介面操作,並設計為非互動式腳本以確保可重複性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/pkpd-modeling

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

藥物動力學與藥效學建模

使用時機

任何關於身體對藥物作用或藥物對身體作用的問題:從濃度-時間數據推導暴露指標、擬合結構模型、建立或檢查群體分析、選擇劑量或給藥方案、將暴露與效應關聯起來、比較配方,或擴展至新的族群。

三條規則

1. 在計算任何數據之前,先確定暴露指標和分析族群。 AUC(0-t)、AUC(0-inf)、穩態 AUC(0-tau) 和 Cavg 是不同量值,回答不同問題。基於觀察值與預測值 Clast 計算的 AUCinf 也是如此。在得出數字後才做選擇,就是讓陰性研究變成陽性結果的方式。

2. 結構模型、變異性模型和共變量模型是三個獨立的決定。 它們經常被混為一談——增加一個額外的房室來吸收實際上未建模的訪視間變異性,或增加一個共變量來修復實際上錯誤的吸收模型。在改變任何一個模型之前,先診斷哪一個是錯誤的。

3. 收斂不等於可識別性。 一個擬合收斂了,但參數的相對標準誤差達到 200%,或兩個參數之間的相關性為 0.99,這告訴你數據無法區分它們。這裡的每個擬合腳本都會報告這兩者並標記它們,因為單看參數表在這種情況下看起來是正常的。

範圍

此技能負責計算、診斷和結構化。它不決定一個配方是否具有生體相等性、為試驗選擇劑量、為病患推薦劑量、斷定藥物無 QT 風險,或取代合格的藥物計量學家、臨床藥理學家或法規審查。腳本負責報告;沒有一個腳本做出結論。特別是 tdm_bayes.py 是一個建模輔助工具——對患者方案的任何更改都是主治醫師的決定。

腳本

cd skills/pkpd-modeling/scripts
腳本回答的問題
nca.py暴露指標是什麼,且終末相是否足夠好以報告它們?
fit_compartmental.py這些資料支持哪個結構模型,且其參數是否可識別?
simulate_regimen.py這個方案在穩態時會如何,以及對族群的何種比例?
check_popk_dataset.pyNONMEM 會按照我預期的方式讀取這個資料集嗎?
exposure_response.py是否存在暴露-反應關係,且資料中是否已達平台期?
bioequivalence.py90% 信賴區間是否符合標準,以及適用哪個標準?
allometry_and_fih.py起始劑量是多少,或者在較小/較年輕族群中的劑量?
ddi_static.py體外數據是否觸發了 ICH M12 下的臨床 DDI 研究?
tdm_bayes.py根據測量到的濃度,這位患者的個體參數為何?

所有腳本都接受 --format table|tsv|json。數據輸出到 stdout,來源與發現輸出到 stderr,因此 > out.tsv 可以將其分開。退出碼為 0 表示無發現,1 表示發現了問題,2 表示輸入錯誤,因此任何腳本都可以用於控制工作流程。

兩個私有模組承載共享機制:_models.py(線性乳突模型的解析解,加上整合的 Michaelis-Menten、TMDD 和間接反應結構)和 _common.py(I/O 和報告)。應匯入它們,而不是重新推導 Bateman 函數。

工作流程

1. 非房室分析

python3 nca.py -i profile.csv --dose 100 --route extravascular --partial-auc 0-24

四個選擇決定了答案,且通常被隱含地處理。此腳本使所有四個選擇明確化:--auc-method(預設 linup-logdown)、--blq-rule、--lambda-z-points 或明確的 --lambda-z-window,以及你報告的是 auc_inf_obs 還是 auc_inf_pred。

Lambda_z 選擇使用標準規則:從最後三個可量化點開始,向後延伸,僅當調整後的 r-squared 改善超過 0.0001 時,才保留較長的視窗。單純的 r-squared 在添加點時只會上升,因此它總是會選擇最長的視窗。Tmax 及之前的點永遠不符合資格——包括 Tmax 會擬合吸收的尾部,從而使半衰期、Vz 和 AUCinf 偏小。

在一個無噪音的、模擬的一房室口服曲線上,CL/F = 5, V/F = 20, ka = 1.2:

id  cmax     tmax  auc_last  lambda_z  t_half   r2_adj  auc_inf_obs  pct_auc_extrap  cl_f     vz_f
1   3.29678  1.5   19.8737   0.25      2.77259  1       19.8739      0.000781037     5.03173  20.1269

CL/F 被高估 0.6% 是梯形法則在稀疏取樣的吸收相上造成的,這不是一個錯誤——在該取樣時間表上 NCA 的固有偏差,也是 NCA 和房室模型清除率估計從不完全一致的原因。

發現是重點。一個在 tau 處截斷的穩態曲線會產生:

finding: subject A: 25.2% of AUCinf is extrapolated (above 20%); AUCinf is driven by the
         lambda_z fit, not by data
finding: subject A: lambda_z window spans 0.58 half-lives (below 2.0); the terminal phase may
         not have been reached

兩者都是正確的,而且兩者都被常規忽略。在穩態下,可報告的暴露指標是 AUC(0-tau),而不是 AUCinf;腳本仍然計算 AUCinf 並告訴你不要相信它。

2. 房室模型擬合與模型選擇

python3 fit_compartmental.py -i profile.csv --dose 500 --route iv-bolus --compare 1cmt,2cmt,3cmt

參數在對數尺度上估計,因此它們不能為負,並且它們的信賴區間是不對稱的。加權預設為 1/y2(恆定 CV),這是 PK 的正確預設值,但對於同方差性的 PD 終點則是錯誤的。

擬合模擬的兩房室數據(CL 4, V1 12, Q 6, V2 40, 8% 比例誤差):

model  parameters  wssr       aic       bic       f_vs_simpler  f_p_value    compared_with
1cmt   2           3.13201    -19.4956  -18.0795  n/a           n/a          n/a
2cmt   4           0.0309579  -84.7477  -81.9155  550.936       9.38016e-12  1cmt
3cmt   6           0.0232859  -85.0193  -80.771   1.4826        0.27762      2cmt

AIC 選擇三房室模型。BIC 和 F 檢定都拒絕它。 AIC 每個參數固定的 2 點懲罰在此樣本量下較弱,並且它選擇過度參數化模型的頻率比從業者預期的更高。參數表說明了問題:

finding: fit: Q3 has 98% RSE - not estimable from these data at this model size
finding: fit: V3 has 71% RSE - not estimable from these data at this model size

與此同時,一房室擬合出現了:

finding: fit: residual signs are not random (runs test p = 0.0036) - a structural
         misspecification, which no amount of reweighting will fix

這個區別——結構性錯誤指定與錯誤的誤差模型——是需要正確掌握的重點。一個殘差-時間圖中出現相同符號的連續序列意味著模型形狀是錯的。具有隨機符號的異方差殘差意味著加權是錯的。對第一種情況重新加權只會隱藏它,而不會修復它。

3. 群體 PK

在執行任何操作之前先檢查資料集。這才是實際花時間的地方。

python3 check_popk_dataset.py -i nmdata.csv --covariates WT,CRCL --time-varying WT

重要的缺陷是那些靜默的。NM-TRAN 不會拒絕非數值的 DV——它將 BLQ 讀取為零,並將其擬合為一個真實的零濃度。空白共變量變成 0,因此缺失的體重變成了一個 0 公斤的患者。沒有 II 的 ADDL 不會放置額外的劑量。共享時間戳的記錄按檔案順序應用,因此一個濃度是給藥前還是給藥後取決於哪一行在前。這些都不會終止一次執行。

severity  check                            detail
error     non-numeric DV                   DV contains text... NM-TRAN reads them as 0
error     subject with no dose             1 subject(s) have observations but no dose: 2
error     TIME not sorted                  1 subject(s) have out-of-order TIME: 1
error     covariate WT missing             1 record(s) have no value...
warning   duplicate TIME within a subject  NONMEM applies them in file order...

至於估計本身,此技能不重新實現 NLME——請參閱 references/population-pk.md 了解估計方法、BLQ M1-M7 方法、共變量模型構建以及決定模型是否可接受的診斷方法,以及 references/software-ecosystem.md 了解應使用哪種工具。

4. 模擬與方案選擇

python3 simulate_regimen.py --cl 5 --v 40 --dose 500 --interval 12 --n-doses 10 --steady-state
python3 simulate_regimen.py --cl 5 --v 40 --dose 500 --interval 12 --n-doses 10 \
    --simulate 2000 --omega-cl 0.35 --omega-v 0.25 --target-trough 4.0

確定性模擬回答了“典型患者看起來像什麼”,這幾乎從來都不是問題所在:

metric             p5        p25      median   p75      p95      geo_mean
peak               11.861    14.6018  16.6702  19.1476  22.9339  16.6453
trough             0.863226  2.15191  3.64412  5.49655  9.21053  3.27035

target       fraction_attaining
trough >= 4  0.444

典型的谷濃度是 3.6,目標是 4,因此44% 的族群達到目標。基於典型患者調整的方案使大約一半的族群處於目標的錯誤一側。此處報告的達成率仍然樂觀:這僅是個體間變異性,沒有殘餘或訪視間成分。

線性模型是解析求解並疊加的,這是精確的。--nonlinear 切換到整合的 Michaelis-Menten 消除,在這種情況下疊加無效,並且多次給藥行為完全無法從單次給藥推斷出來。

5. 暴露-反應

python3 exposure_response.py --emax -i er.csv --sigmoid
python3 exposure_response.py --cqtc -i qt.csv --cmax 250

Emax 擬合報告 fraction_of_emax_reached,並標記出平台期在數據範圍之外的擬合。當觀察到的最高暴露僅達到估計 Emax 的三分之一時,Emax 和 EC50 是相互強烈相關的外推值;將它們作為獨立估計值引用是不可支持的,並且“線性”暴露-反應僅僅是同一曲線的低濃度端。

--cqtc 評估預測的安慰劑校正後基線 QTc 變化的雙側 90% 信賴區間的上限與 10 毫秒閾值的比較,這正是 ICH E14 實際提出的問題。點估計或 95% 區間回答的是不同的問題。捆綁的模型是用於篩選的普通線性回歸;提交級別的 C-QTc 分析需要一個帶有隨機截距和每個受試者斜率的混合模型。

每種模式都帶有相同的警告,因為這是常被忘記的一點:患者被隨機分配到劑量組,而不是暴露組。即使在隨機試驗內部,跨分位數的暴露-反應也是觀察性的,並且可以反映驅動清除率的共變量。

6. 生體相等性

python3 bioequivalence.py -i be.csv --design 2x2 --metric AUC
python3 bioequivalence.py -i be.csv --design replicate --metric Cmax --scaling both
python3 bioequivalence.py --power --cv 0.30 --gmr 0.95 --target-power 0.80

三個標準共用“生體相等性”這個詞,且不可互換:平均 BE(90% CI 落在 80.00-125.00% 內)、EMA 的 ABEL(限值作為 CVwR 的函數而放寬,上限為 69.84-143.19%,點估計仍在 80-125% 內)以及 FDA 的 RSABE(通過 Hyslop 方法的標度線性化邊界,根本不是一個區間)。--scaling 拒絕在 2x2 設計上執行:

error: reference-scaling requires --design replicate. High observed variability in a 2x2 study
does not license widening: without replicated reference administrations there is no estimate of
within-subject reference variability to scale to.

樣本量完全複現了已發表的表格(CV 30%, GMR 0.95, 80% power → N = 40 for a 2x2)。功效是通過對估計標準差的抽樣分佈進行積分來計算的,而不是將標準誤視為已知——在實際樣本量下,正態近似會高估功效。請注意,N 受假設的 GMR 影響遠大於 CV;假設 1.00 而不是 0.95 會使計算出的 N 大致減半,這通常是 BE 研究效能不足的常見原因。

7. 異速增長、兒科與首次人體劑量

python3 allometry_and_fih.py --scale --cl 5 --weight-from 70 --weight-to 6 --pma-weeks 44
python3 allometry_and_fih.py --fih --noael rat=50,dog=10 --safety-factor 10

在大約 2 歲以下僅按體型進行縮放會高估清除率,在新生兒中可能高出數倍,因為清除率受酶和腎臟成熟度的限制,而不是受體型的限制。提供 --pma-weeks 會添加 Anderson-Holford S 形成熟項;在 20 公斤以下省略它會引發一個發現。

parameter  reference  exponent  size_scaled  maturation_factor  final
CL         5          0.75      0.792063     0.30634            0.242641
V          40         1         3.42857      1                  3.42857

僅按體型會預測 0.79 L/h;在 44 週胎齡時考慮成熟度後為 0.24 L/h,相差 3.3 倍。體積沒有成熟度——成熟度描述的是消除能力,而不是分佈空間。

--fih 使用 FDA 2005 年最大安全起始劑量指南中的體表面積換算,並總是發出一個發現,即基於 NOAEL 的 MRSD 本身對於激動劑免疫調節劑是不夠的:應使用 --mabel 計算 MABEL 並取較低值。

8. 藥物交互作用

python3 ddi_static.py --basic --ki 0.5 --imax 2.0 --fu 0.05 --dose 0.4
python3 ddi_static.py --msm --ki 0.5 --imax 2.0 --fu 0.05 --dose 0.4 --fm 0.9 --fg 0.7

ICH M12 基本模型及其閾值(R1 ≥ 1.02 肝臟,≥ 11 腸道… [譯文截斷]

[原始內容被截斷]

9. 治療藥物監測

python3 tdm_bayes.py --prior ka=1.2,cl=5,v=20 --omega ka=0.5,cl=0.35,v=0.25 \
    --sigma-prop 0.15 --dose 500 --interval 12 \
    --levels time=2,conc=11.2 time=6,conc=8.5 time=12,conc=4.1

貝氏回歸使用先驗分佈和觀察到的濃度來得出個體參數估計。當濃度數量少於參數數量時(這是 TDM 的常見情況),此方法是必需的。此腳本回報個體參數、個體預測的濃度-時間曲線以及一些適用性診斷指標。

parameter  prior_median  prior_cv  posterior_median  posterior_cv
ka         1.2           0.5       1.35              0.32
cl         5             0.35      4.2               0.15
v          20            0.25      22.1              0.18

結果是後驗參數分佈,可用於模擬替代給藥方案下的濃度。同樣,對患者方案的任何更改都是主治醫師的決定。

參考文獻

請參閱 references/ 目錄中的文件以獲取關於以下主題的詳細資訊:

  • population-pk.md:群體 PK 方法、BLQ 處理、共變量建模和診斷。
  • software-ecosystem.md:用於 NLME 估計、模擬和數據管理的各種軟體工具及其適用場景。
  • regulatory-guidance.md:相關的 ICH、EMA 和 FDA 指南。

貢獻

歡迎貢獻!請遵循以下指南:

  • 所有新腳本都應遵循現有的 --format 和錯誤報告約定。
  • 新功能應附帶測試。
  • 所有文件都應保持技術準確性。

許可證

此專案採用 MIT 許可證。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

adaptyv

How to use the Adaptyv Bio Foundry API and Python SDK for protein experiment design, submission, and results retrieval. Use this skill whenever the user mentions Adaptyv, Foundry API, protein binding assays, protein screening experiments, BLI/SPR assays, thermostability assays, or wants to submit protein sequences for experimental characterization. Also trigger when code imports `adaptyv`, `adaptyv_sdk`, or `FoundryClient`, or references `foundry-api-public.adaptyvbio.com`.

aeon

This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search. Use when working with temporal data, sequential patterns, or time-indexed observations requiring specialized algorithms beyond standard ML approaches. Particularly suited for univariate and multivariate time series analysis with scikit-learn compatible APIs.

alphagenome

Look up precomputed AlphaGenome Atlas effects for any GRCh38 single-nucleotide variant (AVI score with Phred and 18 SHAP feature attributions, plus raw and quantile scores for RNA-seq, DNase, ATAC, ChIP-TF, ChIP-histone, CAGE, PRO-cap, splicing, polyadenylation and contact-map tracks), score variants or scan windows on demand with the AlphaGenome model for human and mouse (variant scoring, in silico mutagenesis, REF-versus-ALT track prediction), and build Atlas website deep links. Use when the user mentions AlphaGenome, AlphaGenome Atlas, AVI or AlphaGenome Variant Impact, DeepMind variant effect prediction, or wants to prioritise or mechanistically interpret non-coding, regulatory, splicing, enhancer, promoter, or chromatin-accessibility effects of SNVs from a VCF, credible set, or region. Research use only; not a clinical tool.

analytical-method-validation

Plan, execute, and document validation, verification, and transfer of analytical procedures under the governing framework - ICH Q2(R2) and Q14, USP <1220>/<1225>/<1226>, ICH M10 bioanalytical, CLSI EP, or ISO/IEC 17025. Use for HPLC, LC-MS/MS, GC, CE, ICP-MS, dissolution, qNMR, qPCR, NIR, and ligand binding or cell-based assays whenever the question is whether a procedure is fit for its intended purpose. Triggers include

anndata

Data structure for annotated matrices in single-cell analysis. Use when working with .h5ad files or integrating with the scverse ecosystem. This is the data format skill—for analysis workflows use scanpy; for probabilistic models use scvi-tools; for population-scale queries use cellxgene-census.

arbor

Autonomously improve a real artifact (code, training recipe, agent harness, data pipeline, prompt) against an objective and an evaluator, using Hypothesis Tree Refinement (HTR) from the Arbor paper. Use this whenever someone wants to iteratively optimize something over many experiments without overfitting — e.g.

arboreto

Infer gene regulatory networks (GRNs) from gene expression data using scalable algorithms (GRNBoost2, GENIE3). Use when analyzing transcriptomics data (bulk RNA-seq, single-cell RNA-seq) to identify transcription factor-target gene relationships and regulatory interactions. Supports distributed computation for large-scale datasets.

astropy

Core Python library for astronomy and astrophysics workflows that need Astropy APIs, including units/quantities, coordinates, FITS I/O, tables, time systems, WCS, and cosmology. Use when implementing or debugging astronomical data analysis code with Astropy.

autoskill

Observe the user

benchling-integration

Benchling Python SDK and REST API integration for registry entities, inventory, ELN entries, workflows, Benchling Apps, and Data Warehouse queries. Use when automating lab data with benchling-sdk or the v2 API.

bgpt-paper-search

Search scientific papers and retrieve structured experimental data extracted from full-text studies via the BGPT MCP server. Returns 25+ fields per paper including methods, results, sample sizes, quality scores, and conclusions. Use for literature reviews, evidence synthesis, and finding experimental details not available in abstracts alone.

bids

>

biopython

Comprehensive molecular biology toolkit. Use for sequence manipulation, file parsing (FASTA/GenBank/PDB), phylogenetics, and programmatic NCBI/PubMed access (Bio.Entrez). Best for batch processing, custom bioinformatics pipelines, BLAST automation. For quick lookups use gget; for multi-service integration use bioservices.

bioservices

Unified Python interface to 40+ bioinformatics services. Use when querying multiple databases (UniProt, KEGG, ChEMBL, Reactome) in a single workflow with consistent API. Best for cross-database analysis, ID mapping across services. For quick single-database lookups use gget; for sequence/file manipulation use biopython.

bulk-rnaseq

End-to-end bulk RNA-seq orchestrator — takes raw FASTQ reads through QC and trimming (FastQC, fastp/Trim Galore), alignment and quantification (STAR, Salmon, featureCounts), assembles a gene-level counts matrix, then hands off to differential expression (pydeseq2), pathway/GSEA enrichment (pathway-enrichment), and publication figures (scientific-visualization). Use whenever the user has bulk RNA-seq reads or quant output and wants a complete, reproducible differential-expression workflow — e.g.

cellxgene-census

Query the CZ CELLxGENE Census programmatically for versioned public single-cell and spatial transcriptomics data. Use when you need population-scale cell metadata, gene expression slices, Census summary counts, source H5AD URIs/downloads, embeddings, spatial Census data, or reference atlas comparisons across organisms, tissues, diseases, assays, and cell types. For analyzing your own local single-cell data use scanpy, anndata, or scvi-tools.

cirq

Google quantum computing framework. Use when targeting Google Quantum AI hardware, designing noise-aware circuits, or running quantum characterization experiments. Best for Google hardware, noise modeling, and low-level circuit design. For IBM hardware use qiskit; for quantum ML with autodiff use pennylane; for physics simulations use qutip.

citation-management

Comprehensive citation management for academic research. Search OpenAlex, PubMed, and Google Scholar for papers, extract accurate metadata, validate citations, and generate properly formatted BibTeX entries. This skill should be used when you need to find papers, verify citation information, convert DOIs to BibTeX, or ensure reference accuracy in scientific writing.

clinical-decision-support

Prepare and validate research-only clinical decision-support evaluation, evidence-profile, cohort, survival, biomarker/model, privacy, and governance artifacts. Use for aggregate or synthetic research documentation and traceability—not patient care or live clinical operation.

clinical-reports

Create safety-bounded draft structures and run local deterministic checks for clinical case, diagnostic, trial, safety, and aggregate research reports. Use only with synthetic, de-identified, or aggregate inputs and verified source-fact manifests; every output requires qualified review.

相關技能