summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
blob: 6c220b201ae408313928d3f1fea3599af5492aca (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866

\subsection{Axis Descriptions}
Axis descriptions are labels for $x$ and $y$ axis, titles, legends and the like. Axis descriptions are drawn after the plot is finished and they are not subjected to clipping. 

\subsubsection{Placement of Axis Descriptions}
This section describes how to \emph{modify} the placement of titles, labels, legends and other axis descriptions. It may be skipped at first reading.

There are different methods to place axis descriptions. One of them is to provide coordinates relative to the axis' rectangle such that |(0,0)| is the lower left corner and |(1,1)| is the upper right corner -- this is very useful for figure titles or legends. Coordinates of this type, i.e.\ without unit like |(0,0)| or |(1.03,1)|, are called |axis description cs| (the |cs| stands for ``coordinate system''). One other method is of primary interest for axis labels -- they should be placed near the tick labels, but it a way that they don't overlap or obscure tick labels. Furthermore, axis labels shall be placed such that they are automatically moved if the axis is rotated (or tick labels are moved to the right side of the figure). There is a special coordinate system to realize these two demands, the |ticklabel cs|.

In the following, the two coordinate systems |axis description cs| and |ticklabel cs| are described in more details. It should be noted that |axis description cs| is used automatically, so it might never be necessary to use it explicitly.


\begin{coordinatesystem}{axis description cs}
\label{pgfplots:sec:axis:description:cs}
	A coordinate system which is used to place axis descriptions. Whenever the option `|at={(|\meta{x}|,|\meta{y}|)}|' occurs in |label style|, |legend style| or any other axis description, |(|\meta{x}|,|\meta{y}|)| is interpreted to be a coordinate in |axis description cs|.

	The point $(0,0)$ is always the lower left corner of the tightest bounding box around the axis (without any descriptions or ticks) while the point $(1,1)$ is the upper right corner of this bounding box.

	In most cases, it is \emph{not} necessary to explicitly write |axis description cs| as it is the default coordinate system for any axis description. An example for how coordinates are placed is shown below.
	
\begin{codeexample}[width=4cm]
% [See the TikZ manual if you'd like to learn about nodes and pins]
\begin{tikzpicture}
	\tikzset{
		every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
		small dot/.style={fill=black,circle,scale=0.3}
	}
	\begin{axis}[
		clip=false,
		title=How \texttt{axis description cs} works
	]
	\addplot {x};

	\node[small dot,pin=120:{$(0,0)$}]      at (axis description cs:0,0) {};
	\node[small dot,pin=-30:{$(1,1)$}]      at (axis description cs:1,1) {};
	\node[small dot,pin=-90:{$(1.03,0.5)$}] at (axis description cs:1.03,0.5) {};
	\node[small dot,pin=125:{$(0.5,0.5)$}]  at (axis description cs:0.5,0.5) {};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

Axis descriptions are \Tikz\ nodes, that means all placement and detail options of \cite{tikz} apply. The point on the node's boundary which is actually shifted to the |at| coordinate needs to be provided with an anchor (cf~\cite[Nodes and Edges]{tikz}):
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		legend entries={$x$,$x^2$},
		legend style={
			at={(1.03,0.5)},
			anchor=west
		}
	]
	\addplot {x};
	\addplot {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	Standard anchors of nodes are |north|, |east|, |south|, |west| and mixed components like |north east|.
	Please refer to \cite{tikz} for a complete documentation of anchors.

\paragraph{Remarks:} 
\begin{itemize}
	\item Each of the anchors described in section~\ref{pgfplots:sec:align} can be described by |axis description cs| as well.
	\item The |axis description cs| is independent of axis reversals or skewed axes.
	Only for the default configuration of boxed axes is it the same as |rel axis cs|, i.e.\ |(0,0)| is the same as the smallest axis coordinate and |(1,1)| is the largest one in case of standard boxed axes\footnote{This was different in versions before 1.3: earlier versions did not have the distinction between \texttt{axis description cs} and \texttt{rel axis cs}.}.

	\item Even for three dimensional axes, the |axis description cs| is still two-dimensional: it always refers to coordinates relative to the tightest bounding box around the axis (without any descriptions or ticks).
\begin{codeexample}[width=4cm]
% the same as above for 3D ...
% [See the TikZ manual if you'd like to learn about nodes and pins]
\begin{tikzpicture}
	\tikzset{
		every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
		small dot/.style={fill=black,circle,scale=0.3}
	}
	\begin{axis}[
		clip=false,
		title=How \texttt{axis description cs} works in 3D
	]
	\addplot3 coordinates {(-5,-5,-5) (5,5,5)};

	\draw[black!15] (axis description cs:0,0) rectangle (axis description cs:1,1);

	\node[small dot,pin=120:{$(0,0)$}]      at (axis description cs:0,0) {};
	\node[small dot,pin=-30:{$(1,1)$}]      at (axis description cs:1,1) {};
	\node[small dot,pin=-90:{$(1.03,0.5)$}] at (axis description cs:1.03,0.5) {};
	\node[small dot,pin=125:{$(0.5,0.5)$}]  at (axis description cs:0.5,0.5) {};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	\item Since the view does not influence these positions, |axis description cs| might not be a good choice for axis labels in 3D. The |ticklabel cs| is used in this case.
\end{itemize}
\end{coordinatesystem}

\begin{coordinatesystemlist}{%
	xticklabel cs,%
	yticklabel cs,%
	zticklabel cs,
	ticklabel cs}
	A set of special coordinate systems intended to place axis descriptions (or any other drawing operation) besides tick labels, in a way such that neither tick labels nor the axis as such are obscured.

	See also |xlabel near ticks| as one main application of |ticklabel cs|.

	The |xticklabel cs| (and its variants) always refer to one, uniquely identified axis: the one which is (or would be) annotated with tick labels. 
	
	The |ticklabel cs| (without explicit \texttt{x}, \texttt{y} or \texttt{z}) can only be used in contexts where the axis character is known from context (for example, inside of |xlabel style| -- there, the |ticklabel cs| is equivalent to |xticklabel cs|).

	Each of these coordinate systems allows to specify points on a straight line which is placed parallel to an axis containing tick labels, moved away just far enough to avoid overlaps with the tick labels:
\begin{codeexample}[width=4cm]
\tikzset{
	every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
	small dot/.style={fill=black,circle,scale=0.3}
}
\begin{tikzpicture}
\begin{axis}[
	clip=false,
	ticklabel style={draw=red},
	title=Positioning with \texttt{xticklabel cs}]
	\addplot {x};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:0}}]     at (xticklabel cs:0) {};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:0.5}}]   at (xticklabel cs:0.5) {};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:1}}]     at (xticklabel cs:1) {};


	\node[small dot,pin=180:{\texttt{yticklabel cs:0}}]     at (yticklabel cs:0) {};
	\node[small dot,pin=180:{\texttt{yticklabel cs:0.5}}]   at (yticklabel cs:0.5) {};
	\node[small dot,pin=180:{\texttt{yticklabel cs:1}}]     at (yticklabel cs:1) {};
\end{axis}
\end{tikzpicture}
\end{codeexample}

The basic idea is to place coordinates on a straight line which is parallel to the axis containing tick labels -- but shifted such that the line does not cut through tick labels.

Of course, it is relatively simple to get the same coordinates as in the two dimensional example above with |axis description cs|, except that |ticklabel cs| always respects the tick label sizes appropriately. However, |ticklabel cs| becomes far superior when it comes to three dimensional positioning:

\begin{codeexample}[width=4cm]
% the same as above for 3D ...
\begin{tikzpicture}
	\tikzset{
		every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
		small dot/.style={fill=black,circle,scale=0.3}
	}
	\begin{axis}[
		ticklabel style={draw=red},
		clip=false,
		title=Positioning with \texttt{ticklabel cs} in 3D
	]
	\addplot3 coordinates {(-5,-5,-5) (5,5,5)};

	\node[small dot,pin=-90:{\texttt{xticklabel cs:0}}]     at (xticklabel cs:0) {};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:0.5}}]   at (xticklabel cs:0.5) {};
	\node[small dot,pin=-90:{\texttt{xticklabel cs:1}}]     at (xticklabel cs:1) {};

	\node[small dot,pin=-45:{\texttt{yticklabel cs:0}}]     at (yticklabel cs:0) {};
	\node[small dot,pin=-45:{\texttt{yticklabel cs:0.5}}]   at (yticklabel cs:0.5) {};
	\node[small dot,pin=-45:{\texttt{yticklabel cs:1}}]     at (yticklabel cs:1) {};

	\node[small dot,pin=180:{\texttt{zticklabel cs:0}}]     at (zticklabel cs:0) {};
	\node[small dot,pin=180:{\texttt{zticklabel cs:0.5}}]   at (zticklabel cs:0.5) {};
	\node[small dot,pin=180:{\texttt{zticklabel cs:1}}]     at (zticklabel cs:1) {};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The coordinate |ticklabel cs:0| is associated to the lower axis limit while |ticklabel cs:1| is near the upper axis limit.  The value |0.5| is in the middle of the axis, any other values (including negative values or values beyond $1$) are linearly interpolated inbetween.

	The |ticklabel cs| also accepts a second (optional) argument: a shift ``away'' from the tick labels. The shift points to a vector which is orthogonal to the associated axis, away from the tick labels. A shift of |0pt| is directly at the edge of the tick labels in direction of the normal vector, positive values move the position away and negative closer to the tick labels.
\begin{codeexample}[width=4cm]
\tikzset{
	every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny},
	small dot/.style={fill=black,circle,scale=0.3}
}
\begin{tikzpicture}
	\begin{axis}[
		xticklabel style={draw=red},
		clip=false,
		title=\texttt{ticklabel cs} and its optional shift
	]
	\addplot3 coordinates {(-5,-5,-5) (5,5,5)};

	\draw[blue,thick,->]      (xticklabel cs:0,0)     -- (xticklabel cs:1,0);
	\draw[red,thick,->]       (xticklabel cs:0,5pt)   -- (xticklabel cs:1,5pt);
	\draw[magenta,thick,->]   (xticklabel cs:0,10pt)  -- (xticklabel cs:1,10pt);
	\draw[green,thick,->]     (xticklabel cs:0,15pt)  -- (xticklabel cs:1,15pt);
	\node[small dot,pin=0:{\texttt{xticklabel cs:1,0}}]      at (xticklabel cs:1,0) {};
	\node[small dot,pin=0:{\texttt{xticklabel cs:1,15pt}}]   at (xticklabel cs:1,15pt) {};

	\draw[blue,thick,->]      (xticklabel cs:0,0)     -- (xticklabel cs:0,15pt);
	\draw[blue,thick,->]      (xticklabel cs:1,0)     -- (xticklabel cs:1,15pt);
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	Whenever the |ticklabel cs| is used, the anchor should be set to |anchor=near ticklabel| (see below).

	There is one speciality: if you reverse an axis (with |x dir=reverse|), points provided by |ticklabel cs| will be \emph{unaffected} by the axis reversal. This is intented to provide consistent placement even for reversed axes. Use |allow reversal of rel axis cs=false| to disable this feature.
\end{coordinatesystemlist}


Besides the mentioned positioning methods, there is also the predefined node |current axis|. The anchors of |current axis| can also be used to place descriptions: At the time when axis descriptions are drawn, all anchors which refer to the axis origin (that means the ``real'' point $(0,0)$) or any of the axis corners can be referenced using |current axis.|\meta{anchor name}. Please see section~\ref{pgfplots:sec:align}, Alignment, for further details.

\subsubsection{Alignment of Axis Descriptions}
This section describes how to modify the default alignment of axis descriptions. It can be skipped at first reading.

The two topics positioning and alignment always work together: \emph{positioning} means to select an appropriate coordinate and \emph{alignment} means to select an anchor inside of the description which will actually be moved to the desired position.

\Tikz\ uses many anchors to provide alignment; most of them are named like |north|, |north east| etc. These names hold for any axis description as well (as axis description are \Tikz\ nodes). Readers can learn details about this topic in the \Tikz\ manual~\cite{tikz} or some more advice in section~\ref{pgfplots:sec:align}.

When it comes to axis descriptions, \PGFPlots\ offers some specialized anchors and alignment methods which are described below.
\begin{anchorlist}{near xticklabel,near yticklabel,near zticklabel,near ticklabel}
	These anchors can be used to align at the part of a node (for example, an axis description) which is \emph{nearest} to the tick labels of a particular axis (or nearest to the position where tick labels would have been drawn if there were any).

	These anchors are used for axis labels, especially for three dimensional axes. Furthermore, they are used for every tick label.

\label{key:near:ticklabel}
	Maybe it is best to demonstrate it by example:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		title=Without \texttt{near ticklabel},
		ylabel={$f(x)=x$},
		every axis y label/.style=
			{at={(ticklabel cs:0.5)},rotate=90,anchor=center},
		clip=false,% to display the \path below
		ylabel style={draw=red},
		yticklabel style={draw=red}
	]

		\addplot {x};

		% visualize the position:
		\fill (yticklabel cs:0.5) circle(2pt);
	\end{axis}
\end{tikzpicture}%
~
\begin{tikzpicture}
	\begin{axis}[
		title=With \texttt{near ticklabel},
		ylabel={$f(x)=x$},
		every axis y label/.style=
			{at={(ticklabel cs:0.5)},rotate=90,anchor=near ticklabel},
		clip=false,
		ylabel style={draw=red},
		yticklabel style={draw=red}
	]

		\addplot {x};
		\fill (yticklabel cs:0.5) circle(2pt);
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The motivation is to place nodes such that they are anchored next to the tick label, regardless of the node's rotation or the position of ticks. The special anchor |near ticklabel| is only available for axis labels (as they have a uniquely identified axis, either $x$, $y$ or $z$).

	In more detail, the anchor is placed such that first, the node's center is on a line starting in the node's |at| position going in direction of the inwards normal vector of the axis line which contains the tick labels and second, the node does not intrude the axis. This normal vector is the same which is used for the shift argument in |ticklabel cs|: it is orthogonal to the tick label axis. Furthermore, |near ticklabel| inverts the transformation matrix before it computes this intersection point.

	The |near ticklabel| anchor and its friends will be added temporarily to any shape used inside of an axis. This includes axis description, but it is not limited to them: it applies to every \Tikz\ |\node[anchor=near xticklabel] ...| setting.

	Note that it is not necessary at all to \emph{have} tick labels in an axis. The anchor will be placed such that it is near the axis on which tick labels \emph{would} be drawn. In fact, every tick label uses |anchor=near ticklabel| as initial configuration.
\end{anchorlist}

\begin{pgfplotsxykeylist}{/tikz/sloped like \x\space axis}
	A key which replaces the rotational / scaling parts of the transformation matrix such that the node is sloped like the provided axis. For two dimensional plots, |sloped like y axis| is effectively the same as |rotate=90|. For a three dimensional axis, this will lead to a larger difference:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		xlabel=Variable 1,
		ylabel=Variable 2,
		zlabel=value,
		xlabel style={sloped like x axis},
		ylabel style={sloped}
	]

	\addplot3[surf] {y*x*(1-x)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	Inside of axis labels, |sloped| is an alias |sloped like |\meta{char}| axis| with the correct \meta{char} chosen automatically.

	Please note that rotated text might not look very good (neither on screen nor printed).
\end{pgfplotsxykeylist}


\subsubsection{Labels}

\begin{pgfplotsxykey}{\x label=\marg{text}}
These options set axis labels to \marg{text} which is any \TeX\ text. Use curly braces to include special characters, for example ``|xlabel={, = characters}|'' if characters like `|=|' or `|,|' need to be included literally.

	Use |xlabel/.add=|\marg{prefix}\marg{suffix} to modify an already assigned label.

Labels are \Tikz-Nodes which are placed with
\begin{codeexample}[code only]
% for x:
\node 
	[style=every axis label,
	style=every axis x label]

% for y:
\node 
	[style=every axis label,
	style=every axis y label] 
\end{codeexample}
so their position and appearance can be customized. 

\paragraph{Upgrade notice:} Since version 1.3, label placement \emph{can} respect the size of adjacent tick labels. Use |\pgfplotsset{compat=newest}| in the preamble to activate this feature. See |xlabel near ticks| for details.

\begin{pgfplotsxykeylist}{\x label shift=\marg{dimension} (initially 0pt),label shift=\marg{dimension}}
	Shifts labels in direction of the outer normal vector of the axis by an amount of \marg{dimension}. The |label shift| sets all three label shifts to the same value.

	\paragraph{Attention:} This does only work if |\pgfplotsset{compat=newest}| has been called (More precisely: if |xlabel near ticks| is active for the respective axis).
\end{pgfplotsxykeylist}

\begin{pgfplotsxykeylist}{\x label near ticks,compat=newest}
	These keys place axis labels (like |xlabel|) near the tick labels. If tick labels are small, labels will move closer to the axis. If tick labels are large, axis labels will move away from the axis. This is the default for every three dimensional plot, but it \emph{won't} be used initially for two--dimensional plots for backwards compatibility. Take a look at the definition of |near ticklabel| on page~\pageref{key:near:ticklabel} for an example.

	The definition of these styles is
\begin{codeexample}[code only]
\pgfplotsset{
	/pgfplots/xlabel near ticks/.style={
		/pgfplots/every axis x label/.style={
			at={(ticklabel cs:0.5)},anchor=near ticklabel
		}
	},
	/pgfplots/ylabel near ticks/.style={
		/pgfplots/every axis y label/.style={
			at={(ticklabel cs:0.5)},rotate=90,anchor=near ticklabel
		}
	}
}
\end{codeexample}
	
	It is encouraged to write
\begin{codeexample}[code only]
\pgfplotsset{compat=newest}
\end{codeexample}
	\noindent in your preamble to install the styles document-wide -- it leads to the best output (it avoids unnecessary space). It is not activated initially for backwards compatibility with older versions which used fixed distances from the tick labels.
\end{pgfplotsxykeylist}

\begin{pgfplotsxykeylist}{\x label absolute,compat=pre 1.3}
	Installs placement styles for axis labels such that |xlabel| yields a description of absolute, fixed distance to the axis. This is the initial configuration (for backwards compatibility with versions before 1.3). Use |compat=newest| to get the most recent, more flexible configuration. Take a look at the definition of |near ticklabel| on page~\pageref{key:near:ticklabel} for an example.

	These styles are defined by
\begin{codeexample}[code only]
\pgfplotsset{
	/pgfplots/xlabel absolute/.style={%
		/pgfplots/every axis x label/.style={at={(0.5,0)},below,yshift=-15pt},%
		/pgfplots/every x tick scale label/.style={
			at={(1,0)},yshift=-2em,left,inner sep=0pt
		},
	},
	/pgfplots/ylabel absolute/.style={%
		/pgfplots/every axis y label/.style={at={(0,0.5)},xshift=-35pt,rotate=90},
		/pgfplots/every y tick scale label/.style={
			at={(0,1)},above right,inner sep=0pt,yshift=0.3em
		},
	}
}
\end{codeexample}

	There is no predefined absolute placement style for three dimensional axes.
\end{pgfplotsxykeylist}

Whenever possible, consider using |/.append style| instead of overwriting the default styles to ensure compatibility with future versions.
\begin{codeexample}[code only]
\pgfplotsset{every axis label/.append style={...}}
\pgfplotsset{every axis x label/.append style={...}}
\pgfplotsset{every axis y label/.append style={...}}
\end{codeexample}
\end{pgfplotsxykey}

\begin{pgfplotskey}{title=\marg{text}}
Adds a caption to the plot. This will place a \Tikz-Node with
\begin{codeexample}[code only]
\node[every axis title] {text};
\end{codeexample}
to the current axis.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}[
	xlabel=Dof,ylabel=Error,
	title={$\mu=0.1$, $\sigma=0.2$}]

	\addplot coordinates {
		(5,    8.312e-02)
		(17,   2.547e-02)
		(49,   7.407e-03)
		(129,  2.102e-03)
		(321,  5.874e-04)
		(769,  1.623e-04)
		(1793, 4.442e-05)
		(4097, 1.207e-05)
		(9217, 3.261e-06)
	};
\end{loglogaxis}
\end{tikzpicture}%
\end{codeexample}
%--------------------------------------------------
% \hfill
% \begin{tikzpicture}
% \begin{loglogaxis}[
% 	width=0.48\linewidth,
% 	xlabel=Dof,ylabel=Error,
% 	title={$\mu=1$, $\sigma=\frac{1}{2}$}]
% 
% 	\addplot[color=red,mark=*] coordinates {
% 		(7,		8.472e-02)
% 		(31,	3.044e-02)
% 		(111,	1.022e-02)
% 		(351,	3.303e-03)
% 		(1023,	1.039e-03)
% 		(2815,	3.196e-04)
% 		(7423,	9.658e-05)
% 		(18943,	2.873e-05)
% 		(47103,	8.437e-06)
% 	};
% \end{loglogaxis}
% \end{tikzpicture}
%-------------------------------------------------- 
The title's appearance and/or placing can be reconfigured with
\begin{codeexample}[code only]
\pgfplotsset{title style={at={(0.75,1)}}}
% or, equivalently,
\pgfplotsset{every axis title/.append style={at={(0.75,1)}}}
\end{codeexample}
This will place the title at~75\% of the $x$-axis. The coordinate~$(0,0)$ is the lower left corner and~$(1,1)$ the upper right one (see |axis description cs| for details).

Use |title/.add=|\marg{prefix}\marg{suffix} to modify an already assigned title.
\end{pgfplotskey}

\begin{pgfplotscodekey}{extra description}
Allows to insert \marg{commands} after axis labels, titles and legends have been typeset.

As all other axis descriptions, the code can use $(0,0)$ to access the lower left corner and $(1,1)$ to access the upper right one. It won't be clipped.
\begin{codeexample}[]
\pgfplotsset{every axis/.append style={
	extra description/.code={
		\node at (0.5,0.5) {Center!};
	}}}
\begin{tikzpicture}
	\begin{axis}
	\addplot {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotscodekey}


\subsubsection{Legends}
\label{pgfplots:sec:legendopts}
\label{pgfplots:sec:legendcmds}
Legends can be generated in two ways: the first is to use |\addlegendentry| or |\legend| inside of an axis. The other method is to use the key |legend entries|.


\begin{command}{\addlegendentry\marg{name}}
Adds a single legend entry to the legend list. This will also enable legend drawing.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
\addplot[smooth,mark=*,blue] coordinates {
	(0,2)
	(2,3)
	(3,1)
};
\addlegendentry{Case 1}

\addplot[smooth,color=red,mark=x]
	coordinates {
		(0,0)
		(1,1)
		(2,1)
		(3,2)
	};
\addlegendentry{Case 2}
\end{axis}
\end{tikzpicture}
\end{codeexample}
It does not matter where |\addlegendentry| commands are placed, only the sequence matters. You will need one |\addlegendentry| for every |\addplot| command (unless you prefer an empty legend).


Using |\addlegendentry| disables the key |legend entries|.
\end{command}

\begin{command}{\addlegendentryexpanded\marg{\TeX\ text}}
	A variant of |\addlegendentry| which provides a method to deal with macros inside of \meta{\TeX\ text}.

	Suppose \meta{\TeX\ text} contains some sort of parameter which varies \emph{for every plot}. Moreover, you like to use a loop to generate the plots. Then, it is simpler to use |\addlegendentryexpanded|:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
	\foreach \p in {1,2,3} {
	  \addplot {x^\p};
	  \addlegendentryexpanded{$x^\p$}
	}
\end{axis}
\end{tikzpicture}
\end{codeexample}
	Note that this example wouldn't have worked with |\addlegendentry{$x^\p$}| because the macro |\p| is no longer defined when \PGFPlots\ attempts to draw the legend.

	The invocation |\addlegendentryexpanded{$x^\p$}| is equivalent to calling |\addlegendentry{$x^2$}| if |\p| expands to |2|.

	The argument \meta{\TeX\ text} is expanded until nothing but un-expandable material remains (i.e.\ it uses the \TeX\ primitive |\edef|). Occasionally, \marg{\TeX\ text} contains parts which should be expanded (like |\p|) and other parts which should be left unexpanded (for example |\pgfmathprintnumber{\p}|). Then, use
	
		|\noexpand\pgfmathprintnumber{\p}|
	
	or, equivalently

		|\protect\pgfmathprintnumber{\p}|

	to avoid expansion of the macro which follows the |\protect| immediately.
\end{command}



\begin{command}{\legend\marg{list}}
\label{sec:legenddef}%
You can use |\legend|\marg{list} to assign a complete legend.
\begin{codeexample}[code only]
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{codeexample}
The argument of |\legend| is list of entries, one for each plot. 

Two different delimiters are supported:
\begin{enumerate}
	\item There are comma--separated lists like 
\begin{codeexample}[code only]
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{codeexample}
	These lists are processed using the \PGF\ |\foreach| command.
	\item It is also possible to delimit the list by `|\\|'. In this case, the \emph{last element must be terminated} by |\\| as well:
\begin{codeexample}[code only]
\legend{$a=1, b=2$\\,$a=2, b=3$\\$a=3, b=5$\\}
\end{codeexample}
	This syntax simplifies the use of `|,|' inside of legend entries.
\end{enumerate}
The short marker/line combination shown in legends is acquired from the \marg{style options} argument of |\addplot|.

Using |\legend| overwrites any other existing legend entries.
\end{command}


\begin{pgfplotskey}{legend entries=\marg{comma separated list}}
	This key can be used to assign legend entries just like the commands |\addlegendentry| and |\legend|. Again, the positioning is relative to the axis rectangle (unless units like |cm| or |pt| are specified explicitly).
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend entries={$x$,$x^2$}]
	\addplot {x};
	\addplot {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The commands for legend creation take precedence: the key |legend entries| is only considered if there is no legend command in the current axis. 
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend entries={$x$,$x^2$}]
	\addplot {x};
	\addplot {x^2};
	\legend{$a$,$b$}% overrides the option
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	Please be careful with whitespaces in \marg{comma separated list}: they will contribute to legend entries. Consider using `|%|' at the end of each line in multiline arguments (the end of line character is also a whitespace in \TeX).
\end{pgfplotskey}


\begin{command}{\legendimage\marg{options}}
	Adds a further ``plot style'' for legend creation.

	Each |\addplot| command appends its plot style options to a list, and |\legendimage| adds \meta{options} to the very same list.

	Thus, the effect is as if you had provided |\addplot|\oarg{options}, but |\legendimage| bypasses all the logic usually associated with a plot. In other words: except for the legend, the state of the axis remains as if the command would not have been drawn.

	Use |\legendimage| to provide custom styles into legends, for example to document custom |\draw| commands inside of an axis.

	You can call |\label| after |\legendimage| just as for a normal style.
\end{command}

\subsubsection{Legend Appearance}

{%
\pgfplotsset{every axis/.append style={width=3cm,scale only axis,legend style={font=\footnotesize}}}%


\begin{stylekey}{/pgfplots/every axis legend}
The style ``|every axis legend|'' determines the legend's position and outer appearance:
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={
		at={(0,0)},
		anchor=south west}}
\end{codeexample}
will draw it at the lower left corner of the axis while
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={
		at={(1,1)},
		anchor=north east}}
\end{codeexample}
means the upper right corner. The `|anchor|' option determines which point \emph{of the legend} will be placed at $(0,0)$ or $(1,1)$.

