API Reference — Plotting¶

The plotting layer generates static visualizations of CGM data.

Module-level plot functions¶

cgmpy.plotting.agp ¶

Module for ambulatory glucose profile (AGP) plots.

This module contains functions to generate ambulatory profiles: - Standard AGP - AGP by day of week - Helper functions for percentile calculation

plot_agp ¶

plot_agp(data: DataFrame, smoothing_window: int = 15, ax: Axes | None = None) -> Figure

Builds the enhanced Ambulatory Glucose Profile (AGP).

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`smoothing_window`	`int`	Smoothing window in minutes (default 15).	`15`
`ax`	`Axes \| None`	Optional axis to draw into. If `None` a new figure is created.	`None`

Returns:

Type	Description
`Figure`	The matplotlib `Figure` containing the plot.

Source code in cgmpy/plotting/agp.py

def plot_agp(data: pd.DataFrame, smoothing_window: int = 15, ax: Axes | None = None) -> Figure:
    """Builds the enhanced Ambulatory Glucose Profile (AGP).

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        smoothing_window: Smoothing window in minutes (default 15).
        ax: Optional axis to draw into. If ``None`` a new figure is created.

    Returns:
        The matplotlib ``Figure`` containing the plot.
    """
    data_copy = data.copy()
    data_copy["time_decimal"] = (
        data_copy["time"].dt.hour + data_copy["time"].dt.minute / 60.0
    ).round(2)

    percentiles = data_copy.groupby("time_decimal")["glucose"].agg(
        [
            lambda x: np.percentile(x, 5),
            lambda x: np.percentile(x, 25),
            lambda x: np.percentile(x, 50),
            lambda x: np.percentile(x, 75),
            lambda x: np.percentile(x, 95),
        ]
    )

    percentiles.columns = [0.05, 0.25, 0.5, 0.75, 0.95]

    for col in percentiles.columns:
        percentiles[col] = (
            percentiles[col].rolling(window=smoothing_window, center=True, min_periods=1).mean()
        )

    percentiles = percentiles.sort_index()

    fig, ax, created = resolve_axes(ax, figsize=(14, 8))

    add_glucose_zones(ax)

    _plot_percentiles(ax, percentiles)

    _configure_agp_plot(ax, "Ambulatory Glucose Profile (AGP)")

    if created:
        fig.tight_layout()
    return fig

generate_week_agp ¶

generate_week_agp(data: DataFrame, smoothing_window: int = 15, combined: bool = True) -> Figure

Builds the Ambulatory Glucose Profile (AGP) by day of week.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`smoothing_window`	`int`	Smoothing window in minutes (default 15).	`15`
`combined`	`bool`	If True, displays all days in a single chart. If False, displays a subplot for each day.	`True`

Returns:

Type	Description
`Figure`	The matplotlib `Figure` containing the plot.

Source code in cgmpy/plotting/agp.py

def generate_week_agp(
    data: pd.DataFrame, smoothing_window: int = 15, combined: bool = True
) -> Figure:
    """Builds the Ambulatory Glucose Profile (AGP) by day of week.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        smoothing_window: Smoothing window in minutes (default 15).
        combined: If True, displays all days in a single chart.
                 If False, displays a subplot for each day.

    Returns:
        The matplotlib ``Figure`` containing the plot.
    """
    data_copy = data.copy()
    data_copy["time_decimal"] = (
        data_copy["time"].dt.hour + data_copy["time"].dt.minute / 60.0
    ).round(2)
    data_copy["weekday"] = data_copy["time"].dt.day_name()

    if combined:
        return _plot_combined_week_agp(data_copy, smoothing_window)
    return _plot_separate_week_agp(data_copy, smoothing_window)

cgmpy.plotting.daily_plots ¶

Module for daily glucose data plots.

This module contains functions to generate charts related to daily patterns: - Specific day plots - Overlapping multiple days - Boxplots by day of week - Daily variation analysis

Every public function accepts an optional ax and returns the resulting Figure without calling plt.show() — display is left to the caller (e.g. the :class:~cgmpy.analysis.core.GlucoseAnalysis facade), which makes the plots composable inside dashboards.

day_graph ¶

day_graph(data: DataFrame, date: str | None = None, ax: Axes | None = None) -> Figure | None

Builds the glucose chart for a specific day.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`date`	`str \| None`	Optional date in 'YYYY-MM-DD' format. If not provided, the first day of the DataFrame is used.	`None`
`ax`	`Axes \| None`	Optional axis to draw into. If `None` a new figure is created.	`None`

