clinical-trials-database

Files (4)

• SKILL.md
• clinical_trials_api.md · references/
• studies_schema.md · references/
• clinical_trials_api.py · scripts/

SKILL.md (first lines)

# Clinical Trials Database

## Prerequisites

1.  **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
    `uv` is installed and on PATH.
2.  **User Notification**: If LICENSE_NOTIFICATION.txt does not already exist in
    this skill directory then (1) prominently notify the user to check the terms
    at https://clinicaltrials.gov/, then (2) create the file recording the
    notification text and timestamp.

## Overview

Access worldwide clinical trial data from ClinicalTrials.gov via the REST API
v2. The CLI script at `scripts/clinical_trials_api.py` wraps the API with
dedicated flags for common filters (phase, age group, status, intervention,
sponsor, etc.) so you rarely need to construct raw queries.

## Core Rules

-   **Use the Wrapper**: ALWAYS execute the provided helper scripts to query the
    database rather than accessing the database directly. The scripts
    automatically enforce the required rate limit gracefully.
-   **Always use `--fields`** — trial JSON records can be very large; restrict
    to the data points you need.
-   **Use `--count-total` first** — check result volume before fetching all
    records.
-   **Paginate large result sets** — use `--limit` with `--page-token` to
    iterate.
-   **Trust Search Filters**: Do not manually re-filter results unless
    explicitly asked to verify detailed eligibility.
-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

## Context Efficiency Warning

Trial JSON records can be very large. **Always** use the `--fields` parameter to
restrict the response to only the data points you need. After writing to file,
read only the fields you need rather than the entire file.

> [!TIP] Use `references/studies_schema.md` to identify exact field paths for
> `--fields`.

## Response Layout Summary

API responses contain a list of studies (usually in a `studies[]` array). Each
study is split into `protocolSection` and optional `resultsSection`.

> [!Tip] Use the **shorthand aliases** below with the `--fields` parameter to
> request specific data and keep responses small.

### Top-Level Fields

-   `totalCount` — Total studies matching query (integer)
-   `studies[]` — Array of study objects
-   `nextPageToken` — cursor string for pagination

### Common Study Fields (and shorthand alias)

-   **Identification**
    -   `protocolSection.identificationModule.nctId` (`NCTId`) — Unique trial ID
    -   `protocolSection.identificationModule.briefTitle` (`BriefTitle`) — Short
        title
-   **Status**
    -   `protocolSection.statusModule.overallStatus` (`OverallStatus`) —
        Recruitment status
-   **Description**
    -   `protocolSection.descriptionModule.briefSummary` (`BriefSummary`) —
        Short description
-   **Arms & Interventions**
    -   `protocolSection.armsInterventionsModule.interventions`
        (`ArmsInterventionsModule`)
-   **Eligibility**
    -   `protocolSection.eligibilityModule.eligibilityCriteria`
        (`EligibilityCriteria`) — Inclusion/Exclusion
    -   `protocolSection.eligibilityModule.stdAges` (`StdAge`) — CHILD, ADULT,
        etc.

Consult `references/studies_schema.md` for full paths (Locations, Outcomes,
Results) and common `--fields` recipes.

## Commands

### Search for studies

Use for: finding trials by disease, drug, phase, status, age group, or any
combination of these filters.

```bash
uv run scripts/clinical_trials_api.py search \
  --condition "<disease>" \
  --intervention "<drug_or_treatment>" \
  --status "<status>" \
  --phase "<phase>" \
  --age-group "<age_group>" \
  --study-type "<study_type>" \
  --sponsor "<sponsor_name>" \
  --has-results \
  --sort "<field>:<asc|desc>" \
  --fields "<fields>" \
  --limit <N> \
  --count-total \
  --page-token "<token>" \
  --output /tmp/search_results.json
```

All flags are optional and combine via AND logic.

**Flag reference:**

-   `--condition` — Disease or condition to search for (e.g. `"cystic
    fibrosis"`).
-   `--intervention` — Drug, device, or treatment name (e.g. `"pembrolizumab"`).
-   `--status` — Recruitment status filter. Values: RECRUITING, COMPLETED,
    NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, ENROLLING_BY_INVITATION,
    TERMINATED, SUSPENDED, WITHDRAWN.
-   `--phase` — Trial phase filter. Values: PHASE1, PHASE2, PHASE3, PHASE4,
    EARLY_PHASE1, NA.
-   `--age-group` — Patient age group filter. Values: CHILD (0–17), ADULT

From hanyanphysics/AI-for-Physics, Apache-2.0.

More from hanyanphysics/AI-for-Physics