The legend is a \Tikz-matrix, so one can use any \Tikz\ option which affects
nodes and matrizes (see~\cite[section 13~and~14]{tikz}). The matrix is created by something like
\begin{codeexample}[code only]
\matrix[style=every axis legend] {
	draw plot specification 1 & \node{legend 1}\\
	draw plot specification 2 & \node{legend 2}\\
	...
};
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	% this modifies 'every axis legend':
	legend style={font=\large}
]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	% align right:
	legend style={
		cells={anchor=east},
		legend pos=outer north east,
	}
]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$, legend $2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
% similar placement as previous example:
\pgfplotsset{every axis legend/.append style={
		at={(1.02,1)},
		anchor=north west}}
\begin{tikzpicture}
\begin{axis}
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

Use |legend columns=|\marg{number} to configure the number of horizontal legend entries.
\begin{codeexample}[]
\begin{tikzpicture}
\pgfplotsset{every axis legend/.append style={
		at={(0.5,1.03)},
		anchor=south}}
\begin{axis}[legend columns=4]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent
Instead of the |/.append style|, it is possible to use |legend style| as in the following example. It has the same effect.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	legend style={
		at={(1,0.5)},
		anchor=east}]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\noindent
The default |every axis legend| style is
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.style={
	cells={anchor=center},% Centered entries
	inner xsep=3pt,inner ysep=2pt,nodes={inner sep=2pt,text depth=0.15em},
	anchor=north east,
	shape=rectangle,
	fill=white,
	draw=black,
	at={(0.98,0.98)}
	}
}
\end{codeexample}
Whenever possible, consider using |/.append style| to keep the default styles active. This ensures compatibility with future versions.
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={...}}
\end{codeexample}
\end{stylekey}

