Communitygithub.com

modélisation-pkpd

Modélisation et simulation pharmacocinétiques et pharmacodynamiques - analyse non compartimentale, modèles compartimentaux et de population, relations exposition-réponse, TMDD, orientation PBPK, bioéquivalence, allométrie et dose première chez l'humain, prédiction d'interactions médicamenteuses, et suivi thérapeutique bayésien. À utiliser lors de l'analyse de données concentration-temps, du calcul de métriques d'exposition, de l'ajustement de modèles PK ou PD, ou de l'évaluation de schémas posologiques.

Qu'est-ce que modélisation-pkpd ?

Ce composant (skill) automatisé fournit une suite complète d'outils pour l'analyse pharmacocinétique (PK) et pharmacodynamique (PD), allant du calcul non compartimental (NCA) à la modélisation compartimentale, la simulation de populations, la bioéquivalence et les interactions médicamenteuses. Il est conçu pour être intégré dans des flux de travail d'agents IA (tels que Claude Code, Cursor ou IDE similaires) traitant des données concentration-temps, permettant d'extraire des métriques d'exposition, d'ajuster des modèles structurels, de valider des ensembles de données ou d'évaluer des schémas posologiques. Le composant insiste fortement sur la rigueur méthodologique avec trois règles fondamentales : fixer les métriques d'exposition avant tout calcul, traiter séparément les décisions de modèle structurel/variabilité/covariable, et reconnaître que la convergence numérique n'implique pas l'identifiabilité des paramètres. Il inclut des scripts spécialisés comme `nca.py`, `fit_compartmental.py`, `simulate_regimen.py` et `bioequivalence.py`, tous produisant des sorties structurées et des diagnostics via stderr, avec des codes de sortie pour le contrôle de flux. L'outil se positionne comme une aide à la modélisation, pas comme un système décisionnel autonome, en particulier pour le suivi thérapeutique bayésien où toute modification de traitement relève de la responsabilité du clinicien.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Modélisation Pharmacocinétique et Pharmacodynamique

Quand utiliser

Toute question sur ce que le corps fait à un médicament ou ce qu'un médicament fait au corps : calculer des métriques d'exposition à partir de données concentration-temps, ajuster un modèle structurel, construire ou vérifier une analyse de population, choisir une dose ou un schéma, relier l'exposition à l'effet, comparer des formulations, ou adapter à une nouvelle population.

Les trois règles

1. Fixez la métrique d'exposition et la population d'analyse avant tout calcul. AUC(0-t), AUC(0-inf), AUC(0-tau) à l'état d'équilibre, et Cavg sont des grandeurs différentes et répondent à des questions différentes. De même pour l'AUCinf basée sur Clast observée ou prédite. Choisir après avoir vu les chiffres, c'est transformer une étude négative en une positive.

2. Le modèle structurel, le modèle de variabilité et le modèle de covariables sont trois décisions distinctes. Elles sont constamment confondues — un compartiment ajouté en trop pour absorber ce qui est en réalité une variabilité inter-occasions non modélisée, une covariable ajoutée pour corriger ce qui est en réalité un modèle d'absorption mal spécifié. Diagnostiquez lequel est erroné avant d'en modifier un seul.

3. La convergence n'est pas l'identifiabilité. Un ajustement qui converge avec un coefficient de variation relatif (RSE) de 200 % sur un paramètre, ou une corrélation de 0,99 entre deux paramètres, vous indique que les données ne peuvent pas les distinguer. Chaque script ici rapporte les deux et les signale, car le tableau de paramètres seul semble correct exactement dans cette situation.

Périmètre

Ce composant calcule, diagnostique et structure. Il ne décide pas qu'une formulation est bioéquivalente, ne sélectionne pas une dose pour un essai, ne recommande pas une dose pour un patient, ne conclut pas qu'un médicament n'a pas de risque QT, et ne remplace pas un pharmacométricien qualifié, un pharmacologue clinicien ou une revue réglementaire. Les scripts rapportent ; aucun ne conclut. tdm_bayes.py en particulier est une aide à la modélisation — toute modification du schéma thérapeutique d'un patient relève de la décision du clinicien traitant.

