Cohort Tables

fyron.cohort helps create patient-level tables suitable for survival analysis and machine learning. It sits between data acquisition and modeling: once FHIR, SQL, imaging, or document features are extracted, cohort helpers validate and combine them into one analysis table.

The cohort table is the contract between extraction and analysis. It should contain one row per analysis unit, stable identifiers, explicit index/follow-up dates, endpoint columns, and covariates that are available at the intended prediction or analysis time.

What This Module Is For

Use fyron.cohort when you already have feature and outcome tables and need to create a reviewable analysis table. It does not decide your inclusion criteria or endpoint definition for you; it helps encode those decisions into explicit joins, survival columns, and validation checks.

Use DataFrame Operations before this step when raw ICD-10, OPS, local code, or date columns need to become explicit feature columns.

When To Use It

Why Cohort Tables Matter

Most downstream functions assume one row per patient or one row per analysis unit. A good cohort table should make these choices explicit:

• unique patient identifier,
• baseline/index date,
• outcome/event date or last follow-up,
• event indicator,
• covariates measured before the outcome,
• no duplicated patient rows unless intentionally modeled.

Cohort Design Checklist

• Define the analysis unit before joining tables.
• Keep raw source identifiers so joins can be audited.
• Separate baseline covariates from outcome-derived columns.
• Build time and event from documented date fields.
• Validate required columns before running survival or ML functions.

API Contract

Imports

from fyron.cohort import (
    build_time_to_event_endpoint,
    build_survival_columns,
    cohort_profile,
    join_cohort_tables,
    validate_cohort_table,
)

Join Features And Outcomes

cohort = join_cohort_tables(
    features_df,
    outcomes_df,
    on="patient_id",
    how="inner",
)

Required and Optional Parameters

Returns a merged DataFrame.

Typical inputs:

Use how="inner" when final analysis requires both features and outcomes. Use left joins during quality control to inspect missing outcomes.

Validate Required Columns

validate_cohort_table(
    cohort,
    required_columns=["patient_id", "age", "stage", "event"],
    id_column="patient_id",
)

Required and Optional Parameters

Returns a validated copy/reference of the DataFrame or raises a clear error.

Validation should be early and loud. It is better to fail at cohort construction than to fit a model on a silently malformed table.

Build Survival Columns

cohort = build_survival_columns(
    cohort,
    start_col="diagnosis_date",
    end_col="last_followup_or_event_date",
    event_col="death_event",
    time_col="time",
)

Required and Optional Parameters

Returns a DataFrame with time_col and event_out_col.

The resulting time and event columns are ready for fyron.survival.

Build Endpoint From Event And Censor Dates

Use build_time_to_event_endpoint when event and censor dates are stored separately. It records both the final endpoint date and whether that date came from an event or censoring.

cohort = build_time_to_event_endpoint(
    cohort,
    index_date_col="baseline_ct_date",
    event_date_col="death_date",
    censor_date_col="last_followup_date",
    time_unit="days",
)

Returned columns include time, event, endpoint_date, and endpoint_source. If an event happens after the censor date, the row is treated as censored at the censor date.

Cohort Profile

profile = cohort_profile(
    cohort,
    id_col="patient_id",
    endpoint_cols=["event"],
    group_col="stage",
)

Use this table before modeling. It summarizes row counts, unique IDs, missing IDs, duplicate ID rows, endpoint counts/rates, and group sizes.

Full Cohort Pattern

from fyron.cohort import (
    build_survival_columns,
    join_cohort_tables,
    validate_cohort_table,
)

cohort = join_cohort_tables(
    features_df,
    outcomes_df,
    on="patient_id",
    how="inner",
)

cohort = build_survival_columns(
    cohort,
    start_col="index_date",
    end_col="last_followup_or_event_date",
    event_col="event",
)

validate_cohort_table(
    cohort,
    required_columns=["patient_id", "time", "event", "age", "risk_score"],
    id_column="patient_id",
)

Quality-Control Checklist

• Confirm patient_id uniqueness.
• Confirm index dates precede outcome/follow-up dates.
• Check missingness before dropping rows.
• Confirm event coding: 1 means event and 0 means censored for survival.
• Keep feature measurement windows before the index/outcome.
• Save cohort-building code with the analysis, not only the final CSV.

Common Downstream Uses

from fyron.survival import plot_kaplan_meier
from fyron import ml

plot_kaplan_meier(cohort, "time", "event", group_col="stage")

result = ml.run_classification_pipeline(
    cohort[["age", "risk_score"]],
    cohort["binary_endpoint"],
)

Return Values

Related Modules

• Preprocessing QC for missingness, imputation, encoding, leakage checks, and split balance.
• Descriptive Analysis for Table 1 and endpoint summaries.
• Survival Analysis for KM, RMST, Cox, and AFT workflows.
• Machine Learning for classification pipelines.