From 1e965b1eb9531c42b693b8f2280a2dad9aecaeb3 Mon Sep 17 00:00:00 2001 From: Uriah Finkel Date: Tue, 11 Aug 2026 11:13:53 +0300 Subject: [PATCH 1/5] improve Python documentation entry points --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 53e240ce..2f5ad00d 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,17 @@ The library is designed to be easy to use while still offering a high degree of control over the final plots. +For some reproducible examples please visit [rtichoke blog](https://rtichoke-blog.netlify.app/)! + ## Installation -Install `rtichoke` from PyPI: +For a project managed with [uv](https://docs.astral.sh/uv/), add `rtichoke` with: + +```bash +uv add rtichoke +``` + +Alternatively, install `rtichoke` from PyPI with pip: ```bash pip install rtichoke From c8bc54d21ddd112104af8c553e2822309749c09d Mon Sep 17 00:00:00 2001 From: Uriah Finkel Date: Tue, 11 Aug 2026 11:14:09 +0300 Subject: [PATCH 2/5] add uv and blog guidance --- user_guide/00-getting-started.qmd | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/user_guide/00-getting-started.qmd b/user_guide/00-getting-started.qmd index 4e4f5567..8a96dc76 100644 --- a/user_guide/00-getting-started.qmd +++ b/user_guide/00-getting-started.qmd @@ -5,9 +5,19 @@ guide-section: "Getting Started" `rtichoke` is a Python library for interactive visualization of predictive-model performance. It supports discrimination, calibration, utility, and time-to-event evaluation workflows. +For some reproducible examples please visit [rtichoke blog](https://rtichoke-blog.netlify.app/)! + ## Installation -Install `rtichoke` from PyPI: +If you use [uv](https://docs.astral.sh/uv/) to manage your Python project, add `rtichoke` with: + +```bash +uv add rtichoke +``` + +This adds `rtichoke` to your project dependencies and updates the uv lockfile. + +If you are not using uv, install `rtichoke` from PyPI with pip: ```bash pip install rtichoke @@ -89,4 +99,4 @@ fig = rk.create_calibration_curve( fig.show() ``` -From here, use the API Reference for the full set of curve types, parameters, and time-to-event variants. +From here, use the API Reference for the full set of curve types, parameters, and time-to-event variants. The [Naming Conventions](01-naming-conventions.qmd) guide explains how the exported function families fit together. From 9c106227bec8e5c53a35101f853e932810f4ef9e Mon Sep 17 00:00:00 2001 From: Uriah Finkel Date: Tue, 11 Aug 2026 11:14:30 +0300 Subject: [PATCH 3/5] add API naming conventions guide --- user_guide/01-naming-conventions.qmd | 56 ++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 user_guide/01-naming-conventions.qmd diff --git a/user_guide/01-naming-conventions.qmd b/user_guide/01-naming-conventions.qmd new file mode 100644 index 00000000..6276beea --- /dev/null +++ b/user_guide/01-naming-conventions.qmd @@ -0,0 +1,56 @@ +--- +title: "Naming Conventions" +guide-section: "Getting Started" +--- + +`rtichoke` uses consistent function names so that the API becomes easier to predict once you know the main families. + +## Function families + +| Prefix | Purpose | Typical input | Typical output | +|---|---|---|---| +| `prepare_*` | Prepare reusable performance data | predictions and observed outcomes | performance data | +| `create_*` | Prepare data and create a visualization in one call | predictions and observed outcomes | interactive figure | +| `plot_*` | Visualize data that has already been prepared | performance data | interactive figure | + +For example, a direct ROC workflow uses `create_roc_curve()`, while a workflow that first prepares reusable performance data can pass those results to `plot_roc_curve()`. + +## Curve families + +The same naming pattern repeats across the main performance views: + +| Performance view | Direct visualization | Plot prepared data | +|---|---|---| +| ROC | `create_roc_curve()` | `plot_roc_curve()` | +| Precision–Recall | `create_precision_recall_curve()` | `plot_precision_recall_curve()` | +| Gains | `create_gains_curve()` | `plot_gains_curve()` | +| Lift | `create_lift_curve()` | `plot_lift_curve()` | +| Decision curve | `create_decision_curve()` | `plot_decision_curve()` | + +Calibration currently uses the direct `create_calibration_curve()` interface. + +## Time-to-event variants + +Functions ending in `_times` extend the corresponding workflow to time-to-event outcomes. For example: + +- `create_roc_curve()` → binary-outcome ROC curve +- `create_roc_curve_times()` → time-to-event ROC curve +- `create_calibration_curve()` → binary-outcome calibration curve +- `create_calibration_curve_times()` → time-to-event calibration curve +- `create_decision_curve()` → binary-outcome decision curve +- `create_decision_curve_times()` → time-to-event decision curve + +The same convention is used for the performance-data preparation functions, such as `prepare_performance_data()` and `prepare_performance_data_times()`. + +## A useful mental model + +Think of the API as a small grammar: + +```text +prepare + performance data -> reusable data +create + metric/curve -> data to figure +plot + metric/curve -> prepared data to figure +*_times -> time-to-event version +``` + +This convention is intended to make related functions discoverable without requiring users to memorize every exported name. From 41981a773fd5ad4e03187fe6e448d85c14f435da Mon Sep 17 00:00:00 2001 From: Uriah Finkel Date: Tue, 11 Aug 2026 11:14:42 +0300 Subject: [PATCH 4/5] add rtichoke blog navbar link --- great-docs.yml | 104 ++++++++++++++++++++++++++++++------------------- 1 file changed, 64 insertions(+), 40 deletions(-) diff --git a/great-docs.yml b/great-docs.yml index 8dcb1d78..8ebc6ee2 100644 --- a/great-docs.yml +++ b/great-docs.yml @@ -1,49 +1,73 @@ -display_name: rtichoke -parser: numpy -repo: https://github.com/uriahf/rtichoke_python -user_guide: user_guide -homepage: user_guide +display_name: rtichoke +parser: numpy +repo: https://github.com/uriahf/rtichoke_python +user_guide: user_guide +homepage: user_guide site_url: https://uriahf.github.io/rtichoke_python/ +include_in_header: + - text: | + + site: css: site.css source: - enabled: true - branch: main - placement: usage - -reference: - - title: Performance Data - desc: Prepare classification and time-to-event data for visualization. - contents: - - prepare_performance_data - - prepare_binned_classification_data - - prepare_performance_data_times - - prepare_binned_classification_data_times - - - title: Discrimination - desc: ROC, precision-recall, gains, and lift visualizations. - contents: - - create_roc_curve - - create_roc_curve_times - - plot_roc_curve - - create_precision_recall_curve - - create_precision_recall_curve_times - - plot_precision_recall_curve - - create_gains_curve - - create_gains_curve_times - - plot_gains_curve - - create_lift_curve - - create_lift_curve_times - - plot_lift_curve - - - title: Calibration - desc: Calibration visualizations for classification and time-to-event models. - contents: - - create_calibration_curve - - create_calibration_curve_times - + enabled: true + branch: main + placement: usage + +reference: + - title: Performance Data + desc: Prepare classification and time-to-event data for visualization. + contents: + - prepare_performance_data + - prepare_binned_classification_data + - prepare_performance_data_times + - prepare_binned_classification_data_times + + - title: Discrimination + desc: ROC, precision-recall, gains, and lift visualizations. + contents: + - create_roc_curve + - create_roc_curve_times + - plot_roc_curve + - create_precision_recall_curve + - create_precision_recall_curve_times + - plot_precision_recall_curve + - create_gains_curve + - create_gains_curve_times + - plot_gains_curve + - create_lift_curve + - create_lift_curve_times + - plot_lift_curve + + - title: Calibration + desc: Calibration visualizations for classification and time-to-event models. + contents: + - create_calibration_curve + - create_calibration_curve_times + - title: Utility desc: Decision-curve analysis for classification and time-to-event models. contents: From b3c86f1c569cad720e214ed99c803433c315ff8f Mon Sep 17 00:00:00 2001 From: Uriah Finkel Date: Tue, 11 Aug 2026 11:23:20 +0300 Subject: [PATCH 5/5] fix naming conventions link --- user_guide/00-getting-started.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide/00-getting-started.qmd b/user_guide/00-getting-started.qmd index 8a96dc76..b36ed56f 100644 --- a/user_guide/00-getting-started.qmd +++ b/user_guide/00-getting-started.qmd @@ -99,4 +99,4 @@ fig = rk.create_calibration_curve( fig.show() ``` -From here, use the API Reference for the full set of curve types, parameters, and time-to-event variants. The [Naming Conventions](01-naming-conventions.qmd) guide explains how the exported function families fit together. +From here, use the API Reference for the full set of curve types, parameters, and time-to-event variants. The [Naming Conventions](user-guide/naming-conventions.html) guide explains how the exported function families fit together.