FHIR REST

fyron.fhir.rest is the API-facing FHIR client for bounded searches, pagination, row-wise cohort lookups, FHIRPath-style extraction, and server write-back. Use it when your data source is a live FHIR endpoint and you want inspectable pandas.DataFrame outputs rather than opaque client objects.

When To Use It

• query resources such as Patient, Observation, Condition, Procedure, or ImagingStudy,
• page through search results with explicit limits,
• run row-wise queries from a cohort table,
• flatten or project returned resources into analysis columns,
• create/update resources or submit reviewed transaction bundles.

Use FHIR SQL when the same data is already available in a relational warehouse.

Core Concepts

Most read functions return pandas.DataFrame outputs. Write functions return FHIRWriteResult objects with request status and server response information.

API Contract

Research Decision: Extraction Safety

Required Inputs

Optional Inputs

Minimal Example

from fyron import FHIRRestClient

client = FHIRRestClient("https://hapi.fhir.org/baseR4")
patients = client.search_df(
    "Patient",
    params={"_count": 25, "_sort": "_id"},
    max_pages=1,
)

search_df is the right starting point when one FHIR query should become one DataFrame. Keep _count and max_pages explicit so the extract is reproducible.

Clinical Example

observations = client.search_df_from(
    cohort,
    resource_type="Observation",
    column_map={"subject": "patient_id"},
    params={"code": "http://loinc.org|718-7"},
    fhir_paths=[
        ("observation_id", "id"),
        ("patient_ref", "subject.reference"),
        ("value", "valueQuantity.value"),
        ("unit", "valueQuantity.unit"),
    ],
    max_pages=1,
)

search_df_from is for row-wise cohort lookups. In this example, each cohort row contributes a subject search parameter from its patient_id column. This is useful when you already have a reviewed cohort and want to retrieve related resources.

If extracted Condition or Procedure resources contain ICD-10, OPS, medication, or local code strings, use DataFrame Operations to derive broad code indicators or date intervals before cohort modeling.

FHIRPath Extraction

FHIRPath extraction is the most readable way to turn nested FHIR JSON into a stable analysis table when the desired values are direct resource fields. In Fyron, fhir_paths accepts either plain path strings or named tuples:

fhir_paths=[
    ("condition_id", "id"),
    ("patient_reference", "subject.reference"),
    ("diagnosis_date", "recordedDate"),
    ("icd_code", "code.coding.code"),
]

Named tuples are preferred because the first value becomes the DataFrame column name. This keeps downstream cohort joins, Table 1 creation, and model feature tables readable.

FHIRPath results follow a simple table contract:

Use FHIRPath for direct projections. Use process_function when you need logic such as choosing one coding system from many, exploding components into separate rows, unit conversion, extension parsing, or local phenotype rules.

FHIRPath Extraction Presets

Fyron includes copyable defaults for common FHIR R4 resources. They are intended as starting points, not as hidden clinical assumptions. Review the resulting columns against your server profile and remove or add paths before freezing an analysis.

from fyron import FHIRRestClient, get_fhir_path_preset

client = FHIRRestClient("https://fhir.example.org/r4")

paths = get_fhir_path_preset("Observation")
paths.append(("local_lab_flag", "extension.where(url = 'https://example.org/fhir/lab-flag').valueCode"))

labs = client.search_df(
    "Observation",
    params={"code": "http://loinc.org|718-7", "_count": 500},
    max_pages=2,
    fhir_paths=paths,
)

Available presets:

The raw preset dictionary is also available when you want to inspect or document it:

from fyron.fhir import FHIR_PATH_PRESETS

FHIR_PATH_PRESETS["ImagingStudy"]

Preset Examples By Resource

Use Patient for the first cohort identity table:

patients = client.search_df(
    "Patient",
    params={"_count": 500, "_sort": "_id"},
    max_pages=1,
    fhir_paths=get_fhir_path_preset("Patient"),
)

Use Condition to build diagnosis cohorts:

conditions = client.search_df_partitioned(
    "Condition",
    partition_param="recorded-date",
    start="2020-01-01",
    end="2026-01-01",
    params={"code": "http://hl7.org/fhir/sid/icd-10|C34", "_count": 500},
    fhir_paths=get_fhir_path_preset("Condition"),
    deduplicate_by="condition_id",
)

Use ImagingStudy when you need StudyInstanceUID and SeriesInstanceUID for DICOM download or BOA merges:

imaging = client.search_df_from(
    cohort,
    resource_type="ImagingStudy",
    column_map={"subject": "patient_id"},
    param_prefix={"subject": "Patient/"},
    fhir_paths=get_fhir_path_preset("ImagingStudy"),
    include_column_map_columns=True,
    max_pages=1,
)

For high-stakes analyses, save the exact paths beside the extracted CSV as provenance. This makes it possible to reproduce why a column exists and which FHIR field populated it.

Function Guide

Parameter Notes

Sequenced Search For Large Result Sets

