omopy.drug¶
Drug utilisation analysis — generate drug cohorts, compute utilisation metrics (exposures, eras, doses, days), assess indications and treatment patterns, and present results as tables and plots.
This module is the Python equivalent of the R DrugUtilisation package.
Table rendering delegates to omopy.vis; plot rendering uses
plotly; confidence intervals use
scipy.
Cohort Generation¶
Generate drug cohorts from concept sets, ingredient names, or ATC codes. Records are collapsed into eras using a configurable gap.
generate_drug_utilisation_cohort_set(
cdm: CdmReference,
concept_set: Codelist | dict[str, list[int]],
name: str,
*,
gap_era: int = 1,
subset_cohort: str | None = None,
subset_cohort_id: list[int] | None = None,
number_exposures: bool = False,
days_prescribed: bool = False,
) -> CdmReference
Generate a drug utilisation cohort from concept sets.
Subsets drug_exposure to records matching the provided concept IDs
(including descendants), validates against observation periods, and
collapses overlapping records separated by at most gap_era days
into eras.
Parameters¶
cdm
A database-backed CdmReference.
concept_set
Named mapping of concept ID lists. Each entry becomes one cohort.
name
Name for the resulting cohort table in the CDM.
gap_era
Maximum number of days between exposure records for them to be
collapsed into the same era. Default is 1 (adjacent records merge).
subset_cohort
If provided, restricts to persons present in this cohort table.
subset_cohort_id
If provided with subset_cohort, restricts to specific cohort
definition IDs within the subset cohort.
number_exposures
If True, track the number of original exposure records per era
in the settings.
days_prescribed
If True, track the total days prescribed per era in the settings.
Returns¶
CdmReference
The CDM with a new CohortTable under cdm[name].
generate_ingredient_cohort_set(
cdm: CdmReference,
name: str,
ingredient: str
| list[str]
| int
| list[int]
| None = None,
*,
gap_era: int = 1,
subset_cohort: str | None = None,
subset_cohort_id: list[int] | None = None,
number_exposures: bool = False,
days_prescribed: bool = False,
) -> CdmReference
Generate a drug cohort by ingredient name or concept ID.
Resolves ingredient names/IDs to concept sets via the vocabulary,
then delegates to :func:generate_drug_utilisation_cohort_set.
Parameters¶
cdm
A database-backed CdmReference.
name
Name for the cohort table.
ingredient
Ingredient(s) to search for. Can be:
- str or list[str]: keyword search on concept_name
- int or list[int]: direct concept IDs
- None: all available Drug Ingredient concepts
gap_era
Days for era collapse.
subset_cohort
Restrict to persons in this cohort.
subset_cohort_id
Restrict to specific IDs within subset cohort.
number_exposures
Track number of exposures per era.
days_prescribed
Track days prescribed per era.
Returns¶
CdmReference The CDM with a new CohortTable.
generate_atc_cohort_set(
cdm: CdmReference,
name: str,
atc_name: str | list[str] | None = None,
*,
level: str | list[str] | None = None,
gap_era: int = 1,
subset_cohort: str | None = None,
subset_cohort_id: list[int] | None = None,
number_exposures: bool = False,
days_prescribed: bool = False,
) -> CdmReference
Generate a drug cohort by ATC code name.
Resolves ATC names to concept sets via the vocabulary, then delegates
to :func:generate_drug_utilisation_cohort_set.
Parameters¶
cdm
A database-backed CdmReference.
name
Name for the cohort table.
atc_name
ATC classification name(s) to search for. None returns all.
level
ATC hierarchy level(s) to filter by (e.g., "ATC 1st").
gap_era
Days for era collapse.
subset_cohort
Restrict to persons in this cohort.
subset_cohort_id
Restrict to specific IDs within subset cohort.
number_exposures
Track number of exposures per era.
days_prescribed
Track days prescribed per era.
Returns¶
CdmReference The CDM with a new CohortTable.
erafy_cohort(
cohort: CohortTable,
gap_era: int,
*,
cohort_id: list[int] | None = None,
name: str | None = None,
) -> CohortTable
Collapse cohort records into eras.
Records separated by at most gap_era days are merged into a
single era per (cohort_definition_id, subject_id) group.
Parameters¶
cohort The cohort to era-fy. gap_era Maximum gap in days for merging records. cohort_id If provided, only era-fy these cohort definition IDs. name Name for the resulting cohort table.
Returns¶
CohortTable New cohort with collapsed eras.
Daily Dose¶
Compute standardised daily doses from the drug_strength table using
pattern-matched formulas and unit conversions.
add_daily_dose(
x: CdmTable,
cdm: CdmReference | None = None,
*,
ingredient_concept_id: int,
name: str | None = None,
) -> CdmTable
Add daily dose and unit columns to a drug exposure table.
Joins the input table with drug_strength, matches against known
drug strength patterns, standardises units, and applies the appropriate
dose calculation formula.
The input table must have the following columns:
drug_concept_id, drug_exposure_start_date,
drug_exposure_end_date, quantity.
Parameters¶
x
A CdmTable (typically drug_exposure or a subset thereof).
cdm
The CdmReference. If None, uses x.cdm.
ingredient_concept_id
The concept ID of the active ingredient to compute dose for.
Used to filter drug_strength to the relevant ingredient.
name
Unused (kept for API compatibility).
Returns¶
CdmTable
The input table with added daily_dose (Float64) and unit
(Utf8) columns.
Inspect the drug_strength table and return matched patterns.
Joins drug_strength with the known pattern table and returns a
summary of which patterns are present and whether formulas are valid.
Parameters¶
cdm A database-backed CdmReference.
Returns¶
pl.DataFrame DataFrame with pattern_id, formula_name, unit, and counts.
Requirement / Filter Functions¶
Filter drug cohorts by temporal or logical criteria. Each function records attrition in the cohort metadata.
require_is_first_drug_entry(
cohort: CohortTable,
*,
cohort_id: list[int] | None = None,
name: str | None = None,
) -> CohortTable
Keep only the first cohort entry per subject per cohort definition.
Parameters¶
cohort A CohortTable (typically from drug cohort generation). cohort_id If provided, only apply to these cohort definition IDs. name Name for the resulting cohort table.
Returns¶
CohortTable Filtered cohort with only first entries.
require_prior_drug_washout(
cohort: CohortTable,
days: int | float,
*,
cohort_id: list[int] | None = None,
name: str | None = None,
) -> CohortTable
Require a minimum washout period before each drug entry.
Drops records where fewer than days have passed since the previous
cohort entry ended. If days is inf, delegates to
:func:require_is_first_drug_entry.
Parameters¶
cohort
A CohortTable.
days
Minimum days between prior entry end and current entry start.
Use float('inf') for first-entry-only.
cohort_id
If provided, only apply to these cohort definition IDs.
name
Name for the resulting cohort table.
Returns¶
CohortTable Filtered cohort.
require_observation_before_drug(
cohort: CohortTable,
days: int,
*,
cdm: object | None = None,
cohort_id: list[int] | None = None,
name: str | None = None,
) -> CohortTable
Require minimum prior observation before drug entry.
Drops records with fewer than days of observation before the
cohort start date.
Parameters¶
cohort
A CohortTable.
days
Minimum days of prior observation required.
cdm
Optional CdmReference (used to access observation_period if cohort
doesn't already have prior_observation). If not provided, uses
cohort.cdm.
cohort_id
If provided, only apply to these cohort definition IDs.
name
Name for the resulting cohort table.
Returns¶
CohortTable Filtered cohort.
require_drug_in_date_range(
cohort: CohortTable,
date_range: tuple[str | date | None, str | date | None],
*,
index_date: str = "cohort_start_date",
cohort_id: list[int] | None = None,
name: str | None = None,
) -> CohortTable
Require that the drug entry falls within a date range.
Parameters¶
cohort
A CohortTable.
date_range
(start, end) tuple. Either can be None for no bound.
Dates can be strings ("YYYY-MM-DD") or datetime.date.
index_date
Column to check against the range. Default is "cohort_start_date".
cohort_id
If provided, only apply to these cohort definition IDs.
name
Name for the resulting cohort table.
Returns¶
CohortTable Filtered cohort.
Add Drug Use Metrics¶
Enrich a drug cohort with computed utilisation columns. All functions
return a new CohortTable with additional columns.
add_drug_utilisation(
cohort: CohortTable,
gap_era: int,
*,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
ingredient_concept_id: int | None = None,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
number_exposures: bool = True,
number_eras: bool = True,
days_exposed: bool = True,
days_prescribed: bool = True,
time_to_exposure: bool = True,
initial_exposure_duration: bool = True,
initial_quantity: bool = True,
cumulative_quantity: bool = True,
initial_daily_dose: bool = True,
cumulative_dose: bool = True,
name: str | None = None,
) -> CohortTable
Add all drug utilisation metrics to a drug cohort.
This is the all-in-one convenience wrapper. Each metric can be toggled individually via the boolean parameters.
Parameters¶
cohort
A CohortTable (typically from drug cohort generation).
gap_era
Maximum gap in days for era collapse (used by number_eras
and days_exposed).
concept_set
Named concept set mapping. If None, inferred from the
cohort's codelist.
ingredient_concept_id
Ingredient concept ID for dose calculations. Required if
initial_daily_dose or cumulative_dose is True.
index_date
Column for the start of the observation window.
censor_date
Column for the end of the observation window.
restrict_incident
If True, only exposures starting within the window are
counted. If False, any overlapping exposure is included.
number_exposures, number_eras, days_exposed, days_prescribed,
time_to_exposure, initial_exposure_duration, initial_quantity,
cumulative_quantity, initial_daily_dose, cumulative_dose
Metric flags.
name
Unused (reserved for API compatibility).
Returns¶
CohortTable The cohort with metric columns added.
add_number_exposures(
cohort: CohortTable,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
*,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add the number of original drug exposure records per era.
Counts drug_exposure records within the [index_date, censor_date]
window for each person and concept set entry.
Parameters¶
cohort
A CohortTable.
concept_set
Named concept set. If None, inferred from the cohort codelist.
index_date
Start of observation window.
censor_date
End of observation window.
restrict_incident
Only count exposures starting within the window.
name
Unused.
Returns¶
CohortTable
Cohort with number_exposures_{concept_name} column(s).
add_number_eras(
cohort: CohortTable,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
*,
gap_era: int = 0,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add the number of exposure eras (after collapse) per person.
Collapses overlapping/adjacent drug_exposure records separated by
at most gap_era days, then counts the resulting eras.
Parameters¶
cohort A CohortTable. concept_set Named concept set. gap_era Gap in days for era collapse. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with number_eras_{concept_name} column(s).
add_days_exposed(
cohort: CohortTable,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
*,
gap_era: int = 0,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add total days exposed (era-based) within the observation window.
Collapses exposures into eras, clips to the window, and sums the covered days.
Parameters¶
cohort A CohortTable. concept_set Named concept set. gap_era Gap in days for era collapse. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with days_exposed_{concept_name} column(s).
add_days_prescribed(
cohort: CohortTable,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
*,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add total days prescribed (raw exposure-based) within the window.
Sums the clipped duration of each original drug_exposure record
without era collapse. Overlapping records contribute independently,
so the total may exceed calendar days.
Parameters¶
cohort A CohortTable. concept_set Named concept set. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with days_prescribed_{concept_name} column(s).
add_time_to_exposure(
cohort: CohortTable,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
*,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add days from index date to first drug exposure start.
Returns 0 if the first exposure starts on or before the index
date. Returns None if no exposure is found.
Parameters¶
cohort A CohortTable. concept_set Named concept set. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with time_to_exposure_{concept_name} column(s).
add_initial_exposure_duration(
cohort: CohortTable,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
*,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add the duration of the first drug exposure record.
If multiple records share the same earliest start date, the longest duration is used.
Parameters¶
cohort A CohortTable. concept_set Named concept set. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with initial_exposure_duration_{concept_name} column(s).
add_initial_quantity(
cohort: CohortTable,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
*,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add the quantity from the first drug exposure record.
If multiple records share the same earliest start date, quantities are summed.
Parameters¶
cohort A CohortTable. concept_set Named concept set. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with initial_quantity_{concept_name} column(s).
add_cumulative_quantity(
cohort: CohortTable,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
*,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add cumulative quantity across all drug exposure records.
Parameters¶
cohort A CohortTable. concept_set Named concept set. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with cumulative_quantity_{concept_name} column(s).
add_initial_daily_dose(
cohort: CohortTable,
ingredient_concept_id: int,
*,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add the daily dose of the first drug exposure record.
Uses the drug_strength table and dose calculation formulas to
compute the daily dose for the initial exposure.
Parameters¶
cohort A CohortTable. ingredient_concept_id Ingredient concept ID for dose lookup. concept_set Named concept set. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with initial_daily_dose_{concept_name} column(s).
add_cumulative_dose(
cohort: CohortTable,
ingredient_concept_id: int,
*,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
name: str | None = None,
) -> CohortTable
Add cumulative dose across all drug exposure records.
Computes sum(daily_dose * exposure_duration) across all records
in the observation window.
Parameters¶
cohort A CohortTable. ingredient_concept_id Ingredient concept ID for dose lookup. concept_set Named concept set. index_date, censor_date Observation window. restrict_incident Only consider exposures starting within the window. name Unused.
Returns¶
CohortTable
Cohort with cumulative_dose_{concept_name} column(s).
add_drug_restart(
cohort: CohortTable,
switch_cohort_table: str | CohortTable,
*,
cdm: CdmReference | None = None,
switch_cohort_id: list[int] | None = None,
follow_up_days: int | float | list[int | float] = float(
"inf"
),
censor_date: str | None = None,
incident: bool = True,
name: str | None = None,
) -> CohortTable
Add drug restart/switch classification after cohort exit.
Checks whether, after each cohort entry ends, the patient restarts the same drug or switches to an alternative drug within a follow-up window.
Parameters¶
cohort
A CohortTable.
switch_cohort_table
Name of the switch/alternative cohort table in the CDM, or a
CohortTable directly.
cdm
CDM reference. If None, uses cohort.cdm.
switch_cohort_id
Which cohort definition IDs in the switch table to consider.
None = all.
follow_up_days
Follow-up window(s) in days. Can be a single value or a list.
Use float('inf') for unlimited.
censor_date
Column name for censoring. If None, uses observation period
end date.
incident
If True, switch must start after cohort end (incident).
If False, switch can have started before cohort end.
name
Unused.
Returns¶
CohortTable
Cohort with drug_restart_{follow_up_days} column(s) containing
values: "restart", "switch", "restart and switch",
or "untreated".
Add Intersect¶
Enrich a cohort with indication or treatment flags from other cohorts.
add_indication(
cohort: CohortTable,
indication_cohort_name: str | CohortTable,
*,
cdm: CdmReference | None = None,
indication_cohort_id: list[int] | None = None,
indication_window: Window | list[Window] = (0, 0),
unknown_indication_table: str | list[str] | None = None,
index_date: str = "cohort_start_date",
censor_date: str | None = None,
mutually_exclusive: bool = True,
name_style: str | None = None,
name: str | None = None,
) -> CohortTable
Add indication columns to a drug cohort.
Checks whether each subject had a matching indication (was present in
the indication cohort) within the specified indication_window
relative to the index_date.
Parameters¶
cohort
A CohortTable.
indication_cohort_name
Name of the indication cohort table in the CDM, or a CohortTable.
cdm
CDM reference. If None, uses cohort.cdm.
indication_cohort_id
Which cohort IDs in the indication table to consider. None = all.
indication_window
Time window(s) relative to index_date (e.g., (-30, 0)).
unknown_indication_table
OMOP clinical table name(s) (e.g., "condition_occurrence") to
detect unknown indications. If None, no unknown detection.
index_date
Reference date column in the cohort.
censor_date
Optional censoring date column.
mutually_exclusive
If True, produce a single character column per window with
combined labels. If False, produce a binary flag column per
(window, indication) pair.
name_style
Column naming template. Supports {window_name} and
{cohort_name} placeholders.
name
Unused (API compatibility).
Returns¶
CohortTable The cohort with indication column(s) added.
Notes¶
When mutually_exclusive=True, the column values are:
- Individual cohort name (e.g.,
"headache") - Combined names (e.g.,
"headache and asthma") "unknown"— not in any indication cohort but found inunknown_indication_table"none"— not in any indication/unknown table
When mutually_exclusive=False, each column is an integer flag (0/1).
add_treatment(
cohort: CohortTable,
treatment_cohort_name: str | CohortTable,
*,
cdm: CdmReference | None = None,
treatment_cohort_id: list[int] | None = None,
window: Window | list[Window] = (0, 0),
index_date: str = "cohort_start_date",
censor_date: str | None = None,
mutually_exclusive: bool = True,
name_style: str | None = None,
name: str | None = None,
) -> CohortTable
Add treatment columns to a drug cohort.
Checks whether each subject was receiving a treatment (present in
the treatment cohort) within the specified window relative to
the index_date.
Parameters¶
cohort
A CohortTable.
treatment_cohort_name
Name of the treatment cohort table in the CDM, or a CohortTable.
cdm
CDM reference. If None, uses cohort.cdm.
treatment_cohort_id
Which cohort IDs in the treatment table to consider. None = all.
window
Time window(s) relative to index_date.
index_date
Reference date column in the cohort.
censor_date
Optional censoring date column.
mutually_exclusive
If True, produce a single character column per window with
combined labels. If False, produce a binary flag column per
(window, treatment) pair.
name_style
Column naming template.
name
Unused (API compatibility).
Returns¶
CohortTable The cohort with treatment column(s) added.
Notes¶
When mutually_exclusive=True, the column values are:
- Individual cohort name (e.g.,
"metformin") - Combined names (e.g.,
"metformin and simvastatin") "untreated"— not in any treatment cohort
When mutually_exclusive=False, each column is an integer flag (0/1).
Summarise Functions¶
Aggregate drug utilisation data into SummarisedResult objects.
summarise_drug_utilisation(
cohort: CohortTable,
gap_era: int,
*,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
ingredient_concept_id: int | None = None,
index_date: str = "cohort_start_date",
censor_date: str = "cohort_end_date",
restrict_incident: bool = True,
strata: list[str | list[str]] | None = None,
number_exposures: bool = True,
number_eras: bool = True,
days_exposed: bool = True,
days_prescribed: bool = True,
time_to_exposure: bool = True,
initial_exposure_duration: bool = True,
initial_quantity: bool = True,
cumulative_quantity: bool = True,
initial_daily_dose: bool = True,
cumulative_dose: bool = True,
estimates: tuple[str, ...] = (
"min",
"q25",
"median",
"q75",
"max",
"mean",
"sd",
"count_missing",
"percentage_missing",
),
) -> SummarisedResult
Summarise drug utilisation metrics as a SummarisedResult.
Calls :func:add_drug_utilisation to enrich the cohort with metric
columns, then aggregates per cohort × strata into distribution
statistics.
Parameters¶
cohort
A CohortTable (typically from drug cohort generation).
gap_era
Maximum gap in days for era collapse.
concept_set
Named concept set. If None, inferred from cohort codelist.
ingredient_concept_id
Ingredient concept ID for dose calculations.
index_date, censor_date
Observation window columns.
restrict_incident
Only count exposures starting within the window.
strata
Stratification columns.
number_exposures, number_eras, days_exposed, days_prescribed,
time_to_exposure, initial_exposure_duration, initial_quantity,
cumulative_quantity, initial_daily_dose, cumulative_dose
Which metrics to include.
estimates
Statistics to compute per metric.
Returns¶
SummarisedResult
With result_type="summarise_drug_utilisation".
summarise_indication(
cohort: CohortTable,
indication_cohort_name: str | CohortTable,
*,
cdm: CdmReference | None = None,
indication_cohort_id: list[int] | None = None,
indication_window: Any = (0, 0),
unknown_indication_table: str | list[str] | None = None,
index_date: str = "cohort_start_date",
censor_date: str | None = None,
mutually_exclusive: bool = True,
strata: list[str | list[str]] | None = None,
) -> SummarisedResult
Summarise indication prevalence across a drug cohort.
Calls :func:add_indication to classify each record's indication,
then computes count and percentage per indication level per
cohort × strata × window.
Parameters¶
cohort
A CohortTable.
indication_cohort_name
Name of the indication cohort table or a CohortTable.
cdm
CDM reference.
indication_cohort_id
Which indication cohort IDs to consider.
indication_window
Time window(s) relative to index_date.
unknown_indication_table
OMOP table name(s) for unknown indication detection.
index_date, censor_date
Reference date columns.
mutually_exclusive
Collapse to labels (True) or keep flags (False).
strata
Stratification columns.
Returns¶
SummarisedResult
With result_type="summarise_indication".
summarise_treatment(
cohort: CohortTable,
treatment_cohort_name: str | CohortTable,
*,
cdm: CdmReference | None = None,
treatment_cohort_id: list[int] | None = None,
window: Any = (0, 0),
index_date: str = "cohort_start_date",
censor_date: str | None = None,
mutually_exclusive: bool = True,
strata: list[str | list[str]] | None = None,
) -> SummarisedResult
Summarise treatment prevalence across a drug cohort.
Calls :func:add_treatment to classify each record's treatment,
then computes count and percentage per treatment level per
cohort × strata × window.
Parameters¶
cohort
A CohortTable.
treatment_cohort_name
Name of the treatment cohort table or a CohortTable.
cdm
CDM reference.
treatment_cohort_id
Which treatment cohort IDs to consider.
window
Time window(s) relative to index_date.
index_date, censor_date
Reference date columns.
mutually_exclusive
Collapse to labels (True) or keep flags (False).
strata
Stratification columns.
Returns¶
SummarisedResult
With result_type="summarise_treatment".
summarise_drug_restart(
cohort: CohortTable,
switch_cohort_table: str | CohortTable,
*,
cdm: CdmReference | None = None,
switch_cohort_id: list[int] | None = None,
follow_up_days: int | float | list[int | float] = float(
"inf"
),
censor_date: str | None = None,
incident: bool = True,
strata: list[str | list[str]] | None = None,
) -> SummarisedResult
Summarise drug restart/switch classification.
Calls :func:add_drug_restart to classify each record, then
computes count and percentage per category per cohort × strata ×
follow-up window.
Parameters¶
cohort
A CohortTable.
switch_cohort_table
Name of switch cohort table or a CohortTable.
cdm
CDM reference.
switch_cohort_id
Which switch cohort IDs to consider.
follow_up_days
Follow-up window(s) in days.
censor_date
Censoring date column.
incident
If True, switch must start after cohort end.
strata
Stratification columns.
Returns¶
SummarisedResult
With result_type="summarise_drug_restart".
summarise_dose_coverage(
cohort: CohortTable,
ingredient_concept_id: int,
*,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
strata: list[str | list[str]] | None = None,
estimates: tuple[str, ...] = (
"min",
"q25",
"median",
"q75",
"max",
"mean",
"sd",
"count_missing",
"percentage_missing",
),
) -> SummarisedResult
Summarise dose coverage (daily dose distribution and missing rate).
Calls :func:add_daily_dose and summarises the resulting
daily_dose column per ingredient.
Parameters¶
cohort
A CohortTable (or CdmTable backed by drug_exposure data).
ingredient_concept_id
Ingredient concept ID for dose lookup.
concept_set
Named concept set. If None, inferred from cohort codelist.
strata
Stratification columns.
estimates
Statistics to compute.
Returns¶
SummarisedResult
With result_type="summarise_dose_coverage".
summarise_proportion_of_patients_covered(
cohort: CohortTable,
*,
concept_set: Codelist
| dict[str, list[int]]
| None = None,
follow_up_days: int = 365,
strata: list[str | list[str]] | None = None,
index_date: str = "cohort_start_date",
) -> SummarisedResult
Summarise proportion of patients covered (PPC) over time.
For each day from 0 to follow_up_days, computes the proportion
of patients still covered by a drug exposure (era) on that day.
Parameters¶
cohort
A CohortTable from drug cohort generation.
concept_set
Named concept set. If None, inferred from cohort codelist.
follow_up_days
Number of days to compute PPC over.
strata
Stratification columns.
index_date
Column for the start of follow-up.
Returns¶
SummarisedResult
With result_type="summarise_proportion_of_patients_covered".
Notes¶
The PPC at day t is defined as:
PPC(t) = n_covered(t) / n_at_risk(t)
where n_at_risk(t) is the number of subjects still under
observation at day t and n_covered(t) is the number still
receiving the drug.
95% Wilson confidence intervals are computed using
:func:scipy.stats.binom when scipy is available.
Table Functions¶
Thin wrappers around vis_omop_table() with domain-specific defaults
for estimate formatting, headers, and grouping.
table_drug_utilisation(
result: SummarisedResult,
*,
type: Literal["gt", "polars"] | None = None,
header: list[str] | None = None,
group_column: list[str] | None = None,
hide: list[str] | None = None,
style: Any | None = None,
) -> Any
Render a drug utilisation summary table.
Parameters¶
result
A SummarisedResult with
result_type="summarise_drug_utilisation".
type
Output format: "gt" for great_tables, "polars" for
DataFrame.
header
Columns to pivot into header. Defaults to
["cdm_name", "cohort_name"].
group_column
Columns for row grouping.
hide
Columns to hide.
style
A TableStyle for styling.
Returns¶
great_tables.GT or polars.DataFrame
table_indication(
result: SummarisedResult,
*,
type: Literal["gt", "polars"] | None = None,
header: list[str] | None = None,
group_column: list[str] | None = None,
hide: list[str] | None = None,
style: Any | None = None,
) -> Any
Render an indication summary table.
Parameters¶
result
A SummarisedResult with
result_type="summarise_indication".
type
Output format.
header
Columns to pivot into header. Defaults to
["cdm_name", "cohort_name"].
group_column
Row grouping columns.
hide
Columns to hide.
style
Table style.
Returns¶
great_tables.GT or polars.DataFrame
table_treatment(
result: SummarisedResult,
*,
type: Literal["gt", "polars"] | None = None,
header: list[str] | None = None,
group_column: list[str] | None = None,
hide: list[str] | None = None,
style: Any | None = None,
) -> Any
Render a treatment summary table.
Parameters¶
result
A SummarisedResult with
result_type="summarise_treatment".
type
Output format.
header
Columns to pivot into header. Defaults to
["cdm_name", "cohort_name"].
group_column
Row grouping columns.
hide
Columns to hide.
style
Table style.
Returns¶
great_tables.GT or polars.DataFrame
table_drug_restart(
result: SummarisedResult,
*,
type: Literal["gt", "polars"] | None = None,
header: list[str] | None = None,
group_column: list[str] | None = None,
hide: list[str] | None = None,
style: Any | None = None,
) -> Any
Render a drug restart summary table.
Parameters¶
result
A SummarisedResult with
result_type="summarise_drug_restart".
type
Output format.
header
Columns to pivot into header. Defaults to
["cdm_name", "cohort_name"].
group_column
Row grouping columns.
hide
Columns to hide.
style
Table style.
Returns¶
great_tables.GT or polars.DataFrame
table_dose_coverage(
result: SummarisedResult,
*,
type: Literal["gt", "polars"] | None = None,
header: list[str] | None = None,
group_column: list[str] | None = None,
hide: list[str] | None = None,
style: Any | None = None,
) -> Any
Render a dose coverage summary table.
Parameters¶
result
A SummarisedResult with
result_type="summarise_dose_coverage".
type
Output format.
header
Columns to pivot into header. Defaults to
["cdm_name"].
group_column
Row grouping columns. Defaults to ["ingredient_name"].
hide
Columns to hide.
style
Table style.
Returns¶
great_tables.GT or polars.DataFrame
table_proportion_of_patients_covered(
result: SummarisedResult,
*,
type: Literal["gt", "polars"] | None = None,
header: list[str] | None = None,
group_column: list[str] | None = None,
hide: list[str] | None = None,
style: Any | None = None,
) -> Any
Render a proportion of patients covered (PPC) table.
Parameters¶
result
A SummarisedResult with
result_type="summarise_proportion_of_patients_covered".
type
Output format.
header
Columns to pivot into header. Defaults to
["cdm_name", "cohort_name"].
group_column
Row grouping columns.
hide
Columns to hide.
style
Table style.
Returns¶
great_tables.GT or polars.DataFrame
Plot Functions¶
Wrappers around bar_plot(), scatter_plot(), and box_plot() with
drug-utilisation-specific defaults.
plot_drug_utilisation(
result: SummarisedResult,
*,
plot_type: str = "boxplot",
facet: str | list[str] | None = None,
colour: str | None = None,
style: Any | None = None,
) -> Any
Plot drug utilisation summary statistics.
Creates box plots or bar charts of drug utilisation metrics (number exposures, days exposed, etc.) across cohorts.
Parameters¶
result
A SummarisedResult with
result_type="summarise_drug_utilisation".
plot_type
"boxplot" or "barplot".
facet
Column(s) for faceting.
colour
Column for colour grouping.
style
A PlotStyle for styling.
Returns¶
plotly.graph_objects.Figure
plot_indication(
result: SummarisedResult,
*,
facet: str | list[str] | None = None,
colour: str | None = None,
style: Any | None = None,
) -> Any
Plot indication prevalence as a bar chart.
Parameters¶
result
A SummarisedResult with
result_type="summarise_indication".
facet
Column(s) for faceting.
colour
Column for colour grouping. Defaults to
"variable_level" (indication name).
style
A PlotStyle for styling.
Returns¶
plotly.graph_objects.Figure
plot_drug_restart(
result: SummarisedResult,
*,
facet: str | list[str] | None = None,
colour: str | None = None,
style: Any | None = None,
) -> Any
Plot drug restart classification as a stacked bar chart.
Parameters¶
result
A SummarisedResult with
result_type="summarise_drug_restart".
facet
Column(s) for faceting.
colour
Column for colour grouping. Defaults to
"variable_level" (restart category).
style
A PlotStyle for styling.
Returns¶
plotly.graph_objects.Figure
plot_proportion_of_patients_covered(
result: SummarisedResult,
*,
facet: str | list[str] | None = None,
colour: str | None = None,
ribbon: bool = True,
style: Any | None = None,
) -> Any
Plot proportion of patients covered (PPC) over time.
Shows the PPC curve with confidence ribbon (if enabled) over the follow-up period.
Parameters¶
result
A SummarisedResult with
result_type="summarise_proportion_of_patients_covered".
facet
Column(s) for faceting.
colour
Column for colour grouping.
ribbon
Show 95% confidence interval ribbon.
style
A PlotStyle for styling.
Returns¶
plotly.graph_objects.Figure
Mock Data & Benchmarking¶
mock_drug_utilisation(
*,
n_cohorts: int = 2,
n_concept_sets: int = 1,
n_strata: int = 0,
seed: int = 42,
) -> SummarisedResult
Generate a mock SummarisedResult for drug utilisation.
Creates synthetic data representative of a
summarise_drug_utilisation() output, useful for testing
table/plot functions without requiring a database.
Parameters¶
n_cohorts Number of cohorts to simulate. n_concept_sets Number of concept sets per cohort. n_strata Number of additional strata (0 = overall only). seed Random seed for reproducibility.
Returns¶
SummarisedResult
With result_type="summarise_drug_utilisation".