Curation guidelines¶

A study in study format 2 is a folder of text files: study.json, reference.json, review.json, tab-separated tables, the publication PDF and the images of its tables and figures. You change them with the pkdb command, in a workbook, or in the curation app. This page gives the order of the work and links the pages that describe each part.

Some studies are still in study format 1, because pkdb migrate could not convert them yet. Change such a study only to make it convert: pkdb validate --offline studies/<substance>/<name> shows its errors, the cutover page explains each reason, and the archived format 1 guide describes its files. pkdb check and the curation app skip format 1 studies.

Install pkdb¶

Install uv and set up the account and the endpoint as described in Getting started. Then install the pkdb release pinned in requirements/pkdb.txt, not a newer one. The pre-commit hook and the CI check run that release and decide: a newer pkdb can write a canonical form that they reject. Run this from the repository root:

uv tool install --python 3.14 --force pkdb --with-requirements requirements/pkdb.txt
export PKDB_NO_UPDATE=1
pkdb --version

Run the install command again after every change of requirements/pkdb.txt, for example after you pull develop. PKDB_NO_UPDATE=1 stops pkdb from suggesting a newer release; put it in your shell profile. Do not run uv tool upgrade pkdb.

Set PKDB_USER to your PK-DB user name. The commands that write files name you as the author. See the environment variables of the client.

Start a study¶

Put the publication PDF <name>.pdf and the images of its tables and figures, <name>_<source>.png, into the folder papers/<substance>/<name>/, for example Harder1988_Tab2.png or Harder1988_Fig1.png. Then create the study from the repository root:

pkdb new caffeine/Harder1988 --pmid 12345678 --licence open --access private

Use --doi when the paper has no PubMed ID. --licence is open or closed (the licence of the paper). A new study is always --access private: public is refused until the study is released, and the release sets the access. The command needs a GitHub token to create the issue of the study: export GH_TOKEN or GITHUB_TOKEN first, for example export GH_TOKEN="$(gh auth token)". pkdb move needs it too, to rename the issue. The command creates studies/caffeine/Harder1988/ with study.json, reference.json, subjects.tsv and review.json (status draft), moves the PDF and the images from papers/ into it, and opens the GitHub issue of the study. The issue number is stored in study.json. The cutover page describes the papers/ folder.

Create a branch for the study and keep one study per branch:

git switch -c curation/caffeine-Harder1988

The files of a study¶

The study format page is generated from the schema and lists every column of every table, the encoding rules and the statistics. Read it before filling a table. Vocabulary terms are listed on the vocabulary page. Change study.json and review.json through pkdb study and pkdb review or in the curation app, not by hand.

Enter the tables¶

Edit the tables in a workbook. The workbook <name>.xlsx is generated from the tables and is never committed:

pkdb tables open studies/caffeine/Harder1988

The command syncs the workbook with the tables and opens it. Save and close the workbook, then run pkdb tables sync studies/caffeine/Harder1988 to write your changes into the tables. If workbook and tables changed the same rows, the sync stops with a conflict; resolve it with --keep workbook or --keep tables. Add the sheet of a new table with pkdb tables add studies/caffeine/Harder1988 outputs_Tab3. See Edit tables in a workbook for the sheet layout, conflicts and lock files.

You can also edit the TSV files directly in an editor. Write numbers with a decimal point, leave missing cells empty and use tabs between columns. Run pkdb format studies/caffeine/Harder1988 afterwards, which writes every file in canonical form.

Raw tables and figures¶

Keep the extraction of the publication beside the rows you map into the database.

• Raw tables. Add the empty text sheet of a paper table with pkdb tables add studies/caffeine/Harder1988 --raw Tab2. Type the table as printed, then sync. The raw table is the file Harder1988_Tab2.tsv. See Raw tables.
• Figures. Digitize the figure image Harder1988_Fig1.png in WebPlotDigitizer, name each dataset after its series, and import the project:

pkdb digitize import studies/caffeine/Harder1988 Fig1 Harder1988_Fig1.tar