Returns:

Type	Description
`Figure \| None`	The matplotlib `Figure`, or `None` if the date has no data.

Source code in cgmpy/plotting/daily_plots.py

def day_graph(data: pd.DataFrame, date: str | None = None, ax: Axes | None = None) -> Figure | None:
    """Builds the glucose chart for a specific day.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        date: Optional date in 'YYYY-MM-DD' format.
              If not provided, the first day of the DataFrame is used.
        ax: Optional axis to draw into. If ``None`` a new figure is created.

    Returns:
        The matplotlib ``Figure``, or ``None`` if the date has no data.
    """
    if date is None:
        date = data["time"].dt.date.min()
    else:
        date = pd.to_datetime(date).date()

    day_data = data[data["time"].dt.date == date].copy()

    if day_data.empty:
        logger.info("No data for date %s", date)
        return None

    day_data["hours"] = day_data["time"].dt.hour + day_data["time"].dt.minute / 60.0

    sns.set_style("whitegrid")
    sns.set_context("notebook", font_scale=1.1)

    fig, ax, created = resolve_axes(ax, figsize=(16, 9))

    add_glucose_zones(ax)

    ax.plot(
        day_data["hours"],
        day_data["glucose"],
        label="Glucose",
        color="#3366CC",
        linewidth=2,
        marker="o",
        markersize=4,
    )

    _add_reference_lines(ax)

    _configure_daily_plot(ax, f"Glucose Levels - {date}")

    if created:
        fig.tight_layout()
    return fig

plot_overlapping_days ¶

plot_overlapping_days(data: DataFrame, ax: Axes | None = None) -> Figure

Builds a chart with the glucose profiles of multiple overlapping days.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`ax`	`Axes \| None`	Optional axis to draw into. If `None` a new figure is created.	`None`

Returns:

Type	Description
`Figure`	The matplotlib `Figure` containing the plot.

Source code in cgmpy/plotting/daily_plots.py

def plot_overlapping_days(data: pd.DataFrame, ax: Axes | None = None) -> Figure:
    """Builds a chart with the glucose profiles of multiple overlapping days.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        ax: Optional axis to draw into. If ``None`` a new figure is created.

    Returns:
        The matplotlib ``Figure`` containing the plot.
    """
    data_copy = data.copy()
    data_copy["time_decimal"] = data_copy["time"].dt.hour + data_copy["time"].dt.minute / 60.0
    data_copy["date"] = data_copy["time"].dt.date

    fig, ax, created = resolve_axes(ax, figsize=(12, 8))

    mean_profile = (
        data_copy.groupby("time_decimal")["glucose"]
        .mean()
        .rolling(window=15, center=True, min_periods=1)
        .mean()
    )

    dates = data_copy["date"].unique()
    for d in dates:
        day_data = data_copy[data_copy["date"] == d]
        ax.plot(
            day_data["time_decimal"],
            day_data["glucose"],
            color="gray",
            alpha=0.2,
            linewidth=1,
        )

    ax.plot(
        mean_profile.index,
        mean_profile.values,
        color="black",
        linewidth=2,
        label="Mean profile",
    )

    _configure_overlapping_plot(ax)

    if created:
        fig.tight_layout()
    return fig

plot_week_boxplots ¶

plot_week_boxplots(data: DataFrame, ax: Axes | None = None) -> Figure

Builds a boxplot chart of the glucose distribution by day of the week.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`ax`	`Axes \| None`	Optional axis to draw into. If `None` a new figure is created.	`None`

Returns:

Type	Description
`Figure`	The matplotlib `Figure` containing the plot.

Source code in cgmpy/plotting/daily_plots.py

