KFRE: Kidney Failure Risk Estimator

kfre is a Python library designed to estimate the risk of chronic kidney disease (CKD) progression over two distinct timelines: 2 years and 5 years. Using Tangri's Kidney Failure Risk Equation (KFRE), the library provides tools for healthcare professionals and researchers to predict CKD risk based on patient data. It supports predictions for both males and females and includes specific adjustments for individuals from North American and non-North American regions.

Features
Prerequisites
Installation
Usage Guide
Contributor/Maintainer
License
Support
References

Features

Risk Prediction: Utilize Tangri's validated risk prediction model to estimate kidney failure risk using
- 4 variables: sex, age, eGFR, uACR (log-normalized)
- 6 variables: sex, age, eGFR, uACR (log-normalized), diabetes mellitus, hypertension
- 8 variables: sex, age, eGFR, uACR (log-normalized), serum albumin, serum phosphorous, serum calcium, and serum bicarbonate.
Data Flexibility: Handles various input data formats and maps them to required model parameters.
Conversion Utilities: Includes functions to convert common laboratory results to the required units for risk prediction.

Important Note on Data Units

The kfre library requires precise data input, with clear specification of the units for each variable. The variables can be expressed in multiple units, and it's crucial that the data being used clearly delineates which units the variables are expressed in. For instance:

uACR (Urinary Albumin-Creatinine Ratio) can be expressed in either mg/g or mg/mmol.
Albumin levels can be measured in g/dL or g/L.
Phosphorous levels can be noted in mg/dL or mmol/L.
Bicarbonate can be recorded in mEq/L or mmol/L.
Calcium can be documented in mg/dL or mmol/L.

This flexibility allows the library to be used with a variety of clinical data sources, enhancing its applicability across different healthcare settings.

Prerequisites

Before you install kfre, ensure you have the following:

Python: Python 3.6 or higher is required to run kfre.

Additionally, kfre has the following package dependencies:

NumPy: Version 1.18.5 or higher
Pandas: Version 1.0.5 or higher

These dependencies will be automatically installed when you install kfre using pip.

Installation

You can install kfre directly from PyPI:

pip install kfre

Usage Guide

Single Patient Risk Calculation

The kfre library offers a flexible and user-friendly interface to estimate the risk of kidney failure for individual patients using Tangri's KFRE model. With kfre, you can calculate the risk using the classic 4-variable model, the detailed 8-variable model, and, uniquely, a 6-variable model that is not commonly found in online calculators.

`kfre_person`

risk_percentage = kfre_person(
    age=57.28,
    is_male=False,
    eGFR=15.0,
    uACR=1762.001840,
    is_north_american=False,
    years=2,
    dm=None,
    htn=None,
    albumin=None,
    phosphorous=None,
    bicarbonate=None,
    calcium=None
) * 100  # Convert to percentage

Parameters:

age (float): The age of the patient in years.
is_male (bool): Indicates if the patient is male. False indicates a female patient.
eGFR (float): Estimated Glomerular Filtration Rate in mL/min/1.73 m², indicating kidney function.
uACR (float): Urinary Albumin to Creatinine Ratio in mg/g, indicating kidney damage.
is_north_american (bool): Specifies whether the patient is from North America, affecting model constants.
years (int): The time frame in years (2 or 5) over which the risk assessment is projected.
dm (float, optional): Diabetes mellitus status (1 if present, 0 if not). Required for the 6-variable model.
htn (float, optional): Hypertension status (1 if present, 0 if not). Required for the 6-variable model.
albumin (float, optional): Serum albumin level in g/dL. Required for the 8-variable model.
phosphorous (float, optional): Serum phosphorus level in mg/dL. Required for the 8-variable model.
bicarbonate (float, optional): Serum bicarbonate level in mEq/L. Required for the 8-variable model.
calcium (float, optional): Serum calcium level in mg/dL. Required for the 8-variable model.

Returns:

float: The risk of developing CKD within the specified timeframe, as a decimal. Multiply by 100 to convert to a percentage.

Description:

The kfre_person function allows for detailed, personalized risk assessments based on a range of clinical parameters. Depending on the completeness of the data provided, the function can apply a basic 4-variable model or more comprehensive models incorporating additional risk factors like diabetes, hypertension, and various biochemical markers.

The function is designed for ease of use in clinical settings or research, providing immediate risk estimations that are crucial for patient management or further analysis.

Example Calculation for 2-year and 5-year Risk

Here's how to estimate the 2-year and 5-year kidney failure risk for a hypothetical 57.28-year-old female who is not from North America and has specific clinical characteristics:

from kfre import kfre_person

for years in [2, 5]:
    risk_percentage = (
        kfre_person(
            age=57.28,
            is_male=False,  # is the patient male?
            eGFR=15.0,  # ml/min/1.73 m^2
            uACR=1762.001840,  # mg/g
            is_north_american=False,  # is the patient from North America?
            years=years,
            ####################################################################
            # Uncomment "dm" and "htn" for the 6-variable model:
            ####################################################################
            # dm=0,
            # htn=1,
            ####################################################################
            # Comment out "dm" and "htn" and uncomment the following lines for
            # the 8-variable model:
            ####################################################################
            # albumin=3.0, # g/dL
            # phosphorous=3.162, # mg/dL
            # bicarbonate=21.3, # mEq/L
            # calcium=9.72, # mg/dL
        )
        * 100  # multiply by 100 to convert to percentage
    )

    message = f"The {years}-year risk of kidney failure for this patient is"
    print(f"{message} {risk_percentage:.2f}%.")

The 2-year risk of kidney failure for this patient is 44.66%.
The 5-year risk of kidney failure for this patient is 89.89%.

Ensure to:

Uncomment dm and htn if you are using the 6-variable KFRE model.
For the 8-variable KFRE, keep dm and htn commented out and instead, uncomment the albumin, phosphorous, bicarbonate, and calcium variables.

Batch Risk Calculation for Multiple Patients

The kfre library provides the functionality to perform batch processing of patient data, allowing for the computation of kidney failure risk predictions across multiple patients in a single operation. This capability is especially valuable for researchers and clinicians needing to assess risks for large cohorts or patient groups.

Key Features

When using the add_kfre_risk_col function, the library will append new columns for each specified variable model (4-variable, 6-variable, 8-variable) and each time frame (2 years, 5 years) directly to the original DataFrame. This facilitates a seamless integration of risk predictions into existing patient datasets without the need for additional data manipulation steps.

Disclaimer

The kfre library is designed to facilitate risk prediction using Tangri's KFRE model based on a given set of patient data. It is crucial to ensure that all patient data within a batch calculation are consistent in terms of regional categorization—that is, either all North American or all non-North American. To this end, it is crucial to ensure that all patient data within a batch calculation are consistent in terms of regional categorization. Mixing patient data from different regions within a single batch is not supported, as the function is set to apply one regional coefficient set at a time. This approach ensures the accuracy and reliability of the risk predictions.

Example Usage:

Here is how to perform batch risk calculations for a group of non-North American patients. Note the importance of maintaining consistency in regional data:

Note: The following is a mock example using simulated DataFrame structures to illustrate the function usage.

## Note: Ensure that the units for each laboratory value are consistent with
# your model's requirements.

# mock dataframe example
data = pd.DataFrame(
    {
        "Age": [65, 70, 60, 75,

Kfre

Install / Use

README