KFRE Library Logo

Changelog

0.1.18

Fixed

  • risk_pred no longer raises UnboundLocalError when inputs for multiple models are supplied at once. Model selection is now resolved a single time with an explicit 8 > 6 > 4 precedence, so the coefficient block and the risk-score adjustment always agree on the chosen model.

  • RiskPredictor.predict_kfre now validates num_vars and raises ValueError for unsupported values (e.g. num_vars=5) instead of falling through and returning None.

  • Unrecognized or missing sex values are no longer silently coerced to female in the batch paths (upcr_uacr, RiskPredictor.predict_kfre). Recognized values are matched case-insensitively (female/f, male/m); unrecognized non-empty values raise a warning and yield NaN.

  • Non-positive uACR values are no longer silently clamped to 1e-6. A non-positive scalar uACR now raises ValueError; in batch inputs, offending rows are set to NaN with a warning.

  • Corrected the direction described in the perform_conversions comments and docstring (the conversion factors themselves were already correct and are unchanged), and documented the single-pass scope of convert_all.

Added

  • bootstrap_metric_ci: bootstrap confidence intervals for any supported metric (auc_roc, average_precision, precision, sensitivity, specificity, brier), with reproducible resampling via seed and a progress bar over resamples.

  • Out-of-bounds covariate warnings in risk_pred: a UserWarning is emitted when covariates fall outside broad, physiologically plausible ranges for the KFRE’s intended population (adults, CKD stages G3-G5). Predictions are still returned. Applies to all public entry points.

  • censor_incomplete option on class_esrd_outcome: when True, non-event patients whose follow-up ends before the horizon are labeled NaN (censored) rather than 0, so right-censored patients can be excluded from fixed-horizon evaluation. Defaults to False to preserve existing behavior.

  • uPCR-to-uACR approximation disclaimer: upcr_uacr now documents that the conversion is an approximation without universal consensus and emits a one-time UserWarning when it produces estimated values.

  • Explicit num_vars override on risk_pred to force a specific model variant (4, 6, or 8) regardless of which optional inputs are present.

  • Regression test suites for input validation, out-of-bounds warnings, and bootstrap confidence intervals.

Changed

  • Docstring and README wording now consistently describes estimating the risk of kidney failure in patients with CKD, rather than “CKD development” or “CKD progression.”

  • class_esrd_outcome documentation corrected: the event indicator is a user-supplied dialysis/transplantation (kidney replacement therapy / ESKD) flag; the function applies a time window to it and does not derive the event from eGFR.

  • Serum measurements labeled explicitly for albumin, phosphorous, bicarbonate, and calcium in the parameter documentation.

Dependencies

  • Re-added tqdm (>= 4.0) as a dependency, now used for the bootstrap_metric_ci progress bar. (It had been removed in 0.1.16.)

Notes

  • No KFRE coefficients or baseline survival values were changed. Risk estimates for valid inputs are identical to 0.1.17.

0.1.17

Added

  • Figure generation utilities for CKD risk distribution by stage (boxplot) and 4-variable vs. 8-variable model comparison (scatter plot)

  • SVG output support for publication-ready figure export

Changed

  • Updated figure save paths to use figures/ directory structure

  • Improved plot saving to support both PNG and SVG formats via image_path_svg

Removed

  • Removed duplicate precision_score import in perform_eval.py

0.1.16

  • Removed unused tqdm import and library dependency

0.1.15

  • Added precision floating point accuracy to ALL functions

  • Updated MIT License for 2025

0.1.14

  • Added precision floating point accuracy to functions

  • Tightened .gitignore with more robust directory structure

  • Added additional tests in new toy_dataset_test.py file.

0.1.13

  • Renamed the show_grid parameter to show_subplots across all performance‐evaluation plotting functions for clarity.

  • Moved example and helper scripts into a new py_scripts/ directory to cleanly separate library code from ad-hoc scripts.

  • Introduced a comprehensive suite of pytest‐based unittests to validate all core functionality.

  • Added an ASCII-art logo that prints on startup when you fire up the library in a terminal.

  • Refreshed the help() output for a cleaner, more focused presentation.

  • Enhanced module documentation in __init__.py to better explain public API and usage.

0.1.12

Patch Release

