# pyplot 教程
> 原文：[Pyplot tutorial](http://matplotlib.org/users/pyplot_tutorial.html)
> 譯者：[飛龍](https://github.com/)
> 協議：[CC BY-NC-SA 4.0](http://creativecommons.org/licenses/by-nc-sa/4.0/)
`matplotlib.pyplot`是一個命令風格函數的集合，使`matplotlib`的機制更像 MATLAB。 每個繪圖函數對圖形進行一些更改：例如，創建圖形，在圖形中創建繪圖區域，在繪圖區域繪制一些線條，使用標簽裝飾繪圖等。在`matplotlib.pyplot`中，各種狀態跨函數調用保存，以便跟蹤諸如當前圖形和繪圖區域之類的東西，并且繪圖函數始終指向當前軸域（請注意，這里和文檔中的大多數位置中的『軸域』（axes）是指圖形的一部分（兩條坐標軸圍成的區域），而不是指代多于一個軸的嚴格數學術語）。
```py
import matplotlib.pyplot as plt
plt.plot([1,2,3,4])
plt.ylabel('some numbers')
plt.show()
```
你可能想知道為什么`x`軸的范圍為`0-3`，`y`軸的范圍為`1-4`。 如果你向`plot()`命令提供單個列表或數組，則`matplotlib`假定它是一個`y`值序列，并自動為你生成`x`值。 由于 python 范圍從 0 開始，默認`x`向量具有與`y`相同的長度，但從 0 開始。因此`x`數據是`[0,1,2,3]`。
`plot()`是一個通用命令，并且可接受任意數量的參數。 例如，要繪制`x`和`y`，你可以執行命令：
```py
plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
```
對于每個`x,y`參數對，有一個可選的第三個參數，它是指示圖形顏色和線條類型的格式字符串。 格式字符串的字母和符號來自 MATLAB，并且將顏色字符串與線型字符串連接在一起。 默認格式字符串為`"b-"`，它是一條藍色實線。 例如，要繪制上面的紅色圓圈，你需要執行：
```py
import matplotlib.pyplot as plt
plt.plot([1,2,3,4], [1,4,9,16], 'ro')
plt.axis([0, 6, 0, 20])
plt.show()
```
有關線型和格式字符串的完整列表，請參見[`plot()`文檔](http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.plot)。 上例中的`axis()`命令接收`[xmin，xmax，ymin，ymax]`的列表，并指定軸域的可視區域。
如果`matplotlib`僅限于使用列表，它對于數字處理是相當無用的。 一般來說，你可以使用`numpy`數組。 事實上，所有序列都在內部轉換為`numpy`數組。 下面的示例展示了使用數組和不同格式字符串，在一條命令中繪制多個線條。
```py
import numpy as np
import matplotlib.pyplot as plt
# evenly sampled time at 200ms intervals
t = np.arange(0., 5., 0.2)
# red dashes, blue squares and green triangles
plt.plot(t, t, 'r--', t, t**2, 'bs', t, t**3, 'g^')
plt.show()
```
## 控制線條屬性
線條有許多你可以設置的屬性：`linewidth`，`dash style`，`antialiased`等，請參見`matplotlib.lines.Line2D`。 有幾種方法可以設置線屬性：
+ 使用關鍵字參數：
```py
plt.plot(x, y, linewidth=2.0)
```
+ 使用`Line2D`實例的`setter`方法。 `plot`返回`Line2D`對象的列表，例如`line1,line2 = plot(x1，y1，x2，y2)`。 在下面的代碼中，我們假設只有一行，返回的列表長度為 1。我們對`line`使用元組解構，得到該列表的第一個元素：
```py
line, = plt.plot(x, y, '-')
line.set_antialiased(False) # turn off antialising
```
+ 使用`setp()`命令。 下面的示例使用 MATLAB 風格的命令來設置線條列表上的多個屬性。 `setp`使用對象列表或單個對象透明地工作。 你可以使用 python 關鍵字參數或 MATLAB 風格的字符串/值對：
```py
lines = plt.plot(x1, y1, x2, y2)
# 使用關鍵字參數
plt.setp(lines, color='r', linewidth=2.0)
# 或者 MATLAB 風格的字符串值對
plt.setp(lines, 'color', 'r', 'linewidth', 2.0)
```
下面是可用的`Line2D`屬性。
| 屬性 | 值類型 |
| --- | --- |
| `alpha` | 浮點值 |
| `animated` | `[True / False]` |
| `antialiased or aa` | `[True / False]` |
| `clip_box` | `matplotlib.transform.Bbox` 實例 |
| `clip_on` | `[True / False]` |
| `clip_path` | `Path` 實例， `Transform`，以及`Patch`實例 |
| `color or c` | 任何 `matplotlib` 顏色 |
| `contains` | 命中測試函數 |
| `dash_capstyle` | `['butt' / 'round' / 'projecting']` |
| `dash_joinstyle` | `['miter' / 'round' / 'bevel']` |
| `dashes` | 以點為單位的連接/斷開墨水序列 |
| `data` | `(np.array xdata, np.array ydata)` |
| `figure` | `matplotlib.figure.Figure` 實例 |
| `label` | 任何字符串 |
| `linestyle` or `ls` | `[ '-' / '--' / '-.' / ':' / 'steps' / ...]` |
| `linewidth` or `lw` | 以點為單位的浮點值 |
| `lod` | `[True / False]` |
| `marker` | `[ '+' / ',' / '.' / '1' / '2' / '3' / '4' ]` |
| `markeredgecolor or mec` | 任何 `matplotlib` 顏色 |
| `markeredgewidth or mew` | 以點為單位的浮點值 |
| `markerfacecolor or mfc` | 任何 `matplotlib` 顏色 |
| `markersize or ms` | 浮點值 |
| `markevery` | `[ None / 整數值 / (startind, stride) ]` |
| `picker` | 用于交互式線條選擇 |
| `pickradius` | 線條的拾取選擇半徑 |
| `solid_capstyle` | `['butt' / 'round' / 'projecting']` |
| `solid_joinstyle` | `['miter' / 'round' / 'bevel']` |
| `transform` | `matplotlib.transforms.Transform` 實例 |
| `visible` | `[True / False]` |
| `xdata` | `np.array` |
| `ydata` | `np.array` |
| `zorder` | 任何數值 |
要獲取可設置的線條屬性的列表，請以一個或多個線條作為參數調用`step()`函數
```py
In [69]: lines = plt.plot([1, 2, 3])
In [70]: plt.setp(lines)
alpha: float
animated: [True | False]
antialiased or aa: [True | False]
...snip
```
## 處理多個圖形和軸域
MATLAB 和 pyplot 具有當前圖形和當前軸域的概念。 所有繪圖命令適用于當前軸域。 函數`gca()`返回當前軸域（一個`matplotlib.axes.Axes`實例），`gcf()`返回當前圖形（`matplotlib.figure.Figure`實例）。 通常，你不必擔心這一點，因為它都是在幕后處理。 下面是一個創建兩個子圖的腳本。
```py
import numpy as np
import matplotlib.pyplot as plt
def f(t):
return np.exp(-t) * np.cos(2*np.pi*t)
t1 = np.arange(0.0, 5.0, 0.1)
t2 = np.arange(0.0, 5.0, 0.02)
plt.figure(1)
plt.subplot(211)
plt.plot(t1, f(t1), 'bo', t2, f(t2), 'k')
plt.subplot(212)
plt.plot(t2, np.cos(2*np.pi*t2), 'r--')
plt.show()
```
這里的`figure()`命令是可選的，因為默認情況下將創建`figure(1)`，如果不手動指定任何軸域，則默認創建`subplot(111)`。`subplot()`命令指定`numrows`，`numcols`，`fignum`，其中`fignum`的范圍是從`1`到`numrows * numcols`。 如果`numrows * numcols <10`，則`subplot`命令中的逗號是可選的。 因此，子圖`subplot(211)`與`subplot(2, 1, 1)`相同。 你可以創建任意數量的子圖和軸域。 如果要手動放置軸域，即不在矩形網格上，請使用`axes()`命令，該命令允許你將`axes([left, bottom, width, height])`指定為位置，其中所有值都使用小數（0 到 1）坐標。 手動放置軸域的示例請參見[`pylab_examples`示例代碼：`axes_demo.py`](http://matplotlib.org/examples/pylab_examples/axes_demo.html#pylab-examples-axes-demo)，具有大量子圖的示例請參見[`pylab_examples`示例代碼：`subplots_demo.py`](http://matplotlib.org/examples/pylab_examples/subplots_demo.html#pylab-examples-subplots-demo)。
你可以通過使用遞增圖形編號多次調用`figure()`來創建多個圖形。 當然，每個數字可以包含所需的軸和子圖數量：
```py
import matplotlib.pyplot as plt
plt.figure(1) # 第一個圖形
plt.subplot(211) # 第一個圖形的第一個子圖
plt.plot([1, 2, 3])
plt.subplot(212) # 第一個圖形的第二個子圖
plt.plot([4, 5, 6])
plt.figure(2) # 第二個圖形
plt.plot([4, 5, 6]) # 默認創建 subplot(111)
plt.figure(1) # 當前是圖形 1，subplot(212)
plt.subplot(211) # 將第一個圖形的 subplot(211) 設為當前子圖
plt.title('Easy as 1, 2, 3') # 子圖 211 的標題
```
你可以使用`clf()`清除當前圖形，使用`cla()`清除當前軸域。 如果你搞不清在幕后維護的狀態（特別是當前的圖形和軸域），不要絕望：這只是一個面向對象的 API 的簡單的狀態包裝器，你可以使用面向對象 API（見[藝術家教程](http://matplotlib.org/users/artists.html#artist-tutorial)）。
如果你正在制作大量的圖形，你需要注意一件事：在一個圖形用`close()`顯式關閉之前，該圖所需的內存不會完全釋放。 刪除對圖形的所有引用，和/或使用窗口管理器殺死屏幕上出現的圖形的窗口是不夠的，因為在調用`close()`之前，`pyplot`會維護內部引用。
## 處理文本
`text()`命令可用于在任意位置添加文本，`xlabel()`，`ylabel()`和`title()`用于在指定的位置添加文本（詳細示例請參閱[文本介紹](http://matplotlib.org/users/text_intro.html#text-intro)）。
```py
import numpy as np
import matplotlib.pyplot as plt
mu, sigma = 100, 15
x = mu + sigma * np.random.randn(10000)
# 數據的直方圖
n, bins, patches = plt.hist(x, 50, normed=1, facecolor='g', alpha=0.75)
plt.xlabel('Smarts')
plt.ylabel('Probability')
plt.title('Histogram of IQ')
plt.text(60, .025, r'$\mu=100,\ \sigma=15$')
plt.axis([40, 160, 0, 0.03])
plt.grid(True)
plt.show()
```
所有的`text()`命令返回一個`matplotlib.text.Text`實例。 與上面一樣，你可以通過將關鍵字參數傳遞到`text`函數或使用`setp()`來自定義屬性：
```py
t = plt.xlabel('my data', fontsize=14, color='red')
```
這些屬性的更詳細介紹請見[文本屬性和布局](http://matplotlib.org/users/text_props.html#text-properties)。
## 在文本中使用數學表達式
`matplotlib`在任何文本表達式中接受 TeX 方程表達式。 例如，要在標題中寫入表達式，可以編寫一個由美元符號包圍的 TeX 表達式：
```py
plt.title(r'$\sigma_i=15$')
```
標題字符串之前的`r`很重要 - 它表示該字符串是一個原始字符串，而不是將反斜杠作為 python 轉義處理。 `matplotlib`有一個內置的 TeX 表達式解析器和布局引擎，并且自帶了自己的數學字體 - 詳細信息請參閱[編寫數學表達式](http://matplotlib.org/users/mathtext.html#mathtext-tutorial)。 因此，你可以跨平臺使用數學文本，而無需安裝 TeX。 對于安裝了 LaTeX 和`dvipng`的用戶，還可以使用 LaTeX 格式化文本，并將輸出直接合并到顯示圖形或保存的 postscript 中 - 請參閱[使用 LaTeX 進行文本渲染](http://matplotlib.org/users/usetex.html#usetex-tutorial)。
## 標注文本
上面的`text()`基本命令將文本放置在軸域的任意位置。 文本的一個常見用法是對圖的某些特征執行標注，而`annotate()`方法提供一些輔助功能，使標注變得容易。 在標注中，有兩個要考慮的點：由參數`xy`表示的標注位置和`xytext`表示的文本位置。 這兩個參數都是`(x, y)`元組。
在此基本示例中，`xy`（箭頭提示）和`xytext`（文本）都位于數據坐標中。 有多種其他坐標系可供選擇 - 詳細信息請參閱[標注文本](http://matplotlib.org/users/annotations_intro.html#annotations-tutorial)和[標注軸域](http://matplotlib.org/users/annotations_guide.html#plotting-guide-annotation)。 更多示例可以在[`pylab_examples`示例代碼：`annotation_demo.py`](http://matplotlib.org/examples/pylab_examples/annotation_demo.html#pylab-examples-annotation-demo)中找到。
## 對數和其它非線性軸
`matplotlib.pyplot`不僅支持線性軸刻度，還支持對數和對數刻度。 如果數據跨越許多數量級，通常會使用它。 更改軸的刻度很容易：
```py
plt.xscale('log')
```
下面示例顯示了四個圖，具有相同數據和不同刻度的`y`軸。
```py
import numpy as np
import matplotlib.pyplot as plt
# 生成一些區間 [0, 1] 內的數據
y = np.random.normal(loc=0.5, scale=0.4, size=1000)
y = y[(y > 0) & (y < 1)]
y.sort()
x = np.arange(len(y))
# 帶有多個軸域刻度的 plot
plt.figure(1)
# 線性
plt.subplot(221)
plt.plot(x, y)
plt.yscale('linear')
plt.title('linear')
plt.grid(True)
# 對數
plt.subplot(222)
plt.plot(x, y)
plt.yscale('log')
plt.title('log')
plt.grid(True)
# 對稱的對數
plt.subplot(223)
plt.plot(x, y - y.mean())
plt.yscale('symlog', linthreshy=0.05)
plt.title('symlog')
plt.grid(True)
# logit
plt.subplot(224)
plt.plot(x, y)
plt.yscale('logit')
plt.title('logit')
plt.grid(True)
plt.show()
```
還可以添加自己的刻度，詳細信息請參閱[向`matplotlib`添加新的刻度和投影](http://matplotlib.org/devel/add_new_projection.html#adding-new-scales)。
