summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex
blob: 6f805573d050e96fdf44ecc673a429a2227f2819 (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
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237

\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 detail. 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 axes (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 with 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 specialty: 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 descriptions 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 descriptions, 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,%
	/tikz/sloped like \x\space axis=\marg{options}
}
	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 for |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).

	It is possible to customize |sloped like x axis| by means of the following keys, which need to be provided as \meta{options} (simply ignore the lengthy gray key prefixes):
\pgfkeys{
	/pgfmanual/gray key prefixes={/pgfplots/sloped/},
}
	\begin{key}{/pgfplots/sloped/allow upside down=\mchoice{true,false} (initially false)}
		Use |sloped like x axis=allow upside down| to enable upside down labels.
	\end{key}
	\begin{key}{/pgfplots/sloped/execute for upside down=\mchoice{code} (initially empty)}
		Use |sloped like x axis={execute for upside down=\tikzset{anchor=north}}| or something like that to handle upside down text nodes in a customized way (this is used by the |smithchart| library).
	\end{key}
	\begin{key}{/pgfplots/sloped/reset nontranslations=\mchoice{true,false} (initially true)}
		Use |sloped like x axis={reset nontranslations=false}| to \emph{append} the transformations to the actual transformation matrix (instead of replacing it).
	\end{key}
\end{pgfplotsxykeylist}


\subsubsection{Labels}

\begin{pgfplotsxykey}{\x label=\marg{text}}
	These options set axis labels to \meta{text} which is any \TeX\ text.

	To include special characters, you can use curly braces: ``|xlabel={, = characters}|''. This is necessary 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. 

	For example, a multiline |xlabel| can be configured using
	\index{xlabel!Multiline}
	\index{xlabel!Line break}
\begin{codeexample}[code only]
\begin{axis}[xlabel style={align=right,text width=3cm},xlabel=A quite long label with a line break]
...
\end{axis}
\end{codeexample}
	\noindent See \cite{tikz} to learn more about |align| and |text width|.

\paragraph{Upgrade notice:} Since version 1.3, label placement \emph{can} respect the size of adjacent tick labels. Use |\pgfplotsset{compat=1.3}| (or newer) 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 \meta{dimension}. The |label shift| sets all three label shifts to the same value.

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

\begin{pgfplotsxykeylist}{\x label near ticks,compat=1.3}
	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=1.3} % or newer
\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=1.3| 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 placement 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 \meta{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\oarg{options}\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).

The optional \meta{options} affect how the text is drawn; they apply only for this particular description text. For example, |\addlegendentry[red]{Text}| would yield a red legend text. Behind the scenes, the text is placed with |\node|\oarg{options} \marg{name}|;|, so \meta{options} can be any \Tikz\ option which affects nodes.

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