\pgfplotsshortstylekey legend style=every axis legend\pgfeov


\begin{pgfplotskey}{legend pos=\mchoice{south west,south east,north west,north east,outer north east}}
	A style which provides shorthand access to some commonly used legend positions.

	Each of these styles appends |at={(|\meta{x}|,|\meta{y}|)},anchor=|\meta{name} values to |every axis legend|.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=south west]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=south east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=north east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=north west]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend pos=outer north east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{$l_1$,$l_2$,$l_3$}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}

}

\begin{pgfplotskey}{legend columns=\marg{number} (default 1)}
Allows to configure the maximum number of adjacent legend entries. The default value~|1| places legend entries vertically below each other. 

Use |legend columns=-1| to draw all entries horizontally.
\end{pgfplotskey}

\begin{pgfplotskey}{legend plot pos=\mchoice{left,right,none} (initially left)}
Configures where the small line specifications will be drawn: left of the description, right of the description or not at all.
\end{pgfplotskey}

\begin{pgfplotscodekey}{legend image code}
\label{opt:legend:image:code}
Allows to replace the default images which are drawn inside of legends. When this key is evaluated, the current plot specification has already been activated (using |\begin{scope}[current plot style]|)%
\footnote{This was different in versions before 1.3. The new scope features allows plot styles to change |legend image code|.}, so any drawing operations use the same styles as the |\addplot| command.


