.. _quickstart:

==================
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:

.. code-block:: python
   :linenos:

   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:

.. image:: /images/quickstart_anomaly_magnitude.png
   :alt: Example Anomaly Magnitude Plot
   :align: center
   :width: 80%


**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
  :doc:`Plot Gallery <gallery/index>`
* Learn about the concepts behind the visualizations in the
  :doc:`User Guide <user_guide/index>`
* Refer to the :doc:`API Reference <api>` documentation for detailed function
  signatures and parameters.