\begin{command}{\addlegendentryexpanded\oarg{options}\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, \meta{\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 a 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 and are quite powerful.

	The |\foreach| command supports a dots--notation to denote ranges like |\legend{1,2,...,5}| or even |\legend{$x^1$,$x^...$,$x^d$}|. 

	\paragraph{Attention with periods:} to avoid confusion with the dots |...| notation, you may need to encapsulate a legend entry containing periods by curly braces: |\legend{{ML spcm.},{CW spcm.},{ML AC}}| (or use the |\\| delimiter, see below).

	\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, but it does not support the dots--notation.
\end{enumerate}
The short marker/line combination shown in legends is acquired from the \meta{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 \meta{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).

	Just as for |\addlegendentry|, it is possible to provide \oarg{options} to single descriptions. To do so, place the options in square brackets right before the text:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend entries={$x$,[red]$x^2$,$x^3$}]
	\addplot {x};
	\addplot {x^2};
	\addplot {x^3};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	If the square brackets contain a comma, you can enclose the complete entry in curly braces like |{[red,font=\Huge]Text}| (or you can use the `|\\|' delimiters).
\end{pgfplotskey}


\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 matrices (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}

Note that in order to disable drawing of the legend box, you can use |draw=none| as style argument:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[tiny,title=With legend box]
\addplot[blue]{x};
\addplot[red]{2*x};
\legend{$x$,$2x$}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[tiny,title=Without legend box,
	legend style={draw=none}]
\addplot[blue]{x};
\addplot[red]{2*x};
\legend{$x$,$2x$}
\end{axis}
\end{tikzpicture}
\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 cell align=\mchoice{left,right,center} (initially center)}
	These keys provide horizontal alignment of legend cells.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend cell align=left,
	legend pos=outer north east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{a,fine,legend}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend cell align=center,
	legend pos=outer north east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{a,fine,legend}
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[legend cell align=right,
	legend pos=outer north east]
\addplot coordinates {(0,0) (1,1)};
\addplot coordinates {(0,1) (1,2)};
\addplot coordinates {(0,2) (1,3)};
\legend{a,fine,legend}
\end{axis}
\end{tikzpicture}
\end{codeexample}
	They are actually just styles for commonly used alignment choices: the choice |left| is equivalent to |legend style={cells={anchor=west}}|; the second choice |right| is equivalent to |legend style={cells={anchor=east}}|, and |center| to |legend style={cells={anchor=center}}|. Using different values allows more control over cell alignment.
\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{stylekey}{/pgfplots/every legend image post}
	\label{key:legendimagepost}
	A style which can be used to provide drawing options to every small legend image. These options apply after |current plot style| has been set, allowing users different line styles for legends than for plots.

	For example, suppose you have a line plot and you plot selected markers on top of it (in the same color). Then, you may want to draw just a \emph{single} legend entry (which should contain both the line \emph{and} the markers). The following example shows a solution:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[legend image post style={mark=*}]
	\addplot+[only marks,forget plot] 
		coordinates {(0.5,0.75) (1,1) (1.5,0.75)};
	\addplot+[mark=none,smooth,domain=0:2] 
		{-x*(x-2)};
	\addlegendentry{Parabola}
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The example has two |\addplot| commands, one for the line and one for markers. Due to the |forget plot| option, the marker plot (the first one) doesn't advance the |cycle list|. The axis has only one legend entry, and since |legend image post style={mark=*}| has been used, the legend has a plot mark as well. Due to the |forget plot| option, the marker plot will not get a separate legend label.
\end{stylekey}

\pgfplotsshortstylekey legend image post style=every legend image post\pgfeov

\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 allow plot styles to change \texttt{legend image code}.}, so any drawing operations use the same styles as the |\addplot| command.


The default is the style |line legend|.

\paragraph{Technical note:} At the time when legend images are drawn, the style |every axis legend| is in effect -- which have unwanted side-effects due to changed parameters (especially those concerning node placement, alignment, and shifting). It might be necessary to reset these parameters manually (\PGFPlots\ also attempts to reset the fill color).
\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 apply a different legend style to one particular plot (see the documentation on |area legend| for an example).
\end{stylekey}

\begin{stylekey}{/pgfplots/empty legend}
	A style which clears |legend image code|, thereby omitting the legend image.
\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 they are:
\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{pgfplotskeylist}{%
	reverse legend=\mchoice{true,false} (initially false),%
	legend reversed=\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{pgfplotskeylist}

\begin{pgfplotskeylist}{%
	transpose legend=\mchoice{true,false} (initially false),%
	legend transposed=\mchoice{true,false} (initially false)}
	Allows to transpose the order in which the pairs (legend entry, plot style) are drawn. 
	
	Consider a set of $3$ experiments, each consisting of $2$ parameters. We might want to draw them together as in the following example:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		legend columns=2,
		legend pos=outer north east,
		cycle multi list={%
			color list\nextlist
			[2 of]mark list
		}]
	\addplot {-x};   \addlegendentry{A1}
	\addplot {-x+1}; \addlegendentry{A2}

	\addplot {-1.2*x + 4};  \addlegendentry{B1}
	\addplot {-1.2*x + 5};  \addlegendentry{B2}

	\addplot {-1.3*x + 9};  \addlegendentry{C1}
	\addplot {-1.4*x + 10}; \addlegendentry{C2}
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	An alternative might be to draw them horizontally -- then, we'd like to use |transpose legend| to get a flat legend:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		transpose legend,
		legend columns=2,
		legend style={at={(0.5,-0.1)},anchor=north},
		cycle multi list={%
			color list\nextlist
			[2 of]mark list
		}]
	\addplot {-x};   \addlegendentry{A1}
	\addplot {-x+1}; \addlegendentry{A2}

	\addplot {-1.2*x + 4};  \addlegendentry{B1}
	\addplot {-1.2*x + 5};  \addlegendentry{B2}

	\addplot {-1.3*x + 9};  \addlegendentry{C1}
	\addplot {-1.4*x + 10}; \addlegendentry{C2}
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	Thus, |legend columns| defines the \emph{input} columns, before the transposition (in other words, |legend columns| indicates the \emph{rows} of the resulting legend).

	Transposing legends has only an effect if |legend columns|$>1$. Note that |reverse legend| has higher precedence: it is applied first.
\end{pgfplotskeylist}


\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 \meta{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 independent label.
	
	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.


	Note that |\label| information, even the small \Tikz\ pictures here, can be combined with the |external| library for image externalization, see Section~\ref{sec:pgfplots:export} for details (in particular, the |external/mode| key). In other words, references remain valid even if the defining axis has been externalized.
\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}

\begin{pgfplotskeylist}{%
	invoke before crossref tikzpicture=\marg{\TeX\ code},
	invoke after crossref tikzpicture=\marg{\TeX\ code}}
	Code which is invoked just before or just after every cross reference picture. This applies to legend images generated with |\ref|, |legend to name| and |colorbar to name| images. 
	
	The initial configuration checks if the |external| library is in effect. If so, it modifies the generated figure names by means of |\tikzappendtofigurename{_crossref}|.
	\index{crossref file suffix}
\end{pgfplotskeylist}

\subsubsection{Legends Outside Of an Axis}
Occasionally, one has multiple adjacent plots, each with the same legend -- and just \emph{one} legend suffices. But where shall it be placed? And how? One solution is to use the |overlay| key to exclude the legend from bounding box computations, and place it absolutely such that it fits. Another is the |legend to name| feature:

\begin{pgfplotskey}{legend to name=\marg{name} (initially empty)}
\label{key:legend:to:name}
	Enables a legend export mode: instead of drawing the legend, a self--contained, independent set of drawing commands will be stored using the label \meta{name}. The definition is done using |\label|\marg{name}, just like any other \LaTeX\ label. The name can be referenced using 

	|\ref|\marg{name}.

Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside of any picture, will cause the legend to be drawn.
{
\pgfplotsmanualdisablecolorforref
\begin{codeexample}[vbox]
\pgfplotsset{footnotesize,samples=10}
\begin{center}% note that \centering uses less vspace...
\begin{tikzpicture}
	\begin{axis}[
		legend columns=-1,
		legend entries={$(x+0)^k$;,$(x+1)^k$;,$(x+2)^k$;,$(x+3)^k$},
		legend to name=named,
		title={$k=1$}]
	\addplot {x};
	\addplot {x+1};
	\addplot {x+2};
	\addplot {x+3};
	\end{axis}
\end{tikzpicture}
%
\begin{tikzpicture}
	\begin{axis}[title={$k=2$}]
	\addplot {x^2};
	\addplot {(x+1)^2};
	\addplot {(x+2)^2};
	\addplot {(x+3)^2};
	\end{axis}
\end{tikzpicture}
%
\begin{tikzpicture}
	\begin{axis}[title={$k=3$}]
	\addplot {x^3};
	\addplot {(x+1)^3};
	\addplot {(x+2)^3};
	\addplot {(x+3)^3};
	\end{axis}
\end{tikzpicture}
\\

\ref{named}
\end{center}
\end{codeexample}
}

	Note that only the \emph{first} plot has |legend entries|. Thus, its legend will be created as usual, and stored under the name `|named|', but it won't be drawn. The stored legend can then be drawn with |\ref{named}| below the three plots. Since there is no picture in this context, a |\tikz| picture is created and a |\matrix[/pgfplots/every axis legend]| path is drawn inside of it, resulting in the legend as if it had been placed inside of the axis.

	The stored legend will contain the currently active values of legend- and plot style related options. This includes |legend image code|, |every axis legend|, and any plot style options (and some more). The algorithm works in the same way as for |\label| and |\ref|, i.e.\ it keeps any options with |/tikz/| prefix and expands those with |/pgfplots/| prefix.

	Note that the legend is drawn with |every axis legend|, even though the placement options might be chosen to fit into an axis. You may want to adjust the style in the same axis in which the stored legend has been defined (the value will be copied and restored as well).

	\paragraph{About \texttt{\string\ref}\marg{name}} The |\ref|\marg{name} command retrieves a stored legend (one defined by |legend to name|) and draws it.

{
\pgfplotsmanualdisablecolorforref
		|\ref{named}: | \ref{named}
}


		If you want the legend to be exported \emph{and} drawn inside of the current axis, consider using |extra description/.append code={\ref|\marg{name}|}|.

		Note that |\ref| can be combined with the |external| library for image externalization. In other words, the legend will work even if the defining axis has been externalized, see Section~\ref{sec:pgfplots:export} for details (in particular the |external/mode| key).

		Note furthermore that this |.aux| file related stuff is (currently) only supported, if \PGFPlots\ is run by means of \LaTeX, sorry.
	\begin{command}{\pgfplotslegendfromname\marg{name}}
		This command poses an equivalent alternative for |\ref|\marg{name}: it has essentially the same effect, but it does not create links when used with the |hyperref| package\footnote{Since this manual uses colored links, the text in \texttt{\string\ref} would usually be blue. Using \texttt{\string\pgfplotslegendfromname} avoids link text colors in the legend (this has been applied to the manual styles here).}.
	\end{command}

	\begin{stylekey}{/pgfplots/every legend to name picture}
		A style which is installed when |\ref| is used outside of a picture: a new picture will be created with |\tikz[/pgfplots/every legend to name picture]|. 
		
		Thus, you can redefine this style to set alignment options (such as |baseline|).
		For example, the initialization
\begin{codeexample}[code only]
\pgfplotsset{
	legend style={matrix anchor=west,at={(0pt,0pt)}},
	every legend to name picture/.style={baseline},
}
...
\end{codeexample}
		\noindent will cause the legend to be positioned such that its |west| anchor is at |y=0pt|. The |baseline| option will align this point of the legend with the text baseline (please refer to the documentation for |baseline| in Section~\ref{pgfplots:sec:align} for details).
	\end{stylekey}
\end{pgfplotskey}

\subsubsection{Legends with Customized Texts or Multiple Lines}

\begin{command}{\addlegendimage\marg{options}}
	Adds a further legend image for legend creation.

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

	Thus, the effect is as if you had provided |\addplot|\oarg{options}, but |\addlegendimage| 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 issued. Not even the current plot's index is advanced.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{semilogyaxis}[
	domain=0:4,
]
	\addplot {x};   \addlegendentry{$x$}
	\addplot {x^2}; \addlegendentry{$x^2$}
	\addplot {x^3}; \addlegendentry{$x^3$}
	\addlegendimage{empty legend}
	\addlegendentry{---}
	\addplot {x^(-1)}; \addlegendentry{$x^{-1}$}
	\addplot {x^(-2)}; \addlegendentry{$x^{-2}$}
	\addplot {x^(-3)}; \addlegendentry{$x^{-3}$}
\end{semilogyaxis}
\end{tikzpicture}
\end{codeexample}
	The example above has six plots, each with its legend entry. Furthermore, it has an |\addlegendimage| command and its separate legend entry. We see that |\addlegendimage| needs its own legend entry, but it is detached from the processing of plots as such. In our case, we chose |empty legend| as style for the separator.

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

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

Occasionally, one may want multiple lines for legend entries. That is possible as well using a fixed |text width|:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{semilogyaxis}[
	domain=0:4,
]
	\addplot {x};   \addlegendentry{$x$}
	\addplot {x^2}; \addlegendentry{$x^2$}
	\addplot {x^3}; \addlegendentry{$x^3$}
	\addlegendimage{empty legend}
	\addlegendentry[text width=25pt,text depth=]
		{Neg. Sign:}
	\addplot {x^(-1)}; \addlegendentry{$x^{-1}$}
	\addplot {x^(-2)}; \addlegendentry{$x^{-2}$}
	\addplot {x^(-3)}; \addlegendentry{$x^{-3}$}
\end{semilogyaxis}
\end{tikzpicture}
\end{codeexample}
\noindent The example provides options for the single multiline element. Note that the initial configuration of |legend style| employs |text depth=0.15em|, which needs to be reset manually to |text depth={}|\footnote{Perhaps I can reset \texttt{text depth} automatically in the future.}.

\noindent There are two approaches with the same effect which are subject of the following example:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{semilogyaxis}[
	domain=0:4,
	legend entries={%
	  $x$,$x^2$,$x^3$,%
	  {[text width=25pt,text depth=]Neg. Sign:},%
	  $x^{-1}$,$x^{-2}$,$x^{-3}$},
	% same effect:
	% legend style={
	% 	nodes={text width=25pt,text depth=}}
]
	\addplot {x}; 
	\addplot {x^2};
	\addplot {x^3};
	\addlegendimage{empty legend}
	\addplot {x^(-1)};
	\addplot {x^(-2)};
	\addplot {x^(-3)}; 
\end{semilogyaxis}
\end{tikzpicture}
\end{codeexample}
\noindent Here, the |legend entries| are provided using the single key syntax. Note that the special options are provided as part of the legend entry, using square brackets right before the text as such. The comments indicate that you could also add the |text width| stuff to |legend style|, in which case it would hold for every node.


Note that legend texts are realized using |\node|\oarg{options} \marg{text}|;|, so anything which produces a valid \Tikz\ node is permitted (this includes |minipage| or |tabular| environments inside of \meta{text}).

\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 choice |axis x line=none| is an alias for |hide x axis|. The $y$- and $z$ variants work in a similar way. 

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, some of these choices will modify axis label positions.
\end{itemize}
The handling of |axis y line| and |axis z line| is similar. 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}
In addition, conditional modifications of axis label styles will be taken. For example, |axis x line=middle| will set
\begin{codeexample}[code only]
\pgfplotsset{every axis x label/.style={at={(current axis.left of origin)},anchor=south west}}
\end{codeexample}
if the matching $y$ style has value |axis y line=right| and 
\begin{codeexample}[code only]
\pgfplotsset{every axis x label/.style={at={(current axis.right of origin)},anchor=south east}}
\end{codeexample}
if |axis y line|$\neq$|right|.

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 appearance.

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, preferably 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}

