Which API?

EncodeBox has three ways to write the same query. Prefer the highest level that fits; drop down only when you need to.

Name	Use when	How you get it
EventFrame	Find events (codes, gaps, first/last)	`db.diagnosis`
Cohort	Define a study population + attrition	`eb.Cohort(name, database=db)`
Table / Column	Custom predicates verbs cannot express	`db.diagnosis.as_table()`

Cohort        who is in the study (entry → include → exclude)
EventFrame    which events qualify (match → occur → pick one row)
Table/Column  raw boolean filters on columns
──────────────────────────────────────────────────────────────
              same IR → same SQL → DataFrame

Setup

import encodebox as eb

eb.register_connector("connectors/postgres_local_sentinel/connector.yml")
db = eb.connect(
    "postgres",
    host="localhost",
    port=5433,
    database="encodebox_sample",
    username="postgres",
    password="postgres",
    connector="postgres_local_sentinel",
)

With connector=, you get a Database. Domains are attributes: db.diagnosis, db.procedure, db.medication, db.enrollment, …

EventFrame — finding events

An EventFrame is a lazy list of clinical events (one row ≈ one code on one date for one patient). You chain verbs; nothing hits the database until .to_df().

Typical index-date chain

index = (
    db.diagnosis
    .matching("E11", code_type="10", match="starts_with")
    .occurring(at_least=2, gap_days=30)
    .with_index_date()
    .first_per_patient()
)

“Patients with at least two E11* diagnoses on different days, with at least 30 days between some consecutive visits; use the start of the first such pair as their index date.”

EventFrame verbs

Verb	Meaning
`matching(codes, code_type=…, match=…)`	Keep rows whose code matches. `"E11"` prefix, `["A","B"]` = either code, `[["A"],["B"]]` = UNION of two code sets.
`in_position("primary")`	Keep only primary (or non-primary) diagnosis positions.
`occurring(at_least=n, at_most=m, gap_days=d)`	Keep patients who have enough events. Counts distinct dates by default. `gap_days` requires a consecutive day gap (`lead()`), not first-to-last span.
`with_index_date()`	Expose `index_date` (after a gap rule: first qualifying consecutive-pair start).
`first_per_patient()` / `last_per_patient()`	Keep one row per patient. After `occurring(gap_days=…)`, “first” is gap-aware.
`between(start, end)` / `in_years(2020)`	Calendar filter on `event_date`.
`with_age(...)` / `with_followup(...)`	Attach age or follow-up time columns.
`union(other)`	Stack two event streams.
`label("name")`	Name a step (shows in repr / explain / attrition).
`to_sql()` / `to_df()` / `explain()`	Inspect SQL, run query, or show the IR tree.

Gap semantics

gap_days=30 means: look at ordered distinct dates and require some neighboring pair to be ≥30 days apart.

Patient dates	Span (max−min)	Max consecutive gap	`gap_days=30`
Jan 1, 11, 21, 31	30 days	10 days	out
Jan 1, Jan 16, Mar 1	60 days	45 days	in

Legacy filter_event(..., gap=30) used span (max−min). New gap_days uses consecutive gaps. They do not select the same patients.

Cohort — defining a study population

A Cohort starts from an entry EventFrame (people + index date), then requires or excludes criteria. Each step is a set operation on patient_id. .attrition() counts how many people remain after each step.

t1dm = (
    db.diagnosis
    .matching("E10", code_type="10", match="starts_with")
    .occurring(at_least=2, gap_days=30)
    .with_index_date()
    .first_per_patient()
)

cohort = (
    eb.Cohort("t2dm", database=db)
    .entry(index, index="first")
    .include(db.demographic.age_at_index(18, 89))
    .include(db.enrollment.covering_index(days_before=365, days_after=0))
    .include(t1dm, window=(-365, 0))
    .exclude(db.diagnosis.matching("C", match="starts_with"), window=(-365, 0))
)

print(cohort.attrition())
final = cohort.to_df()

Cohort building blocks

Piece	Meaning
`.entry(frame, index="first")`	Starting population and each person’s index date. Called once.
`.include(source, window=…)`	Inclusion: age / enrollment / EventFrame (optional day window vs index).
`.exclude(source, window=…)`	Exclusion: remove patients who meet the criterion.
`.attrition()`	Remaining / dropped counts at each labeled step.
`.spec()` / `eb.from_spec(...)`	Serialize / restore the definition.

Built-in criteria

Criterion	Meaning
`db.diagnosis.matching(...)` on include/exclude	Event-based patient set (optional `window=` relative to index).
`db.enrollment.covering_index(days_before=a, days_after=b)`	Continuous enrollment covering `[index−a, index+b]`.
`db.demographic.age_at_index(lo, hi)`	Age at index in `[lo, hi]`.
`db.demographic.sex(...)` / `.race(...)`	Demographic match at index.
`db.death.recorded(window=…)`	Death recorded (optionally in a window).

Windows are always (days_before, days_after) relative to the cohort entry index date. Example: window=(-365, 0) = the year ending on the index day.

Table / Column — custom predicates

dx = db.diagnosis.as_table()
t2dm = dx.filter(dx.code.startswith("E11") & (dx.code_type == "10"))
frame = t2dm.as_events()

Use column expressions when EventFrame verbs cannot say what you mean. Prefer EventFrame for matching / occurrence / ranking.

Inspect anything

Method	Meaning
`print(obj)`	Show the pipeline steps.
`.explain()`	Show the IR tree / SQL fragments.
`.to_sql()`	Full SQL without running it.
`.to_df()`	Run the query.
`.attrition()`	Cohort: remaining and dropped at each step.

Legacy API

query_event / filter_event still import but warn. Their gap rule is span, not consecutive days — see Migration.

Getting started

Data model

Guides

API reference

Setup

EventFrame — finding events

Typical index-date chain

EventFrame verbs

Gap semantics

Cohort — defining a study population

Cohort building blocks

Built-in criteria

Table / Column — custom predicates

Inspect anything

Legacy API

​Setup

​EventFrame — finding events

​Typical index-date chain

​EventFrame verbs

​Gap semantics

​Cohort — defining a study population

​Cohort building blocks

​Built-in criteria

​Table / Column — custom predicates

​Inspect anything

​Legacy API

Setup

EventFrame — finding events

Typical index-date chain

EventFrame verbs

Gap semantics

Cohort — defining a study population

Cohort building blocks

Built-in criteria

Table / Column — custom predicates

Inspect anything

Legacy API