Matplotlib 3.4.0 的新功能 (2021 年 3 月 26 日)#

如需自上次修訂以來的所有問題和提取請求列表，請參閱 3.10.0 的 GitHub 統計資料 (2024 年 12 月 13 日)。

圖形和軸的建立/管理#

新的子圖形功能#

新的 figure.Figure.add_subfigure 和 figure.Figure.subfigures 功能允許在圖形內建立虛擬圖形。先前使用巢狀 gridspecs 完成了類似的巢狀結構（請參閱 巢狀 Gridspecs）。然而，這不允許本地化的圖形圖形（例如，僅與每個子網格規範相關的顏色條或 suptitle）。

新的方法 figure.Figure.add_subfigure 和 figure.Figure.subfigures 的目的是與 figure.Figure.add_subplot 和 figure.Figure.subplots 押韻，並具有大多數相同的參數。

有關詳細資訊，請參閱 圖形子圖形。

注意

截至 v3.4，子圖形功能為實驗性 API。

(原始碼, 2x.png, png)

subplot_mosaic 的單行字串標記法#

Figure.subplot_mosaic 和 pyplot.subplot_mosaic 現在接受單行字串，使用分號來分隔列。也就是說，

plt.subplot_mosaic(
    """
    AB
    CC
    """)

可以寫成較短的

plt.subplot_mosaic("AB;CC")

(原始碼, 2x.png, png)

軸建立方法 ( gca、add_axes、add_subplot ) 的行為變更#

建立新軸的函式 (pyplot.axes、pyplot.subplot、figure.Figure.add_axes、figure.Figure.add_subplot) 的行為已變更。過去，這些函式會偵測您是否嘗試使用與目前圖形中已存在的軸相同的關鍵字引數建立軸，如果是，則它們會傳回現有的軸。現在，pyplot.axes、figure.Figure.add_axes 和 figure.Figure.add_subplot 將永遠建立新的軸。pyplot.subplot 將繼續重複使用具有相符子圖規格和相等 kwargs 的現有軸。

對應地，取得目前軸的函式 (pyplot.gca、figure.Figure.gca) 的行為已變更。過去，這些函式接受關鍵字引數。如果關鍵字引數與已存在的軸相符，則會傳回該軸，否則將使用這些關鍵字引數建立新的軸。現在，只有當目前圖形中完全沒有軸時，才會考慮關鍵字引數。在未來的版本中，這些函式將完全不接受關鍵字引數。

add_subplot/add_axes 取得 axes_class 參數#

特別是，現在可以使用 fig.add_subplot(axes_class=mpl_toolkits.axislines.Axes) 等習慣用法來慣用地使用 mpl_toolkits 軸子類別

Subplot 和 subplot2grid 現在可以搭配受限的版面配置運作#

constrained_layout 取決於圖形上每個邏輯版面配置的單一 GridSpec。先前，pyplot.subplot 和 pyplot.subplot2grid 每次呼叫時都會新增一個新的 GridSpec，因此與 constrained_layout 不相容。

現在，如果列數和欄數與圖形中已有的最上層 GridSpec 相同，subplot 會嘗試重複使用 GridSpec，也就是說，plt.subplot(2, 1, 2) 將使用與 plt.subplot(2, 1, 1) 相同的 GridSpec，並且 Figure 的 constrained_layout=True 選項將會運作。

相反地，混合使用 nrows 和 ncols 將無法與 constrained_layout 搭配運作：plt.subplot(2, 2, 1) 接著 plt.subplots(2, 1, 2) 仍會產生兩個 GridSpecs，而 constrained_layout=True 會產生不好的結果。為了達到預期的效果，第二次呼叫可以指定第二個 Axes 打算涵蓋的儲存格：plt.subplots(2, 2, (2, 4))，或者可以使用更具 Python 風格的 plt.subplot2grid((2, 2), (0, 1), rowspan=2)。

繪圖方法#

axline 支援 transform 參數#

axline 現在支援 transform 參數，該參數應用於點 xy1、xy2。slope（如果給定）始終以數據座標表示。

