API Reference

Welcome to the k-diagram API reference. This section provides detailed information on the functions, classes, and modules included in the package.

The documentation here is largely auto-generated from the docstrings within the k-diagram source code. Ensure you have installed the package (see Installation) for the documentation build process to find the modules correctly.

Plotting Functions (kdiagram.plot)

This is the core module containing the specialized visualization functions, organized by their diagnostic purpose.

Uncertainty Visualization (kdiagram.plot.uncertainty)

Functions focused on visualizing prediction intervals, coverage, anomalies, drift, and other uncertainty-related diagnostics.

plot_actual_vs_predicted	Polar plot comparing actual observed vs predicted values.
plot_anomaly_magnitude	Visualize magnitude and type of prediction-interval anomalies.
plot_coverage	Plot overall coverage scores for forecast intervals or points.
plot_coverage_diagnostic	Diagnose prediction-interval coverage on a polar plot.
plot_interval_consistency	Polar plot showing consistency of prediction interval widths.
plot_interval_width	Polar scatter plot visualizing prediction interval width.
plot_model_drift	Visualize forecast drift across prediction horizons.
plot_temporal_uncertainty	Visualize multiple data series using polar scatter plots.
plot_uncertainty_drift	Polar plot visualizing temporal drift of uncertainty width.
plot_velocity	Polar plot visualizing average velocity across locations.
plot_radial_density_ring	Plot a radial density ring to visualize a 1D distribution.
plot_polar_heatmap	Plot a polar heatmap to visualize a 2D density distribution.
plot_polar_quiver	Plot a polar quiver plot to visualize vector data.

Error Analysis (kdiagram.plot.errors)

Functions for diagnosing and visualizing model errors, focusing on systemic vs. random errors, comparing error distributions, and visualizing 2D uncertainty.

plot_error_bands	Plot polar error bands to visualize systemic vs random error.
plot_error_violins	Plot polar violin plots to compare multiple error distributions.
plot_error_ellipses	Plot polar error ellipses to visualize two-dimensional uncertainty.

Probabilistic Diagnostics (kdiagram.plot.probabilistic)

Functions for the in-depth evaluation of probabilistic forecasts, assessing calibration, sharpness, and overall performance.

plot_pit_histogram	Plots a Polar Probability Integral Transform (PIT) Histogram.
plot_polar_sharpness	Plots a Polar Sharpness Diagram to compare forecast precision.
plot_crps_comparison	Plots a Polar CRPS Comparison Diagram.
plot_credibility_bands	Plots Polar Credibility Bands to visualize forecast uncertainty.
plot_calibration_sharpness	Plots a Polar Calibration-Sharpness Diagram.

Model Comparison (kdiagram.plot.comparison)

Functions for comparing multi-model performances using radar charts and reliability diagrams.

plot_model_comparison	Plot multi-metric model performance comparison on a radar chart.
plot_reliability_diagram	Plot a reliability diagram (calibration plot) for one or more classification models.
plot_polar_reliability	Plot a Polar Reliability Diagram (Calibration Spiral).
plot_horizon_metrics	Plot a polar bar chart comparing metrics across different horizons.

Relationship Visualization (kdiagram.plot.relationship)

Functions for visualizing relationships between true values, predictions, and errors.

plot_relationship	Visualize the relationship between true values and one or more prediction series on a polar (circular) scatter plot.
plot_conditional_quantiles	Plots polar conditional quantile bands.
plot_error_relationship	Plots the relationship between forecast error and the true value.
plot_residual_relationship	Plots the relationship between forecast error and predicted value.

Feature-Based Visualization (kdiagram.plot.feature_based)

Functions for visualizing feature importance and influence patterns.

plot_feature_fingerprint	Create a radar chart visualizing feature-importance profiles.
plot_feature_interaction	Plots a polar heatmap of feature interactions.
plot_fingerprint	Create a flexible polar 'fingerprint' (radar) chart.

Contextual Diagnostics (kdiagram.plot.context)

Standard Cartesian plots that provide essential context for the main polar diagrams, covering time series, correlation, and error distribution analysis.

plot_time_series	Plots one or more time series from a DataFrame.
plot_scatter_correlation	Plots a scatter plot of true vs predicted values.
plot_error_distribution	Plots a histogram and KDE of the forecast errors.
plot_qq	Generates a Quantile-Quantile (Q-Q) plot of forecast errors.
plot_error_autocorrelation	Plots the autocorrelation of forecast errors.
plot_error_pacf	Plots the partial autocorrelation of forecast errors.

Classification Evaluation (kdiagram.plot.evaluation)

Functions for evaluating the performance of classification models, featuring novel polar adaptations of standard diagnostic tools.

