tprdb-utilities 0.3.0

A toolkit for accessing and working with data from the CRITT Translation Process Research Database (TPR-DB).

tprdb-utilities

A Python toolkit for downloading and reading data tables from the CRITT Translation Process Research Database (TPR-DB).

Two functions cover the full workflow:

Function	What it does
fetch_TPRDB_tables	Downloads study tables from the CRITT API and saves them to a local directory structure
read_TPRDB_tables	Reads those tables from a local clone into a single pandas.DataFrame

---

Installation

# pip
pip install tprdb-utilities

# uv
uv add tprdb-utilities

# poetry
poetry add tprdb-utilities

---

Quick Start

1 — Download data (fetcher)

Public study (no credentials needed):

from tprdb_utilities import fetch_TPRDB_tables

fetch_TPRDB_tables(
    path="/path/to/local/data",
    studies=["DG21"],
    extensions=["ss", "st"],
    public=True,
)

Private study (requires your TPR-DB username and API token):

from tprdb_utilities import fetch_TPRDB_tables

fetch_TPRDB_tables(
    path="/path/to/local/data",
    studies=["MYSTUDY"],
    extensions=["st"],
    public=False,
    username="myTPRDBusername",   # case-sensitive, must match your account
    token="my-api-token",
)

After downloading, the function always prints a summary like this:

DG21 [ss]: Done fetching (^_^)
DG21 [st]: Done fetching (^_^)

=== fetch_TPRDB_tables Summary ===
StudyID  : DG21
Clone dir: /path/to/local/data/tprdb-mothership-clone
User dir : PUBLIC

Extension  Status            Time
---------  ----------------  ------
ss         Downloaded        1.23s
st         Downloaded        0.98s

To read these files with read_TPRDB_tables:
  path      = "/path/to/local/data/tprdb-mothership-clone"
  user      = "PUBLIC"
  studies   = ["DG21"]

Copy those argument values directly into read_TPRDB_tables.

Subsequent calls are bandwidth-efficient. When files for an extension are already present, fetch_TPRDB_tables sends the X-Client-Tables-Timestamp header (sourced from the studySummary.xml bundled with the study). The server returns 304 Not Modified when nothing has changed, so no data is transferred. The summary will reflect the outcome:

Extension  Status            Time
---------  ----------------  ------
ss         Up to date (304)  0.21s
st         Updated           1.05s

---

2 — Read data (reader)

Use the path and user values printed by fetch_TPRDB_tables at the end of its summary output.

Public study (user="PUBLIC"):

from tprdb_utilities import read_TPRDB_tables

df = read_TPRDB_tables(
    studies=["DG21", "AR22"],
    extension="st",
    path="/path/to/local/data/tprdb-mothership-clone",
    user="PUBLIC",
)

Private study (user="<your TPR-DB username>"):

from tprdb_utilities import read_TPRDB_tables

df = read_TPRDB_tables(
    studies=["MYSTUDY"],
    extension="st",
    path="/path/to/local/data/tprdb-mothership-clone",
    user="USER_DIRECTORY_NAME",
)

---

Directory Structure

fetch_TPRDB_tables creates the following layout under path:

<path>/
└── tprdb-mothership-clone/
    ├── PUBLIC/                  ← public studies
    │   └── <StudyID>/
    │       ├── studySummary.xml
    │       └── Tables/
    │           ├── session1.st
    │           └── ...
    └── <username>/             ← private studies
        └── <StudyID>/
            ├── studySummary.xml
            └── Tables/
                ├── session1.st
                └── ...

Each zip response bundles a studySummary.xml file alongside the table files. fetch_TPRDB_tables places it in the <StudyID>/ directory (one level above Tables/) and uses it on subsequent calls to detect whether the server data has changed.

read_TPRDB_tables expects this exact layout, so the two functions are designed to work together seamlessly.

---

Supported Table Extensions

ag, au, ex, fd, fu, hc, hs, kd, ku, pu, sg, ss, st, tt

License

MIT — see LICENSE.