\label{pgfplots:page:axislines}
\begin{pgfplotskey}{axis line style=\marg{key-value-list}}
	A command which appends \meta{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 \meta{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 \meta{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 \meta{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 and taste.
\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}


\subsubsection[Two Ordinates]{Two Ordinates ($y$ axis) or Multiple Axes}
{%
\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. The idea in \PGFPlots\ is to draw two axes on top of each other, one with descriptions only on the left and the second with descriptions only on the right:

\begin{codeexample}[]
\begin{tikzpicture}
  % let both axes use the same layers
  \pgfplotsset{set layers}
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    axis y line*=left,% the '*' avoids arrow heads
    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 Thus, the two axes are drawn ``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.
	\item You need to tell \PGFPlots\ that it should share the same graphics layers for both axes. In this case, \PGFPlots\ will draw plots of the first axis and of the second axis onto the same layer. It will also draw background(s) into the background layer and descriptions into the foreground layer. Use the key |\pgfplotsset{set layers}| in front of the first axis to prepare the complete picture for layered graphics.
\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}
  % let both axes use the same layers
  \pgfplotsset{set layers}
  \begin{axis}[
    scale only axis,
    xmin=-5,xmax=5,
    axis y line*=left,%'*' avoids arrow heads
    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,
    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 to |axis y discontinuity| and |axis z discontinuity| as well, simply substitute $x$ by $y$ or $z$, respectively.

\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 with non--zero color data range, more precisely, for which minimum and maximum |point meta| data is available. Usually, this is the case for |scatter|, |mesh| or |surf| (or similar) plots, but you can also set |point meta min| and |point meta max| manually in order to draw a |colorbar|. 
	
	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. Consider using |colorbar source| to select color data limits of a particular |\addplot| command instead.
		\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 redefines |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 as
\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 as
\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 as
\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}
	\label{key: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 intended 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|.

	The value is usually determined using the axis wide point meta limits, i.e.\ they are computed as minimum and maximum value over all plots (unless the user provided limits manually). Consider the |colorbar source| key if you'd like to select point meta limits of one specific |\addplot| command.
\end{pgfplotskeylist}
\begin{pgfplotskey}{colorbar source=\marg{true,false} (initially false)}
	Allows to select a specific |\addplot| command whose point meta limits are taken as upper and lower limit of a |colorbar|'s data range. This affects the tick descriptions of the |colorbar|. It needs to be provided as argument to |\addplot|, i.e.\ using
\begin{codeexample}[code only]
\addplot[...,colorbar source] ...
% or
\addplot+[colorbar source] ...
\end{codeexample}
	\noindent or as key inside of a |cycle list|.

	Using |colorbar source| automatically implies |point meta rel=per plot| for  that specific plot.

	If there are more than one |\addplot| commands with |colorbar source|, the last one is selected. 
\end{pgfplotskey}
\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 horizontal color bars, this sets the height.
\end{pgfplotskey}


\begin{stylekey}{/pgfplots/colorbar shift}
	This style is installed after |every colorbar|. It is intended 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 itself).
\end{predefinednode}

\begin{pgfplotscodekey}{colorbar/draw}
	This code key belongs to the low level interface of color bars. It is invoked whenever a color bar needs to be drawn. Usually, it won't be necessary to use or modify this key explicitly.
	
	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 initialized.

	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}

\begin{stylekey}{/pgfplots/colorbar sampled=\marg{optional options} (default surf,mark=none,shader=flat)}
	A style which installs a discretely sampled color bar.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar sampled]
	\addplot[mesh,samples=40] {sin(deg(x))};	
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The style uses |\addplot3|\oarg{options} to draw the |colorbar|, with |domain| set to the color range and the current value of the |samples| key to determine the number of samples. In other words: it uses |plot expression| and a surface plot to visualize the |colorbar|. Use |colorbar style={samples=10}| to change the number of samples.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar sampled,colorbar style={samples=8}]
	\addplot[mesh,samples=40] {sin(deg(x))};	
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The \meta{options} can be used to change the |\addplot3| options used for the colorbar visualization. For example, |colorbar sampled={surf,shader=interp}| will use Gouraud shading which has visually the same effect as the standard color bar.
\end{stylekey}