例如，這可以與 ax.transAxes 搭配使用，以繪製具有固定斜率的線條。在以下繪圖中，該線條會穿過兩個 Axes 上的同一個點，即使它們顯示不同的數據限制。

fig, axs = plt.subplots(1, 2)

for i, ax in enumerate(axs):
    ax.axline((0.25, 0), slope=2, transform=ax.transAxes)
    ax.set(xlim=(i, i+5), ylim=(i, i+5))

(原始碼, 2x.png, png)

長條圖的新自動標籤功能#

新增了一個新的 Axes.bar_label 方法，用於自動標記長條圖。

../../_images/sphx_glr_bar_label_demo_001.png

新自動標籤功能的範例。#

可以為 bar 和 barh 指定陰影線清單#

與其他一些矩形屬性類似，現在可以將陰影線樣式的清單傳遞給 bar 和 barh，以便建立具有不同陰影線樣式的長條，例如：

(原始碼, 2x.png, png)

設定 BarContainer 方向#

BarContainer 現在接受新的字串引數 orientation。它可以是 'vertical' 或 'horizontal'，預設值為 None。

等高線圖現在預設使用 ScalarFormatter#

將 fmt="%1.3f" 傳遞給等高線呼叫，以還原舊的預設標籤格式。

Axes.errorbar 正確循環非顏色屬性#

以前，如果明確指定了顏色，即使屬性循環器用於其他屬性（例如線條樣式），Axes.errorbar 會不正確地跳過 Axes 屬性循環。現在，Axes.errorbar 將會像對 Axes.plot 所做的那樣推進 Axes 屬性循環，也就是說，只要循環器中的所有屬性都不是明確傳遞的。

例如，以下內容將會循環瀏覽線條樣式

x = np.arange(0.1, 4, 0.5)
y = np.exp(-x)
offsets = [0, 1]

plt.rcParams['axes.prop_cycle'] = plt.cycler('linestyle', ['-', '--'])

fig, ax = plt.subplots()
for offset in offsets:
    ax.errorbar(x, y + offset, xerr=0.1, yerr=0.3, fmt='tab:blue')

(原始碼, 2x.png, png)

errorbar errorevery 參數與 markevery 相符#

與 plot 的 markevery 參數類似，errorbar 的 errorevery 參數現在接受切片和 NumPy 花式索引（必須與 x 的大小相符）。

(原始碼, 2x.png, png)

hexbin 支援 C 參數的數據參考#

與 x 和 y 參數一樣，Axes.hexbin 現在支援使用數據參考傳遞 C 參數。

data = {
    'a': np.random.rand(1000),
    'b': np.random.rand(1000),
    'c': np.random.rand(1000),
}

fig, ax = plt.subplots()
ax.hexbin('a', 'b', C='c', data=data, gridsize=10)

(原始碼, 2x.png, png)

支援可呼叫的 Sankey 標籤格式#

format 的 matplotlib.sankey.Sankey 參數現在可以接受可呼叫的物件。

這允許使用任意函數來標記流程，例如允許將數字對應到表情符號。

(原始碼, 2x.png, png)

Axes.spines 存取快捷方式#

Axes.spines 現在是專用的容器類別 Spines，用於一組 Spine，而不是 OrderedDict。除了類似字典的存取方式之外，Axes.spines 現在還支援一些類似 pandas.Series 的功能。

通過項目或屬性存取單個元素

ax.spines['top'].set_visible(False)
ax.spines.top.set_visible(False)

存取項目的子集

ax.spines[['top', 'right']].set_visible(False)

同時存取所有項目

ax.spines[:].set_visible(False)

新的 stairs 方法和 StepPatch 繪圖物件#

pyplot.stairs 和底層繪圖物件 StepPatch 為繪製階梯式常數函數提供更清晰的介面，對於您知道階梯邊緣的常見情況。這取代了 pyplot.step 的許多使用案例，例如在繪製 numpy.histogram 的輸出時。