The default is the style |line legend|.
\end{pgfplotscodekey}

\begin{stylekey}{/pgfplots/line legend}
	A style which sets |legend image code| (back) to its initial value. 

	Its initial value is
\begin{codeexample}[code only]
\pgfplotsset{
	/pgfplots/line legend/.style={
		legend image code/.code={
			\draw[mark repeat=2,mark phase=2,##1] 
				plot coordinates {
					(0cm,0cm) 
					(0.3cm,0cm)
					(0.6cm,0cm)
				};%
		}
	}
}
\end{codeexample}

	The style |line legend| can also be used to use a different legend style for one particular plot (see the docs for |area legend| for an example).
\end{stylekey}


\begin{stylekey}{/pgfplots/area legend}
	A style which sets |legend image code| to
\begin{codeexample}[code only]
\pgfplotsset{
	legend image code/.code={%
		\draw[#1] (0cm,-0.1cm) rectangle (0.6cm,0.1cm);
	}
}	
\end{codeexample}
	
% \usetikzlibrary{patterns}
\begin{codeexample}[]
% \usetikzlibrary{patterns}
\begin{tikzpicture}
\begin{axis}[area legend,
	axis x line=bottom,
	axis y line=left,
	domain=0:1,
	legend style={at={(0.03,0.97)},
		anchor=north west},
	axis on top,xmin=0]
\addplot[pattern=crosshatch dots,
	pattern color=blue,draw=blue,
	samples=500] 
	{sqrt(x)}	\closedcycle;

\addplot[pattern=crosshatch,
	pattern color=blue!30!white,
	draw=blue!30!white]
	{x^2} \closedcycle;

\addplot[red,line legend] coordinates {(0,0) (1,1)};
\legend{$\sqrt x$,$x^2$,$x$}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{stylekey}

\begin{pgfplotsxykeylist}{\x bar legend,\x bar interval legend}
	These style keys redefine |legend image code| such that legends use |xbar|, |ybar| or the |xbar interval| and |ybar interval| handlers.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend pos=north west]
	\addplot {x^3};
	\addplot[ybar,fill=red,draw=red!60,
		ybar legend,mark=none,samples=5] 
		{-30*(x +4)};
	\legend{first,second}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
The initial values for these styles might be interesting if someone wants to modify them. Here are they:
\begin{codeexample}[code only]
\pgfplotsset{
	/pgfplots/xbar legend/.style={
		/pgfplots/legend image code/.code={%
			\draw[##1,/tikz/.cd,bar width=3pt,yshift=-0.2em,bar shift=0pt] 
			plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};},
	},
	/pgfplots/ybar legend/.style={
		/pgfplots/legend image code/.code={%
			\draw[##1,/tikz/.cd,bar width=3pt,yshift=-0.2em,bar shift=0pt] 
			plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};},
	},
	/pgfplots/xbar interval legend/.style={%
		/pgfplots/legend image code/.code={%
			\draw[##1,/tikz/.cd,yshift=-0.2em,bar interval width=0.7,bar interval shift=0.5]
			plot coordinates {(0cm,0.8em) (5pt,0.6em) (10pt,0.6em)};},
	},
	/pgfplots/ybar interval legend/.style={
		/pgfplots/legend image code/.code={%
			\draw[##1,/tikz/.cd,yshift=-0.2em,bar interval width=0.7,bar interval shift=0.5] 
			plot coordinates {(0cm,0.8em) (5pt,0.6em) (10pt,0.6em)};},
	},
}
\end{codeexample}
\end{pgfplotsxykeylist}

\begin{pgfplotskey}{mesh legend}
	Redefines |legend image code| such that it is compatible with |mesh| and |surf| plot handlers (for three dimensional visualization mainly).
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend pos=outer north east]
	\addplot3[surf,samples=9,domain=0:1] 
		{(1-abs(2*(x-0.5))) * (1-abs(2*(y-0.5)))};
	\addlegendentry{$\phi_x \phi_y$}

	\addplot3+[ultra thick] coordinates {(0,0,0) (0.5,0,1) (1,0,0)};
	\addlegendentry{$\phi_x $}

	\addplot3+[ultra thick] coordinates {(1,0,0) (1,0.5,1) (1,1,0)};
	\addlegendentry{$\phi_y $}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}

\begin{pgfplotskey}{reverse legend=\mchoice{true,false} (initially false)}
	Allows to reverse the order in which the pairs (legend entry, plot style) are drawn.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[reverse legend]
	\addplot {x};
	\addlegendentry{$x$}
	\addplot {x^2};
	\addlegendentry{$x^2$}
	\addplot {x^3};
	\addlegendentry{$x^3$}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}


