Quick Start Guide

This guide provides a minimal, runnable example to get you started with k-diagram. We’ll generate some sample data and create our first diagnostic polar plot: the Anomaly Magnitude plot.

This plot helps identify where actual values fall outside predicted uncertainty intervals and visualizes the magnitude of those errors.

Setup and Example

1. Import Libraries: We need kdiagram, pandas for data handling, and numpy for data generation.

2. Generate Sample Data: We create a simple DataFrame with actual values and corresponding prediction interval bounds (e.g., 10th and 90th percentiles). Crucially, we’ll ensure some ‘actual’ values fall outside these bounds to simulate prediction anomalies.

3. Create the Plot: Call kd.plot_anomaly_magnitude, specifying the columns for actual values and the interval bounds.

Copy and run the following Python code:

import kdiagram as kd
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt # Often needed alongside plotting libs

# 1. Generate Sample Data
np.random.seed(42) # for reproducible results
n_points = 180
data = pd.DataFrame({'sample_id': range(n_points)})

# Create base actual values and interval bounds
data['actual'] = np.random.normal(loc=20, scale=5, size=n_points)
data['q10'] = data['actual'] - np.random.uniform(2, 6, size=n_points)
data['q90'] = data['actual'] + np.random.uniform(2, 6, size=n_points)

# Introduce some anomalies (points outside the interval)
# Make ~10% under-predictions
under_indices = np.random.choice(n_points, size=n_points // 10, replace=False)
data.loc[under_indices, 'actual'] = data.loc[under_indices, 'q10'] - \
                                    np.random.uniform(1, 5, size=len(under_indices))

# Make ~10% over-predictions (avoiding indices already used)
available_indices = list(set(range(n_points)) - set(under_indices))
over_indices = np.random.choice(available_indices, size=n_points // 10, replace=False)
data.loc[over_indices, 'actual'] = data.loc[over_indices, 'q90'] + \
                                   np.random.uniform(1, 5, size=len(over_indices))

print("Sample Data Head:")
print(data.head())
print(f"\nTotal points: {len(data)}")

# 2. Create the Anomaly Magnitude Plot
print("\nGenerating Anomaly Magnitude plot...")
ax = kd.plot_anomaly_magnitude(
    df=data,
    actual_col='actual',
    q_cols=['q10', 'q90'], # Provide lower and upper bounds as a list
    title="Quick Start: Anomaly Magnitude Example",
    cbar=True,            # Show color bar indicating magnitude
    verbose=1             # Print summary of anomalies found
)

# The plot is displayed automatically by default
# Alternatively, save it using savefig:
# kd.plot_anomaly_magnitude(..., savefig="quickstart_anomaly.png")

# Optional: Explicitly show plot if needed in some environments
# plt.show()

Expected Output

Running the code above will first print the head of the generated DataFrame and a summary of detected anomalies. It will then display a polar plot similar to this:

Interpreting the Plot:

• Angles: Each point around the circle represents a sample from the DataFrame (ordered by index in this case).

• Radius: The distance from the center indicates the magnitude of the anomaly (how far the actual value was from the interval bound). Points perfectly within the interval are not shown.

• Color: Points are colored based on the type of anomaly:

  • Blue tones (default) indicate under-predictions (actual < q10).

  • Red tones (default) indicate over-predictions (actual > q90).

  • The color intensity corresponds to the anomaly magnitude shown on the color bar.

Next Steps

Congratulations! You’ve created your first k-diagram plot.

• Explore more plot types and their capabilities in the Plot Gallery

• Learn about the concepts behind the visualizations in the User Guide

• Refer to the API Reference documentation for detailed function signatures and parameters.