Visualization API¶

Plotting functions for change point detection results.

Overview¶

Visualization utilities for change point detection.

This module provides plotting functions to visualize: - Change point detection results - Metric comparisons across algorithms - Multi-annotator scenarios - Dataset characteristics

fastcpd.visualization.plot_detection(data: ndarray | List, true_cps: List | ndarray, pred_cps: List | ndarray, metric_result: Dict | None = None, title: str = 'Change Point Detection', figsize: tuple = (14, 8), show_legend: bool = True, save_path: str | None = None) → tuple[source]¶

Plot change point detection results.

Parameters:

data – Time series data (1D or 2D array)
true_cps – True change point indices
pred_cps – Predicted change point indices
metric_result – Optional dict from metrics.evaluate_all()
title – Plot title
figsize – Figure size (width, height)
show_legend – Whether to show legend
save_path – Optional path to save figure

Returns:

Tuple of (fig, axes)

Examples

>>> from fastcpd.visualization import plot_detection
>>> from fastcpd.datasets import make_mean_change
>>> from fastcpd import fastcpd
>>> from fastcpd.metrics import evaluate_all
>>>
>>> # Generate data
>>> data_dict = make_mean_change(n_samples=500, n_changepoints=3)
>>> result = fastcpd(data_dict['data'], family='mean')
>>>
>>> # Evaluate and plot
>>> metrics = evaluate_all(data_dict['changepoints'], result.cp_set.tolist(),
...                        n_samples=500, margin=10)
>>> plot_detection(data_dict['data'], data_dict['changepoints'],
...               result.cp_set.tolist(), metrics)

fastcpd.visualization.plot_metric_comparison(results_dict: Dict[str, Dict], metrics: List[str] = None, figsize: tuple = (12, 6), save_path: str | None = None) → tuple[source]¶

Compare metrics across multiple algorithms.

Parameters:

results_dict – Dict mapping algorithm names to metric results {‘PELT’: metrics_dict, ‘SeGD’: metrics_dict, …}
metrics – List of metrics to compare (default: precision, recall, f1)
figsize – Figure size
save_path – Optional path to save figure

Returns:

Tuple of (fig, ax)

Examples

>>> from fastcpd.metrics import evaluate_all
>>> from fastcpd.visualization import plot_metric_comparison
>>>
>>> # Assume you have multiple algorithm results
>>> pelt_metrics = evaluate_all(true_cps, pelt_cps, n_samples=500, margin=10)
>>> segd_metrics = evaluate_all(true_cps, segd_cps, n_samples=500, margin=10)
>>>
>>> results = {'PELT': pelt_metrics, 'SeGD': segd_metrics}
>>> plot_metric_comparison(results)

fastcpd.visualization.plot_annotators(data: ndarray | List, annotators_list: List[List], pred_cps: List | ndarray, title: str = 'Multi-Annotator Change Point Detection', figsize: tuple = (14, 6), save_path: str | None = None) → tuple[source]¶

Visualize multi-annotator scenario.

Parameters:

data – Time series data
annotators_list – List of lists, each containing one annotator’s CPs
pred_cps – Predicted change points
title – Plot title
figsize – Figure size
save_path – Optional path to save figure

Returns:

Tuple of (fig, ax)

Examples

>>> from fastcpd.datasets import add_annotation_noise
>>> from fastcpd.visualization import plot_annotators
>>>
>>> true_cps = [100, 200, 300]
>>> annotators = add_annotation_noise(true_cps, n_annotators=5, seed=42)
>>> pred_cps = [98, 205, 295]
>>>
>>> plot_annotators(data, annotators, pred_cps)

fastcpd.visualization.plot_dataset_characteristics(data_dict: Dict[str, Any], figsize: tuple = (14, 10), save_path: str | None = None) → tuple[source]¶

Visualize dataset characteristics and metadata.

Parameters:

data_dict – Dictionary from datasets module (e.g., make_mean_change)
figsize – Figure size
save_path – Optional path to save figure

Returns:

Tuple of (fig, axes)

Examples