\subsubsection{Legends with \texttt{\textbackslash label} and \texttt{\textbackslash ref}}
\label{pgfplots:legend:labelref}
\PGFPlots\ offers a |\label| and |\ref| feature for \LaTeX\ to assemble a legend manually, for example as part of the figure caption. These references work as usual \LaTeX\ references: a |\label| remembers where and what needs to be referenced and a |\ref| expands to proper text. In context of plots, a |\label| remembers the plot specification of one plot and a |\ref| expands to the small image which would also be used inside of legends.
\begin{codeexample}[]
\begin{tikzpicture}[baseline]
\begin{axis}
	\addplot+[only marks,
			samples=15,
			error bars/y dir=both,
			error bars/y fixed=2.5]
		{3*x+2.5*rand};
	\label{pgfplots:label1}

	\addplot+[mark=none] {3*x};
	\label{pgfplots:label2}

	\addplot {4*cos(deg(x))};
	\label{pgfplots:label3}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\begin{codeexample}[code only]
The picture shows the estimations \ref{pgfplots:label1} which are subjected to noise.
It appears the model \ref{pgfplots:label2} fits the data appropriately. 
Finally, \ref{pgfplots:label3} is only here to get three examples.
\end{codeexample}
\noindent The picture shows the estimations \ref{pgfplots:label1} which are subjected to noise.
It appears the model \ref{pgfplots:label2} fits the data appropriately. 
Finally, \ref{pgfplots:label3} is only here to get three examples.

\begin{commandlist}{\label\marg{label name},\label\oarg{reference}\marg{label name}}
	When used after |\addplot|, this command creates a \LaTeX\ label named \marg{label name}\footnote{This feature is \emph{only} available in \LaTeX, sorry.}. If this label is cross-referenced with |\ref|\marg{label name} somewhere, the associated plot specification will be inserted.
\begin{codeexample}[]
Label3 = \ref{pgfplots:label3}; 
Label2 = \ref{pgfplots:label2}
\end{codeexample}
	The label is assembled using |legend image code| and the plot style of the last plot. Any \PGFPlots\ option is expanded until only \Tikz\ (or \pgfname) options remain; these options are used to get an independant label\footnote{Please note that you can't use the label/ref mechanism in conjunction with image externalization as this will (naturally) lead to undefined references.}.

	More precisely, the small image generated by |\ref|\marg{label name} is 
\begin{codeexample}[code only]
\tikz[/pgfplots/every crossref picture] {...}
\end{codeexample}
	\noindent where the contents is determined by |legend image code| and the plot style.

	The second syntax, |\label|\oarg{reference}\marg{label name} allows to label particular pieces of an |\addplot| command. It is (currently) only interesting for |scatter/classes|: there,  it allows to reference particular classes of the scatter plot. See page~\pageref{pgfplots:scatterclasses} for more details.
\end{commandlist}

\begin{command}{\ref\marg{label name}}
	Can be used to reference a labeled, single plot. See the example above.

	This will also work together with |hyperref| links and |\pageref|\footnote{Older versions of \PGFPlots\ required the use of \texttt{\textbackslash protect\textbackslash ref} when used inside of captions or section headings. This is no longer necessary.}.
\end{command}

\begin{key}{/pgfplots/refstyle=\marg{label name}}
	Can be used to set the \emph{styles} of a labeled, single plot. This allows to write
\begin{codeexample}[code only]
\addplot[/pgfplots/refstyle={pgfplots:label2}]
\end{codeexample}
	\noindent somewhere. Please note that it may be easier to define a style with |.style|.
\end{key}

\begin{stylekey}{/pgfplots/every crossref picture}
	A style which will be used by the cross-referencing feature for plots. The default is
\begin{codeexample}[code only]
\pgfplotsset{every crossref picture/.style={baseline,yshift=0.3em}}
\end{codeexample}
\end{stylekey}

\subsubsection{Axis Lines}

{\small \emph{An extension by Pascal Wolkotte}}
\vspace{0.4cm}%

\label{sec:pgfplots:axislines}
\noindent By default the axis lines are drawn as a |box|, but it is possible to change the appearance of the $x$~and~$y$ axis lines.

\begin{pgfplotskeylist}{
	axis x line=\mchoice{box,top,middle,center,bottom,none} (initially box),
	axis x line*=\mchoice{box,top,middle,center,bottom,none} (initially box),
	axis y line=\mchoice{box,left,middle,center,right,none} (initially box),
	axis y line*=\mchoice{box,left,middle,center,right,none} (initially box),
	axis lines=\mchoice{box,left,middle,center,right,none},
	axis lines*=\mchoice{box,left,middle,center,right,none}}
	These keys allow to choose the locations of the axis lines. The last one, |axis lines| sets the same value for every axis.

Ticks and tick labels are placed according to the chosen value as well.
The choice |bottom| will draw the $x$ line at $y=y_\text{min}$, |middle| will draw the $x$~line at $y=0$, and |top| will draw it at $y=y_\text{max}$. Finally, |box| is a combination of options |top| and |bottom|. The $y$~variant works similarly.

The case |center| is a synonym for |middle|, both draw the line through the respective coordinate~$0$. If this coordinate is not part of the axis limit, the lower axis limit is chosen instead.


The starred versions $\dotsc$|line*| \emph{only} affect the axis lines, without correcting the positions of axis labels, tick lines or other keys which are (possibly) affected by a changed axis line. The non-starred versions are actually styles which set the starred key \emph{and} some other keys which also affect the figure layout:
\begin{itemize}
	\item In case |axis x line=box|, the style |every boxed x axis| will be installed immediately.
	\item In case |axis x line|$\neq$|box|, the style |every non boxed x axis| will be installed immediately. Furthermore, axis labels positions will be adjusted to fit the choosen value.
\end{itemize}
The same holds true for the |y|-variants. The default styles are defined as
\begin{codeexample}[code only]
\pgfplotsset{
	every non boxed x axis/.style={
		xtick align=center,
		enlarge x limits=false,
		x axis line style={-stealth}
	},
	every boxed x axis/.style={}
}
\end{codeexample}
Feel free to overwrite these styles if the default doesn't fit your needs or taste. Again, these styles will \emph{not} be used for |axis line*|. 

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	xlabel=$x$,ylabel=$\sin x$]

	\addplot[blue,mark=none,
		 domain=-10:0,samples=40]
		{sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=middle,
	axis y line=right,
	ymax=1.1, ymin=-1.1,
	xlabel=$x$,ylabel=$\sin x$
]
	\addplot[blue,mark=none,
		 domain=-10:0,samples=40]
		{sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}