\begin{stylekey}{/pgfplots/colorbar sampled line=\marg{optional options} (default scatter,only marks)}
	A style which draws a discrete colorbar. In contrast to |colorbar sampled|, it visualizes the |colorbar| using a line plot, not a |surf| plot.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar sampled line]
	\addplot+[scatter] {sin(deg(x))};	
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The initial configuration uses a |scatter| plot to visualize the |colorbar|, it can be changed by specifying \meta{options}.

	Furthermore, the axis appearance is changed using |axis y line*=|\mchoice{left,right}, depending on the position of the color bar (or |axis x line*=bottom| for |colorbar horizontal|).

	Consider the |tick align=outside| feature if you prefer tick lines outside of the colorbar instead of inside.

	\begin{stylekey}{/pgfplots/every colorbar sampled line}
		A style which is used by |colorbar sampled line| to change the color of the line without ticks.

		It is initially set to |help lines|.
	\end{stylekey}
\end{stylekey}

\subsubsection{Color Bars Outside Of an Axis}

Occasionally, one has multiple adjacent plots, each with the same |colormap| and the same |point meta min| and |point meta max| values and we'd like to show a \emph{single} |colorbar|. \PGFPlots\ supports the |colorbar to name| feature which is similar to the related method for legends, |legend to name|:


