Getting started¶

Set up the tools and server access needed to curate studies in pkdb_data. This guide covers installation, editing, vocabulary synchronization, checks and upload. For the scientific workflow and data encoding, use the curation guidelines.

Install the curation tools¶

Configure the spreadsheet editor to use a decimal point (1.234), and save workbooks as .xlsx. Keep figure and table names consistent with the publication. WebPlotDigitizer runs in the browser: load a saved figure, choose its plot type and calibrate the axes before extracting values. The section Raw tables and figures explains how a digitized figure enters a study.

The shell examples below use Bash. In VS Code, choose a Bash terminal profile (for example, Git Bash or WSL on Windows) for these commands.

Get the study data¶

Clone the repository and switch to its development branch:

git clone https://github.com/matthiaskoenig/pkdb_data.git
cd pkdb_data
git switch develop

In VS Code, use File → Open Folder to open pkdb_data. Open Terminal → New Terminal and run the remaining commands from this repository root. Create a branch for your study edits before making changes:

git switch -c curation/your-study

Replace your-study with a descriptive name. The section The files of a study lists what a study folder holds.

Configure VS Code for JSON¶

VS Code has built-in JSON syntax highlighting and error detection. Open study.json and check that its language mode is JSON. Use the Problems panel to find syntax errors. See Editing JSON with VS Code.

Change study.json and review.json with the pkdb study and pkdb review commands or in the curation app instead of by hand. pkdb check requires the canonical form that pkdb writes, so do not let VS Code format study files when you save them. After you edit a file of a study by hand, run pkdb format studies/<substance>/<study>, which writes every file of the study in canonical form.

Install pkdb as a uv tool¶

After installing uv, install the pkdb tool in the release that this repository pins in requirements/pkdb.txt. Run the command from the repository root:

uv tool install --python 3.14 --force pkdb --with-requirements requirements/pkdb.txt
uv tool update-shell

Restart your VS Code terminal after updating the shell path, then verify the tool:

pkdb --version
pkdb --help

uv manages a separate tool environment and downloads Python 3.14 if needed. No project environment needs to be activated. See Installing tools with uv.

The pre-commit hook and the CI check run the pinned release and decide: a newer pkdb can write a canonical form that they reject. Add export PKDB_NO_UPDATE=1 to your shell profile, so that pkdb does not suggest a newer release.

Update pkdb¶

Run the install command again from the repository root after every change of requirements/pkdb.txt, for example after you pull develop:

uv tool install --python 3.14 --force pkdb --with-requirements requirements/pkdb.txt
pkdb --version

Do not run uv tool upgrade pkdb: it installs the newest release instead of the pinned one.

Updating the program and synchronizing the server's vocabulary are separate steps. After configuring the endpoint below, synchronize the latest terms too.

Configure your account and endpoint¶

Curation examples use alpha.pk-db.com. Follow the PK-DB Accounts and API keys guide to create an account, verify your email and request curator access.

In Account settings → API keys, create a key with read and studies:write scopes. Save the secret when it is displayed; it is shown only once. Your account also needs permission to upload or edit the study. See Create an API key for the current account instructions.

In the VS Code terminal, export the endpoint and API key:

export PKDB_ENDPOINT="https://alpha.pk-db.com"
read -r -s -p 'PK-DB API key: ' PKDB_API_KEY
echo
export PKDB_API_KEY

Paste your key at the prompt. read -s hides it while you type and keeps the secret out of the command entered in shell history. export makes each variable available to pkdb commands launched from this terminal:

• PKDB_ENDPOINT sets the server URL and selects the vocabulary cached for that server. Commands below inherit it, so you do not need to repeat --endpoint.
• PKDB_API_KEY authenticates requests with your key. A key belongs to the server that issued it; changing servers also requires the appropriate key.

These exports apply to the current terminal session. Repeat them in a new terminal. Keep API keys out of study files and Git. An explicit --endpoint option overrides PKDB_ENDPOINT; use the same server for synchronization, validation and upload.

Synchronize the latest terms¶

With PKDB_API_KEY and PKDB_ENDPOINT set, download the server's current vocabulary:

pkdb vocabulary sync

The vocabulary contains substances, measurement types, allowed terms and validation rules. Synchronization caches it for the selected endpoint. Subsequent preparation and offline validation use that cache when the endpoint remains set. Without a cached vocabulary, local commands fall back to the snapshot bundled with the installed tool.

Inside the pkdb_data repository, offline checks use vocabulary.lock.json at the repository root instead of this cache (see the curation guide).

Synchronize at the start of a curation session and whenever the server reports a vocabulary mismatch. Browse the curation terms to find suitable terms for your study. For portable vocabulary snapshots and additional options, see the PK-DB client documentation.

Check a study¶

Set STUDY_DIR to the actual folder you are curating; replace both placeholders:

STUDY_DIR="studies/<substance>/<study>"
pkdb check "$STUDY_DIR"

pkdb check is the check of pre-commit and CI. It checks the canonical form of the files and validates the study offline with the vocabulary of vocabulary.lock.json, and reports errors and warnings with their file and line. It writes nothing, does not contact the server and does not require an account; a nonzero exit status indicates errors. The section Check the study explains how to deal with warnings. Check the curated values against the publication as well as resolving reported errors.

pkdb check skips a study that is still in study format 1; pkdb validate --offline "$STUDY_DIR" shows the errors of such a study.

Upload a study¶

Upload follows the review: a reviewer releases the approved study, the pull request is merged, and then the study is uploaded with the endpoint and API key exported:

pkdb upload "$STUDY_DIR"

Upload validates the sources, checks client/server compatibility, and sends the original files for server validation. Uploading a study that exists on the server replaces it, subject to your permissions. The access of study.json, which the release sets, controls whether the study is public or private; contributor attribution alone does not grant access. See Study access and curation.

After uploading, inspect the study in the web interface and compare its groups, interventions and measurements with the publication.

Resolve validation and upload errors¶

• Vocabulary mismatch: run pkdb vocabulary sync, validate again and retry the upload using the same endpoint.
• Processing-version mismatch: pull develop and install the pinned release again (see Update pkdb). If the server requires a newer release than the pin, ask a maintainer to update requirements/pkdb.txt; the client documentation describes the compatibility check.
• Authentication or permission error: check the selected endpoint, key expiry, studies:write scope and study assignment using the account guide.
• Study validation error: use the reported file, sheet, row or field to correct the source. Preserve contributor names if the server reports an unknown user; ask its administrator to provision the missing identity.

Continue with the curation guidelines for the sequence of scientific curation and review steps.