hist

Distributions

Minimal call

import random
rng = random.Random(7)
df = {"x": [rng.gauss(0, 1) for _ in range(800)]}

c = pt.chart(df, aes(x="x"), xlabel="value", ylabel="count")
c.add_hist(bins=24)

Worked example

import math

import plotlet as pt
from plotlet import aes

raw = pt.load_dataset("penguins")
keep = [i for i in range(len(raw["species"]))
        if not math.isnan(raw["body_mass_g"][i])]
df = {k: [raw[k][i] for i in keep] for k in ("species", "body_mass_g")}

c = pt.chart(df, aes(x="body_mass_g", fill="species"),
             title="body mass", xlabel="body mass (g)", ylabel="count",
             data_width=380, data_height=200)
c.add_hist(bins=24, position="stack")

Docstring

Histogram — binned counts of a 1-D distribution.

  c.add_hist(aes(x="col"))                          # columns via aes
  c.add_hist(aes(x="col", fill="group"))            # overlaid by group
  c.add_hist(aes(x="col", fill="group"), position="stack")

Multi-group calls share bin edges so the bars are comparable and the
positions line up.

Aesthetics:
  fill=         bare → constant color; aes(fill="col") → grouped multi-series
  color=        stroke color (constant, default None = no stroke)
  palette=      maps group levels → colors when fill is mapped in aes

Binning:
  bins=10             number of bins, or an explicit edge sequence
  binwidth=           fixed bin width (instead of a count)
  binrange=(lo, hi)   span to bin over; values outside are dropped
  weights=            aes(weights="col") or a literal sequence — sums
                      weights per bin instead of counting rows

Stats:
  density=False       True normalises so area under each set of bars is 1
  cumulative=False    running totals; with density=True the empirical CDF

Multi-group layout:
  position='overlay'  'stack' (bars pile up), 'fill' (100% stack), or
                      'dodge' (side-by-side within each bin);
                      histtype='bar' only

Other styling kwargs:
  histtype='bar'      'bar', 'step' (outline-only), or 'stepfilled'
  orientation='v'     'h' for horizontal bars
  alpha=<themed>      bar fill opacity
  linewidth=<themed>  stroke width (used only when color is set)