Skip to main content

Naming Conventions

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 or table in one call predictions and observed outcomes figure or rendered table
plot_* Visualize data that has already been prepared performance data interactive figure
render_* Render already-prepared data as a table prepared performance data rendered table

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(). Performance tables follow the same direct-versus-prepared-data idea: create_performance_table() prepares and renders in one call, while render_performance_table() renders an already-prepared performance-data frame.

Curve families

The same naming pattern repeats across the main performance curves:

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.

Performance tables

Performance tables use a closely related naming pattern:

Workflow Function
Prepare and render a binary-outcome table create_performance_table()
Prepare and render a time-to-event table create_performance_table_times()
Render already-prepared performance data render_performance_table()

The table constructors use the same underlying prepare_performance_data() and prepare_performance_data_times() pipelines as the curve functions. The render_* prefix is used when the numerical performance data already exist and only the presentation layer is needed.

Time-to-event variants

Functions ending in _times extend the corresponding workflow to time-to-event outcomes. For example:

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:

prepare + performance data        -> reusable data
create  + curve/table             -> data to rendered output
plot    + curve                   -> prepared data to figure
render  + table                   -> prepared data to rendered table
*_times                           -> time-to-event version

This convention is intended to make related functions discoverable without requiring users to memorize every exported name.