>>> from fastcpd.datasets import make_mean_change
>>> from fastcpd.visualization import plot_dataset_characteristics
>>>
>>> data_dict = make_mean_change(n_samples=500, n_changepoints=3, seed=42)
>>> plot_dataset_characteristics(data_dict)

fastcpd.visualization.plot_roc_curve(true_cps: List | ndarray, pred_cps_list: List[List | ndarray], labels: List[str], n_samples: int, figsize: tuple = (8, 8), save_path: str | None = None) → tuple[source]¶

Plot ROC-like curve for change point detection.

For each threshold (margin), computes precision and recall.

Parameters:

true_cps – True change points
pred_cps_list – List of predicted CP arrays (one per algorithm)
labels – Algorithm labels
n_samples – Total number of samples
figsize – Figure size
save_path – Optional path to save figure

Returns:

Tuple of (fig, ax)

Plotting Functions¶

Main Plot Functions¶

Plot change point detection results.

Parameters:

data – Time series data (1D or 2D array)
true_cps – True change point indices
pred_cps – Predicted change point indices
metric_result – Optional dict from metrics.evaluate_all()
title – Plot title
figsize – Figure size (width, height)
show_legend – Whether to show legend
save_path – Optional path to save figure

Returns:

Tuple of (fig, axes)

Examples

>>> from fastcpd.visualization import plot_detection
>>> from fastcpd.datasets import make_mean_change
>>> from fastcpd import fastcpd
>>> from fastcpd.metrics import evaluate_all
>>>
>>> # Generate data
>>> data_dict = make_mean_change(n_samples=500, n_changepoints=3)
>>> result = fastcpd(data_dict['data'], family='mean')
>>>
>>> # Evaluate and plot
>>> metrics = evaluate_all(data_dict['changepoints'], result.cp_set.tolist(),
...                        n_samples=500, margin=10)
>>> plot_detection(data_dict['data'], data_dict['changepoints'],
...               result.cp_set.tolist(), metrics)

Visualize multi-annotator scenario.

Parameters:

data – Time series data
annotators_list – List of lists, each containing one annotator’s CPs
pred_cps – Predicted change points
title – Plot title
figsize – Figure size
save_path – Optional path to save figure

Returns:

Tuple of (fig, ax)

Examples

>>> from fastcpd.datasets import add_annotation_noise
>>> from fastcpd.visualization import plot_annotators
>>>
>>> true_cps = [100, 200, 300]
>>> annotators = add_annotation_noise(true_cps, n_annotators=5, seed=42)
>>> pred_cps = [98, 205, 295]
>>>
>>> plot_annotators(data, annotators, pred_cps)

fastcpd.visualization.plot_metric_comparison(results_dict: Dict[str, Dict], metrics: List[str] = None, figsize: tuple = (12, 6), save_path: str | None = None) → tuple[source]¶

Compare metrics across multiple algorithms.

Parameters:

results_dict – Dict mapping algorithm names to metric results {‘PELT’: metrics_dict, ‘SeGD’: metrics_dict, …}
metrics – List of metrics to compare (default: precision, recall, f1)
figsize – Figure size
save_path – Optional path to save figure

Returns:

Tuple of (fig, ax)

Examples

>>> from fastcpd.metrics import evaluate_all
>>> from fastcpd.visualization import plot_metric_comparison
>>>
>>> # Assume you have multiple algorithm results
>>> pelt_metrics = evaluate_all(true_cps, pelt_cps, n_samples=500, margin=10)
>>> segd_metrics = evaluate_all(true_cps, segd_cps, n_samples=500, margin=10)
>>>
>>> results = {'PELT': pelt_metrics, 'SeGD': segd_metrics}
>>> plot_metric_comparison(results)

Advanced Plots¶

Plot ROC-like curve for change point detection.

For each threshold (margin), computes precision and recall.

Parameters:

true_cps – True change points
pred_cps_list – List of predicted CP arrays (one per algorithm)
labels – Algorithm labels
n_samples – Total number of samples
figsize – Figure size
save_path – Optional path to save figure

Returns:

Tuple of (fig, ax)

fastcpd.visualization.plot_dataset_characteristics(data_dict: Dict[str, Any], figsize: tuple = (14, 10), save_path: str | None = None) → tuple[source]¶