This release is a comprehensive stable build encompassing changes from version 0.1.8 forward.

  • Package version fix in min_readme.md citation section

  • Python version fix in min_readme.md

  • Python version fix from 3.74 to 3.7.4

  • new functions for classifying outcomes and ckd stages

    • class_esrd_outcome

    • class_ckd_stages

  • new functions for performance assessment

    • plot_kfre_metrics

    • eval_kfre_metrics

      • roc_auc curves

      • precision-recall curves

  • performance metrics:

    • Precision/PPV

    • Average Precision

    • Sensitivity

    • Specificity

    • AUC ROC

    • Brier Score

0.1.11

Patch Release

  • Package version fix in min_readme.md citation section

0.1.10

Patch Release

  • Python version fix in min_readme.md

0.1.9

  • Python version fix from 3.74 to 3.7.4

  • updated functions for classifying outcomes and ckd stages

    • class_esrd_outcome

    • class_ckd_stages

0.1.8

  • Updated docs toc format and published on new site lshpaner.github.io/kfre

  • new functions for classifying outcomes and ckd stages

    • calc_esrd_outcome(),

    • class_ckd_stages(),

  • new functions for performance assessment:
    • plot_kfre_metrics()

      • roc_auc curves

      • precision-recall curves

    • eval_kfre_metrics():

      • Precision/PPV

      • Average PRecision

      • Sensitivity

      • Specificity

      • AUC ROC

      • Brier Score

0.1.7

This release includes the following updates and improvements:

  • Acknowledgements for key influencers whose exceptional work on end-stage kidney disease has greatly inspired the creation of this library.

  • Implemented comprehensive exception handling within the kfre_person() function to ensure proper parameter validation:

    • Combined all exceptions into a single exception.

    • Concatenated exceptions using a newline character for better readability.

    • Added checks to ensure age, is_male, eGFR, and uACR parameters are supplied.

    • Validated that the years parameter can only be 2 or 5.

    • Ensured dm and htn parameters, if provided, are either 0, 1, True, or False.

    • Added a check to ensure is_north_american is specified as either True or False.

0.1.6

This release includes the following updates and improvements:

  • Added version information to the __init__.py file. The version of this release is 0.1.6.

0.1.5

This stable release, kfre 0.1.5, builds directly upon the foundations set in version 0.1.2 and 0.1.4 with no changes to the codebase. The key highlight of this update is a an update of citing version 0.1.5 under citations section on PyPI landing page.

0.1.4

Documentation Enhancements

Core Documentation Migration: All essential documentation has been transferred to this new site, available here at lshpaner.github.io/kfre_docs. This migration enhances accessibility and ease of navigation.

Visual Updates: A new logo has been introduced, now featured on both the documentation site and the PyPI landing page to enhance brand recognition.

Citation Instructions: Detailed guidance on how to properly cite the kfre project has been added, including a direct link to the Zenodo archive for easy reference.

Updated References: All references have been meticulously updated to conform with the latest APA 7 standards.

Note

Why no version 0.1.3? In alignment with common superstitions, version 0.1.3 was skipped, much like how many buildings lack a 13th floor.

0.1.2

This release, kfre 0.1.2, marks a substantial update from the preliminary alpha versions, introducing significant enhancements and features that elevate the tool’s flexibility, accuracy, and ease of use:

Enhanced Core Functionality: A comprehensive overhaul from earlier minimal viable products to a more robust and feature-rich application.

New Calculator Function: The introduction of the kfre_person() function enables risk metrics calculations for individuals one at a time, customizing the analysis to each unique dataset.

Increased Flexibility: The add_kfre_risk_col() function now allows for direct execution of kfre without the need to instantiate a class, simplifying the process for users.

Model Variability: Users can specify models with 4, 6, or 8 variables through the add_kfre_risk_col() function, adapting to different data requirements.

Timeframe Options: The function now accommodates specification of projection years (2 or 5 years, or either), providing tailored risk assessments.

DataFrame Handling: An option to either copy the dataframe or modify it in place when adding kfre columns is now available, offering greater flexibility in data management.

Formula Correction: The formula for the 6-variable calculation has been updated with the correct coefficients from Tangri et al., enhancing prediction accuracy.

Conversion Tools: The new perform_conversions() function facilitates the conversion of relevant clinical metrics, streamlining data preparation for analysis.

This release reflects ongoing efforts to enhance and refine kfre, driven by feedback from users and continuous research into improving its utility and functionality.