Some FHIR servers enforce hard result caps, commonly around 10,000 resources. When a query reaches that cap, ordinary Bundle next links may stop even though more matching resources exist. This is a server-side search behavior; the remedy is to split the search into smaller, non-overlapping windows and run those windows one after another.

Fyron calls this partitioned search in the API. Conceptually, it is a sequenced FHIR REST extraction: build date windows, query each window, merge the rows, and optionally de-duplicate by the resource ID.

Use search_df_partitioned when a resource supports a date-like search parameter such as recorded-date, date, authored, issued, started, or _lastUpdated.

Minimal Sequenced Example

from fyron import FHIRRestClient

client = FHIRRestClient("https://fhir.example.org/r4")

conditions = client.search_df_partitioned(
    "Condition",
    partition_param="recorded-date",
    start="2020-01-01",
    end="2024-01-01",
    frequency="YS",
    params={"_count": 500, "code": "C34,C34.9"},
    max_pages_per_partition=-1,
)

This creates yearly windows:

recorded-date=ge2020-01-01&recorded-date=lt2021-01-01
recorded-date=ge2021-01-01&recorded-date=lt2022-01-01
recorded-date=ge2022-01-01&recorded-date=lt2023-01-01
recorded-date=ge2023-01-01&recorded-date=lt2024-01-01

Clinical Condition Extraction

conditions = client.search_df_partitioned(
    "Condition",
    partition_param="recorded-date",
    start="2018-01-01",
    end="2026-01-01",
    frequency="YS",
    params={
        "_count": 500,
        "identifier": "https://example.org/system|",
        "code": "C34,C34.0,C34.1,C34.2,C34.3,C34.4,C34.5,C34.8,C34.9",
    },
    fhir_paths=[
        ("condition_id", "id"),
        ("patient_reference", "subject.reference"),
        ("encounter_reference", "encounter.reference"),
        ("diagnosis_date", "recordedDate"),
        ("icd_code", "code.coding[0].code"),
    ],
    deduplicate_by="condition_id",
    show_progress=True,
)

Partitioned search adds _sort=_id by default when no sort is provided, uses valid repeated FHIR date bounds like recorded-date=ge2020-01-01&recorded-date=lt2021-01-01, and adds _fyron_partition_start / _fyron_partition_end columns for traceability.

Monthly Or Fixed-Day Windows

Use monthly windows when yearly windows still hit the server cap:

monthly_observations = client.search_df_partitioned(
    "Observation",
    partition_param="date",
    start="2023-01-01",
    end="2024-01-01",
    frequency="MS",
    params={"_count": 500, "code": "http://loinc.org|718-7"},
    deduplicate_by="id",
)

Use fixed-day windows when you want predictable partition size:

weekly_reports = client.search_df_partitioned(
    "DiagnosticReport",
    partition_param="issued",
    start="2023-01-01",
    end="2024-01-01",
    window_days=7,
    params={"_count": 200},
)

De-Duplication

Use deduplicate_by when partitions may overlap or when a server returns the same resource in adjacent windows because of date precision:

conditions = client.search_df_partitioned(
    "Condition",
    partition_param="recorded-date",
    start="2018-01-01",
    end="2026-01-01",
    frequency="YS",
    params={"code": "C34,C34.9"},
    fhir_paths=[
        ("condition_id", "id"),
        ("patient_reference", "subject.reference"),
        ("diagnosis_date", "recordedDate"),
    ],
    deduplicate_by="condition_id",
)

Parameter Reference

Preview Windows Before Running

Preview the query windows before running a large extraction:

from fyron.fhir import build_partition_params

windows = build_partition_params(
    {"_count": 500, "code": "C34,C34.9"},
    partition_param="recorded-date",
    start="2018-01-01",
    end="2026-01-01",
    frequency="YS",
)

The output is a list of ordinary parameter dictionaries. The partition bounds are represented internally as repeated FHIR parameters so Fyron sends a valid query string instead of a comma-joined date expression.

Choosing The Right Partition Parameter

When Not To Use It

Do not use partitioning as a substitute for correct clinical filters. It is a transport strategy for large result sets. If every monthly or weekly partition still reaches the server cap, narrow the clinical query, use a smaller window_days, or ask the FHIR server administrator whether the endpoint supports asynchronous bulk export.

CLI Workflow

fyron fhir-rest \
  --base-url "$FHIR_BASE_URL" \
  --resource Observation \
  --input cohort.csv \
  --column-map subject=patient_id \
  --param 'code=http://loinc.org|718-7' \
  --max-pages 1 \
  --output observations.csv

Function Table

Return Values

Common Pitfalls

• Keep max_pages during development so exploratory queries do not pull a whole server.
• If a server caps broad searches, partition by date instead of relying on endless pagination.
• FHIR references often need Patient/<id> rather than a bare ID; inspect your server behavior.
• collection bundles are for local review; submit transaction bundles to servers.
• Fyron validates structure lightly. Production write-back should still use server/profile validation.

Related Modules

• FHIR for the overview.
• FHIR Mapping for CSV/DataFrame-to-FHIR bundles.
• Core I/O for .env, table, Teable, and S3 helpers.