Clinical DataFrame Operations

Explicit Date Handling

date_difference, add_date_difference, age_at_date, and add_time_window_flag accept keyword-only errors="coerce" (the existing default) or errors="raise". Coercion makes malformed dates missing. Strict mode rejects malformed values but permits genuinely absent dates. Missing dates yield missing differences and zero time-window flags.

Scalars broadcast against vectors. Vectors must have equal lengths; Series must have identical indices in the same order. Results preserve indices rather than silently aligning unrelated rows. Aware timestamps use UTC elapsed time, including DST offsets. Mixing naive and aware nonmissing dates raises.

Window bounds must be finite and nonnegative. Months mean 30.4375 days and years 365.25 days; age_at_date is elapsed age, not completed birthdays. For event/censor selection and quality flags, use the cohort module, not an absolute date difference that could hide invalid chronology.

fyron.dataframe provides small, explicit helpers for deriving clinical columns from ordinary pandas DataFrames. Use it when you need stable one-hot indicators for delimited code strings or reusable date/time interval columns before cohort construction, phenotyping, preprocessing, survival analysis, or machine learning. ICD-10, OPS, MDC partition, encounter status, and Charlson helpers are also available here for compatibility, with their dedicated home in fyron.clinical_codes.

This module is not a replacement for pandas and it is not a validated terminology ontology. It gives researchers transparent, reviewable feature derivations that can be saved, inspected, and challenged in a study protocol.

Install

uv add fyron

Imports

from fyron import dataframe as fdf

API Contract

When To Use It

Study Pattern

In most projects this module is used early, right after extraction and before statistical modeling:

from fyron import dataframe as fdf

cohort = fdf.add_icd10_disease_groups(cohort, icd_col="icd10_codes")
cohort = fdf.add_ops_categories(cohort, ops_col="ops_codes")
cohort = fdf.age_at_date(
    cohort,
    birth_date_col="birth_date",
    reference_date_col="index_date",
    output_col="age_at_index",
)

code_qc = fdf.icd10_group_prevalence(cohort)

Save both cohort and code_qc. The enriched cohort becomes the modeling table; the prevalence table becomes a lightweight audit artifact for the methods supplement or internal review.

ICD-10 Disease Groups

For new clinical coding work, prefer fyron.clinical_codes. The same ICD-10 helpers remain available here for existing DataFrame workflows.

ICD-10 helpers use broad pragmatic chapter-style groups such as cancer, cardiovascular, respiratory, gastrointestinal, renal/urologic, trauma, external cause, and healthcare encounter. These are useful for quick cohort description and feature engineering, but they should not replace a study-specific phenotype definition or validated comorbidity score.

cohort = fdf.add_icd10_disease_groups(
    cohort,
    icd_col="diagnosis_codes",
    sep=";",
    prefix="icd10_group_",
)

prevalence = fdf.icd10_group_prevalence(cohort)

The output keeps the original diagnosis_codes column and adds binary columns such as icd10_group_cancer, icd10_group_cardiovascular, plus icd10_groups and n_icd10_groups.

Built-In ICD-10 Groups

OPS Procedure Categories

For new OPS/MDC work, prefer fyron.clinical_codes. The same broad OPS category helpers remain available here for existing DataFrame workflows.

German OPS codes are grouped into broad procedure categories: diagnostic procedures, imaging, surgery, medication/therapy, radiation/nuclear medicine, intensive care, rehabilitation, and other. OPS coding can be site-specific, so treat these as transparent research features that still need clinical review.

cohort = fdf.add_ops_categories(
    cohort,
    ops_col="ops_codes",
    sep=";",
    prefix="ops_category_",
)

ops_summary = fdf.ops_category_prevalence(cohort)

Use the summary table in supplements or QC notebooks to check whether procedure features match clinical expectations.

Built-In OPS Categories

Generic Code Columns

Use the generic helpers for medication codes, local registry fields, procedure codes, or any delimited string column where exact code membership matters.

long_codes = fdf.explode_code_column(
    cohort,
    code_col="medication_codes",
    output_col="medication_code",
)

cohort = fdf.add_code_indicators(
    cohort,
    code_col="medication_codes",
    codes=["L01XA01", "L01XA02"],
    prefix="atc_",
)

By default, codes are uppercased and spaces are removed. Dots are preserved unless you pass remove_dots=True through normalize_code directly. Preserve the raw source column alongside derived indicators so reviewers can trace the feature.

For multiple local definitions, pass a mapping. This gives stable, readable output names without repeating code lists across notebooks.

cohort = fdf.add_code_indicators(
    cohort,
    code_col="procedure_codes",
    codes={
        "has_biopsy": ["1-440", "1-444"],
        "has_resection": ["5-324", "5-325"],
    },
    prefix="proc_",
)

Date And Time Features

Date helpers use the same clinical time-unit convention as cohort endpoint helpers: months are 30.4375 days and years are 365.25 days.

cohort = fdf.add_date_difference(
    cohort,
    start_col="baseline_ct_date",
    end_col="surgery_date",
    output_col="days_ct_to_surgery",
    unit="days",
    allow_negative=False,
)

cohort = fdf.age_at_date(
    cohort,
    birth_date_col="birth_date",
    reference_date_col="baseline_ct_date",
    output_col="age_at_ct",
)

cohort = fdf.add_time_window_flag(
    cohort,
    date_col="biopsy_date",
    index_date_col="baseline_ct_date",
    output_col="biopsy_within_30d",
    before=30,
    after=30,
)

add_time_window_flag computes the event date relative to the index date. Negative values are before the index, positive values are after the index.

Function Guide

Common Pitfalls

• Broad ICD-10 and OPS groups are feature-engineering assumptions, not validated disease ontologies.
• Keep raw code columns and code-system metadata whenever possible.
• Use prefixed indicator columns to avoid spaces and slashes in downstream ML formulas.
• Check whether repeated codes should count once per patient or once per event before exploding.
• Define the index date before creating time-window flags.
• Use allow_negative=False when a negative interval indicates a data error for the study.

Related Modules

• FHIR REST extracts source resources that often contain ICD, OPS, medication, and observation codes.
• Clinical Codes is the dedicated namespace for ICD-10, OPS, MDC partition, encounter status, and Charlson helpers.
• Phenotyping builds explicit rule-based patient flags from code, lab, and medication tables.
• Cohort Tables joins derived features with endpoints and validates cohort shape.
• Preprocessing QC handles imputation, train/test encoding, and leakage checks after feature derivation.
• Machine Learning trains and evaluates models once a cohort table and feature matrix are ready.