Study format¶

A study folder in study format 2 contains study.json, reference.json, review.json, the tab-separated tables below, the publication PDF and an image <study>_<source>.png for every paper table or figure the data come from; a paper table without an image, such as unpublished data, has its raw table <study>_<source>.tsv as its source instead. pkdb format writes all files in canonical form, pkdb validate checks them, pkdb tables edits the tables in a workbook, and pkdb schema export writes the same definitions as JSON Schema.

Identity and upload¶

A study is identified by its folder location <substance>/<name>, for example caffeine/Harder1988: the folder name is the study name and its parent folder the substance. The folder names publication and validate are reserved, because PK-DB uses them in study URLs, and so are outputs, timecourses and scatters, because a file such as outputs_Tab2.tsv would be both a table and a raw table of a study named like the kind. pkdb upload sends the exact text of study.json and reference.json and every other file of the folder to /api/v2/studies/<substance>/<name>, where the server validates the folder like pkdb validate and stores the study. The study page is /data/<substance>/<name>.

A released study has a PKDB identifier in the release block of study.json. Uploading a folder with a release.pkdb_id takes over the study that PK-DB stores under that identifier and renames it to the folder location, so a moved or renamed folder keeps its study. A folder without one, or whose PKDB identifier no stored study has, takes over the study format 1 study of the same publication and source, if you may edit it. PKDB identifiers and former study format 1 identifiers in URLs, such as /data/PKDB00198 or /data/Vilsboll2008, redirect to the study.

Statistics and schedules¶

There is no value column. mean is the arithmetic mean, the value of a single subject (count 1) or, with the calculation unspecified summary, the central value of a summary whose statistic the publication does not state. cv and gcv are entered in percent and are fractions in the prepared study and the API. A digitized error_bar with its error_type completes sd, se or gsd; missing sd, se and cv are derived from each other, and gsd and gcv as well, where the reported values allow it, and reported statistics that contradict each other, including an error bar, are a warning that a review item acknowledges at the column of the statistic that disagrees with the most others (see the data model). An intervention time is a number, or a ;-separated list for an irregular schedule; a regular schedule uses interval and doses instead.

Review¶

review.json holds the review status (draft, in_review, approved), the reviewers and the review items. approved_by and approved record the person who approved the study and when; pkdb review status <study> approved requires zero open items and zero validation errors and is refused for agents (--agent or PKDB_AGENT). A dismissed item no longer acknowledges a warning, and its rows are no longer checked (review_target_unmatched). A review item targets the whole study, a file, the rows of a table with given values (rows) and a column, or a part of a file without rows that a key names: the dataset of a WebPlotDigitizer project or a review item of review.json. acknowledges names a warning code, and pkdb review acknowledge targets exactly one warning, at its row and column or by its key. A target of a file alone acknowledges every warning of the code in that file, also later ones. pkdb study and pkdb review write study.json and review.json; every write is refused when the file changed since the revision the caller read.

Tables¶

Raw extraction¶

Every paper table and figure can keep its raw extraction beside the rows mapped into the tables. <study>_<source>.tsv is a paper table as printed: a grid of text cells in their printed positions without a header line, study or source columns. pkdb format strips the cells, pads the rows to the widest row and removes trailing empty cells and empty rows, and never sorts the rows or parses numbers. In the workbook it is the sheet <study>_<source> after the data sheets, written as text cells; pkdb tables add <study> --raw Tab2 adds it.

The raw table is the source of data that no image shows: unpublished data, raw data provided elsewhere, such as a data workbook of the authors, or a supplement that is not available. Name the source as a paper table, such as TabS4 or TabRawData, and transcribe the data into <study>_<source>.tsv; then the source needs no image <study>_<source>.png, its rows have no image in PK-DB, and the source views show the raw table without an image. A figure always needs its image.

<study>_<source>.wpd.json is a WebPlotDigitizer 4 project digitized on the figure image <study>_<source>.png, imported with pkdb digitize import <study> <source> <file> from a wpd.json or a saved .tar project. Only XY axes are supported. A dataset named like a timecourse label holds the central values of that series (time on x; mean, else median, else gmean on y), a dataset <label>;error_bar the ends of its error bars, and a dataset named like a scatter name its points. Digitize and map in the units printed on the axes. pkdb validate warns about datasets without rows (unknown_dataset) and rows more than 2 pixels from their dataset (digitized_mismatch), and pkdb plot draws both on the image.

TSV encoding¶

• UTF-8 without byte order mark, LF line endings and a final newline.
• Tab separated without quoting. Cells contain no tabs or line breaks.
• One header row with every template column in template order.
• The header is line 0 and the first entry line 1, so line n is row n + 1 of the sheet in the workbook. A raw table has no header: its first line is line 1 and row 1. Validation, pkdb curate and the command line name lines this way, with the address of the cell in the workbook, such as line 96 · error_bar · workbook cell Y97.
• An empty cell means missing. NR (not reported) is allowed only in time and time_unit and their scatter variants x_time, x_time_unit, y_time and y_time_unit.
• Numbers use a decimal point and are written in their shortest form.
• pkdb format sorts the rows and writes the study column and, in files named after a source, the source column.

subjects.tsv¶

Groups and individuals. A subject with count 1 is an individual; every subject except all has a parent group.

interventions.tsv¶

Interventions such as doses, fasting or smoking, referenced by name from the other tables.

characteristica.tsv¶

Baseline values of subjects, such as age, weight, sex or creatinine clearance.

outputs_<source>.tsv¶

Single values after interventions, such as pharmacokinetic parameters, from one paper table or figure.

timecourses_<source>.tsv¶

Timecourse points from one paper figure or table. Rows with the same label form one series.

scatters_<source>.tsv¶

Points of scatter plots, one row per point with an x and a y value.