jk-vpop

Jinkō Vpop SDK Workflows

Use this skill for technical vpop and vpop-design workflows through the SDK. Keep distribution guidance minimal; use the allowed distribution shapes in assets/distrib.json and defer deeper distribution design to a dedicated distribution skill when available.

Core Rules

• Use client.create_vpop_from_csv() or client.create_vpop_from_dataframe() for direct vpop upload.
• Use client.create_vpop_generator_from_design() for marginal-distribution vpop designs.
• Use vpop_generator.generate_vpop_by_design() to generate an immutable Vpop from a design.
• Treat Vpop project items as generated/uploaded artifacts that are not edited in place.
• Edit vpop designs, not generated vpops, then regenerate a new vpop.
• Require explicit confirmation or script --apply before creating or updating project items.
• Descriptor IDs in CSV headers and marginal designs must match real model component IDs when the vpop will be used with that model.

Project Folder Hygiene

• Prefer creating vpops and vpop designs inside a dedicated Jinkō folder instead of the project root. At the start of a workflow, ask for or propose a folder name, for example YYYY-MM-DD-<experiment-name>.
• Reuse an existing exact-match folder when possible: client.folders.get_by_name(name, exact_match_only=True).
• If the folder does not exist, create it only after user confirmation or when a script is run with --apply.
• Resolve one folder object or folder id, then pass folder=folder to SDK creation calls that support it.

Bundled Assets

• assets/toy_vpop.csv: two-patient vpop CSV using the toy model descriptors Dose and k_elim.
• assets/toy_marginals.json: list-of-marginals vpop design for Dose and k_elim.
• assets/distrib.json: source of truth for admissible marginal distribution shapes.

Bundled Scripts

Use scripts rather than embedding long Python examples in chat.

• scripts/create_vpop_from_csv.py: uploads a CSV directly, or via pandas DataFrame with --method dataframe.
• scripts/create_vpop_generator_from_design.py: creates a vpop design from a list of { "id": ..., "distribution": ... } entries and can optionally generate a vpop.
• scripts/inspect_vpop.py: inspects content, description, or statistics for an existing vpop.
• scripts/edit_vpop_generator_design.py: replaces the marginal distribution list in an existing vpop design.

Examples:

python skills/jk-vpop/scripts/create_vpop_from_csv.py --csv skills/jk-vpop/assets/toy_vpop.csv
python skills/jk-vpop/scripts/create_vpop_from_csv.py --csv skills/jk-vpop/assets/toy_vpop.csv --apply
python skills/jk-vpop/scripts/create_vpop_from_csv.py --csv skills/jk-vpop/assets/toy_vpop.csv --folder 2026-06-15-vpop-study --create-folder --apply
python skills/jk-vpop/scripts/create_vpop_generator_from_design.py --design skills/jk-vpop/assets/toy_marginals.json --model-sid cm-... --apply --generate
python skills/jk-vpop/scripts/inspect_vpop.py --vpop-sid vp-... --statistics --correlations

CSV Upload Pattern

The minimal CSV shape is one row per patient:

patientIndex,Dose,k_elim
1,1.0,0.08
2,1.2,0.12

Use actual component IDs, not biological labels such as age or weight, when the vpop is meant to drive a model.

Marginal Design Pattern

Use a list of marginal entries in skill assets and scripts:

[
  {"id": "Dose", "distribution": {"tag": "Uniform", "lowBound": 0.8, "highBound": 1.2}},
  {"id": "k_elim", "distribution": {"tag": "NormalTruncated", "mean": 0.1, "stdev": 0.02, "lowBound": 0.01, "highBound": 0.3}}
]

The script converts this list to the SDK mapping expected by create_vpop_generator_from_design(marginal_distributions=...).

Reference Routing

• Read references/csv-vpop.md for direct CSV/DataFrame upload details.
• Read references/vpop-design.md for marginal vpop design and generation details.
• Read assets/distrib.json before adding or changing marginal distribution shapes.