updated changelog to latest releases, changed classifiying esrd outco…

…mes header

docs/_sources/changelog.rst.txt

@@ -26,6 +26,51 @@
 Changelog
 =========
 
+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
 -----
 
@@ -48,17 +93,18 @@ Changelog
 0.1.7
 -----
 
-This release includes the following updates and improvements:
+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.   
 
-- 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:  
 
-- 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``.
+  - 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

docs/_sources/citations.rst.txt

@@ -25,7 +25,7 @@
 Citing KFRE
 ============
 
-Shpaner, L. (2024). kfre: A Python Library for Reproducing Kidney Failure Risk Equations (KFRE) (0.1.8). Zenodo. https://doi.org/10.5281/zenodo.11100222
+Shpaner, L. (2024). kfre: A Python Library for Reproducing Kidney Failure Risk Equations (KFRE) (0.1.12). Zenodo. https://doi.org/10.5281/zenodo.11100222
 
 
 .. code:: bash

docs/_sources/references.rst.txt

@@ -27,11 +27,12 @@ The ``kfre`` library is based on the risk prediction models developed in the fol
 References
 ===========
 
-Ali, I., Donne, R. L., & Kalra, P. A. (2021). A validation study of the kidney failure risk equation in advanced chronic kidney disease according to disease aetiology with evaluation of discrimination, calibration and clinical utility. *BMC Nephrology, 22(1),* 194.  doi: 10.1186/s12882-021-02402-1
+Ali, I., Donne, R. L., & Kalra, P. A. (2021). A validation study of the kidney failure risk equation in advanced chronic kidney disease according to disease aetiology with evaluation of discrimination, calibration and clinical utility. *BMC Nephrology, 22(1),* 194. https://doi.org/10.1186/s12882-021-02402-1 [1]_
 
 Sumida, K., Nadkarni, G. N., Grams, M. E., Sang, Y., Ballew, S. H., Coresh, J., Matsushita, K., Surapaneni, A., Brunskill, N., Chadban, S. J., Chang, A. R., Cirillo, M., Daratha, K. B., Gansevoort, R. T., Garg, A. X., Iacoviello, L., Kayama, T., Konta, T., Kovesdy, C. P., Lash, J., Lee, B. J., Major, R. W., Metzger, M., Miura, K., Naimark, D. M. J., Nelson, R. G., Sawhney, S., Stempniewicz, N., Tang, M., Townsend, R. R., Traynor, J. P., Valdivielso, J. M., Wetzels, J., Polkinghorne, K. R., & Heerspink, H. J. L. (2020). Conversion of urine protein-creatinine ratio or urine dipstick protein to urine albumin-creatinine ratio for use in chronic kidney disease screening and prognosis. *Annals of Internal Medicine, 173* (6), 426-435. https://doi.org/10.7326/M20-0529
 
 Tangri, N., Grams, M. E., Levey, A. S., Coresh, J., Appel, L. J., Astor, B. C., Chodick, G., Collins, A. J., Djurdjev, O., Elley, C. R., Evans, M., Garg, A. X., Hallan, S. I., Inker, L. A., Ito, S., Jee, S. H., Kovesdy, C. P., Kronenberg, F., Heerspink, H. J. L., Marks, A., Nadkarni, G. N., Navaneethan, S. D., Nelson, R. G., Titze, S., Sarnak, M. J., Stengel, B., Woodward, M., Iseki, K., & for the CKD Prognosis Consortium. (2016). Multinational assessment of accuracy of equations for predicting risk of kidney failure: A meta-analysis. *JAMA, 315* (2), 164–174. https://doi.org/10.1001/jama.2015.18202
 
 Tangri, N., Stevens, L. A., Griffith, J., Tighiouart, H., Djurdjev, O., Naimark, D., Levin, A., & Levey, A. S. (2011). A predictive model for progression of chronic kidney disease to kidney failure. *JAMA, 305* (15), 1553-1559. https://doi.org/10.1001/jama.2011.451
 
