alphapepttools.pl.histogram

Contents

alphapepttools.pl.histogram#

alphapepttools.pl.histogram(data, value_column, color_map_column=None, bins=10, ax=None, color='blue', palette=None, color_dict=None, legend=None, hist_kwargs=None, legend_kwargs=None, xlim=None, ylim=None)#

Plot a histogram from a DataFrame or AnnData object

Creates a histogram showing the distribution of values, with optional grouping by a categorical column. When grouping is used, overlapping histograms are created with the same bin edges for easy comparison.

Parameters:

  • data (DataFrame | AnnData) – Data to plot, must contain the value_column and optionally the color_map_column for grouping.

  • value_column (str) – Column containing numeric values to plot in the histogram.

  • color_map_column (str | None (default: None)) – Column for categorical grouping. Each unique value gets its own colored histogram overlay. NaN values are converted to strings.

  • bins (int (default: 10)) – Number of bins for the histogram. Default is 10.

  • ax (Axes | None (default: None)) – Matplotlib axes to plot on. If None, a new figure is created.

  • color (str (default: 'blue')) – Single color for ungrouped histogram. Default is “blue”.

  • palette (list[tuple] | None (default: None)) – Color palette for grouped histograms. Defaults to qualitative palette.

  • color_dict (dict[str, str | tuple] | None (default: None)) – Explicit mapping of groups to colors. Overrides palette if provided.

  • legend (str | Legend | None (default: None)) – If “auto”, creates legend for grouped data. Can also pass existing Legend.

  • hist_kwargs (dict | None (default: None)) – Additional arguments for matplotlib.hist() like: - alpha: transparency (0-1) - histtype: ‘bar’, ‘step’, ‘stepfilled’ - edgecolor: outline color - linewidth: outline width

  • legend_kwargs (dict | None (default: None)) – Additional arguments for legend like title, loc, fontsize.

  • xlim (tuple[float, float] | None (default: None)) – X-axis limits as (min, max).

  • ylim (tuple[float, float] | None (default: None)) – Y-axis limits as (min, max).

Return type:

None

Returns:

None

Examples

Simple histogram:

import pandas as pd
from alphapepttools.pl.figure import create_figure
import alphapepttools as apt

df = pd.DataFrame({"intensity": [1.5, 2.3, 2.8, 1.9, 3.1, 2.5]})

fig, axm = create_figure(1, 1, figsize=(6, 4))
ax = axm.next()
apt.pl.histogram(data=df, value_column="intensity", bins=30, color="skyblue", ax=ax)

Grouped histogram with transparency:

import pandas as pd
from alphapepttools.pl.figure import create_figure
import alphapepttools as apt

df = pd.DataFrame(
    {
        "values": [1.5, 2.3, 2.8, 1.9, 3.1, 2.5, 4.2, 3.8],
        "condition": ["A", "A", "B", "B", "A", "B", "A", "B"],
    }
)

fig, axm = create_figure(1, 1, figsize=(6, 4))
ax = axm.next()
apt.pl.histogram(
    data=df,
    value_column="values",
    color_map_column="condition",
    bins=20,
    legend="auto",
    hist_kwargs={"alpha": 0.7, "histtype": "stepfilled"},
    legend_kwargs={"title": "Condition"},
    ax=ax,
)

Custom color mapping:

import pandas as pd
from alphapepttools.pl.figure import create_figure
import alphapepttools as apt

example_df = pd.DataFrame(
    {
        "values": [1, 2, 3, 4, 5, 6, 7, 8, 9],
        "levels": ["A", "B", "C", "A", "B", "C", "A", "B", "C"],
    }
)

fig, axm = create_figure(1, 1, figsize=(6, 4))
ax = axm.next()
apt.pl.histogram(
    data=example_df,
    value_column="values",
    color_map_column="levels",
    color_dict={"A": "red", "B": "blue", "C": "green"},
    bins=20,
    ax=ax,
    legend="auto",
    hist_kwargs={"alpha": 0.7, "histtype": "stepfilled", "edgecolor": "k"},
    legend_kwargs={"title": "Levels", "loc": "upper left"},
)

Notes

  • When grouping data, all groups use the same bin edges for comparison

  • Unmapped groups in color_dict default to grey

  • NaN values are excluded from the histogram

Contents