對於藝術家和函數來說，x 軸類邊緣的輸入會比 y 軸類數值的輸入多一個元素。

(原始碼, 2x.png, png)

請參閱階梯圖範例。

為莖狀圖新增orientation參數#

預設情況下，莖狀線是垂直的。可以使用 Axes.stem 或 pyplot.stem 的 orientation 參數將其更改為水平。

(原始碼, 2x.png, png)

括號箭頭樣式上的角度#

現在會套用在 Bracket 箭頭樣式（傳遞給 FancyArrowPatch 的 arrowstyle 參數的 ]-[、]-、-[ 或 |-|）上指定的角度。先前，允許使用 angleA 和 angleB 選項，但沒有作用。

(原始碼, 2x.png, png)

TickedStroke 路徑效果#

新的 TickedStroke 路徑效果可用於產生帶有刻度樣式的線條。這可用於區分，例如，最佳化解空間中約束邊界的有效和無效側。

../../_images/sphx_glr_tickedstroke_demo_002.png

顏色和色圖#

集合顏色規格和映射#

重新設計顏色映射以及 facecolor 和 edgecolor 的關鍵字引數的處理方式，導致了三個行為變更：

  1. 可以呼叫 Collection.set_array(None) 來關閉顏色映射。先前，這會沒有效果。

  2. 當設定可映射的陣列時，使用 facecolor='none' 和 edgecolor='face'，則面和邊緣都會保持無色。先前，邊緣會進行顏色映射。

  3. 當設定可映射的陣列時，使用 facecolor='none' 和 edgecolor='red'，則邊緣會是紅色。這解決了 Issue #1302。先前，邊緣會進行顏色映射。

透明度（alpha）可以在集合中設定為陣列#

先前，控制集合中透明度的 alpha 值只能指定為套用至集合中所有元素的純量。例如，scatter 圖中的所有標記，或 pcolormesh 圖中的所有四邊形，都會具有相同的 alpha 值。

現在可以將 alpha 提供為一個陣列，其中包含集合中每個元素（標記、四邊形等）的一個值。

(原始碼, 2x.png, png)

pcolormesh 透過啟用對齊功能改善了透明度處理#

由於對齊關鍵字引數傳遞至 Agg 後端的方式，先前版本的 Matplotlib 在具有透明度的網格邊緣之間似乎會顯示線條。此版本現在預設會套用對齊功能。若要還原舊的行為（例如，用於測試影像），您可以將 rcParams["pcolormesh.snap"] (預設值：True) 設定為 False。

(原始碼, 2x.png, png)

請注意，主要繪圖的網格邊界之間存在一些透明度不同的線條。當將透明度新增至色圖時，色條也會顯示這些線條，因為它在內部使用 pcolormesh 來繪製色條。在預設開啟對齊功能的情況下（如下所示），網格邊界的線條會消失。

(原始碼, 2x.png, png)

Colormap 物件的 IPython 表示法#

matplotlib.colors.Colormap 物件現在具有 IPython / Jupyter 後端的影像表示法。在最後一行傳回色圖的儲存格將顯示色圖的影像。

In[1]: cmap = plt.get_cmap('viridis').with_extremes(bad='r', under='g', over='b')

In[2]: cmap
Out[2]:
viridis
viridis colormap
under
bad
over

Colormap.set_extremes 和 Colormap.with_extremes#

由於 Colormap.set_bad、Colormap.set_under 和 Colormap.set_over 方法會就地修改色圖，因此使用者必須小心，如果設定極端顏色（例如，用於內建色圖），則必須先製作色圖的複本。

新的 Colormap.with_extremes(bad=..., under=..., over=...) 可用於先複製色圖，然後在該複本上設定極端顏色。

為了與 Colormap.with_extremes 達到 API 對稱性，提供了新的 Colormap.set_extremes 方法，但請注意，它與先前的個別設定器存在相同的問題。

取得 Colormap 物件的下/上/壞顏色#

matplotlib.colors.Colormap 現在具有方法 get_under、get_over、get_bad，用於超出範圍和遮罩值的顏色。

新的 cm.unregister_cmap 函數#

matplotlib.cm.unregister_cmap 允許使用者移除他們先前已註冊的色圖。

新的 CenteredNorm，用於中心周圍的對稱資料#

在資料呈現以中心點對稱的情況下，例如以零為中心的正負異常值，CenteredNorm 是一種新的正規化方式，會自動建立以中心點為對稱的映射。這種正規化方式非常適合搭配中心使用非飽和色彩的發散式色圖。

(原始碼, 2x.png, png)

如果對稱中心不是 0，可以使用 vcenter 參數設定。若要手動設定 CenteredNorm 的範圍，請使用 halfrange 參數。

請參閱 色圖正規化 以取得範例和更多關於資料正規化的詳細資訊。

新的 FuncNorm 用於任意正規化#

FuncNorm 允許使用正向和反向函數進行任意正規化。

(原始碼, 2x.png, png)

請參閱 色圖正規化 以取得範例和更多關於資料正規化的詳細資訊。

基於 GridSpec 的顏色條現在可以放置在主要軸的上方或左側#

... 透過將 location="top" 或 location="left" 傳遞給 colorbar() 呼叫。

標題、刻度與標籤#

supxlabel 和 supylabel#

可以使用新的 Figure.supxlabel 和 Figure.supylabel 方法，為整個圖形新增 x 軸和 y 軸標籤，類似於 Figure.suptitle。

(原始碼, 2x.png, png)

共用軸的 subplots 刻度標籤可見度現在對於頂部或左側標籤是正確的#

當呼叫 subplots(..., sharex=True, sharey=True) 時，Matplotlib 會自動隱藏不在第一欄的軸的 x 刻度標籤，以及不在最後一列的軸的 y 刻度標籤。如果 rcParams 指定軸應該在頂部（rcParams["xtick.labeltop"] = True）或在右側（rcParams["ytick.labelright"] = True）標示，則此行為不正確。

現在可以正確處理以下情況（根據需要在軸的第一列和最後一列調整可見度）

plt.rcParams["xtick.labelbottom"] = False
plt.rcParams["xtick.labeltop"] = True
plt.rcParams["ytick.labelleft"] = False
plt.rcParams["ytick.labelright"] = True

fig, axs = plt.subplots(2, 2, sharex=True, sharey=True)

(原始碼, 2x.png, png)

帶有標籤的可迭代物件可以傳遞給Axes.plot#

當透過將 2D 資料作為 y 值傳遞給 plot 來繪製多個資料集時，可以將資料集的標籤作為列表傳遞，其長度與 y 中的列數相符。

x = [1, 2, 3]

y = [[1, 2],
     [2, 5],
     [4, 9]]

plt.plot(x, y, label=['low', 'high'])
plt.legend()

(原始碼, 2x.png, png)

字體與文字#

文字轉換可以旋轉文字方向#

新的 Text 參數 transform_rotates_text 現在設定轉換的旋轉是否會影響文字方向。

../../_images/sphx_glr_text_rotation_relative_to_line_001.png

新 transform_rotates_text 參數的範例#

matplotlib.mathtext 現在支援 overset 和 underset LaTeX 符號#

mathtext 現在支援 overset 和 underset，分別以 \overset{annotation}{body} 或 \underset{annotation}{body} 呼叫，其中 annotation 是 body 「上方」或「下方」的文字。

(原始碼, 2x.png, png)

math_fontfamily 參數用於變更 Text 字體系列#

新的 math_fontfamily 參數可以用來變更繪圖中每個個別文字元素的字體系列。如果沒有設定參數，則會使用全域值 rcParams["mathtext.fontset"] (預設值：'dejavusans')。

../../_images/sphx_glr_mathtext_fontfamily_example_001.png

TextArea/AnchoredText 支援 horizontalalignment#

現在可以指定 TextArea 或 AnchoredText 中文字的水平對齊方式，這對於多行文字最為有效。

(原始碼, 2x.png, png)

PDF 支援 Text 繪圖上的 URL#

現在 URL 會儲存在 PDF 檔案中，這些 URL 位於 text.Text 繪圖上（即來自 Artist.set_url）。

rcParams 的改進#

日期的新 rcParams：設定轉換器以及是否使用 interval_multiples#

新的 rcParams["date.converter"] (預設值：'auto') 允許使用字串 'auto' 和 'concise' 分別在 matplotlib.dates.DateConverter 和 matplotlib.dates.ConciseDateConverter 之間切換。

新的 rcParams["date.interval_multiples"] (預設值：True) 允許在日期定位器嘗試選取設定間隔的刻度（例如，每月 1 號和 15 號），與從時間序列開始的任何位置開始的均勻間隔刻度之間切換。

dates = np.arange('2001-01-10', '2001-05-23', dtype='datetime64[D]')
y = np.sin(dates.astype(float) / 10)
fig, axs = plt.subplots(nrows=2, constrained_layout=True)

plt.rcParams['date.converter'] = 'concise'
plt.rcParams['date.interval_multiples'] = True
axs[0].plot(dates, y)

plt.rcParams['date.converter'] = 'auto'
plt.rcParams['date.interval_multiples'] = False
axs[1].plot(dates, y)

(原始碼、2x.png、png)

日期格式化程式現在會遵循 usetex rcParam#

AutoDateFormatter 和 ConciseDateFormatter 現在會遵循 rcParams["text.usetex"] (預設值：False)，因此將使用與預設（非日期）格式化程式的 TeX 渲染一致的字體。也可以在建立格式化程式實例時傳遞 usetex 參數來啟用/停用 TeX 渲染。

在以下繪圖中，x 軸（日期）和 y 軸（數字）現在都使用相同的 (TeX) 字體

(原始碼、2x.png、png)

將 image.cmap 設定為 Colormap#

現在可以將 rcParams["image.cmap"] (預設值：'viridis') 設定為 Colormap 實例，例如使用新的 set_extremes 建立的色彩映射表。（這只能從 Python 程式碼完成，而不能從 matplotlibrc 檔案完成。）

刻度和刻度標籤顏色可以使用 rcParams 獨立設定#

先前，rcParams["xtick.color"] (預設值：'black') 定義了刻度顏色和標籤顏色。現在可以使用 rcParams["xtick.labelcolor"] (預設值：'inherit') 獨立設定標籤顏色。它預設為 'inherit'，這將從 rcParams["xtick.color"] (預設值：'black') 取得值。ytick.[label]color 的情況也是如此。例如，要將刻度設定為淺灰色，刻度標籤設定為黑色，可以在腳本中使用以下程式碼

import matplotlib as mpl

mpl.rcParams['xtick.labelcolor'] = 'lightgrey'
mpl.rcParams['xtick.color'] = 'black'
mpl.rcParams['ytick.labelcolor'] = 'lightgrey'
mpl.rcParams['ytick.color'] = 'black'

或將以下程式碼行加入 matplotlibrc 檔案或 Matplotlib 樣式檔案

xtick.labelcolor : lightgrey
xtick.color      : black
ytick.labelcolor : lightgrey
ytick.color      : black

3D 軸的改進#

3D 軸中的 Errorbar 方法#

errorbar 函數 Axes.errorbar 完整移植到 3D 軸框架中，支援錯誤線和帽標記的自訂樣式、錯誤列間距的控制、上限和下限標記等功能。

../../_images/sphx_glr_errorbar3d_001.png

3D 軸中的莖圖#

3D 軸現在支援莖圖。與 2D 莖圖非常相似，stem 支援以各種方向繪製莖圖

(原始碼、2x.png、png)

另請參閱 3D 莖圖 示範。

3D 集合屬性現在可修改#

先前，用於 3D 效果的 3D 集合屬性（例如，修改顏色以產生深度陰影）在建立後無法變更。

現在可以隨時修改 3D 集合的所有屬性。

在 3D 軸中平移#

按住滑鼠中鍵並拖曳即可平移 3D 軸。

互動式工具的改進#

新的 RangeSlider 小工具#

widgets.RangeSlider 允許建立定義範圍而非單一值的滑桿。

(原始碼、2x.png、png)

滑桿現在可以對齊任意值#

Slider UI 小工具現在接受 valstep 的陣列。這透過允許滑桿對齊任意值來概括了先前的行為。

暫停和恢復動畫#

animation.Animation.pause 和 animation.Animation.resume 方法允許您暫停和恢復動畫。這些方法可以用作 UI 元素上事件監聽器的回呼，以便您的繪圖可以具有一些播放控制 UI。

Sphinx 擴充功能#

plot_directive caption 選項#

先前在使用 plot_directive 指令搭配外部來源檔案時，可以透過指定內容來支援圖說。

.. plot:: path/to/plot.py

    This is the caption for the plot.

:caption: 選項允許為外部

.. plot:: path/to/plot.py
    :caption: This is the caption for the plot.

和內嵌的圖表指定圖說。

.. plot::
    :caption: This is a caption for the plot.

    plt.plot([1, 2, 3])

後端特定改進#

連續的點陣化繪圖現在會合併#

向量輸出的元素可以使用 *rasterized* 關鍵字引數，或 set_rasterized()，單獨設定為點陣化。這對於減少檔案大小很有用。對於具有多個點陣元素的圖形，它們現在會自動合併為較少數量的點陣圖，而不會影響視覺輸出。對於具有許多元素的情況，這可以顯著縮減檔案大小。

為了確保這種情況發生，請勿在點陣元素之間放置向量元素。

若要禁止此合併，請將 Figure.suppressComposite 設定為 True。

在 FFMpegFileWriter 中支援 raw/rgba 幀格式#

當使用 FFMpegFileWriter 時，*frame_format* 現在可以設定為 "raw" 或 "rgba"，這可能會比影像格式快一點，因為在 Matplotlib 和 FFmpeg 之間不需要進行編碼/解碼。

nbAgg/WebAgg 支援中鍵點擊和雙擊#

nbAgg 和 WebAgg 後端現在支援雙擊事件。先前，WebAgg 會將中鍵點擊事件回報為右鍵點擊，但現在會回報正確的按鈕類型。

nbAgg 支援二進制通訊#

如果網頁瀏覽器和筆記本支援二進制 WebSocket，nbAgg 現在將使用它們來稍微改善圖形顯示的傳輸。

盡可能在 PDF 檔案中使用 PNG 影像的索引顏色#

當 PNG 影像具有 256 種或更少的顏色時，它們會在儲存到 PDF 之前轉換為索引顏色。在某些情況下，這可以顯著減少檔案大小。對於使用色彩映射但沒有插值的點陣資料（例如 Healpy mollview 圖表）尤其如此。目前，這僅針對 RGB 影像執行。

改進 PDF/PS 中的字型子集#

PDF 和 PostScript 中的字型子集已從嵌入的 ttconv C 程式碼重寫為 Python。一些複合字元和輪廓可能略有改變。這修正了 PDF 中的 ttc 子集，並增加了對類型 3 OTF 字型子集的支援，從而產生更小的檔案（使用 CJK 字型時檔案會小得多），並避免遇到類型 42 嵌入和某些 PDF 閱讀器（例如 Acrobat Reader）的問題。

在 PDF 中為字串新增字距調整#

與 Agg 後端中產生的文字一樣（請參閱 先前的新增功能項目 中的範例），PDF 現在在文字字串中包含字距調整。

QtAgg 中的完全分數 HiDPI#

Qt 5.14 中新增了完全分數 HiDPI（也就是說，HiDPI 比率不是整數），現在在使用此版本的 Qt 或更新版本時，QtAgg 後端支援此功能。

wxAgg 支援全螢幕切換#

wxAgg 後端支援使用 f 快捷鍵或管理員函式 FigureManagerBase.full_screen_toggle 切換全螢幕。

在本頁