pgfplots

pgfplots — Data Visualization & Plotting

CTAN: https://ctan.org/pkg/pgfplots
Manual: texdoc pgfplots

Setup

\usepackage{pgfplots}
\pgfplotsset{compat=1.18}  % ALWAYS set this — enables latest features

% Optional libraries
\usepgfplotslibrary{fillbetween, groupplots, statistics, colorbrewer, polar}

Basic Plot

\begin{tikzpicture}
\begin{axis}[
  xlabel={$x$},
  ylabel={$f(x)$},
  title={My Plot},
  grid=major,
]
  \addplot[blue, thick, domain=-3:3, samples=100] {x^2};
  \addlegend{$x^2$}
\end{axis}
\end{tikzpicture}

Axis Environments

Environment	Description
axis	Standard linear axes
semilogxaxis	Log scale on x-axis
semilogyaxis	Log scale on y-axis
loglogaxis	Log scale on both axes
polaraxis	Polar coordinates (requires polar library)

Axis Options Reference

Option	Example	Description
xlabel	xlabel={Time (s)}	X-axis label
ylabel	ylabel={Voltage}	Y-axis label
title	title={Results}	Plot title
xmin/xmax	xmin=0, xmax=10	Axis limits
ymin/ymax	ymin=-1, ymax=1	Axis limits
domain	domain=0:2*pi	Default plot domain
samples	samples=200	Default sample count
grid	grid=major	major, minor, both, none
legend pos	legend pos=north west	Legend placement
width/height	width=10cm	Axis dimensions
axis lines	axis lines=middle	box, left, middle, none
enlargelimits	enlargelimits=0.1	Pad axis range
xtick	xtick={0,1,...,5}	Custom tick positions
xticklabels	xticklabels={A,B,C}	Custom tick labels
x tick label style	x tick label style={rotate=45}	Tick label formatting
legend style	legend style={at={(0.5,-0.2)}}	Legend customization
cycle list name	cycle list name=color list	Color cycling
scaled ticks	scaled ticks=false	Disable tick scaling
restrict y to domain	restrict y to domain=-10:10	Clip extreme values

Plot Types & Examples

Line Plot (from expression)

\begin{axis}[domain=0:2*pi, samples=100, grid=major,
  legend pos=south west]
  \addplot[blue, thick] {sin(deg(x))};
  \addplot[red, thick, dashed] {cos(deg(x))};
  \legend{$\sin(x)$, $\cos(x)$}
\end{axis}

Line Plot (from data)

\begin{axis}[xlabel=Year, ylabel=Value]
  \addplot coordinates {
    (2018, 10) (2019, 15) (2020, 12) (2021, 20) (2022, 25)
  };
\end{axis}

Scatter Plot

\begin{axis}[only marks, xlabel=$x$, ylabel=$y$]
  \addplot[mark=*, blue] coordinates {
    (1,2) (2,3.5) (3,2.8) (4,5.1) (5,4.2)
  };
  % Or with mark options:
  \addplot+[mark=o, mark size=3pt, red] coordinates { ... };
\end{axis}

Bar Chart

\begin{axis}[
  ybar,                    % vertical bars (xbar for horizontal)
  symbolic x coords={A, B, C, D},
  xtick=data,
  ylabel={Count},
  nodes near coords,       % value labels on bars
  bar width=15pt,
]
  \addplot coordinates {(A,20) (B,35) (C,30) (D,15)};
  \addplot coordinates {(A,25) (B,20) (C,40) (D,10)};
  \legend{2022, 2023}
\end{axis}

Stacked Bar

\begin{axis}[ybar stacked, symbolic x coords={Q1,Q2,Q3,Q4}, xtick=data]
  \addplot coordinates {(Q1,10) (Q2,15) (Q3,12) (Q4,18)};
  \addplot coordinates {(Q1,8)  (Q2,10) (Q3,15) (Q4,12)};
  \legend{Product A, Product B}
\end{axis}

Histogram

\usepgfplotslibrary{statistics}

\begin{axis}[ybar interval, ylabel=Frequency, xlabel=Value]
  \addplot+[hist={bins=10, data min=0, data max=100}]
    table[y index=0] {data.csv};
\end{axis}

Box Plot

\usepgfplotslibrary{statistics}

\begin{axis}[boxplot/draw direction=y]
  \addplot[boxplot prepared={
    lower whisker=2, lower quartile=4,
    median=6, upper quartile=8, upper whisker=10
  }] coordinates {};
\end{axis}

Area / Fill Between

\usepgfplotslibrary{fillbetween}

\begin{axis}
  \addplot[name path=upper, blue, thick, domain=0:4] {x^2};
  \addplot[name path=lower, red, thick, domain=0:4] {x};
  \addplot[fill=blue!10] fill between[of=upper and lower, soft clip={domain=1:3}];
\end{axis}

Error Bars

\begin{axis}
  \addplot+[error bars/.cd, y dir=both, y explicit]
    coordinates {
      (1, 2) +- (0, 0.5)
      (2, 4) +- (0, 0.8)
      (3, 3) +- (0, 0.3)
    };
\end{axis}