Scripts

cd skills/pkpd-modeling/scripts
ScriptQuestion répondue
nca.pyQuelles sont les métriques d'exposition, et la phase terminale est-elle assez bonne pour les rapporter ?
fit_compartmental.pyQuel modèle structurel ces données soutiennent-elles, et ses paramètres sont-ils identifiables ?
simulate_regimen.pyQue fait ce schéma à l'état d'équilibre, et pour quelle fraction de la population ?
check_popk_dataset.pyNONMEM lira-t-il cet ensemble de données comme je le pense ?
exposure_response.pyExiste-t-il une relation exposition-réponse, et le plateau est-il dans les données ?
bioequivalence.pyL'IC à 90 % répond-il au critère, et quel critère s'applique ?
allometry_and_fih.pyQuelle est la dose de départ, ou la dose dans une population plus petite/plus jeune ?
ddi_static.pyLes données in vitro déclenchent-elles une étude clinique d'interaction médicamenteuse selon ICH M12 ?
tdm_bayes.pyQuels sont les paramètres individuels de ce patient à partir de ses niveaux mesurés ?

Tous prennent --format table|tsv|json. Les données vont sur stdout, les informations de provenance et les observations sur stderr, donc > out.tsv les garde séparés. Le code de sortie est 0 pour aucune observation, 1 lorsque des observations ont été émises, 2 pour une entrée invalide, de sorte que n'importe lequel peut conditionner un flux de travail.

Deux modules privés portent les mécanismes partagés : _models.py (solutions analytiques pour les modèles mammillaires linéaires, plus les structures intégrées de Michaelis-Menten, TMDD et réponse indirecte) et _common.py (E/S et rapports). Importez-les plutôt que de redériver une fonction de Bateman.

Flux de travail

1. Analyse non compartimentale

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

Quatre choix déterminent la réponse et sont généralement laissés implicites. Ce script rend les quatre explicites : --auc-method (par défaut linup-logdown), --blq-rule, --lambda-z-points ou une --lambda-z-window explicite, et selon que vous rapportez auc_inf_obs ou auc_inf_pred.

La sélection de Lambda_z utilise la règle standard : commencer par les trois derniers points quantifiables, étendre en arrière, ne garder la fenêtre plus longue que si le r-carré ajusté s'améliore de plus de 0,0001. Le r-carré simple ne peut qu'augmenter à mesure que des points sont ajoutés, donc il choisirait toujours la fenêtre la plus longue. Les points à ou avant Tmax ne sont jamais éligibles — inclure Tmax ajuste la queue de l'absorption et biaise la demi-vie, Vz et AUCinf à la baisse.

Sur un profil oral monocompartimental simulé sans bruit avec 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

La surestimation de 0,6 % de CL/F est due à la règle trapézoïdale sur une phase d'absorption échantillonnée de manière clairsemée, pas une erreur — c'est le biais irréductible de l'ANC sur ce plan d'échantillonnage, et c'est pourquoi les estimations de la clairance par ANC et par modèle compartimental ne concordent jamais exactement.

Les observations sont le point essentiel. Un profil à l'état d'équilibre tronqué à tau produit :

finding: subject A: 25.2 % de l'AUCinf est extrapolé (au-dessus de 20 %) ; l'AUCinf est déterminée par l'ajustement de lambda_z, pas par les données
finding: subject A: la fenêtre de lambda_z couvre 0,58 demi-vies (en dessous de 2,0) ; la phase terminale peut ne pas avoir été atteinte

Les deux sont corrects et les deux sont systématiquement ignorés. À l'état d'équilibre, la métrique d'exposition rapportable est AUC(0-tau), pas AUCinf ; le script calcule AUCinf quand même et vous dit de ne pas lui faire confiance.

2. Ajustement compartimental et sélection de modèle

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

Les paramètres sont estimés sur l'échelle logarithmique, donc ils ne peuvent pas devenir négatifs et leurs intervalles de confiance sont asymétriques. La pondération par défaut est 1/y2 (CV constant), ce qui est la valeur par défaut correcte pour la PK et la valeur incorrecte pour un critère PD homoscédastique.