\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=bottom,
	axis y line=left,
	xlabel=$x$,ylabel=$\sqrt{|x|}$
]
\addplot[blue,mark=none,
	 domain=-4:4,samples=501]
	{sqrt(abs(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	minor tick num=3,
	axis y line=center,
	axis x line=middle,
	xlabel=$x$,ylabel=$\sin x$
	]
	\addplot[smooth,blue,mark=none,
		 domain=-5:5,samples=40] 
		{sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	minor tick num=3,
	axis y line=left,
	axis x line=middle,
	xlabel=$x$,ylabel=$\sin x$
	]
	\addplot[smooth,blue,mark=none,
		 domain=-5:5,samples=40] 
		{sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

In case |middle|, the style |every inner axis x line| allows to adjust the appearenace.

Note that three dimensional axes only support to use the same value for every axis, i.e.\ three dimensional axes support only the |axis lines| key (or, preferrably for 3D axes, the |axis lines*| key -- check what looks best). See section~\ref{sec:pgfplots:axislines:3d} for examples of three dimensional axis line variations.
\end{pgfplotskeylist}

\begin{pgfplotsxykey}{every inner \x\ axis line}
	A style key which can be redefined to customize the appearance of \emph{inner} axis lines. Inner axis lines are those drawn by the |middle| (or |center|) choice of |axis x line|, see above.

	This style affects \emph{only} the line as such.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	minor tick num=1,
	axis x line=middle,
	axis y line=middle,
	every inner x axis line/.append style=
		{|->>},
	every inner y axis line/.append style=
		{|->>},
	xlabel=$x$,ylabel=$y^3$
]
\addplot[blue,domain=-3:5] {x^3};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{every outer \x\ axis line}
	Similar to |every inner x axis line|, this style configures the appearance of all axis lines which are part of the outer box.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	separate axis lines, % important !
	every outer x axis line/.append style=
		{-stealth},
	every outer y axis line/.append style=
		{-stealth},
]
\addplot[blue,id=DoG,
		samples=100,
		domain=-15:15] 
  gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykey}

\begin{pgfplotskey}{separate axis lines=\marg{true,false} (default true)}
	Enables or disables separate path commands for every axis line. This option affects \emph{only} the case if axis lines are drawn as a \emph{box}.

	Both cases have their advantages and disadvantages, I fear there is no reasonable default (suggestions are welcome).

	The case |separate axis lines=true| allows to draw arrow heads on each single axis line, but it can't close edges very well -- in case of thick lines, unsatisfactory edges occur.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	separate axis lines,
	every outer x axis line/.append style=
		{-stealth,red},
	every outer y axis line/.append style=
		{-stealth,green!30!black},
]
\addplot[blue,
		samples=100,
		domain=-15:15] 
	{1.3*exp(0-x^2/10) - exp(0-x^2/20)};
  % Unfortunately, there is a bug in PGF 2.00
  % something like exp(-10^2)
  % must be written as exp(0-10^2) :-(
\end{axis}
\end{tikzpicture}
\end{codeexample}

	The case |separate axis lines=false| issues just \emph{one} path for all axis lines. It draws a kind of rectangle, where some parts of the rectangle may be skipped over if they are not wanted. The advantage is that edges are closed properly. The disadvantage is that at most one arrow head is added to the path (and yes, only one drawing color is possible).
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	separate axis lines=false,
	every outer x axis line/.append style=
		{-stealth,red},
	every outer y axis line/.append style=
		{-stealth,green!30!black},
]
\addplot[blue,id=DoG,
		samples=100,
		domain=-15:15] 
  gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}


\label{pgfplots:page:axislines}
\begin{pgfplotskey}{axis line style=\marg{key-value-list}}
	A command which appends \marg{key-value-list} to \emph{all} axis line appearance styles.
\end{pgfplotskey}

\begin{pgfplotskey}{inner axis line style=\marg{key-value-list}}
	A command which appends \marg{key-value-list} to both, |every inner x axis line| and the $y$ variant.
\end{pgfplotskey}
\begin{pgfplotskey}{outer axis line style=\marg{key-value-list}}
	A command which appends \marg{key-value-list} to both, |every outer x axis line| and the $y$ variant.
\end{pgfplotskey}
\begin{pgfplotsxykey}{\x\ axis line style=\marg{key-value-list}}
	A command which appends \marg{key-value-list} to all axis lines styles for either $x$ or $y$ axis.
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{every boxed \x\ axis}
	A style which will be installed as soon as |axis x line=box| (|y|) is set.

	The default is simply empty.
\end{pgfplotsxykey}
\begin{pgfplotsxykey}{every non boxed \x\ axis}
	A style which will be installed as soon as |axis x line| (|y|) will be set to something different than |box|. 
	
	The default is 
\begin{codeexample}[code only]
\pgfplotsset{
	every non boxed x axis/.style={
		xtick align=center,
		enlarge x limits=false,
		x axis line style={-stealth}}}
\end{codeexample}
	\noindent with similar values for the |y|-variant. Feel free to redefine this style to your needs / taste.
\end{pgfplotsxykey}

\subsubsection[Two Ordinates]{Two Ordinates ($y$ axis)}
{%
\pgfplotsset{every axis/.append style={width=4.5cm}}%
In some applications, more than one $y$ axis is used if the $x$ range is the same. This section demonstrates how to create them.

\begin{codeexample}[]
\begin{tikzpicture}
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    axis y line=left,
    xlabel=$x$,
    ylabel=First ordinate]
  \addplot {x^2};
  \end{axis}
  
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    axis y line=right,
    axis x line=none,
    ylabel=Second ordinate]
  \addplot[red] {3*x};
  \end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent The basic idea is to draw two axis ``on top'' of each other -- one, which contains the $x$ axis and the left $y$ axis, and one which has \emph{only} the right $y$ axis. Since \PGFPlots\ does not really know what it's doing here, user attention in the following possibly non-obvious aspects is required:
\begin{enumerate}
	\item Scaling. You should set |scale only axis| because this forces equal dimensions for both axis, without respecting any labels.
	\item Same $x$ limits. You should set those limits explicitly.
\end{enumerate}
You may want to consider different legend styles.
It is also possible to use only the axis, without any plots:
% \usepackage{textcomp}
\begin{codeexample}[]
% \usepackage{textcomp}
\begin{tikzpicture}
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    axis y line=left,
    xlabel=$x$,
    ylabel=Absolute]
  \addplot {x^2};
  \end{axis}
  
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    ymin=0,ymax=1000,
    yticklabel=
{$\pgfmathprintnumber{\tick}$\textperthousand},
    axis y line=right,
    axis x line=none,
    y label style={yshift=-10pt},
    ylabel=per thousand]
  \end{axis}
\end{tikzpicture}
\end{codeexample}
}

\subsubsection{Axis Discontinuities}

{\small \emph{An extension by Pascal Wolkotte}}
\vspace{0.4cm}%

\noindent In case the range of either of the axis do not include the zero value, it is possible to visualize this with a discontinuity decoration on the corresponding axis line.

\begin{pgfplotsxykey}{axis \x\ discontinuity=\mchoice{crunch,parallel,none} (initially none)}
Insert a discontinuity decoration on the $x$ (or $y$, respectively) axis. 
This is to visualize that the $y$ axis does cross the $x$ axis at its $0$ value, because the minimum $x$ axis value is positive or the maximum value is negative.

The description applies |axis y discontinuity| as well, with interchanged meanings of $x$~and~$y$.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=bottom,
	axis x discontinuity=parallel,
	axis y line=left,
	xmin=360, xmax=600,
	ymin=0, ymax=7,
 	enlargelimits=false
]
	\addplot coordinates {
		(420,2)
		(500,6)
		(590,4)
	};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=bottom,
	axis y line=center,
	tick align=outside,
	axis y discontinuity=crunch,
	ymin=95, enlargelimits=false
]
	\addplot[blue,mark=none,
		 domain=-4:4,samples=20] 
		{x*x+x+104};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykey}