def plot_week_boxplots(data: pd.DataFrame, ax: Axes | None = None) -> Figure:
    """Builds a boxplot chart of the glucose distribution by day of the week.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        ax: Optional axis to draw into. If ``None`` a new figure is created.

    Returns:
        The matplotlib ``Figure`` containing the plot.
    """
    data_copy = data.copy()
    data_copy["weekday"] = data_copy["time"].dt.day_name()
    data_copy["date"] = data_copy["time"].dt.date

    day_order = [
        "Monday",
        "Tuesday",
        "Wednesday",
        "Thursday",
        "Friday",
        "Saturday",
        "Sunday",
    ]

    unique_days = data_copy.groupby("weekday")["date"].nunique()

    labels = [f"{day}\n(n={unique_days.get(day, 0)} days)" for day in day_order]

    fig, ax, created = resolve_axes(ax, figsize=(12, 8))

    ax.axhspan(GLUCOSE_AXIS_MIN, TARGET_LOW, color="#ffcccb", alpha=0.2, label="Hypoglycemia")
    ax.axhspan(TARGET_LOW, TARGET_HIGH, color="#90ee90", alpha=0.2, label="Target range")
    ax.axhspan(TARGET_HIGH, GLUCOSE_AXIS_MAX, color="#ffcccb", alpha=0.2, label="Hyperglycemia")

    sns.boxplot(
        x="weekday",
        y="glucose",
        data=data_copy,
        order=day_order,
        whis=1.5,
        medianprops={"color": "red", "linewidth": 1.5},
        flierprops={"marker": "o", "markerfacecolor": "gray", "markersize": 4},
        ax=ax,
    )

    ax.axhline(y=TARGET_LOW, color="red", linestyle="--", linewidth=1)
    ax.axhline(y=TARGET_HIGH, color="red", linestyle="--", linewidth=1)

    ax.set_title("Glucose Distribution by Day of Week", fontsize=14, pad=20)
    ax.set_xlabel("Day of Week", fontsize=12)
    ax.set_ylabel("Glucose Level (mg/dL)", fontsize=12)

    ax.set_xticks(range(len(day_order)))
    ax.set_xticklabels(labels, rotation=45, ha="right")
    ax.set_ylim(GLUCOSE_AXIS_MIN, GLUCOSE_AXIS_MAX)

    ax.legend(title="Ranges", bbox_to_anchor=(1.05, 1), loc="upper left")

    if created:
        fig.tight_layout()
    return fig

plot_daily_variations ¶

plot_daily_variations(data: DataFrame, ax: Axes | None = None) -> Figure

Builds a chart of the average daily variations with confidence bands.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`ax`	`Axes \| None`	Optional axis to draw into. If `None` a new figure is created.	`None`

Returns:

Type	Description
`Figure`	The matplotlib `Figure` containing the plot.

Source code in cgmpy/plotting/daily_plots.py

def plot_daily_variations(data: pd.DataFrame, ax: Axes | None = None) -> Figure:
    """Builds a chart of the average daily variations with confidence bands.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        ax: Optional axis to draw into. If ``None`` a new figure is created.

    Returns:
        The matplotlib ``Figure`` containing the plot.
    """
    data_copy = data.copy()
    data_copy["time_decimal"] = data_copy["time"].dt.hour + data_copy["time"].dt.minute / 60.0

    hourly_stats = (
        data_copy.groupby("time_decimal")["glucose"]
        .agg(
            [
                "mean",
                "std",
                "count",
                lambda x: np.percentile(x, 25),
                lambda x: np.percentile(x, 75),
            ]
        )
        .reset_index()
    )

    hourly_stats.columns = ["time_decimal", "mean", "std", "count", "p25", "p75"]

    window_size = 15
    for col in ["mean", "std", "p25", "p75"]:
        hourly_stats[col] = (
            hourly_stats[col].rolling(window=window_size, center=True, min_periods=1).mean()
        )

    fig, ax, created = resolve_axes(ax, figsize=(14, 8))

    add_glucose_zones(ax)

    ax.plot(
        hourly_stats["time_decimal"],
        hourly_stats["mean"],
        color="blue",
        linewidth=2,
        label="Mean",
    )

    ax.fill_between(
        hourly_stats["time_decimal"],
        hourly_stats["mean"] - hourly_stats["std"],
        hourly_stats["mean"] + hourly_stats["std"],
        alpha=0.3,
        color="blue",
        label="± 1 SD",
    )

    ax.fill_between(
        hourly_stats["time_decimal"],
        hourly_stats["p25"],
        hourly_stats["p75"],
        alpha=0.2,
        color="green",
        label="Interquartile range",
    )

    ax.set_xlabel("Time of Day", fontsize=12)
    ax.set_ylabel("Glucose Level (mg/dL)", fontsize=12)
    ax.set_title("Average Daily Glucose Variations", fontsize=14)

    ax.set_xticks(range(0, 25, 3))
    ax.set_xticklabels([f"{h:02d}:00" for h in range(0, 25, 3)])
    ax.set_xlim(0, 24)
    ax.set_ylim(GLUCOSE_AXIS_MIN, GLUCOSE_AXIS_MAX)

    ax.axhline(y=TARGET_LOW, color="red", linestyle="--", linewidth=1, alpha=0.7)
    ax.axhline(y=TARGET_HIGH, color="red", linestyle="--", linewidth=1, alpha=0.7)

    ax.grid(True, alpha=0.3)
    ax.legend()

    if created:
        fig.tight_layout()
    return fig

