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.

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.
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.

Model Evaluation (kdiagram.plot.evaluation)

Functions for evaluating model performance, primarily 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.

Model 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.
plot_error_violins	Plot polar violin plots to compare multiple error distributions.
plot_error_ellipses	Plot polar error ellipses to visualize two-dimensional uncertainty.

Model Comparison (kdiagram.plot.comparison)

Functions for comparing multi-model performances on a radar chart.

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_horizon_metrics	Plot a polar bar chart comparing metrics across different horizons.

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.

Relationship Visualization (kdiagram.plot.relationship)

Functions for visualizing the relationship between true and predicted values using polar coordinates.

plot_relationship

Visualize the relationship between true values and one or more prediction series on a polar (circular) scatter plot.

Utility Functions (kdiagram.utils)

Helper functions primarily focused on detecting, validating, and manipulating quantile-related data within pandas DataFrames, often used for preparing data for visualization functions.

build_q_column_names	Generate and validate quantile column names following naming conventions.
detect_quantiles_in	Detect quantile columns in a DataFrame using naming patterns and value validation.
melt_q_data	Reshape wide-format DataFrame with quantile columns to long format with explicit temporal and quantile dimensions.
pivot_q_data	Convert long-format DataFrame with quantile columns back to wide format with temporal quantile measurements.
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.
plot_hist_kde	Plot histogram and Kernel Density Estimate (KDE) for uncertainty evaluation.

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_taylor_data	Generate synthetic data for Taylor diagrams.
make_uncertainty_data	Generate a synthetic multi-period uncertainty dataset.