publiplots.lineplot¶

publiplots.lineplot(data, x=None, y=None, hue=None, size=None, style=None, units=None, weights=None, palette=None, hue_order=None, hue_norm=None, sizes=None, size_order=None, size_norm=None, dashes=True, markers=None, style_order=None, estimator='mean', errorbar=('ci', 95), n_boot=1000, seed=None, orient='x', sort=True, err_style='band', err_kws=None, color=None, alpha=None, linewidth=None, markersize=None, markeredgewidth=None, edgecolor=None, ax=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None, **kwargs)[source]¶

Create a line plot with publiplots styling and seaborn-parity kwargs.

Line plots draw one or more line series over a shared x variable. Observations at each x are aggregated with estimator and error uncertainty is drawn as bands or bars per err_style. Supports visual encoding of additional variables via hue (color), size (line width), and style (marker + dash pattern).

Parameters:

data (pd.DataFrame) – Input data containing x, y, and any encoded columns.
x (str, optional) – Column name for the x-axis variable.
y (str, optional) – Column name for the y-axis variable.
hue (str, optional) – Column name for color encoding. Can be categorical (uses palette mapping) or continuous (renders a colorbar legend).
size (str, optional) – Column name for line-width encoding.
style (str, optional) – Column name for marker/dash style encoding. Categorical only.
units (str, optional) – Column name for sampling units (for nested data).
weights (str, optional) – Column name for observation weights.
palette (str, dict, list, or None) –
Color palette for hue:
- str: palette name (e.g., “viridis”, “pastel”)
- dict: mapping of hue values to colors (categorical only)
- list: list of colors
- None: uses default palette
hue_order (list, optional) – Order of categorical hue levels.
hue_norm (tuple of float or Normalize, optional) – (vmin, vmax) or a Normalize instance for continuous hue. If None with numeric hue, inferred from data.
sizes (list, dict, or tuple of float, optional) – Width range or mapping for size encoding.
size_order (list, optional) – Order of categorical size levels.
size_norm (tuple of float or Normalize, optional) – Normalization for numeric size.
dashes (bool, list, or dict, default=True) – Dash patterns for style levels. True uses defaults, a list/dict specifies patterns, False disables dashing.
markers (bool, list, or dict, optional) – Markers for style levels. True uses defaults, a list/dict specifies markers, None/False draws no markers.
style_order (list, optional) – Order of categorical style levels.
estimator (str or callable, default="mean") – Aggregator applied within each x group. None disables aggregation (one line per observation).
errorbar (str or tuple, default=("ci", 95)) –
Error-bar / band specification. Accepts every seaborn-native form — see seaborn.lineplot() for the full list: ("ci", level), ("pi", level), ("se", mult), "sd", None.

publiplots additionally supports ("custom", (lower_col, upper_col)) to render a shaded band from precomputed lower/upper bounds stored on the data (e.g. from a LOESS / GAM / spline fit, a Bayesian posterior, or a bootstrap CI you already computed). When this form is used, estimator is forced to "median" and any n_boot / seed arguments are ignored.

Example:
```
pp.lineplot(
    data=smooth_df, x='day', y='y', hue='group',
    errorbar=('custom', ('ci_lo', 'ci_hi')),
    err_style='band',
)
```
n_boot (int, default=1000) – Number of bootstrap iterations for CI computation.
seed (int, optional) – Seed for the random number generator used in bootstrapping.
orient (str, default="x") – Aggregation axis. “x” aggregates within x; “y” within y.
sort (bool, default=True) – Sort by x before drawing. Set False to preserve input order.
err_style (str, default="band") – How to draw error uncertainty: "band" (shaded region) or "bars" (discrete error bars per estimate).
err_kws (dict, optional) – Extra styling kwargs forwarded to the error-band/bar artists.
color (str, optional) – Fixed color used when hue is None. Falls back to rcParams.
alpha (float, optional) – Transparency for lines and fills. Falls back to rcParams.
linewidth (float, optional) – Base line width. Falls back to rcParams.
markersize (float, optional) – Marker size for style legend. Falls back to rcParams.
markeredgewidth (float, optional) – Width of marker edges for style legend. Falls back to rcParams.
edgecolor (str, optional) – Edge color for categorical legend swatches. Falls back to rcParams.
ax (Axes, optional) – Matplotlib axes to draw on. If None, a new figure is created via publiplots.layout.subplots(). Recover the figure from the returned axes with ax.get_figure().
title (str, default="") – Plot title.
xlabel (str, default="") – X-axis label. Passed through only if non-empty.
ylabel (str, default="") – Y-axis label. Passed through only if non-empty.
legend (bool or dict, default=True) – Legend control. True stashes and renders all legend kinds. False stashes and renders nothing. A dict enables/disables specific kinds, e.g. {"hue": False} hides only hue.
legend_kws (dict, optional) – Legend builder tuning. Supported keys: hue_label, size_label, style_label (override kind titles); size_nbins, size_min_n_ticks, size_include_min_max (forwarded to get_size_ticks()).
**kwargs – Extra keyword arguments forwarded to seaborn.lineplot(). figsize is rejected — use pp.subplots(axes_size=...) first and pass ax= instead.

Returns:

The axes where the plot was drawn. Use ax.get_figure() to recover the figure handle.

Return type:

Axes

Examples

Simple line plot with aggregation:

>>> ax = pp.lineplot(data=df, x="time", y="value")

Categorical hue with custom palette:

>>> ax = pp.lineplot(
...     data=df, x="time", y="value",
...     hue="group", palette="pastel",
... )

Continuous hue (renders a colorbar) with bars for uncertainty:

>>> ax = pp.lineplot(
...     data=df, x="time", y="value",
...     hue="score", palette="viridis",
...     hue_norm=(0, 100), err_style="bars",
... )