Introduction

grplot introduces powerful features through an intuitive, hierarchical argument system. Every feature is directly accessible via plot2d parameters, allowing you to configure everything from high-level data inputs to the finest label details in a single function call.

Understanding the Argument System

Arguments in grplot are processed at four different levels of granularity:

• Ordinary arguments — Apply to the entire figure (e.g., df, figsize, Nx).

• Axes arguments — Apply to specific subplots (e.g., plot, filter, title).

• Axes-plot arguments — Apply to specific plots within a subplot (e.g., zorder).

• Axes-axislabel arguments — Apply to specific axes and labels (e.g., lim, sep).

💡 Global Rule: The X and Y Counterparts

To reduce repetition, almost all axes-axislabel arguments (like sep, lim, log, dt, tick_add, label_add, statdesc, text, rot) apply to both axes by default.

You can easily target a specific axis by prefixing the argument with x or y. (Example: lim sets both limits; xlim sets only the x-axis limit; ylim sets only the y-axis limit.)

Argument Syntax Guide

Depending on the hierarchical level of the argument, grplot allows you to target specific subplots or layers using dictionary mapping. Below is the syntax guide showing how to assign a value (represented by return) to an argument (arg).

Note

• A 1-row figure uses a 1D axes index: '[i]' (e.g., '[1]').

• A multi-row figure uses a 2D axes index: '[i,j]' (e.g., '[1,1]').

• Important: Axes arguments start from 1 (unlike pure matplotlib, which starts from 0).

Ordinary argument:

arg = return

Axes arguments:

arg = return
arg = {'[i,j]': return}
arg = {return: '[i,j]'}
arg = {return: ['[i,j]']}

Axes-plot arguments:

arg = return
arg = {'plot': return}
arg = {'[i,j]': {'plot': return}}
arg = {'[i,j]': {return: 'plot'}}
arg = {'[i,j]': {return: ['plot']}}
arg = {'[i,j]': return}
arg = {return: 'plot'}
arg = {return: ['plot']}

Axes-axislabel arguments:

arg = return
arg = {'axislabel': return}
arg = {'[i,j]': {'axislabel': return}}
arg = {'[i,j]': {return: 'axislabel'}}
arg = {'[i,j]': {return: ['axislabel']}}
arg = {'[i,j]': return}
arg = {return: 'axislabel'}
arg = {return: ['axislabel']}

Core Data & Plot Setup

These parameters define what you are plotting and the data behind it.

Parameter	Argument Level	Input	Description
plot	Axes	e.g., 'scatterplot' (combine multiple plots using + such as 'plot1+plot2')	Plot type
df	Ordinary	pandas.DataFrame, dict of lists, or dict of numpy.ndarray	Input data source
x / y	Ordinary	str, list, numpy.ndarray, pandas.Index, or None; returns key(s) mapping to df	Input variable(s)
filter	Axes	Pandas query string or boolean pandas.Series	Data filtering prior to plotting

Figure & Subplot Layout

Control the grid structure and spacing of your overall figure. All are Ordinary arguments.

Parameter	Input	Default	Description
Nx / Ny	int (grid size) or None for auto	Dynamic	Grid columns (Nx) / rows (Ny). Defaults: Nx = max(Nx, Ny) if ≤ 2 else 2. Ny = 1 if max(Nx, Ny) ≤ 2 else ceil(max/2).
figsize	list/tuple of two numbers	[8, 6]	Figure dimensions: Width, height in inches.
pad	numeric	6	Outer padding between figure edge and subplots (fraction of font size).
hpad / wpad	numeric	pad	Inner padding height/width between adjacent subplots.

Axis Controls & Scales

Fine-tune the behavior of your x and y axes. All are Axes-axislabel arguments. (Remember: prefix with x or y to target a single axis).

Parameter	Input	Default	Description
lim	[bottom, top]	None	Axis limit.
log	'linear', 'log', 'symlog', or 'logit'	None	Axis scale.
dt	strftime date format (e.g., '%Y-%m-%d')	None	Datetime format using Python’s standard strftime formats.
rot	float (degrees)	None	Tick rotation in degrees.

Formatting & Units

grplot provides powerful built-in string manipulation for numbers and labels. (Remember: prefix with x or y to target a single axis).

Number formatting uses the sep argument. Patterns may include separators, currency, and large-number abbreviations.

Pattern	Meaning	Example
',' / '.'	Thousand separator	1,000 / 1.000
',c' / '.c'	Currency-style formatting (adds trailing zeros)	1000 → 1,000.00 or 1.000,00
',L' / '.L'	Large-number abbreviation (K, M, B, T, Q)	1.5M, 1,000 / 1,5M, 1.000
',cL' / '.cL'	Currency + abbreviation	1.5M, 1,000.00 / 1,5M, 1.000,00

Unit patterns are specified separately for ticks and labels:

Parameter	Input	Effect
tick_add	'{}_' '_{}' '{}_{}'	Prefix/suffix value with unit
tick_add (negatives)	'{}(_)' '(_){}' '{}(_){}'	Wrap negatives in parentheses: ($100), (100)kg
label_add	'{}_' '_{}' '{}_{}'	Add unit to axis label itself

Annotations & Statistics

Easily layer text and statistical descriptions over your data.

Parameter	Argument Level	Description
statdesc	Axes-axislabel	Statistical summaries added to the plot. Combine using + (e.g., 'mean+std'). Prefix with x or y to apply only to one axis (xstatdesc, ystatdesc).
text	Axes-axislabel	Data annotations (see details below). Prefix with x or y to target a single axis (xtext, ytext).
xlabel / ylabel	Axes	Explicit axis labels (str). Overrides label_add configurations.
title	Axes	Plot/Subplot title (str).

Text argument details:

• Type & default: bool/str/None (default None).

• Both axes by default: apply to x‑ and y‑axes unless prefixed with x or y.

• When `bool`: toggles automatic labels on points/bars. Used by scatterplot, lineplot, pieplot, treemapsplot, packedbubblesplot, and residplot.

• When `str`: specifies base position(s) using 'h' (horizontal), 'v' (vertical), 'i' (inside), or 'o' (outside). Accepts a single position or a combination separated by + (e.g., 'h+i'). Used by histplot, barplot, countplot, and paretoplot.

Available statdesc Returns:

• Grouped: 'general', 'boxplot'

• Central & Spread: 'mean', 'median', 'std', 'range', 'min', 'max'

• Counts: 'count', 'nonzero', 'unique'

• Quartiles & Bounds: 'q1', 'q3', 'pct1', 'pct5', 'pct95', 'pct99', 'whislo', 'whishi', 'cilo', 'cihi'

Styling, Typography & Drawing Order

Control the aesthetic elements of the plot. All font parameters belong to the Axes level.

Parameter	Input	Default	Description
fontsize	numeric	10	Base font size. Acts as the fallback for all text.
*_fontsize	numeric	fontsize	Specific sizing for: tick, legend, text, label, or title.
legend_loc	str	'best'	Legend position; valid keywords include: 'best', 'upper right', 'upper left', 'lower left', 'lower right', 'right', 'center left', 'center right', 'lower center', 'upper center', 'center'.

Performance & Export

Manage system resources and save your output. Both are Ordinary arguments.

Parameter	Input	Default	Description
optimizer	str	'perf'	'perf'/'pandas' — fast, more memory. 'saver'/'numpy' — slower, less memory.
saveas	str or None	None	Save figure as .png, .pdf, .svg, or .eps