+.. [1] This article is licensed under a Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/. The Creative Commons Public Domain Dedication waiver (http://creativecommons.org/publicdomain/zero/1.0/) applies to the data made available in this article, unless otherwise stated.

docs/_sources/usage_guide.rst.txt

@@ -244,7 +244,9 @@ These parameters provide the flexibility to tailor the unit conversion process t
 
 The following is an example to illustrate the usage of the ``perform_conversions`` function. This example shows how to convert values from mmol to mg for various clinical parameters within a DataFrame.
 
-.. table:: First 5 Rows of Biochemical Data (Adapted from Ali et al., 2021, BMC Nephrol)
+`First 5 Rows of Biochemical Data (Adapted from Ali et al., 2021, BMC Nephrol)` [1]_.
+
+.. table:: 
 
    ====== =================== ================ ==================
    uPCR   Calcium (mmol/L)    Albumin (g/l)    Phosphate (mmol/L)
@@ -286,13 +288,7 @@ The following is an example to illustrate the usage of the ``perform_conversions
     Converted 'Albumin (g/l)' to new column 'Albumin_g_dl' with factor 0.1
 
 
-.. raw:: html
-
-    <div style="text-align: left; margin-bottom: 10px;">
-    <i>
-    First 5 Rows of Biochemical Data with Conversions (Adapted from Ali et al., 2021, BMC Nephrol)
-    </i>
-    </div>
+`First 5 Rows of Biochemical Data with Conversions (Adapted from Ali et al., 2021, BMC Nephrol)` [1]_.
 
 .. table:: 
    :align: left
@@ -353,8 +349,8 @@ The ``upcr_uacr`` function is typically used in clinical data processing where a
     744            NaN
     Name: uACR, Length: 745, dtype: float64
 
-Classifying ESRD Outcome by 2 and 5 Year Outcomes
-=================================================
+Classifying ESRD Outcomes
+=========================
 
 .. code-block:: python
 
@@ -403,13 +399,7 @@ This function creates a new column in the DataFrame which is populated with a ``
     )
 
 
-.. raw:: html
-
-    <div style="text-align: left; margin-bottom: 10px;">
-    <i>
-    First 5 Rows of Outcome Data
-    </i>
-    </div>
+`First 5 Rows of Outcome Data (Adapted from Ali et al., 2021, BMC Nephrol)` [1]_.
 
 .. table:: 
    :align: left
@@ -512,19 +502,10 @@ This function is designed to compute the risk of chronic kidney disease (CKD) ov
     # The resulting DataFrame 'df' now includes new columns with risk 
     # predictions for each model and time frame
 
-.. raw:: html
 
-    <div style="text-align: left;">
-
-    <i>
-    First 5 Rows of Kidney Failure Risk Data (Adapted from Ali et al., 2021, BMC Nephrol) <br> 
-    </i>
-
-    <br>
+`First 5 Rows of Kidney Failure Risk Data (Adapted from Ali et al., 2021, BMC Nephrol)` [1]_.
 
-    </div>
-
-.. table::
+.. table:: 
    :align: left
 
    ======== ====== ======================== ========================== ========= ============ ================ ================ ================ ================ ================ ================ ================ ================  
@@ -538,10 +519,31 @@ This function is designed to compute the risk of chronic kidney disease (CKD) ov
    ======== ====== ======================== ========================== ========= ============ ================ ================ ================ ================ ================ ================ ================ ================ 
 
 
-
 Performance Assessment
 =======================
 