\begin{pgfplotskey}{colorbar to name=\marg{name} (initially empty)}
	Enables to detach a |colorbar| from its parent axis: instead of drawing the |colorbar|, a self--contained, independent set of drawing commands will be stored using the label \meta{name}. The label is defined using |\label|\marg{name}, just as for any other \LaTeX\ label. The name can be referenced using 

	|\ref|\marg{name}.

Thus, typing |\ref|\marg{name} somewhere outside of the axis, maybe even outside of any picture, will cause the |colorbar| to be drawn.

{
\pgfplotsmanualdisablecolorforref
\begin{codeexample}[vbox]
\pgfplotsset{footnotesize,samples=10, domain=0:1,point meta min=0, point meta max=1}
\begin{center}% note that \centering uses less vspace...
\begin{tikzpicture}
	\begin{axis}[colorbar,colorbar horizontal,colorbar to name={storedcolorbar}]
	\addplot[scatter,only marks,mark=*] {rnd};
	\end{axis}
\end{tikzpicture}
%
\begin{tikzpicture}
	\begin{axis}
	\addplot+[domain=0:1,mark=none,mesh] {x^2};
	\end{axis}
\end{tikzpicture}
%
\begin{tikzpicture}
	\begin{axis}[view={0}{90}]
	\addplot3[surf] {x*y};
	\end{axis}
\end{tikzpicture}
\\

\ref{storedcolorbar}
\end{center}
\end{codeexample}
}

	The feature works in the same way as described for |legend to name|, please refer to its description on page~\pageref{key:legend:to:name} for the details. We only summarize the differences here.
	\begin{command}{\pgfplotscolorbarfromname\marg{name}}
		This command poses an equivalent alternative for |\ref|\marg{name}: it has essentially the same effect, but it does not create links when used with the |hyperref| package.
	\end{command}

	\begin{stylekey}{/pgfplots/every colorbar to name picture}
		A style which is installed when |\ref| is used outside of a picture: a new picture will be created with |\tikz[/pgfplots/every colorbar to name picture]|. 
		
		See also the |every legend to name picture| style.
	\end{stylekey}
\end{pgfplotskey}