• Compare. pkdb plot studies/caffeine/Harder1988 --source Fig1 renders the digitized points and the mapped rows on the figure image into a PNG file in a temporary folder (--out DIR chooses the folder). Compare the rendering with the figure.

See Raw extraction for the accepted projects and the dataset names.

Check the study¶

pkdb check studies/caffeine/Harder1988

pkdb check is the check of pre-commit and CI. It checks the canonical form of the files, validates offline with the vocabulary of vocabulary.lock.json, and checks identifiers and issue numbers across the repository. It writes nothing and needs no network. Errors fail the check. Warnings do not, but you have to deal with each one: fix the data, or acknowledge the warning with a review item that explains it. --line is the line that the warning names; the header of a table is line 0, so the first entry is line 1:

pkdb review acknowledge studies/caffeine/Harder1988 <warning code> --file outputs_Tab2.tsv --line 3 --text "The paper reports this value without a unit."

Inside this repository every offline validation (pkdb validate, pkdb tables, pkdb review, pkdb release, the curation app and pkdb check) uses the vocabulary of --vocabulary, else vocabulary.lock.json at the repository root, else the cache of the endpoint, else the bundled vocabulary. pkdb check never uses the cache of the endpoint. pkdb vocabulary sync refreshes that cache, but it does not change what the checks in this repository use. If the server has a term that the lock lacks, the check reports it as unknown: wait for the pull request of the vocabulary workflow, which refreshes the lock every week, or ask a maintainer to start the workflow, and update your branch after it is merged.

Also check the values against the publication. The checks cannot tell whether a number was read correctly. See Check a pkdb_data checkout for all modes and exit codes.

Review and approve¶

Record what you are not sure about as a review item, for example:

pkdb review add studies/caffeine/Harder1988 --kind question --file interventions.tsv --text "The dose is not given for the second period."

The kinds are question, uncertainty and issue. Set the status to in_review when the study is ready for a second person: pkdb review status studies/caffeine/Harder1988 in_review.

The review happens in the curation app:

pkdb curate .

The app shows the tables of a study first, color coded by the information they hold (subjects, interventions, data and raw extractions), beside the paper (the PDF of the study), its figures and the images of its tables, with the notes of each table above its rows, the review items with their rows and the validation problems at their cells. A failed action says what failed and why, with details to copy into an issue. A reviewer answers, resolves or dismisses items and sets the status to approved. Approving needs no open items and no validation errors, and only a person can approve. See Local curation app. An AI agent may have curated the study; see AI-curated studies and AGENTS.md.

Release and upload¶

After the review, a reviewer releases the approved studies. A release gives each study the next PKDB identifier in the release block of study.json. --access sets the access of the studies in the same step:

pkdb release --access public studies/caffeine/Harder1988
pkdb registry --check

pkdb registry --check lists the released studies and fails when two studies share an identifier or an issue number. Commit the release together with the study. Upload happens after the merge, with the endpoint and the API key of Getting started:

pkdb upload studies/caffeine/Harder1988

See Python client and API for the upload options. A reviewed merge is the gate for production: do not upload studies that nobody has reviewed.

Rename or move a study¶

pkdb move caffeine/Harder1988 caffeine/Harder1988a

The command needs GH_TOKEN or GITHUB_TOKEN as pkdb new does. It renames the folder and every file named after the study, updates the references in the tables and the review, keeps the PKDB identifier of a released study, and renames the GitHub issue. A workbook with edits that are not in the tables refuses the move; sync it first.

The GitHub issue¶

Each study has one GitHub issue, created by pkdb new. The issue title is <substance>/<name>, its labels are the substance of its folder, every other substance folder that its interventions and data name (for example midazolam on the issue of talinolol/Xiao2012), and its review status (curate, check, approved), and its assignees are the curators and reviewers. You do not edit the issue by hand. The workflow issues runs pkdb issues sync on every push that changes studies and every night, and closes the issue when the study is released and approved. See GitHub issues of studies.

Pull requests¶

Open one pull request per study against develop and link its issue in the description. Before you commit, pre-commit runs pkdb check --staged (set it up once with uvx pre-commit install, see Development). The required check studies runs pkdb check on the changed studies. Merge only when it passes and the study is approved.