Visualize dataset characteristics and metadata.

Parameters:

data_dict – Dictionary from datasets module (e.g., make_mean_change)
figsize – Figure size
save_path – Optional path to save figure

Returns:

Tuple of (fig, axes)

Examples

>>> from fastcpd.datasets import make_mean_change
>>> from fastcpd.visualization import plot_dataset_characteristics
>>>
>>> data_dict = make_mean_change(n_samples=500, n_changepoints=3, seed=42)
>>> plot_dataset_characteristics(data_dict)

Example Usage¶

Basic Detection Plot¶

from fastcpd.visualization import plot_detection
import matplotlib.pyplot as plt
import numpy as np

# Generate simple data
data = np.concatenate([
    np.random.normal(0, 1, 200),
    np.random.normal(3, 1, 200)
])

# Plot
fig, ax = plot_detection(
    data=data,
    true_cps=[200],
    pred_cps=[198],
    title="Example Detection"
)
plt.show()

With Metrics Overlay¶

from fastcpd.metrics import evaluate_all
from fastcpd.visualization import plot_detection

# Evaluate metrics
metrics = evaluate_all(
    true_cps=[200],
    pred_cps=[198],
    n_samples=400,
    margin=10
)

# Plot with metrics
fig, ax = plot_detection(
    data=data,
    true_cps=[200],
    pred_cps=[198],
    metric_result=metrics,
    title="Detection with Metrics"
)

Multi-Annotator Visualization¶

from fastcpd.visualization import plot_annotators

# Multiple expert annotations
annotators_list = [
    [100, 200, 300],
    [105, 195, 305],
    [98, 203, 298]
]

fig, ax = plot_annotators(
    data=data,
    annotators_list=annotators_list,
    pred_cps=[102, 201, 299],
    title="Multi-Annotator Detection"
)

Algorithm Comparison¶

from fastcpd.visualization import plot_metric_comparison

# Compare multiple algorithms
results_dict = {
    'Mean': metrics_mean,
    'Rank': metrics_rank,
    'RBF': metrics_rbf
}

fig, axes = plot_metric_comparison(
    results_dict=results_dict,
    metrics=['precision', 'recall', 'f1_score']
)

Customization Options¶

Figure Size¶

fig, ax = plot_detection(
    data=data,
    pred_cps=[100],
    figsize=(14, 6)  # Custom size
)

Title and Labels¶

fig, ax = plot_detection(
    data=data,
    pred_cps=[100],
    title="Custom Title"
)

# Further customization
ax.set_xlabel('Time (seconds)')
ax.set_ylabel('Sensor Reading')

Legend Control¶

fig, ax = plot_detection(
    data=data,
    pred_cps=[100],
    show_legend=False  # Hide legend
)

Return Values¶

All plotting functions return matplotlib figure and axes objects:

fig, ax = plot_detection(data, pred_cps=[100])

# fig: matplotlib.figure.Figure
# ax: matplotlib.axes.Axes (or array of axes for subplots)

# Further customization
ax.grid(True, alpha=0.3)
fig.tight_layout()

# Save
fig.savefig('my_plot.pdf', dpi=300, bbox_inches='tight')

Saving Figures¶

Save in Multiple Formats¶

fig, ax = plot_detection(data, pred_cps=[100])

# High-resolution PNG
fig.savefig('plot.png', dpi=300, bbox_inches='tight')

# Vector graphics (PDF)
fig.savefig('plot.pdf', bbox_inches='tight')

# SVG
fig.savefig('plot.svg', bbox_inches='tight')

Publication Quality¶

import matplotlib.pyplot as plt

# Set publication style
plt.rcParams['font.size'] = 12
plt.rcParams['axes.labelsize'] = 14
plt.rcParams['figure.dpi'] = 100
plt.rcParams['pdf.fonttype'] = 42  # TrueType fonts

fig, ax = plot_detection(
    data=data,
    pred_cps=[100],
    figsize=(10, 5)
)

fig.savefig('publication_figure.pdf', dpi=300, bbox_inches='tight')