cgmpy.plotting.statistical_plots ¶

Module for statistical glucose data plots.

This module contains functions to generate statistical charts: - Distribution histograms - Time in range charts - Correlation charts - Statistical distribution analysis

histogram ¶

histogram(data: DataFrame, bin_width: int = 10, ax: Axes | None = None) -> Figure

Builds the glucose histogram with fixed intervals.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`bin_width`	`int`	Width of each interval in mg/dL (default 10).	`10`
`ax`	`Axes \| None`	Optional axis to draw into. If `None` a new figure is created.	`None`

Returns:

Type	Description
`Figure`	The matplotlib `Figure` containing the plot.

Source code in cgmpy/plotting/statistical_plots.py

def histogram(data: pd.DataFrame, bin_width: int = 10, ax: Axes | None = None) -> Figure:
    """Builds the glucose histogram with fixed intervals.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        bin_width: Width of each interval in mg/dL (default 10).
        ax: Optional axis to draw into. If ``None`` a new figure is created.

    Returns:
        The matplotlib ``Figure`` containing the plot.
    """
    bins = range(GLUCOSE_AXIS_MIN, GLUCOSE_HIST_MAX + bin_width, bin_width)

    fig, ax, created = resolve_axes(ax, figsize=(12, 8))

    ax.hist(data["glucose"], bins=bins, edgecolor="black", alpha=0.7)

    ax.axvspan(GLUCOSE_AXIS_MIN, TARGET_LOW, color="#ffcccb", alpha=0.3, label="Hypoglycemia")
    ax.axvspan(TARGET_LOW, TARGET_HIGH, color="#90ee90", alpha=0.3, label="Target range")
    ax.axvspan(TARGET_HIGH, GLUCOSE_AXIS_MAX, color="#ffcccb", alpha=0.3, label="Hyperglycemia")

    ax.set_xlabel("Glucose Level (mg/dL)", fontsize=12)
    ax.set_ylabel("Frequency", fontsize=12)
    ax.set_title(f"Glucose Histogram ({bin_width} mg/dL bins)", fontsize=14)
    ax.legend()
    ax.grid(True, alpha=0.3)

    if created:
        fig.tight_layout()
    return fig

plot_time_in_range ¶

plot_time_in_range(data: DataFrame, pregnancy: bool = False, tir_pregnancy: float = 0, tbr63: float = 0, tar140: float = 0, tir: float = 0, tbr70: float = 0, tbr55: float = 0, tar180: float = 0, tar250: float = 0) -> Figure

Generates a pie chart of time in range.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`pregnancy`	`bool`	If True, uses pregnancy-specific ranges.	`False`
`tir_pregnancy`	`float`	TIR for pregnancy (63-140 mg/dL).	`0`
`tbr63`	`float`	TBR below 63 mg/dL.	`0`
`tar140`	`float`	TAR above 140 mg/dL.	`0`
`tir`	`float`	Standard TIR (70-180 mg/dL).	`0`
`tbr70`	`float`	TBR Level 1 (55-70 mg/dL).	`0`
`tbr55`	`float`	TBR Level 2 (< 55 mg/dL).	`0`
`tar180`	`float`	TAR Level 1 (180-250 mg/dL).	`0`
`tar250`	`float`	TAR Level 2 (> 250 mg/dL).	`0`

Source code in cgmpy/plotting/statistical_plots.py

