Communitygithub.com

modelagem-pkpd

Modelagem e simulação farmacocinética e farmacodinâmica — análise não compartimental, PK/PD compartimental e populacional, exposição-resposta, TMDD, PBPK, bioequivalência, alometria e dose inicial em humanos, previsão de interações medicamentosas e monitoramento terapêutico bayesiano.

O que é modelagem-pkpd?

Esta skill fornece um conjunto completo de scripts para modelagem farmacocinética (PK) e farmacodinâmica (PD), abrangendo desde análise não compartimental (NCA) até modelos populacionais, simulação de regimes, bioequivalência e escalonamento alométrico. Ela é projetada para ser utilizada em ambientes de linha de comando (como Claude Code ou Cursor) e auxilia na análise de dados de concentração-tempo, ajuste de modelos estruturais, avaliação de exposição-resposta e tomada de decisões sobre dosagem. A skill enfatiza boas práticas rigorosas: separa explicitamente as decisões sobre métrica de exposição, modelo estrutural e modelo de covariáveis; diagnostica problemas de identificabilidade e convergência; e utiliza códigos de saída para automatizar fluxos de trabalho. Ela se integra perfeitamente com ferramentas como NONMEM, mas também fornece implementações analíticas para modelos lineares, Michaelis-Menten, TMDD e resposta indireta. A documentação incluída detalha cada script, seus parâmetros e interpretação de resultados, garantindo que o usuário entenda não apenas como executar a análise, mas também como interpretar os achados críticos que frequentemente são ignorados.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Modelagem Farmacocinética e Farmacodinâmica

Quando usar

Qualquer pergunta sobre o que o corpo faz com um fármaco ou o que o fármaco faz com o corpo: derivar métricas de exposição a partir de dados de concentração-tempo, ajustar um modelo estrutural, construir ou verificar uma análise populacional, escolher uma dose ou regime, relacionar exposição ao efeito, comparar formulações ou escalonar para uma nova população.

As três regras

1. Fixe a métrica de exposição e a população da análise antes de calcular qualquer coisa. AUC(0-t), AUC(0-inf), AUC(0-tau) no estado de equilíbrio e Cavg são quantidades diferentes e respondem a perguntas diferentes. O mesmo ocorre com AUCinf baseada em Clast observado versus predito. Escolher depois de ver os números é como um estudo negativo se torna positivo.

2. Modelo estrutural, modelo de variabilidade e modelo de covariáveis são três decisões separadas. Eles são constantemente confundidos — um compartimento extra adicionado para absorver o que é, na verdade, variabilidade não modelada entre ocasiões, uma covariável adicionada para corrigir o que é, na verdade, um modelo de absorção mal especificado. Diagnostique qual deles está errado antes de alterar qualquer um deles.

3. Convergência não é identificabilidade. Um ajuste que converge com 200% de erro padrão relativo em um parâmetro, ou uma correlação de 0,99 entre dois, indica que os dados não conseguem separá-los. Cada script de ajuste aqui relata ambos e os sinaliza, porque a tabela de parâmetros isoladamente parece boa exatamente nesta situação.

Escopo

Esta habilidade calcula, diagnostica e estrutura. Ela não decide que uma formulação é bioequivalente, seleciona uma dose para um ensaio, recomenda uma dose para um paciente, conclui que um fármaco não tem risco de prolongamento de QT, ou substitui um farmacometrista qualificado, um farmacologista clínico ou a revisão regulatória. Os scripts relatam; nenhum deles conclui. tdm_bayes.py em particular é um auxílio de modelagem — qualquer alteração no regime de um paciente é uma decisão do médico assistente.

Scripts

cd skills/pkpd-modeling/scripts
ScriptPergunta respondida
nca.pyQuais são as métricas de exposição, e a fase terminal é boa o suficiente para relatá-las?
fit_compartmental.pyQual modelo estrutural esses dados suportam, e seus parâmetros são identificáveis?
simulate_regimen.pyO que este regime faz no estado de equilíbrio, e para qual fração da população?
check_popk_dataset.pyO NONMEM lerá este conjunto de dados como eu penso que vai?
exposure_response.pyExiste uma relação exposição-resposta, e o platô está nos dados?
bioequivalence.pyO IC 90% atende ao critério, e qual critério se aplica?
allometry_and_fih.pyQual é a dose inicial, ou a dose em uma população menor/mais jovem?
ddi_static.pyOs dados in vitro desencadeiam um estudo clínico de DDI sob ICH M12?
tdm_bayes.pyQuais são os parâmetros individuais deste paciente a partir de seus níveis medidos?

Todos aceitam --format table|tsv|json. Os dados vão para stdout, a proveniência e os achados para stderr, portanto > out.tsv os mantém separados. O código de saída é 0 para nenhum achado, 1 quando achados são levantados, 2 para entrada inválida, de modo que qualquer um deles pode controlar um fluxo de trabalho.