A problem might occur with the placement of the ticks on the axis.
This can be solved by specifying the minimum or maximum axis value for which a tick will be placed.

\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord} (default axis limits), \x tickmax=\marg{coord} (default axis limits)}
\label{key:xytickminmax}
The options |xtickmin|, |xtickmax| and |ytickmin|, |ytickmax| allow to define the axis tick limits, i.e.\ the axis values before respectively after no ticks will be placed.
Everything outside of the axis tick limits will be not drawn.
Their default values are equal to the axis limits.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	axis x line=bottom,
	axis y line=center,
	tick align=outside,
	axis y discontinuity=crunch,
	xtickmax=3,
	ytickmin=110,
	ymin=95, enlargelimits=false
]
	\addplot[blue,mark=none,
		 domain=-4:4,samples=20] 
		{x*x+x+104};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykeylist}

\begin{pgfplotsxykeylist}{%
	hide \x\ axis=\mchoice{true,false} (initially false),
	hide axis=\mchoice{true,false} (initially false)}
Allows to hide either a selected axis or all of them. No outer rectangle, no tick marks and no labels will be drawn. Only titles and legends will be processed as usual.

Axis scaling and clipping will be done as if you did not use |hide axis|.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		hide x axis,
		hide y axis,
		title={$x^2\cos(x)$}]
	\addplot {cos(x)*x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		hide x axis,
		axis y line=left,
		title={$x^2\cos(x)$}]
	\addplot {cos(x)*x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykeylist}

\subsubsection{Color Bars}
\label{pgfplots:colorbar}
\PGFPlots\ supports mesh, surface and scatter plots which can use color maps. While color maps can be chosen as described in section~\ref{pgfplots:colormap}, they can be visualized using color bars.

\begin{pgfplotskey}{colorbar=\mchoice{true,false} (initially false)}
	Activates or deactivates color bars.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar]
		\addplot[mesh,ultra thick] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar,colormap/greenyellow]
		\addplot[mesh,ultra thick] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar horizontal]
		\addplot[mesh,ultra thick] {x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	A color bar is only useful for plots which actually use color data -- that is, the special data which is called ``point meta'' in \PGFPlots\ (see section~\ref{pgfplots:point:meta}). Activating color bars for a plot without color map results in an empty color bar.

	Color bars are just normal axes which are placed right besides their parent axes. The only difference is that they inherit several styles such as line width and fonts and they contain a bar shaded with the color map of the current axis.
	
	Color bars are drawn internally with
\begin{codeexample}[code only]
\axis[every colorbar,colorbar shift,colorbar=false]
	\addplot graphics {};
\endaxis
\end{codeexample}
	\noindent where the placement, alignment, appearance and other options are done by the two styles |every colorbar| and |colorbar shift|. These styles and the possible placement and alignment options are described below.

	\paragraph{Remarks for special cases:}
	\begin{itemize}
		\item Since there is always only one color bar per plot, this color bar uses the axis wide configurations of color map and color data.
		\item If someone needs more than one color bar, the draw command above needs to be updated. See the key 
		|colorbar/draw/.code| for this special case.
	\end{itemize}
\end{pgfplotskey}

\begin{stylekey}{/pgfplots/colorbar right}
	A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed right of their parent axis.

	This is the initial configuration.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar right]
	\addplot[mesh,thick,samples=150,domain=0.1:3] 
		{1/x};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	The style |colorbar right| is defined to be
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar right/.style={
		/pgfplots/colorbar=true,
		/pgfplots/colorbar shift/.style={xshift=0.3cm},
		/pgfplots/every colorbar/.style={
			title=,
			xlabel=,
			ylabel=,
			zlabel=,
			legend entries=,
			axis on top,
			at={(parent axis.right of north east)},
			anchor=north west,
			xmin=0,
			xmax=1,
			ymin=\pgfkeysvalueof{/pgfplots/point meta min},
			ymax=\pgfkeysvalueof{/pgfplots/point meta max},
			plot graphics/xmin=0,
			plot graphics/xmax=1,
			plot graphics/ymin=\pgfkeysvalueof{/pgfplots/point meta min},
			plot graphics/ymax=\pgfkeysvalueof{/pgfplots/point meta max},
			enlargelimits=false,
			scale only axis,
			height=\pgfkeysvalueof{/pgfplots/parent axis height},
			x=\pgfkeysvalueof{/pgfplots/colorbar/width},
			yticklabel pos=right,
			xtick=\empty,
			colorbar vertical/lowlevel,
		}
	},
	/pgfplots/colorbar vertical/lowlevel/.style={
		plot graphics/lowlevel draw/.code 2 args={%
			\pgfuseshading{...} % some advanced basic level shading operations
		}
	},
}
\end{codeexample}
	\paragraph{Attention:} |colorbar right| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar right|:
\begin{codeexample}[code only]
% correct:
\begin{axis}[colorbar right, colorbar style={<some customization>}]
% wrong, colorbar right resets the customization:
\begin{axis}[colorbar style={<some customization>}, colorbar right]
\end{codeexample}
\end{stylekey}

\begin{stylekey}{/pgfplots/colorbar left}
	A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed left of their parent axis.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar left]
	\addplot[mesh,thick,samples=150] 
		{x*sin(deg(4*x))};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	The style |colorbar left| is defined to be
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar left/.style={
		/pgfplots/colorbar right,
		/pgfplots/colorbar shift/.style={xshift=-0.3cm},
		/pgfplots/every colorbar/.append style={
			at={(parent axis.left of north west)},
			anchor=north east,
			yticklabel pos=left,
		}
	}
}
\end{codeexample}
	\paragraph{Attention:} |colorbar left| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar left| (see also the documentation for |colorbar right|).
\end{stylekey}

\begin{stylekey}{/pgfplots/colorbar horizontal}
	A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed below their parent axis, with a horizontal bar.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar horizontal]
	\addplot[only marks,scatter,
		scatter src={mod(\coordindex,15)},samples=150] 
		{rand};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	This style is defined to be
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar horizontal/.style={
		/pgfplots/colorbar=true,
		/pgfplots/colorbar shift/.style={yshift=-0.3cm},
		/pgfplots/every colorbar/.style={
			title=,
			xlabel=,
			ylabel=,
			zlabel=,
			legend entries=,
			axis on top,
			at={(parent axis.below south west)},
			anchor=north west,
			ymin=0,
			ymax=1,
			xmin=\pgfkeysvalueof{/pgfplots/point meta min},
			xmax=\pgfkeysvalueof{/pgfplots/point meta max},
			plot graphics/ymin=0,
			plot graphics/ymax=1,
			plot graphics/xmin=\pgfkeysvalueof{/pgfplots/point meta min},
			plot graphics/xmax=\pgfkeysvalueof{/pgfplots/point meta max},
			enlargelimits=false,
			scale only axis,
			width=\pgfkeysvalueof{/pgfplots/parent axis width},
			y=\pgfkeysvalueof{/pgfplots/colorbar/width},
			xticklabel pos=left,
			ytick=\empty,
			colorbar horizontal/lowlevel,
		}%
	},%
	/pgfplots/colorbar horizontal/lowlevel/.style={%
		plot graphics/lowlevel draw/.code 2 args={%
			\pgfuseshading{...} % some advanced basic level shading operations
		},%
	},%
}
\end{codeexample}
	\paragraph{Attention:} |colorbar horizontal| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar horizontal|:
\begin{codeexample}[code only]
% correct:
\begin{axis}[colorbar horizontal, colorbar style={<some customization>}]
% wrong, colorbar horizontal resets the customization:
\begin{axis}[colorbar style={<some customization>}, colorbar horizontal]
\end{codeexample}
\end{stylekey}

\begin{stylekey}{/pgfplots/every colorbar}
	This style governs the placement, alignment and appearance of color bars. Any desired detail changes for color bars can be put into this style. Additionally, there is a style |colorbar shift| which is set after |every colorbar|. The latter style is intented to contain only shift transformations like |xshift| or |yshift| (making it easier to overwrite or deactivate them).

	While a color bar is drawn, the predefined node |parent axis| can be used to align at the parent axis.
\begin{predefinednode}{parent axis}
	A node for the parent axis of a color bar. It is only valid for color bars.
\end{predefinednode}

	Thus, 
