Clinical DataFrame Operations

fyron.dataframe provides small, explicit helpers for deriving clinical columns from ordinary pandas DataFrames. Use it when you need ICD-10 disease-group indicators, German OPS procedure categories, stable one-hot indicators for delimited code strings, or reusable date/time interval columns before cohort construction, phenotyping, preprocessing, survival analysis, or machine learning.

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

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

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.
• 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.