Analysis Code Guidelines
FHIR Helpers Library
Always import the helpers library at the top of every analysis script:
import sys
sys.path.insert(0, '/sandbox/clinical-intelligence/skills/analysis-methods/scripts')
from fhir_helpers import *
Available functions
| Function |
Use for |
HTTP calls |
get_patients_with_condition(snomed_code) |
Find patients with a condition → list of IDs |
1-2 |
get_latest_labs_batch(loinc_code, patient_ids) |
Labs for a cohort → dict: pid → (value, unit, date) |
1-2 |
get_all_medications_batch(patient_ids) |
Meds for a cohort → dict: pid → [med names] |
1-2 |
build_cohort_df(patient_ids, loinc, lab_name, drug_check_fn) |
Full DataFrame with labs + meds |
2-3 |
get_latest_lab(patient_id, loinc_code) |
Lab for ONE patient → (value, unit, date) |
1 |
get_medications(patient_id) |
Meds for ONE patient → [names] |
1 |
get_latest_bp(patient_id) |
BP for ONE patient → (sys, dia, date) |
1-2 |
check_drug_class(med_list, drug_names) |
Check if any med matches drug list → bool |
0 |
fhir_get(path, params) |
Raw FHIR GET → parsed JSON |
1 |
get_all_pages(path, params) |
Paginated FHIR GET → all entries |
1+ |
save_chart_to_canvas(fig, filename) |
Save matplotlib figure to canvas directory |
0 |
Performance rules
- Cohort queries (2+ patients): Use
get_latest_labs_batch() and get_all_medications_batch(). These make 1-2 HTTP calls total regardless of patient count.
- Single patient: Use
get_latest_lab(), get_medications(), get_latest_bp().
- NEVER loop over patients calling
get_latest_lab() per patient. Each HTTP call through the sandbox proxy adds 1-3s. For 48 patients = 48 calls = 2+ minutes. The batch function does it in one call.
Execution Rules
- Run scripts with
python (NOT python3)
- Write a SINGLE Python script for the entire task
- Write the script to
/tmp/<name>.py, then execute it
- All HTTP inside the sandbox must use
subprocess.run(["curl", ...]) — the requests library does NOT work
Mandatory Workflow
STEP 1 - WRITE SCRIPT (import fhir_helpers, write analysis)
STEP 2 - VALIDATE: python /sandbox/clinical-intelligence/scripts/validate_and_run.py --validate-only /tmp/<name>.py
STEP 3 - EXECUTE: python /tmp/<name>.py
STEP 4 - INTERPRET: explain results using clinical-knowledge skill
Code Structure
- Imports (always start with fhir_helpers import)
- Data collection (use batch functions)
- DataFrame construction
- Analysis (filters, aggregations)
- Visualization -- use
save_chart_to_canvas(fig, filename) (NOT plt.savefig)
- Summary (print findings)
- Disclaimer
Care Gap Analysis Pattern
# Example: diabetes care gap
patients = get_patients_with_condition("44054006") # SNOMED for diabetes
df = build_cohort_df(patients, "4548-4", "HbA1c",
lambda meds: check_drug_class(meds, ["metformin", "insulin", "glipizide"]))
gap = df[(df['HbA1c'] > 9) & (~df['on_target_med'])]
denom = len(df[df['HbA1c'].notna()])
pct = f"{len(gap)/denom*100:.1f}%" if denom > 0 else "N/A (no HbA1c data)"
print(f"Care gap: {len(gap)}/{denom} ({pct})")
Visualization
Always use dark theme. Use save_chart_to_canvas() instead of plt.savefig() directly.
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
plt.style.use('dark_background')
fig, ax = plt.subplots(figsize=(10, 6))
fig.patch.set_facecolor('#1a1a1a')
ax.set_facecolor('#1a1a1a')
# Histogram with NVIDIA green
ax.hist(values, bins=15, color='#76B900', edgecolor='#1a1a1a', alpha=0.85)
ax.axvline(x=threshold, color='#ff4444', linestyle='--', linewidth=2, label=f'Threshold ({threshold})')
ax.set_title("Title", fontsize=14, fontweight='bold', color='white')
ax.legend()
ax.grid(axis='y', alpha=0.2, color='#444444')
ax.text(0.98, 0.95, f"N = {len(values)}", transform=ax.transAxes, fontsize=11, color='#888888', ha='right', va='top')
# MANDATORY: use save_chart_to_canvas (NOT plt.savefig)
save_chart_to_canvas(fig, "chart.png")
plt.close()
Guardrails
- Never compute statistics on fewer than 5 data points
- Always report sample size: "45.0% (27 out of 60)"
- Flag data quality issues if >30% missing
- Do not fabricate data — report what exists, flag what's missing
- All charts must include N annotation
Output Format
End every script with:
print(f"\nDisclaimer: This analysis is for research and operational purposes.")
print("Clinical decisions should be made by qualified clinicians.")
1---2name: analysis-methods3description: Teaches the analyst agent how to write correct, robust Python analysis code for FHIR clinical data using pandas, matplotlib, and scipy.4---56# Analysis Code Guidelines78## FHIR Helpers Library910**Always import the helpers library at the top of every analysis script:**1112```python13import sys14sys.path.insert(0, '/sandbox/clinical-intelligence/skills/analysis-methods/scripts')15from fhir_helpers import *16```1718### Available functions1920| Function | Use for | HTTP calls |21|----------|---------|------------|22| `get_patients_with_condition(snomed_code)` | Find patients with a condition → list of IDs | 1-2 |23| `get_latest_labs_batch(loinc_code, patient_ids)` | Labs for a cohort → dict: pid → (value, unit, date) | 1-2 |24| `get_all_medications_batch(patient_ids)` | Meds for a cohort → dict: pid → [med names] | 1-2 |25| `build_cohort_df(patient_ids, loinc, lab_name, drug_check_fn)` | Full DataFrame with labs + meds | 2-3 |26| `get_latest_lab(patient_id, loinc_code)` | Lab for ONE patient → (value, unit, date) | 1 |27| `get_medications(patient_id)` | Meds for ONE patient → [names] | 1 |28| `get_latest_bp(patient_id)` | BP for ONE patient → (sys, dia, date) | 1-2 |29| `check_drug_class(med_list, drug_names)` | Check if any med matches drug list → bool | 0 |30| `fhir_get(path, params)` | Raw FHIR GET → parsed JSON | 1 |31| `get_all_pages(path, params)` | Paginated FHIR GET → all entries | 1+ |32| `save_chart_to_canvas(fig, filename)` | Save matplotlib figure to canvas directory | 0 |3334### Performance rules3536- **Cohort queries (2+ patients):** Use `get_latest_labs_batch()` and `get_all_medications_batch()`. These make 1-2 HTTP calls total regardless of patient count.37- **Single patient:** Use `get_latest_lab()`, `get_medications()`, `get_latest_bp()`.38- **NEVER** loop over patients calling `get_latest_lab()` per patient. Each HTTP call through the sandbox proxy adds 1-3s. For 48 patients = 48 calls = 2+ minutes. The batch function does it in one call.3940## Execution Rules4142- Run scripts with `python` (NOT `python3`)43- Write a SINGLE Python script for the entire task44- Write the script to `/tmp/<name>.py`, then execute it45- All HTTP inside the sandbox must use `subprocess.run(["curl", ...])` — the `requests` library does NOT work4647## Mandatory Workflow4849```50STEP 1 - WRITE SCRIPT (import fhir_helpers, write analysis)51STEP 2 - VALIDATE: python /sandbox/clinical-intelligence/scripts/validate_and_run.py --validate-only /tmp/<name>.py52STEP 3 - EXECUTE: python /tmp/<name>.py53STEP 4 - INTERPRET: explain results using clinical-knowledge skill54```5556## Code Structure57581. Imports (always start with fhir_helpers import)592. Data collection (use batch functions)603. DataFrame construction614. Analysis (filters, aggregations)625. Visualization -- use `save_chart_to_canvas(fig, filename)` (NOT plt.savefig)636. Summary (print findings)647. Disclaimer6566## Care Gap Analysis Pattern6768```python69# Example: diabetes care gap70patients = get_patients_with_condition("44054006") # SNOMED for diabetes71df = build_cohort_df(patients, "4548-4", "HbA1c",72 lambda meds: check_drug_class(meds, ["metformin", "insulin", "glipizide"]))7374gap = df[(df['HbA1c'] > 9) & (~df['on_target_med'])]75denom = len(df[df['HbA1c'].notna()])76pct = f"{len(gap)/denom*100:.1f}%" if denom > 0 else "N/A (no HbA1c data)"77print(f"Care gap: {len(gap)}/{denom} ({pct})")78```7980## Visualization8182Always use dark theme. Use `save_chart_to_canvas()` instead of `plt.savefig()` directly.8384```python85import matplotlib86matplotlib.use('Agg')87import matplotlib.pyplot as plt8889plt.style.use('dark_background')90fig, ax = plt.subplots(figsize=(10, 6))91fig.patch.set_facecolor('#1a1a1a')92ax.set_facecolor('#1a1a1a')9394# Histogram with NVIDIA green95ax.hist(values, bins=15, color='#76B900', edgecolor='#1a1a1a', alpha=0.85)96ax.axvline(x=threshold, color='#ff4444', linestyle='--', linewidth=2, label=f'Threshold ({threshold})')97ax.set_title("Title", fontsize=14, fontweight='bold', color='white')98ax.legend()99ax.grid(axis='y', alpha=0.2, color='#444444')100ax.text(0.98, 0.95, f"N = {len(values)}", transform=ax.transAxes, fontsize=11, color='#888888', ha='right', va='top')101102# MANDATORY: use save_chart_to_canvas (NOT plt.savefig)103save_chart_to_canvas(fig, "chart.png")104plt.close()105```106107## Guardrails108109- Never compute statistics on fewer than 5 data points110- Always report sample size: "45.0% (27 out of 60)"111- Flag data quality issues if >30% missing112- Do not fabricate data — report what exists, flag what's missing113- All charts must include N annotation114115## Output Format116117End every script with:118119```python120print(f"\nDisclaimer: This analysis is for research and operational purposes.")121print("Clinical decisions should be made by qualified clinicians.")122```
NVIDIA