\begin{codeexample}[code only]
\pgfplotsset{
	colorbar style={
		at={(parent axis.right of north east)},
		anchor=north west,
	},
	colorbar shift/.style={xshift=0.3cm}
}
\end{codeexample}
	\noindent places the colorbar in a way that its top-left (north west) corner is aligned right of the top right corner (|right of north east|) of its parent axis. Combining this with the |colorbar shift| is actually the same as the initial setting.

	Since color bars depend on some of its parent's properties, these properties are available as values of the following keys:
\begin{pgfplotskeylist}{point meta min,point meta max}
	The values of these keys contain the lower and upper bound of the color map, i.e.\ the lower and upper limit for the color bar. 
	
	The value is |\pgfkeysvalueof{/pgfplots/point meta min}| inside of |every colorbar|.
\end{pgfplotskeylist}
\begin{pgfplotskeylist}{parent axis width,parent axis height}
	The values of these keys contain the size of the parent axis. They can be used as |width| and/or |height| arguments for |every colorbar| with |\pgfkeysvalueof{/pgfplots/parent axis width}|.

	These values are only valid inside of color bars.
\end{pgfplotskeylist}

	Besides these values, each color bar inherits a list of styles of its parent axis, namely

	\begin{itemize}
		\item |every tick|,
		\item |every minor tick|,
		\item |every major tick|,
		\item |every axis grid|,
		\item |every minor grid|,
		\item |every major grid|,
		\item |every tick label|.
	\end{itemize}
	This can be used to inherit line width and/or fonts.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	colorbar horizontal, 
	colorbar style={
	  at={(0.5,1.03)},anchor=south,
	  xticklabel pos=upper
	},
	title style={yshift=1cm},
	title=Customization: ``colorbar top'']

	\addplot[mesh,thick,samples=150,domain=0.1:3] 
		{x};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	colorbar horizontal, 
	colorbar style={
	  at={(1,1.03)},anchor=south east,
	  width=0.5*
	    \pgfkeysvalueof{/pgfplots/parent axis width},
	  xticklabel pos=upper,
	},
	title style={yshift=1cm},
	title=More Customization: ``colorbar top'']

	\addplot[mesh,thick,samples=150,domain=0.1:3] 
		{x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	Please take a look at the predefined styles |colorbar right|, |colorbar left| and |colorbar horizontal| for more details about configuration possibilities for |every colorbar|.

	\paragraph{Remark:} A color bar is just a normal axis. That means |every colorbar| can contain specifications where to place tick labels, extra ticks, scalings and most other features of a normal axis as well (except nested color bars).
\end{stylekey}

\begin{pgfplotskey}{colorbar style=\marg{key-value list}}
	A shortcut for |every colorbar/.append style=|\marg{key-value list}. It appends options to the colorbar style.
\end{pgfplotskey}

\begin{pgfplotskey}{colorbar/width=\marg{dimension} (initially 0.5cm)}
	Sets the width of a color bar.
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		view/az=45,
		colorbar,
		colorbar/width=2cm,
		colormap/blackwhite]

	\addplot3[surf,domain=0:1,y domain=-3:3] {x*(1-x)*tanh(y)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	For vertical color bars, this sets the height.
\end{pgfplotskey}


\begin{stylekey}{/pgfplots/colorbar shift}
	This style is installed after |every colorbar|. It is intented to contain only shift transformations like |xshift| and/or |yshift|. The reason to provide two separate styles is to allow easier deactivation of shift transformations.

\begin{codeexample}[code only]
\pgfplotsset{
	colorbar shift/.style={xshift=1cm}
}
\end{codeexample}
\end{stylekey}

\begin{predefinednode}{current colorbar axis}
	A predefined node for the color bar of an axis. After |\end{axis}|, this node can be used to align further graphical elements at the color bar. Note that |current axis| refers to the axis as such while |current colorbar axis| refers to the color bar (which is an axis itsself).
\end{predefinednode}

\begin{pgfplotscodekey}{colorbar/draw}
	This code key belongs to the low level interface of colorbars. It is invoked whenever a color bar needs to be drawn. Usually, it won't be necessary to use or modify this key explicitly.
	
	In the context when this key is invoked, the styles inherited from the parent axis are already set and the required variables (see the documentation of |every colorbar|) are initialised.

	This code key can be replaced if one needs more than one color bar (or other wrinkles).

	The initial configuration is
\begin{codeexample}[code only]
\pgfplotsset{colorbar/draw/.code={%
	\axis[every colorbar,colorbar shift,colorbar=false]
	\addplot graphics {};
	\endaxis
	}
}
\end{codeexample}

	Please note that a color bar axis is nothing special as such -- it is just a normal axis with one |plot graphics| command and it is invoked with a special set of options. The only special thing is that a set of styles and some variables are inherited from its parent axis.
\end{pgfplotscodekey}

\subsubsection{Scaling Descriptions: Predefined Styles}
\label{sec:scaling:styles}
It is reasonable to change font sizes, marker sizes etc. together with the overall plot size: Large plots should also have larger fonts and small plots should have small fonts and a smaller distance between ticks.

\begin{keylist}{
	/tikz/font=\mchoice{\textbackslash normalfont,\textbackslash small,\textbackslash tiny,$\dotsc$},
	/pgfplots/max space between ticks=\marg{integer},
	/pgfplots/try min ticks=\marg{integer},
	/tikz/mark size=\marg{integer}}
	These keys should be adjusted to the figure's dimensions. Use 
\begin{codeexample}[code only]
\pgfplotsset{tick label style={font=\footnotesize},
	label style={font=\small},
	legend style={font=\small}
}
\end{codeexample}
	to provide different fonts for different descriptions.

	The keys |max space between ticks| and |try min ticks| are described on page~\pageref{maxspacebetweenticks} and configure the approximate distance and number of successive tick labels (in |pt|). Please omit the |pt| suffix here.
\end{keylist}

There are a couple of predefined scaling styles which set some of these options:

\begin{stylekey}{/pgfplots/normalsize}
	Re-initialises the standard scaling options of \PGFPlots.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[normalsize,
		title=A ``normalsize'' figure,
		xlabel=The $x$ axis,
		ylabel=The $y$ axis,
		minor tick num=1,
		legend entries={Leg}]
		\addplot {max(4*x,7*x)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The initial setting is
\begin{codeexample}[code only]
\pgfplotsset{
	normalsize/.style={
		/pgfplots/width=240pt,
		/pgfplots/height=207pt,
		/pgfplots/max space between ticks=35
	}
}
\end{codeexample}
\end{stylekey}

\begin{stylekey}{/pgfplots/small}
	Redefines several keys such that the axis is ``smaller''.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[small,
		title=A ``small'' figure,
		xlabel=The $x$ axis,
		ylabel=The $y$ axis,
		minor tick num=1,
		legend entries={Leg}]
		\addplot {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The initial setting is
\begin{codeexample}[code only]
\pgfplotsset{
	small/.style={
		/pgfplots/width=6.5cm,
		/pgfplots/height=,
		/pgfplots/max space between ticks=25
	}
}
\end{codeexample}
Feel free to redefine the scaling -- the option may still be useful to get more ticks without typing too much. You could, for example, set |small,width=6cm|.
\end{stylekey}

\begin{stylekey}{/pgfplots/footnotesize}
	Redefines several keys such that the axis is even smaller. The tick labels will have |\footnotesize|.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[footnotesize,
		title=A ``footnotesize'' figure,
		xlabel=The $x$ axis,
		ylabel=The $y$ axis,
		minor tick num=1,
		legend entries={Leg}]
		\addplot+[const plot]
			coordinates {
			(0,0) (1,1) (3,3) (5,10)
		};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The initial setting is
\begin{codeexample}[code only]
\pgfplotsset{
	footnotesize/.style={
		/pgfplots/width=5cm,
		/pgfplots/height=,
		legend style={font=\footnotesize},
		tick label style={font=\footnotesize},
		label style={font=\small},
		/pgfplots/max space between ticks=20,
		every mark/.append style={mark size=8},
		major tick length=0.1cm,
		minor tick length=0.066cm,
	},
}
\end{codeexample}
As for |small|, it can be convenient to set |footnotesize| and set |width| afterwards.

See also the |compat=newest| method which causes the positions of |xlabel|, |ylabel| and |zlabel| to be right near the tick labels.
\end{stylekey}