3D Surface

\begin{axis}[view={45}{30}, xlabel=$x$, ylabel=$y$, zlabel=$z$,
  colormap/viridis]
  \addplot3[surf, domain=-2:2, domain y=-2:2, samples=25]
    {exp(-x^2 - y^2)};
\end{axis}

3D Mesh

\begin{axis}[view={60}{30}]
  \addplot3[mesh, domain=-2:2, domain y=-2:2, samples=20]
    {sin(deg(x)) * cos(deg(y))};
\end{axis}

Contour

\begin{axis}[view={0}{90}]  % top-down view
  \addplot3[contour filled, domain=-2:2, domain y=-2:2, samples=30]
    {exp(-x^2 - y^2)};
\end{axis}

Parametric Plot

\begin{axis}[axis equal]
  \addplot[domain=0:360, samples=100, thick, blue]
    ({cos(x)}, {sin(x)});  % circle
\end{axis}

Polar Plot

\usepgfplotslibrary{polar}

\begin{polaraxis}
  \addplot[domain=0:360, samples=100, thick]
    {1 + cos(x)};  % cardioid
\end{polaraxis}

Data from Files

% CSV file: data.csv
% x, y
% 1, 2.3
% 2, 4.1
% ...

\begin{axis}
  \addplot table[col sep=comma, x=x, y=y] {data.csv};
  
  % TSV (default separator is space/tab)
  \addplot table[x index=0, y index=1] {data.tsv};
  
  % With expression on column
  \addplot table[x=time, y expr=\thisrow{value}*100] {data.csv};
\end{axis}

Color Maps

% Built-in colormaps
colormap/hot, colormap/cool, colormap/viridis,
colormap/bluered, colormap/greenyellow, colormap/jet

% Custom
\pgfplotsset{
  colormap={mymap}{rgb255(0cm)=(0,0,180); rgb255(1cm)=(0,180,0); rgb255(2cm)=(180,0,0)}
}

% Colorbar
\begin{axis}[colorbar, colormap/viridis]

Multiple Axes

\begin{tikzpicture}
\begin{axis}[
  axis y line*=left, xlabel=Time, ylabel=Temperature,
  ymin=0, ymax=100,
]
  \addplot[blue, thick] coordinates {(1,20)(2,40)(3,60)(4,80)};
  \label{plot:temp}
\end{axis}

\begin{axis}[
  axis y line*=right, axis x line=none,
  ylabel=Pressure, ymin=0, ymax=10,
]
  \addplot[red, thick, dashed] coordinates {(1,2)(2,5)(3,3)(4,8)};
  \label{plot:press}
\end{axis}
\end{tikzpicture}

Group Plots

\usepgfplotslibrary{groupplots}

\begin{tikzpicture}
\begin{groupplot}[
  group style={group size=2 by 2, horizontal sep=1.5cm, vertical sep=1.5cm},
  width=6cm, height=5cm,
]
  \nextgroupplot[title=Plot 1]
    \addplot {x};
  \nextgroupplot[title=Plot 2]
    \addplot {x^2};
  \nextgroupplot[title=Plot 3]
    \addplot {sqrt(x)};
  \nextgroupplot[title=Plot 4]
    \addplot {ln(x)};
\end{groupplot}
\end{tikzpicture}

Annotations

\begin{axis}
  \addplot[blue, thick, domain=0:5] {x^2};
  
  % Pin annotation
  \node[pin=60:{Maximum}] at (axis cs:4, 16) {};
  
  % Arrow annotation
  \draw[->, thick] (axis cs:2, 10) -- (axis cs:3, 9)
    node[above, pos=0] {Note};
  
  % Vertical line
  \draw[dashed, gray] (axis cs:2.5, 0) -- (axis cs:2.5, 25);
  
  % Horizontal band
  \draw[fill=red!10, draw=none] (axis cs:0,5) rectangle (axis cs:5,10);
  
  % Text node
  \node at (axis cs:1, 20) {$f(x) = x^2$};
\end{axis}

Mark Options

Mark	Description
*	Filled circle
o	Open circle
square*	Filled square
square	Open square
triangle*	Filled triangle
diamond*	Filled diamond
x	Cross
+	Plus
star	Star
none	No marks

\addplot+[mark=triangle*, mark size=3pt, mark options={fill=red}] ...;

Common Pitfalls

Problem	Cause	Fix
"Dimension too large"	Large values or domain	Use restrict y to domain, check domain
Missing compat warning	No \pgfplotsset{compat=..}	Add \pgfplotsset{compat=1.18}
Trig functions wrong	pgfplots uses degrees	Use sin(deg(x)) for radians input
Bars overlapping	Multiple bar plots without grouping	Use ybar with bar shift or legend
Legend in wrong spot	Default position	Set legend pos=north west etc.
3D plot too slow	Too many samples	Reduce samples for 3D
Axis labels cut off	Tight bounding box	Use trim axis left/right or increase margins
Fill between fails	Paths not named	Add name path=A to each plot
CSV column error	Wrong separator	Set col sep=comma for CSV files
\addlegendentry order	Must follow its \addplot	Put legend entry right after its plot