# Jinko Task From Nonmem > Convert a NONMEM run into a Jinkō trial set-up via the jinko-sdk. Use this skill whenever the user wants to import, translate, port or migrate a NONMEM model, control stream, .mod/.ctl/.lst file, .ext estimates, .phi individual estimates or a NONMEM data set into Jinkō, or asks to reproduce a published population-PK model that exists as NONMEM code. Emits the computational model, virtual population, protocol design and output set, checks the result numerically against a declared reference, and can publish the evidence as a Jinkō document. Use jinko-model to author a model from scratch, jinko-protocol to edit an existing protocol, jinko-vpop to edit a population, and jinko-calibration-cmaes to fit parameters. - Skill: `novainsilico/jinko-task-from-nonmem` (Agent Skill, multi-file: 14 files) - Install (CLI): `npx skillmds@latest add novainsilico/jinko-task-from-nonmem` - Raw SKILL.md: https://api.skillmd.com/api/skills/novainsilico/jinko-task-from-nonmem/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: novainsilico (https://skillmd.com/u/novainsilico) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/novainsilico/jinko-task-from-nonmem --- # Jinkō Task: From NONMEM Convert a NONMEM run into a working Jinkō trial. > **PREREQUISITE:** This skill needs an initialized `jinko-sdk` connection and an > SDK satisfying its `metadata.requires_sdk` range. Run the `jinko-sdk-setup` skill > (`../jinko-sdk-setup/SKILL.md`) and proceed only once its check passes. If that > skill is not found, install it from `novainsilico/jinko-skills`. > > This skill additionally needs the converter's extra, which the SDK does not > install by default: > > ```bash > pip install "jinko-sdk[nonmem2jinko]" > ``` > > The converter is the `nonmem2jinko` package. It ships inside `jinko-sdk` and > is imported separately. The extra adds scipy, which the numerical check > integrates the reference solve with. Without it every script still runs, and > `--check solve` raises a message naming the extra. ## Core Rules - Run the scripts. Never hand-translate `$PK`; only the scripts' output is verified. - Always check the numbers, and report the measured agreement. Never claim a conversion succeeded without one, and never publish a report whose verdict has no result in it. - Say which reference the numbers came from. `--reference scipy` isolates the platform; `rxode2` covers the reading too; `nonmem` compares against a `$TABLE` the original run wrote and needs no licence, only that file. They are not interchangeable. The `rxode2` numerical reference currently refuses models needing covariate overrides rather than comparing unequal inputs. - Blocking error means stop. Do not pass `--allow-issues` without telling the user what is lost. - Read the report before applying. Units and names are inferred, and some inferences will be wrong for a given data set. - Wrong time unit changes the kinetics silently. Jinkō accepts arbitrary time units but solves and returns results in seconds. Confirm amount, volume and time against the data set. - Compare on the platform's own time grid. `Time` is a requestable series; request it. A recorded event inserts its own points, so a grid rebuilt from `tMin`/`tStep` pairs values with the wrong times. ## Scripts | Script | Does | | --- | --- | | `convert_model.py` | Control stream to computational model | | `convert_trial.py` | Model plus vpop, protocol, output set, trial | | `compare_against_reference.py` | The numerical check. Not optional | | `upload_data_tables.py` | Population to data tables, bound to the trial and overlaid on a viz | | `render_equivalence_report.py` | Measured comparison artifacts to a Markdown report | | `publish_equivalence_report.py` | Report to a Jinkō document | Project writes are dry-run by default and gated by `--apply`. Local artifact outputs are explicit path arguments and preserve existing files where their scripts expose `--overwrite`. ## Orchestration 1. Ask for `.ext`, `.phi` and the data set. Each improves the conversion; the control stream alone is enough to start. 2. Convert dry-run. Resolve what the report raises: `--time-unit`, `--amount-unit`, `--volume-unit`, `--unit SYMBOL=unit`, `--rename NONMEM=jinkoId`. 3. Apply, then run. 4. Check numerically using the same `--time-unit` as conversion. A skipped solve is a failure, not evidence. Report the number and its reference. 5. Render and offer an equivalence report whenever anyone other than the person running the conversion will rely on the model. Every write step takes `--folder NAME --create-folder`, which keeps one run's items together, and `--json-out FILE`, which is how the next step gets the SIDs. Do not scrape them out of the prose. `--parent-folder NAME` nests that folder inside another one. Use it when a project accumulates several conversions: a folder named for the day holding one subfolder per model keeps each run's evidence together, and the runs sort chronologically. Without it a project's root fills up with model names and nothing says which run each belongs to. ## Decisions **Population** (`convert_trial.py`). `--population design` (default) is editable in Jinkō afterwards. `phi` replays the fitted subjects. `sampled` draws from the full multivariate normal represented by `$OMEGA`; a finite sample's realised covariance has sampling error and must be measured rather than called exact. **Random effects** (both converters). `--vpop-mode etas` (default) represents the target `$OMEGA` covariance through ETA marginals and correlations. `parameters` puts marginals on the derived parameters instead: it reads better in the UI but is equivalent only without covariate effects. **Dosing** (`convert_trial.py`). `--dosing auto` (default) uses arms when the data set has an arm structure and per-patient slots when it does not. A study where every subject has an individualised history — neonatal phenobarbital, weight-banded single doses — has no arm structure, and `per-patient` puts each patient's own dose times and amounts in the vpop. Needs `--population phi` or `sampled`, because the schedule rides on the patient table. **Uncertainty** (`convert_trial.py`). `--eps-clones N` gives a per-patient predictive cone. Needs `--population phi` or `sampled`. Not a VPC — see `references/residual-error.md`. **Refused, with the record named:** steady-state (`SS`) dosing, `$MIX`, nested random effects, `$OMEGA`/`$SIGMA` as SD, correlation or Cholesky, `$PRED`-only models, abbreviated code that cannot be read (`MPAST`, a variable `ETA()` subscript, `CALL`, `include`), a parameter the kinetics need that reads a record-level data item such as `DV` or `EVID`, and `IF(AMT.GT.0) TDOS = TIME` — which is refused precisely because substituting simulation time for it looks right and silently gives zero time-since-dose. **Reported, not refused:** `$PRIOR` and `$NONPARAMETRIC` shaped the estimation, not the forward model, so the estimates convert as given. **Converted with a stated approximation:** `DOSE = AMT` points at the model's dose parameter, so a subject whose doses differ in amount reads only the first; time-varying covariates keep their baseline only; a covariate selecting *which* random effect applies cannot be one vpop marginal; a combined error model written through a weight (`Y = F + W*EPS(1)`, `W = F*θ + θ`) is diagnosed with its coefficients but the observable is emitted without residual error. ## References - `references/workflow.md` — commands, flags, worked sequence - `references/validation.md` — the numerical checks and what each proves - `references/reporting.md` — equivalence reports, data tables, overlays - `references/conversion-map.md` — what each NONMEM construct becomes - `references/residual-error.md` — `$ERROR`, `$SIGMA`, the clone approximation Generic mechanics belong to the lower-level skills: `jinko-model` for components, `jinko-vpop` for populations, `jinko-protocol` for arms, `jinko-trial` for runs, `jinko-data-table` for tables, `jinko-trial-viz` for visualisations, `jinko-document` for documents.