cohort-compare

Analyze a patient cohort: $ARGUMENTS

Use your fhir-basics skill to query FHIR endpoints. Use your clinical-knowledge skill to identify care gaps and apply correct thresholds. Use your analysis-methods skill to write correct Python analysis code.

Execution Rules

• Do NOT explore the workspace or list files. Begin the analysis immediately.
• Write ONE Python script that does everything: FHIR queries, analysis, chart, and summary.
• Write the script correctly the first time. Do NOT write a draft and then edit it.
• Run it with python (NOT python3).
• All HTTP calls must use subprocess.run(["curl", "-sf", "--max-time", "30", url], capture_output=True, text=True) -- the requests library does NOT work through the sandbox proxy. See the fhir-basics skill for the fhir_get helper pattern.
• Save the script to /tmp/<name>.py, run it once, interpret the output.

Steps

1. Identify the cohort -- Query GET /Condition?code={snomed_code}&_count=200 and follow pagination links to get all matching Condition resources. Extract unique patient IDs from entry[].resource.subject.reference. Report the cohort size.

2. Pull clinical data in BATCHED queries (do NOT loop per-patient):

   • Lab values: Use get_latest_labs_batch(loinc_code, patient_ids) to fetch ALL observations for the LOINC code in one call and filter client-side. This queries GET /Observation?code={loinc_code}&_count=500&_sort=-date without a patient filter, then builds a dict keyed by patient ID. Handle both valueQuantity (numeric) and valueString (text) formats. For blood pressure, query the BP panel code 85354-9 in batch and parse components.
   • Medications: Use get_all_medications_batch(patient_ids) to fetch GET /MedicationRequest?status=active&_count=500 in one call, then filter to cohort patients client-side.
   • NEVER write a for pid in patient_ids: loop that makes FHIR HTTP calls inside the loop. The sandbox proxy adds 1-3s latency per call. With 24 patients x 4 LOINC codes = 96 calls = 5+ minutes. Batching brings this to 4-6 total calls = 30 seconds.

3. Build a pandas DataFrame with one row per patient:

   • patient_id (string)
   • {lab_name} (float or None)
   • lab_date (string)
   • on_target_med (boolean -- True if the patient is on the specified medication class)
   • medications (comma-separated string of all active med names)
   • med_count (int)

4. Data quality check:

   • Report how many patients have the lab recorded vs. missing
   • If > 30% missing, flag as a data quality issue but continue analysis
   • If < 5 patients have data, warn that the sample is too small for meaningful statistics

5. Identify care gap patients: Apply the threshold and medication check:

   • Gap = lab value exceeds threshold AND patient is NOT on the specified medication class
   • Report: total with condition, total with lab data, total above threshold, total in care gap
   • Compute gap rate as percentage of patients with lab data (not total cohort)

6. Generate visualization:

   • Histogram of the lab value distribution with threshold line
   • Use NVIDIA dark theme: plt.style.use('dark_background'), primary color #76B900, background #1a1a1a
   • Annotate with sample size (N = ...) and gap count
   • Save as PNG with dpi=150

7. Write a plain-English summary including:

   • Cohort size and data completeness
   • Distribution statistics (mean, median, range)
   • Gap patient count and percentage with absolute numbers
   • Comparison to relevant CMS quality measure if applicable
   • Any notable patterns (e.g., "All gap patients had no medications recorded at all")

8. Disclaimer: "This analysis is for research and operational purposes. Clinical decisions should be made by qualified clinicians."

Example: Diabetes Gap Analysis (CMS122)

Condition: Type 2 Diabetes (SNOMED 44054006) Lab: HbA1c (LOINC 4548-4) Threshold: > 9.0% Gap medication: insulin or GLP-1 agonist Quality measure: CMS122v12 (poor glycemic control)

INSULIN_AND_GLP1 = ["insulin", "liraglutide", "semaglutide", "dulaglutide",
                     "exenatide", "tirzepatide", "victoza", "ozempic",
                     "trulicity", "byetta", "mounjaro", "rybelsus"]
 
def is_on_insulin_or_glp1(med_list):
    med_lower = [m.lower() for m in med_list]
    return any(drug in med_text for drug in INSULIN_AND_GLP1 for med_text in med_lower)

Example: Hypertension Gap Analysis (CMS165)

Condition: Essential Hypertension (SNOMED 38341003) Lab: Systolic BP (LOINC 8480-6) -- use component Observation pattern Threshold: >= 140 mmHg Gap medication: any antihypertensive Quality measure: CMS165v12 (controlling high blood pressure)

Note: Use get_latest_bp() from the analysis-methods skill to handle both BP panel (85354-9) and standalone systolic Observations.

ANTIHYPERTENSIVES = ["lisinopril", "enalapril", "ramipril", "benazepril",
    "losartan", "valsartan", "irbesartan", "olmesartan", "telmisartan",
    "amlodipine", "nifedipine", "diltiazem",
    "metoprolol", "atenolol", "carvedilol", "bisoprolol",
    "hydrochlorothiazide", "hctz", "chlorthalidone",
    "furosemide", "spironolactone"]
 
def is_on_antihypertensive(med_list):
    med_lower = [m.lower() for m in med_list]
    return any(drug in med_text for drug in ANTIHYPERTENSIVES for med_text in med_lower)