plot_polar_roc	Plots a Polar Receiver Operating Characteristic (ROC) Curve.
plot_polar_pr_curve	Plots a Polar Precision-Recall (PR) Curve.
plot_polar_confusion_matrix	Plots a Polar Confusion Matrix for binary classification.
plot_polar_confusion_matrix_in	Plots a Polar Confusion Matrix for multiclass classification.
plot_polar_confusion_multiclass	Plots a Polar Confusion Matrix for multiclass classification.
plot_polar_classification_report	Plots a Polar Classification Report.
plot_pinball_loss	Plots the Pinball Loss for each quantile of a forecast.
plot_regression_performance	Creates a Polar Performance Chart for regression models.

Anomaly Diagnostics (kdiagram.plot.anomaly)

Functions for creating detailed visualizations of forecast failures (anomalies) and their characteristics.

plot_anomaly_severity	Visualizes clustered anomaly severity using a polar scatter plot.
plot_anomaly_profile	Visualize anomaly severity as a polar profile or "fiery ring".
plot_glyphs	Visualizes anomaly characteristics using a polar glyph plot.
plot_cas_layers	Visualizes anomaly severity in layered Cartesian coordinates.
plot_cas_profile	Visualizes clustered anomaly severity on a Cartesian plot.

Taylor Diagram (kdiagram.plot.taylor_diagram)

Functions for evaluating model performance against a reference using Taylor Diagrams.

taylor_diagram	Plot a Taylor diagram to compare multiple predictions against a reference by visualizing their correlation and standard deviation.
plot_taylor_diagram_in	Plot Taylor Diagram with background color map.
plot_taylor_diagram	Plot a standard Taylor Diagram.

Specialized Forecasting Metrics (kdiagram.metrics)

Functions for computing specialized scores for forecast evaluation, such as the Clustered Anomaly Severity (CAS) score.

cluster_aware_severity_score	Compute the Cluster-Aware Severity (CAS) score.
clustered_anomaly_severity	Computes the Clustered Anomaly Severity (CAS) score.

Utility Functions (kdiagram.utils)

Helper functions for data preparation, mathematical computations, and validations.

bin_by_feature	Bins data by a feature and computes aggregate statistics.
build_cdf_interpolator	Builds an interpolator to act as a Cumulative Distribution Function.
build_q_column_names	Generate and validate quantile column names following naming conventions.
calculate_calibration_error	Calculates the calibration error using the PIT and KS test.
calculate_probabilistic_scores	Calculates probabilistic scores for each observation.
compute_coverage_score	Computes the coverage score for a given prediction interval.
compute_crps	Approximates the Continuous Ranked Probability Score (CRPS).
compute_forecast_errors	Computes forecast errors for one or more models.
compute_interval_width	Computes the width of one or more prediction intervals.
compute_pinball_loss	Computes the Pinball Loss for a single quantile forecast.
compute_pit	Computes the Probability Integral Transform (PIT) for each observation.
compute_winkler_score	Computes the Winkler score for a given prediction interval.
detect_quantiles_in	Detect quantile columns in a DataFrame using naming patterns and value validation.
get_forecast_arrays	Extract true and/or predicted values from a DataFrame.
melt_q_data	Reshape a wide DataFrame with time-embedded quantile columns into a tidy wide table with explicit temporal and quantile dimensions.
minmax_scaler	Scale features to a specified range using a Min-Max approach.
pivot_forecasts_long	Reshapes multi-horizon forecast data from wide to long format.
pivot_q_data	Convert a long/tidy-wide quantile table back to a time-embedded wide format with columns named like {value_prefix}_{t}_q{α}.
plot_hist_kde	Plot histogram and Kernel Density Estimate (KDE) for uncertainty evaluation.
reshape_quantile_data	Reshape a wide-format DataFrame with quantile columns into a DataFrame where the quantiles are separated into distinct columns for each quantile value.
savefig	Save a Matplotlib figure robustly.

Datasets (kdiagram.datasets)

Functions for loading sample datasets and generating synthetic data for examples and testing.

load_uncertainty_data	Generate a synthetic dataset for uncertainty diagnostics.
load_zhongshan_subsidence	Load the Zhongshan land subsidence prediction dataset.
make_cyclical_data	Generate synthetic cyclical data for relationship and temporal plots.
make_fingerprint_data	Generate synthetic feature-importance data for fingerprint plots.
make_multi_model_quantile_data	Generate multi-model quantile forecast data for a single horizon.
make_regression_data	Generate a synthetic regression dataset with a configurable true process and multiple model prediction profiles.
make_classification_data	Generate a synthetic classification dataset with a configurable feature process and multiple model outputs (labels and/or probabilities).
make_taylor_data	Generate synthetic data for Taylor diagrams.
make_uncertainty_data	Generate a synthetic multi-period uncertainty dataset.

Command-Line Interface (CLI)

In addition to the Python API, k-diagram also provides a command-line interface for generating plots directly from your terminal. This is an option for quick exploration and batch processing without writing any Python code.

For a full guide to all available commands and their options, please see the CLI Reference.