API Reference

def save_chart(
    ax: Axes,
    path: str | Path,
    *,
    bbox_inches: str | None = "tight",
) -> None:
    """Save chart.

    Args:
        ax (Axes): The matplotlib Axes object containing the chart to save.
        path (str | Path): The file path where the chart should be saved.
        bbox_inches (str | None, optional): The bounding box in inches. Defaults to "tight".

    Raises:
        ValueError: If the Axes is not attached to a Figure.

    """
    output_path = Path(path)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    figure = ax.get_figure(root=True)
    if figure is None:
        raise ValueError("Axes must be attached to a Figure before saving.")

    figure.savefig(output_path, bbox_inches=bbox_inches)

def show_categorical_distribution(
    df: pd.DataFrame,
    *,
    column: str,
    ax: Axes | None = None,
) -> Axes:
    """Show category frequencies for one categorical variable.

    Args:
        df (pd.DataFrame): The DataFrame containing the data.
        column (str): The name of the categorical column.
        ax (Axes | None, optional): The matplotlib Axes object to plot on. If None, a new figure and axes will be created.

    Returns:
        Axes: The matplotlib Axes object containing the plot.
    """
    require_columns(df, columns=[column])

    if ax is None:
        _, ax = plt.subplots()

    counts = df[column].value_counts(dropna=False)

    labels = ["<missing>" if pd.isna(value) else str(value) for value in counts.index]

    ax.bar(labels, counts.to_numpy())
    ax.set_title(f"Distribution of {column}")
    ax.set_xlabel(column)
    ax.set_ylabel("Count")
    ax.tick_params(axis="x", labelrotation=45)

    return ax

def show_missing_values(
    df: pd.DataFrame,
    *,
    ax: Axes | None = None,
) -> Axes:
    """Show missing-value counts for DataFrame columns.

    Args:
        df (pd.DataFrame): The DataFrame containing the data.
        ax (Axes | None, optional): The matplotlib Axes object to plot on. If None, a new figure and axes will be created.

    Returns:
        Axes: The matplotlib Axes object containing the plot.
    """
    if ax is None:
        _, ax = plt.subplots()

    missing = df.isna().sum()
    missing = missing[missing > 0].sort_values(ascending=False)

    if missing.empty:
        ax.text(
            0.5,
            0.5,
            "No missing values",
            ha="center",
            va="center",
            transform=ax.transAxes,
        )
        ax.set_title("Missing values")
        ax.set_axis_off()

        return ax

    ax.bar(
        missing.index,
        missing.to_numpy(),
    )

    ax.set_title("Missing values")
    ax.set_xlabel("Variable")
    ax.set_ylabel("Missing count")
    ax.tick_params(axis="x", labelrotation=45)

    return ax

def show_numeric_by_category(
    df: pd.DataFrame,
    *,
    numeric: str,
    category: str,
    ax: Axes | None = None,
) -> Axes:
    """Show a numeric distribution across categories.

    Args:
        df (pd.DataFrame): The DataFrame containing the data.
        numeric (str): The name of the numeric column.
        category (str): The name of the categorical column.
        ax (Axes | None, optional): The matplotlib Axes object to plot on. If None, a new figure and axes will be created.

    Returns:
        Axes: The matplotlib Axes object containing the plot.
    """
    require_numeric_column(df, column=numeric)
    require_columns(df, columns=[category])

    if ax is None:
        _, ax = plt.subplots()

    complete = df[[category, numeric]].dropna()

    categories = list(complete[category].drop_duplicates())

    groups = [
        complete.loc[
            complete[category] == value,
            numeric,
        ].to_numpy()
        for value in categories
    ]

    ax.boxplot(
        groups,
        tick_labels=[str(value) for value in categories],
    )

    ax.set_title(f"{numeric} by {category}")
    ax.set_xlabel(category)
    ax.set_ylabel(numeric)

    return ax

def show_numeric_distribution(
    df: pd.DataFrame,
    *,
    column: str,
    bins: int = 20,
    ax: Axes | None = None,
) -> Axes:
    """Show the distribution of one numeric variable.

    Args:
        df (pd.DataFrame): The DataFrame containing the data.
        column (str): The name of the numeric column.
        bins (int, optional): The number of bins for the histogram. Defaults to 20.
        ax (Axes | None, optional): The matplotlib Axes object to plot on. If None, a new figure and axes will be created.

    Returns:
        Axes: The matplotlib Axes object containing the plot.
    """
    require_numeric_column(df, column=column)

    if bins < 1:
        raise ValueError("bins must be at least 1")

    if ax is None:
        _, ax = plt.subplots()

    values = df[column].dropna()

    ax.hist(values, bins=bins)
    ax.set_title(f"Distribution of {column}")
    ax.set_xlabel(column)
    ax.set_ylabel("Count")

    return ax

def show_numeric_relationship(
    df: pd.DataFrame,
    *,
    x: str,
    y: str,
    ax: Axes | None = None,
) -> Axes:
    """Show the relationship between two numeric variables.

    Args:
        df (pd.DataFrame): The DataFrame containing the data.
        x (str): The name of the numeric column to be used as the x-axis.
        y (str): The name of the numeric column to be used as the y-axis.
        ax (Axes | None, optional): The matplotlib Axes object to plot on. If None, a new figure and axes will be created.

    Returns:
        Axes: The matplotlib Axes object containing the plot.
    """
    require_numeric_column(df, column=x)
    require_numeric_column(df, column=y)

    if ax is None:
        _, ax = plt.subplots()

    complete = df[[x, y]].dropna()

    ax.scatter(
        complete[x],
        complete[y],
    )

    ax.set_title(f"{y} by {x}")
    ax.set_xlabel(x)
    ax.set_ylabel(y)

    return ax