+AUC ROC & Precision-Recall Curves
+---------------------------------
+
+.. raw:: html
+
+   <div class="no-click">
+
+.. image:: ../assets/performance_grid.svg
+   :alt: AUC_ROC_and_Precision_Recall
+   :align: left
+   :width: 900px
+
+.. raw:: html
+
+   </div>
+
+.. raw:: html
+
+   <div style="height: 106px;"></div>
+
+\
+
 .. function:: plot_kfre_metrics(df, num_vars, fig_size=(12, 6), mode="both", image_path_png=None, image_path_svg=None, image_prefix=None, bbox_inches="tight", plot_type="all_plots", save_plots=False, show_years=[2, 5], plot_combinations=False, show_grids=False, decimal_places=2)
 
     :param DataFrame df: The input DataFrame containing the necessary columns for truth and predictions.
@@ -597,67 +599,8 @@ This function generates the true labels and predicted probabilities for 2-year a
     )
 
 
-AUC ROC & Precision-Recall Curves
----------------------------------
-
-.. raw:: html
-
-   <div class="no-click">
-
-.. image:: ../assets/performance_grid.svg
-   :alt: AUC_ROC_and_Precision_Recall
-   :align: left
-   :width: 900px
-
-.. raw:: html
-
-   </div>
-
-.. raw:: html
-
-   <div style="height: 106px;"></div>
-
-\
-
-
-.. function:: eval_kfre_metrics(df, n_var_list, outcome_years=[2, 5], decimal_places=6)
-
-    :param DataFrame df: The input DataFrame containing the necessary columns for truth and predictions. Rows with NaN values will be dropped.
-    :param list of int n_var_list: List of variable numbers to consider, e.g., ``[4, 6, 8]``.
-    :param list, tuple, or int outcome_years: (`optional`) List, tuple, or single year to consider for outcomes. Default is ``[2, 5]``.
-    :param int decimal_places: (`optional`) Number of decimal places for the calculated metrics. Default is ``6``.
-
-    :returns: ``pd.DataFrame``: A DataFrame containing the calculated metrics for each outcome.
-
-    :raises: ``ValueError``: If required outcome columns are missing in the DataFrame.  
-              ``ValueError``: If an invalid variable number is provided in ``n_var_list``.
-
-    This function computes a set of performance metrics for multiple binary classification models given the true labels and the predicted probabilities for each outcome. The metrics calculated include precision (positive predictive value), average precision, sensitivity (recall), specificity, AUC ROC, and Brier score.
-
-    Notes:
-        - Precision is calculated with a threshold of `0.5` for the predicted probabilities.   
-        - Sensitivity is also known as recall.  
-        - Specificity is calculated as the recall for the negative class.  
-        - AUC ROC is calculated using the receiver operating characteristic curve.  
-        - Brier score measures the mean squared difference between predicted probabilities and the true binary outcomes.  
-
-**Example Usage**
-
-.. code-block:: python
-
-    from kfre import eval_kfre_metrics
-
-
-.. code-block:: python
-
-    metrics_df_n_var = eval_kfre_metrics(
-        df=df,                 # Metrics-ready DataFrame as the first argument
-        n_var_list=[4, 6, 8],  # Specify the list of variable numbers to consider
-        outcome_years=[2, 5],  # Specify the list of outcome years to consider
-    )
-
-Performance Metrics Explained
------------------------------
+Performance Metrics
+--------------------
 
 This section explains the various performance metrics calculated by the `eval_kfre_metrics` function.
 
@@ -733,4 +676,47 @@ Where:
     - :math:`N` is the number of total observations.  
     - :math:`f_i` is the predicted probability for the :math:`i`-th observation.  
     - :math:`o_i` is the actual outcome for the :math:`i`-th observation (`0` or `1`).