def plot_time_in_range(
    data: pd.DataFrame,
    pregnancy: bool = False,
    tir_pregnancy: float = 0,
    tbr63: float = 0,
    tar140: float = 0,
    tir: float = 0,
    tbr70: float = 0,
    tbr55: float = 0,
    tar180: float = 0,
    tar250: float = 0,
) -> Figure:
    """Generates a pie chart of time in range.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        pregnancy: If True, uses pregnancy-specific ranges.
        tir_pregnancy: TIR for pregnancy (63-140 mg/dL).
        tbr63: TBR below 63 mg/dL.
        tar140: TAR above 140 mg/dL.
        tir: Standard TIR (70-180 mg/dL).
        tbr70: TBR Level 1 (55-70 mg/dL).
        tbr55: TBR Level 2 (< 55 mg/dL).
        tar180: TAR Level 1 (180-250 mg/dL).
        tar250: TAR Level 2 (> 250 mg/dL).
    """
    if pregnancy:
        labels = [
            "TIR Pregnancy\n(63-140 mg/dL)",
            "TBR\n(< 63 mg/dL)",
            "TAR\n(> 140 mg/dL)",
        ]
        sizes = [tir_pregnancy, tbr63, tar140]
        colors = ["#90ee90", "#ffcccb", "#ffa500"]
        title = "Time in Range - Pregnancy"
    else:
        labels = [
            "TIR\n(70-180 mg/dL)",
            "TBR Level 1\n(55-70 mg/dL)",
            "TBR Level 2\n(< 55 mg/dL)",
            "TAR Level 1\n(180-250 mg/dL)",
            "TAR Level 2\n(> 250 mg/dL)",
        ]
        sizes = [tir, tbr70, tbr55, tar180, tar250]
        colors = ["#90ee90", "#ffeb9c", "#ffcccb", "#ffa500", "#ff6666"]
        title = "Time in Range - Standard"

    non_zero_data = [
        (label, size, color)
        for label, size, color in zip(labels, sizes, colors, strict=False)
        if size > 0
    ]
    if non_zero_data:
        labels, sizes, colors = map(list, zip(*non_zero_data, strict=False))

    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(16, 8))

    wedges, texts, autotexts = ax1.pie(
        sizes,
        labels=labels,
        colors=colors,
        autopct="%1.1f%%",
        startangle=90,
        textprops={"fontsize": 10},
    )

    ax1.set_title(title, fontsize=14, fontweight="bold")

    y_pos = np.arange(len(labels))
    bars = ax2.barh(y_pos, sizes, color=colors, alpha=0.7)

    ax2.set_yticks(y_pos)
    ax2.set_yticklabels(labels, fontsize=10)
    ax2.set_xlabel("Percentage (%)", fontsize=12)
    ax2.set_title("Detailed Distribution", fontsize=14, fontweight="bold")

    for _i, (bar, size) in enumerate(zip(bars, sizes, strict=False)):
        ax2.text(
            bar.get_width() + 0.5,
            bar.get_y() + bar.get_height() / 2,
            f"{size:.1f}%",
            ha="left",
            va="center",
            fontsize=10,
        )

    ax2.grid(True, alpha=0.3, axis="x")

    fig.tight_layout()
    return fig

plot_distribution_comparison ¶

plot_distribution_comparison(data: DataFrame, target_ranges: list[tuple] | None = None, tir_val: float = 0, tbr_val: float = 0, tar_val: float = 0, gmi_val: float = 0) -> Figure

Compares the current distribution with target ranges.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`target_ranges`	`list[tuple] \| None`	List of tuples (min, max, label, color) to compare.	`None`
`tir_val`	`float`	Time in Range value.	`0`
`tbr_val`	`float`	Time Below Range value (< 70 mg/dL).	`0`
`tar_val`	`float`	Time Above Range value (> 180 mg/dL).	`0`
`gmi_val`	`float`	Glucose Management Index value.	`0`

Source code in cgmpy/plotting/statistical_plots.py