Ajustement de données simulées à deux compartiments (CL 4, V1 12, Q 6, V2 40, erreur proportionnelle de 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

L'AIC sélectionne le modèle à trois compartiments. Le BIC et le test F le rejettent tous deux. La pénalité fixe de 2 par paramètre de l'AIC est faible pour cette taille d'échantillon, et il sélectionne le modèle surparamétré plus souvent que les praticiens ne s'y attendent. Le tableau des paramètres le confirme :

finding: fit: Q3 a un RSE de 98 % - non estimable à partir de ces données à cette taille de modèle
finding: fit: V3 a un RSE de 71 % - non estimable à partir de ces données à cette taille de modèle

L'ajustement à un compartiment mérite quant à lui :

finding: fit: les signes résiduels ne sont pas aléatoires (test de runs p = 0,0036) - une mauvaise spécification structurelle, qu'aucune repondération ne corrigera

Cette distinction — mauvaise spécification structurelle versus modèle d'erreur erroné — est celle à bien faire. Un graphique résidus-temps avec des séquences de même signe signifie que la forme du modèle est erronée. Des résidus hétéroscédastiques avec des signes aléatoires signifient que la pondération est erronée. Repondérer le premier cas le masque sans le corriger.

3. PK de population

Vérifiez l'ensemble de données avant d'exécuter quoi que ce soit. C'est là que le temps est réellement passé.

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

Les défauts qui comptent sont les silencieux. NM-TRAN ne rejette pas une variable dépendante (DV) non numérique — il lit BLQ comme zéro et l'ajuste comme une concentration zéro réelle. Une covariable vide devient 0, donc un poids corporel manquant devient un patient de 0 kg. ADDL sans II ne place aucune dose supplémentaire. Les enregistrements partageant un horodatage sont appliqués dans l'ordre du fichier, donc selon que un niveau est pré- ou post-dose dépend de la ligne qui vient en premier. Aucun de ces problèmes n'arrête une exécution.

severity  check                            detail
erreur     DV non numérique                 DV contient du texte... NM-TRAN les lit comme 0
erreur     sujet sans dose                  1 sujet(s) a (ont) des observations mais pas de dose : 2
erreur     TIME non trié                    1 sujet(s) a (ont) TIME dans le désordre : 1
erreur     covariable WT manquante          1 enregistrement(s) n'ont pas de valeur...
avertissement  TIME en double dans un sujet  NONMEM les applique dans l'ordre du fichier...

Pour l'estimation elle-même, ce composant ne réimplémente pas NLME — voir references/population-pk.md pour les méthodes d'estimation, les méthodes BLQ M1-M7, la construction de modèle de covariables, et les diagnostics qui décident si un modèle est acceptable, et references/software-ecosystem.md pour savoir quel outil utiliser.

4. Simulation et sélection de schéma

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

La simulation déterministe répond à « à quoi ressemble le patient typique », ce qui n'est presque jamais la question :

métrique          p5        p25      médiane   p75      p95      moyenne_geo
pic               11.861    14.6018  16.6702   19.1476  22.9339  16.6453
creux             0.863226  2.15191  3.64412   5.49655  9.21053  3.27035

cible       fraction_atteignant
creux >= 4  0,444

Le creux typique est de 3,6 et la cible est de 4, donc 44 % de la population l'atteint. Un schéma ajusté sur le patient typique laisse environ la moitié de la population du mauvais côté de la cible. L'atteinte rapportée est ici encore optimiste : il s'agit uniquement de la variabilité inter-sujets, sans composante résiduelle ou inter-occasions.

Les modèles linéaires sont résolus analytiquement et superposés, ce qui est exact. --nonlinear bascule vers une élimination intégrée de Michaelis-Menten, où la superposition n'est pas valide et où le comportement à doses multiples ne peut être déduit du tout à partir d'une dose unique.

5. Exposition-réponse

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

L'ajustement Emax rapporte fraction_of_emax_reached et signale un ajustement dont le plateau est en dehors des données. Lorsque l'exposition la plus élevée observée n'atteint qu'un tiers de l'Emax estimé, Emax et EC50 sont des extrapolations fortement corrélées entre elles ; les citer comme des estimations indépendantes n'est pas justifiable, et une relation exposition-réponse « linéaire » est simplement la partie inférieure de la même courbe.

--cqtc évalue la borne supérieure de l'intervalle de confiance bilatéral à 90 % du QTc corrigé prédit par rapport à la valeur de base, ajusté pour le placebo, par rapport au seuil de 10 ms, ce qui est la question que pose réellement ICH E14. Une estimation ponctuelle, ou un intervalle à 95 %, répond à une question différente. Le modèle fourni est une régression linéaire ordinaire pour le dépistage ; une analyse C-QTc de qualité de soumission nécessite un modèle mixte avec interception et pente aléatoires par sujet.

Chaque mode comporte la même mise en garde, car c'est celle qui est oubliée : les patients sont randomisés pour dose, pas pour exposition. L'exposition-réponse à travers les quantiles est observationnelle même au sein d'un essai randomisé, et peut refléter les covariables qui déterminent la clairance.

6. Bioéquivalence

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

Trois critères partagent le mot « bioéquivalence » et ne sont pas interchangeables : BE moyenne (IC à 90 % dans 80,00-125,00 %), ABEL de l'EMA (limites élargies en fonction du CVwR, plafonnées à 69,84-143,19 %, estimation ponctuelle toujours dans 80-125 %), et RSABE de la FDA (une borne linéarisée mise à l'échelle via la méthode de Hyslop, pas du tout un intervalle). --scaling refuse de s'exécuter sur un plan 2x2 :