Dois módulos privados carregam a maquinaria compartilhada: _models.py (soluções analíticas para modelos mamilar lineares, além de Michaelis-Menten integrado, TMDD e estruturas de resposta indireta) e _common.py (E/S e relatórios). Importe-os em vez de rededuzir uma função de Bateman.

Fluxo de trabalho

1. Análise não compartimental

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

Quatro escolhas decidem a resposta e geralmente são deixadas implícitas. Este script torna todas as quatro explícitas: --auc-method (padrão linup-logdown), --blq-rule, --lambda-z-points ou uma --lambda-z-window explícita, e se você relata auc_inf_obs ou auc_inf_pred.

A seleção de Lambda_z usa a regra padrão: comece com os últimos três pontos quantificáveis, estenda para trás, mantenha a janela mais longa somente se o r-quadrado ajustado melhorar em mais de 0,0001. O r-quadrado simples só pode aumentar à medida que os pontos são adicionados, portanto sempre escolheria a janela mais longa. Pontos em ou antes do Tmax nunca são elegíveis — incluir o Tmax ajusta a cauda da absorção e distorce a meia-vida, Vz e AUCinf para baixo.

Em um perfil oral de um compartimento simulado sem ruído com 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

A superestimativa de 0,6% do CL/F é a regra trapezoidal em uma fase de absorção escassamente amostrada, não um erro — é o viés irredutível da NCA nesse esquema de amostragem, e é por isso que as estimativas de depuração da NCA e compartimentais nunca concordam exatamente.

Os achados são o ponto central. Um perfil de estado de equilíbrio truncado em tau produz:

finding: sujeito A: 25,2% da AUCinf é extrapolada (acima de 20%); a AUCinf é determinada pelo
         ajuste lambda_z, não pelos dados
finding: sujeito A: a janela lambda_z abrange 0,58 meias-vidas (abaixo de 2,0); a fase terminal
         pode não ter sido alcançada

Ambos estão corretos e ambos são rotineiramente ignorados. No estado de equilíbrio, a métrica de exposição relatável é AUC(0-tau), não AUCinf; o script calcula AUCinf de qualquer maneira e informa que você não confie nela.

2. Ajuste compartimental e seleção de modelo

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

Os parâmetros são estimados na escala logarítmica, portanto não podem se tornar negativos e seus intervalos de confiança são assimétricos. A ponderação padrão é 1/y2 (CV constante), que é o padrão correto para PK e o errado para um endpoint PD homocedástico.

Ajustando dados simulados de dois compartimentos (CL 4, V1 12, Q 6, V2 40, erro proporcional de 8%):

modelo  parâmetros  wssr       aic       bic       f_vs_simpler  f_p_value    comparado_com
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 escolhe o modelo de três compartimentos. BIC e o teste F o rejeitam. A penalidade fixa de 2 por parâmetro do AIC é fraca neste tamanho de amostra, e ele seleciona o modelo superparametrizado com mais frequência do que os profissionais esperam. A tabela de parâmetros resolve:

finding: ajuste: Q3 tem 98% de RSE - não estimável a partir destes dados neste tamanho de modelo
finding: ajuste: V3 tem 71% de RSE - não estimável a partir destes dados neste tamanho de modelo

O ajuste de um compartimento, entretanto, ganha:

finding: ajuste: os sinais dos resíduos não são aleatórios (teste de runtas p = 0,0036) - uma
         má especificação estrutural, que nenhuma quantidade de re-ponderação corrigirá

Essa distinção — má especificação estrutural versus um modelo de erro errado — é a que deve ser acertada. Um gráfico de resíduos versus tempo com sequências do mesmo sinal significa que a forma do modelo está errada. Resíduos heterocedásticos com sinais aleatórios significam que a ponderação está errada. Reponderar o primeiro caso esconde o problema sem corrigi-lo.

3. PK populacional

Verifique o conjunto de dados antes de executar qualquer coisa. É aqui que o tempo realmente é gasto.

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

Os defeitos que importam são os silenciosos. O NM-TRAN não rejeita um DV não numérico — ele lê BLQ como zero e o ajusta como uma concentração zero genuína. Uma covariável em branco torna-se 0, então um peso corporal ausente torna-se um paciente de 0 kg. ADDL sem II não adiciona doses adicionais. Registros compartilhando um timestamp são aplicados na ordem do arquivo, então se um nível é pré ou pós-dose depende de qual linha veio primeiro. Nenhum desses interrompe uma execução.

gravidade  verificação                      detalhe
erro       DV não numérico                 DV contém texto... NM-TRAN os lê como 0
erro       sujeito sem dose                1 sujeito(s) têm observações mas sem dose: 2
erro       TIME não ordenado               1 sujeito(s) têm TIME fora de ordem: 1
erro       covariável WT faltando          1 registro(s) não têm valor...
warning    TIME duplicado dentro de sujeito  NONMEM os aplica na ordem do arquivo...

Para a estimativa em si, esta habilidade não reimplementa NLME — veja references/population-pk.md para métodos de estimativa, os métodos BLQ M1-M7, construção de modelo de covariáveis e os diagnósticos que decidem se um modelo é aceitável, e references/software-ecosystem.md para qual ferramenta usar.