+
+
+----
+
+.. function:: eval_kfre_metrics(df, n_var_list, outcome_years=[2, 5], decimal_places=6)
+
+    :param DataFrame df: The input DataFrame containing the necessary columns for truth and predictions. Rows with NaN values will be dropped.
+    :param list of int n_var_list: List of variable numbers to consider, e.g., ``[4, 6, 8]``.
+    :param list, tuple, or int outcome_years: (`optional`) List, tuple, or single year to consider for outcomes. Default is ``[2, 5]``.
+    :param int decimal_places: (`optional`) Number of decimal places for the calculated metrics. Default is ``6``.
+
+    :returns: ``pd.DataFrame``: A DataFrame containing the calculated metrics for each outcome.
+
+    :raises: ``ValueError``: If required outcome columns are missing in the DataFrame.  
+              ``ValueError``: If an invalid variable number is provided in ``n_var_list``.
+
+    This function computes a set of performance metrics for multiple binary classification models given the true labels and the predicted probabilities for each outcome. The metrics calculated include precision (positive predictive value), average precision, sensitivity (recall), specificity, AUC ROC, and Brier score.
+
+    Notes:
+        - Precision is calculated with a threshold of `0.5` for the predicted probabilities.   
+        - Sensitivity is also known as recall.  
+        - Specificity is calculated as the recall for the negative class.  
+        - AUC ROC is calculated using the receiver operating characteristic curve.  
+        - Brier score measures the mean squared difference between predicted probabilities and the true binary outcomes.  
+
+**Example Usage**
+
+.. code-block:: python
+
+    from kfre import eval_kfre_metrics
+
+
+.. code-block:: python
+
+    metrics_df_n_var = eval_kfre_metrics(
+        df=df,                 # Metrics-ready DataFrame as the first argument
+        n_var_list=[4, 6, 8],  # Specify the list of variable numbers to consider
+        outcome_years=[2, 5],  # Specify the list of outcome years to consider
+    )
+
+
+----
 
+.. [1] Ali, I., Donne, R. L., & Kalra, P. A. (2021). A validation study of the kidney failure risk equation in advanced chronic kidney disease according to disease aetiology with evaluation of discrimination, calibration and clinical utility. *BMC Nephrology, 22(1),* 194. https://doi.org/10.1186/s12882-021-02402-1 

docs/acknowledgements.html

@@ -59,7 +59,7 @@
 <li class="toctree-l1"><a class="reference internal" href="usage_guide.html">Usage Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage_guide.html#single-patient-risk-calculation">Single Patient Risk Calculation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage_guide.html#conversion-of-clinical-parameters">Conversion of Clinical Parameters</a></li>
-<li class="toctree-l1"><a class="reference internal" href="usage_guide.html#classifying-esrd-outcome-by-2-and-5-year-outcomes">Classifying ESRD Outcome by 2 and 5 Year Outcomes</a></li>
+<li class="toctree-l1"><a class="reference internal" href="usage_guide.html#classifying-esrd-outcomes">Classifying ESRD Outcomes</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage_guide.html#batch-risk-calculation-for-multiple-patients">Batch Risk Calculation for Multiple Patients</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage_guide.html#performance-assessment">Performance Assessment</a></li>
 </ul>
@@ -70,7 +70,7 @@
 <li class="toctree-l2"><a class="reference internal" href="usage_guide.html">Usage Guide</a></li>
 <li class="toctree-l2"><a class="reference internal" href="usage_guide.html#single-patient-risk-calculation">Single Patient Risk Calculation</a></li>
 <li class="toctree-l2"><a class="reference internal" href="usage_guide.html#conversion-of-clinical-parameters">Conversion of Clinical Parameters</a></li>
-<li class="toctree-l2"><a class="reference internal" href="usage_guide.html#classifying-esrd-outcome-by-2-and-5-year-outcomes">Classifying ESRD Outcome by 2 and 5 Year Outcomes</a></li>
+<li class="toctree-l2"><a class="reference internal" href="usage_guide.html#classifying-esrd-outcomes">Classifying ESRD Outcomes</a></li>
 <li class="toctree-l2"><a class="reference internal" href="usage_guide.html#batch-risk-calculation-for-multiple-patients">Batch Risk Calculation for Multiple Patients</a></li>
 <li class="toctree-l2"><a class="reference internal" href="usage_guide.html#performance-assessment">Performance Assessment</a></li>
 </ul>