erreur : la mise à l'échelle de référence nécessite --design replicate. Une variabilité observée élevée dans une étude 2x2 ne permet pas un élargissement : sans administrations de référence répétées, il n'y a pas d'estimation de la variabilité intra-sujet de référence à mettre à l'échelle.

La taille de l'échantillon reproduit exactement les tableaux publiés (CV 30 %, GMR 0,95, puissance 80 % → N = 40 pour un 2x2). La puissance est calculée en intégrant sur la distribution d'échantillonnage de l'écart-type estimé plutôt qu'en traitant l'erreur standard comme connue — l'approximation normale surestime la puissance pour des tailles d'échantillon réalistes. Notez que N est bien plus déterminé par le GMR supposé que par le CV ; supposer 1,00 au lieu de 0,95 réduit approximativement de moitié le N calculé et est la raison habituelle pour laquelle une étude de BE est sous-dimensionnée.

7. Mise à l'échelle, pédiatrie et première fois chez l'humain

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

La mise à l'échelle par la taille seule en dessous d'environ 2 ans surestime la clairance, chez un nouveau-né de plusieurs fois, car la clairance est limitée par la maturation enzymatique et rénale plutôt que par la taille. Fournir --pma-weeks ajoute le terme de maturation sigmoïde d'Anderson-Holford ; l'omettre en dessous de 20 kg émet une observation.

paramètre  référence  exposant  taille_ajustée  facteur_maturation  final
CL         5          0.75      0,792063        0,30634             0,242641
V          40         1         3,42857         1                   3,42857

La taille seule prédirait 0,79 L/h ; avec maturation à 44 semaines d'âge post-menstruel, elle est de 0,24 L/h, une différence de 3,3 fois. Le volume n'est pas maturé — la maturation décrit la capacité d'élimination, pas l'espace de distribution.

--fih utilise la conversion de surface corporelle du guide de la FDA de 2005 sur la dose initiale maximale sécuritaire et émet toujours une observation selon laquelle une MRSD dérivée d'une NOAEL n'est pas suffisante en soi pour les immunomodulateurs agonistes : calculez MABEL avec --mabel et prenez la valeur la plus basse.

8. Interactions médicamenteuses

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

Modèles de base ICH M12 avec leurs seuils (R1 ≥ 1,02 hépatique, ≥ 11 intestinal…) [contenu tronqué pour la traduction]

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.

Skills associés