def plot_distribution_comparison(
    data: pd.DataFrame,
    target_ranges: list[tuple] | None = None,
    tir_val: float = 0,
    tbr_val: float = 0,
    tar_val: float = 0,
    gmi_val: float = 0,
) -> Figure:
    """Compares the current distribution with target ranges.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        target_ranges: List of tuples (min, max, label, color) to compare.
        tir_val: Time in Range value.
        tbr_val: Time Below Range value (< 70 mg/dL).
        tar_val: Time Above Range value (> 180 mg/dL).
        gmi_val: Glucose Management Index value.
    """
    if target_ranges is None:
        target_ranges = [
            (70, 180, "Target Range", "#90ee90"),
            (0, 70, "Hypoglycemia", "#ffcccb"),
            (180, 400, "Hyperglycemia", "#ffa500"),
        ]

    fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(16, 12))

    ax1.hist(
        data["glucose"],
        bins=50,
        density=True,
        alpha=0.7,
        color="skyblue",
        edgecolor="black",
    )

    for min_val, max_val, label, color in target_ranges:
        ax1.axvspan(min_val, max_val, alpha=0.3, color=color, label=label)

    ax1.set_xlabel("Glucose (mg/dL)")
    ax1.set_ylabel("Density")
    ax1.set_title("Glucose Distribution")
    ax1.legend()
    ax1.grid(True, alpha=0.3)

    ax2.boxplot(
        data["glucose"],
        vert=True,
        patch_artist=True,
        boxprops={"facecolor": "lightblue"},
    )
    ax2.set_ylabel("Glucose (mg/dL)")
    ax2.set_title("Glucose Box Plot")
    ax2.grid(True, alpha=0.3)

    from scipy import stats

    stats.probplot(data["glucose"], dist="norm", plot=ax3)
    ax3.set_title("Q-Q Plot (Normality)")
    ax3.grid(True, alpha=0.3)

    ax4.axis("off")
    stats_text = _generate_statistics_text(data["glucose"], tir_val, tbr_val, tar_val, gmi_val)
    ax4.text(
        0.1,
        0.9,
        stats_text,
        transform=ax4.transAxes,
        fontsize=11,
        verticalalignment="top",
        fontfamily="monospace",
        bbox={"boxstyle": "round", "facecolor": "lightgray", "alpha": 0.8},
    )

    fig.tight_layout()
    return fig

plot_correlation_matrix ¶

plot_correlation_matrix(data: DataFrame, time_segments: list[str] | None = None, ax: Axes | None = None) -> Figure

Builds a correlation matrix between different time segments.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Glucose DataFrame with `time` and `glucose` columns.	required
`time_segments`	`list[str] \| None`	List of time segments to analyze.	`None`
`ax`	`Axes \| None`	Optional axis to draw into. If `None` a new figure is created.	`None`

Returns:

Type	Description
`Figure`	The matplotlib `Figure` containing the plot.

Source code in cgmpy/plotting/statistical_plots.py

def plot_correlation_matrix(
    data: pd.DataFrame,
    time_segments: list[str] | None = None,
    ax: Axes | None = None,
) -> Figure:
    """Builds a correlation matrix between different time segments.

    Args:
        data: Glucose DataFrame with ``time`` and ``glucose`` columns.
        time_segments: List of time segments to analyze.
        ax: Optional axis to draw into. If ``None`` a new figure is created.

    Returns:
        The matplotlib ``Figure`` containing the plot.
    """
    if time_segments is None:
        time_segments = ["00:00-06:00", "06:00-12:00", "12:00-18:00", "18:00-24:00"]

    data_copy = data.copy()
    data_copy["hour"] = data_copy["time"].dt.hour
    data_copy["date"] = data_copy["time"].dt.date

    segment_data = {}

    for segment in time_segments:
        start_hour, end_hour = segment.split("-")
        start_h = int(start_hour.split(":")[0])
        end_h = int(end_hour.split(":")[0])

        if end_h == 0:
            end_h = 24

        if start_h < end_h:
            mask = (data_copy["hour"] >= start_h) & (data_copy["hour"] < end_h)
        else:
            mask = (data_copy["hour"] >= start_h) | (data_copy["hour"] < end_h)

        segment_glucose = data_copy[mask].groupby("date")["glucose"].mean()
        segment_data[segment] = segment_glucose

    correlation_df = pd.DataFrame(segment_data)
    correlation_matrix = correlation_df.corr()

    fig, ax, created = resolve_axes(ax, figsize=(10, 8))

    sns.heatmap(
        correlation_matrix,
        annot=True,
        cmap="coolwarm",
        center=0,
        square=True,
        fmt=".3f",
        cbar_kws={"shrink": 0.8},
        ax=ax,
    )

    ax.set_title(
        "Correlation Matrix between Time Segments",
        fontsize=14,
        fontweight="bold",
    )
    if created:
        fig.tight_layout()
    return fig

High-level facade¶

cgmpy.analysis.core.GlucoseAnalysis ¶

Full CGM analysis by composition.

Wraps a :class:GlucoseData instance and provides access to all metrics, plots, and reports via delegation to pure functions.

Parameters:

Name	Type	Description	Default
`data`	`GlucoseData \| str \| DataFrame`	A :class:`GlucoseData` instance, or a file path / DataFrame (backward-compatible shorthand that wraps in `GlucoseData`).	required