4. Simulação e seleção de regime

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

A simulação determinística responde "como é o paciente típico", que quase nunca é a pergunta:

métrica             p5        p25      mediana   p75      p95      geo_media
pico                11,861    14,6018  16,6702   19,1476  22,9339  16,6453
vale                0,863226  2,15191  3,64412   5,49655  9,21053  3,27035

alvo         fração_atingindo
vale >= 4    0,444

O vale típico é 3,6 e o alvo é 4, então 44% da população o atinge. Um regime ajustado para o paciente típico deixa cerca de metade da população do lado errado do alvo. A taxa de atingimento relatada ainda é otimista aqui: é apenas variabilidade entre sujeitos, sem componente residual ou entre ocasiões.

Modelos lineares são resolvidos analiticamente e sobrepostos, o que é exato. --nonlinear muda para eliminação integrada de Michaelis-Menten, onde a superposição é inválida e o comportamento de doses múltiplas não pode ser inferido a partir de uma dose única.

5. Exposição-resposta

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

O ajuste Emax relata fraction_of_emax_reached e sinaliza um ajuste cujo platô está fora dos dados. Quando a exposição observada mais alta atinge apenas um terço do Emax estimado, Emax e EC50 são extrapolações que são fortemente correlacionadas entre si; citá-los como estimativas independentes não é defensável, e uma relação exposição-resposta "linear" é simplesmente o ramo de baixa concentração da mesma curva.

--cqtc avalia o limite superior do intervalo de confiança bilateral de 90% do QTc previsto corrigido por placebo e ajustado pela linha de base em relação ao limiar de 10 ms, que é a pergunta que ICH E14 realmente faz. Uma estimativa pontual, ou um intervalo de 95%, responde a uma pergunta diferente. O modelo incluído é uma regressão linear comum para triagem; uma análise C-QTc de nível de submissão precisa de um modelo misto com intercepto e inclinação aleatórios por sujeito.

Cada modo carrega a mesma ressalva, porque é a que é esquecida: os pacientes são randomizados para dose, não para exposição. A exposição-resposta entre quantis é observacional mesmo dentro de um ensaio randomizado e pode refletir as covariáveis que impulsionam a depuração.

6. Bioequivalência

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

Três critérios compartilham a palavra "bioequivalência" e não são intercambiáveis: BE média (IC 90% dentro de 80,00-125,00%), o ABEL da EMA (limites ampliados em função de CVwR, limitados a 69,84-143,19%, estimativa pontual ainda dentro de 80-125%) e o RSABE do FDA (um limite linearizado escalado via método de Hyslop, não um intervalo). --scaling se recusa a ser executado em um design 2x2:

error: o referência-escalonamento requer --design replicate. Alta variabilidade observada em um
estudo 2x2 não autoriza alargamento: sem administrações de referência replicadas, não há
estimação da variabilidade intra-sujeito de referência para escalonar.

O tamanho da amostra reproduz exatamente as tabelas publicadas (CV 30%, GMR 0,95, poder de 80% → N = 40 para um 2x2). O poder é calculado integrando sobre a distribuição amostral do desvio padrão estimado, em vez de tratar o erro padrão como conhecido — a aproximação normal superestima o poder em tamanhos de amostra realistas. Observe que N é muito mais influenciado pelo GMR assumido do que pelo CV; assumir 1,00 em vez de 0,95 reduz aproximadamente pela metade o N calculado e é a razão usual para um estudo de BE ser subdimensionado.

7. Escalonamento, pediatria e primeira vez em humanos

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

O escalonamento apenas por tamanho abaixo de cerca de 2 anos de idade superestima a depuração, em um neonato em várias vezes, porque a depuração é limitada pela maturação enzimática e renal, e não pelo tamanho. Fornecer --pma-weeks adiciona o termo de maturação sigmoidal de Anderson-Holford; omiti-lo abaixo de 20 kg levanta um achado.

parâmetro  referência  expoente  size_scaled  maturation_factor  final
CL         5           0,75      0,792063     0,30634            0,242641
V          40          1         3,42857      1                  3,42857

Apenas o tamanho preveria 0,79 L/h; com maturação em 44 semanas de idade pós-menstrual, é 0,24 L/h, uma diferença de 3,3 vezes. O volume não é maturado — a maturação descreve a capacidade de eliminação, não o espaço de distribuição.

--fih usa a conversão de área de superfície corporal do guia de 2005 da FDA para a dose inicial máxima segura e sempre emite um achado de que um MRSD derivado de NOAEL não é suficiente por si só para imunomoduladores agonistas: calcule o MABEL com --mabel e pegue o menor valor.

8. Interações medicamentosas

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

Modelos básicos do ICH M12 com seus pontos de corte (R1 ≥ 1,02 hepático, ≥ 11 intestinal

…

[truncado para tradução]

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.

Habilidades Relacionadas