Matplotlib 3.3.0 (2020 年 7 月 16 日) 的新功能 #

如需自上次修訂以來的全部問題和提取請求清單，請參閱 3.10.0 (2024 年 12 月 13 日) 的 GitHub 統計資訊。

圖表和軸建立/管理 #

從文字或巢狀清單組成語意軸佈局的臨時 API #

Figure 類別有一個臨時方法，可以根據巢狀清單輸入或 ASCII art，產生具名 axes.Axes 的複雜格線

axd = plt.figure(constrained_layout=True).subplot_mosaic(
    [['.', 'histx'],
     ['histy', 'scat']]
)
for k, ax in axd.items():
    ax.text(0.5, 0.5, k,
            ha='center', va='center', fontsize=36,
            color='darkgrey')

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

或以字串形式 (使用單一字元的 Axes 標籤)

axd = plt.figure(constrained_layout=True).subplot_mosaic(
    """
    TTE
    L.E
    """)
for k, ax in axd.items():
    ax.text(0.5, 0.5, k,
            ha='center', va='center', fontsize=36,
            color='darkgrey')

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

請參閱複雜且語意化的圖形組合 (subplot_mosaic) 以了解更多詳細資訊和範例。

`GridSpec.subplots()`#

GridSpec 類別新增了 subplots 方法，因此可以使用以下方式撰寫：

fig.add_gridspec(2, 2, height_ratios=[3, 1]).subplots()

作為以下方式的替代方案：

fig.subplots(2, 2, gridspec_kw={"height_ratios": [3, 1]})

新的 `Axes.sharex`、`Axes.sharey` 方法 #

這些新方法允許在建立軸 之後立即 共享軸。請注意，如果在建立軸之後未立即共享，則行為是不確定的。

例如，它們可用於選擇性地連結使用 subplot_mosaic 一起建立的一些軸：

fig = plt.figure(constrained_layout=True)
axd = fig.subplot_mosaic([['.', 'histx'], ['histy', 'scat']],
                         gridspec_kw={'width_ratios': [1, 7],
                                      'height_ratios': [2, 7]})

axd['histx'].sharex(axd['scat'])
axd['histy'].sharey(axd['scat'])

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

tight_layout 現在支援 suptitle #

先前的版本不考慮 Figure.suptitle，因此在呼叫 tight_layout 後，它可能會與其他藝術家重疊。

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

從現在開始，將會考慮 suptitle

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

設定軸的方塊外觀比例 #

現在可以透過 set_box_aspect 直接設定軸方塊的外觀比例。方塊外觀比例是軸高度與軸寬度之間的比例，以物理單位表示，與資料限制無關。這對於產生一個正方形圖形非常有用，而與其包含的資料無關，或者使非影像圖形與具有固定 (資料) 外觀比例的影像圖形具有相同的軸尺寸。

如需使用案例，請查看軸方塊外觀比例範例。

色彩和色彩對應 #

Turbo 色彩對應 #

Turbo 是一種改進的彩虹色彩對應，用於視覺化，由 Google AI 團隊為電腦視覺和機器學習創建。其目的是顯示深度和視差資料。請參閱 Google AI 網誌以取得更多詳細資訊。

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

`colors.BoundaryNorm` 支援 extend 關鍵字引數 #

BoundaryNorm 現在具有 extend 關鍵字引數，類似於 contourf 中的 extend。當設定為 'both'、'min' 或 'max' 時，它會將對應的超出範圍的值對應到 Colormap 查找表索引，這些索引在其範圍的適當末端附近，因此超出範圍的值的顏色與其範圍內的相鄰顏色相鄰但又不同。色彩條繼承了來自範數的 extend 引數，因此舉例來說，使用 extend='both'，色彩條將具有超出範圍值的三角形擴展，其顏色與相鄰的範圍內顏色不同。

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

圖例標籤的文字顏色 #

現在可以透過將參數 labelcolor 傳遞給 legend 來設定圖例標籤的文字顏色。labelcolor 關鍵字可以是

單一顏色 (字串或 RGBA 元組)，它會調整所有標籤的文字顏色。
清單或元組，允許個別設定每個標籤的文字顏色。
linecolor，它將每個標籤的文字顏色設定為與對應的線條顏色相符。
markerfacecolor，它將每個標籤的文字顏色設定為與對應的標記面顏色相符。
markeredgecolor，它將每個標籤的文字顏色設定為與對應的標記邊緣顏色相符。

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

Pcolor 和 Pcolormesh 現在接受 `shading='nearest'` 和 `'auto'`#

先前，axes.Axes.pcolor 和 axes.Axes.pcolormesh 在處理 x 和 y 與 C 具有相同（各自）尺寸的情況時，會捨棄 C 的最後一行和最後一列，並將 x 和 y 視為 C 中剩餘的行和列的邊界。然而，許多使用者希望 x 和 y 置於 C 的行和列的中心。

為了滿足這個需求，shading='nearest' 和 shading='auto' 是 shading 關鍵字參數中允許的新字串。'nearest' 將在 x 和 y 與 C 具有相同維度時，將顏色置於 x 和 y 的中心（否則會拋出錯誤）。shading='auto' 將根據 X、Y、C 的尺寸選擇 'flat' 或 'nearest'。

如果 shading='flat'，則 X 和 Y 的維度應比 C 大 1。如果 X 和 Y 與 C 具有相同的維度，則會使用先前的行為，並且會捨棄 C 的最後一行和最後一列，並發出 DeprecationWarning。

使用者也可以在他們的 .matplotlibrc 中，透過新的 rcParams["pcolor.shading"] （預設值：'auto'）或透過 rcParams 來指定此設定。

有關範例，請參閱 pcolormesh。

標題、刻度和標籤 #

將標籤對齊到軸邊緣 #

set_xlabel、set_ylabel 和 ColorbarBase.set_label 支援一個參數 loc 以簡化定位。對於 xlabel，支援的值為 'left'、'center' 或 'right'。對於 ylabel，支援的值為 'bottom'、'center' 或 'top'。

預設值透過 rcParams["xaxis.labellocation"] （預設值：'center'）和 rcParams["yaxis.labellocation"] （預設值：'center'）控制；Colorbar 標籤會根據其方向採用 rcParam。

（原始碼）

（2x.png、png）

（2x.png、png）

允許使用字串或函數輸入設定刻度格式器 #

set_major_formatter 和 set_minor_formatter 現在除了 Formatter 實例之外，還接受 str 或函數輸入。對於 str，會自動產生並使用 StrMethodFormatter。對於函數，會自動產生並使用 FuncFormatter。換句話說，

ax.xaxis.set_major_formatter('{x} km')
ax.xaxis.set_minor_formatter(lambda x, pos: str(x-5))

是以下的快捷方式

import matplotlib.ticker as mticker

ax.xaxis.set_major_formatter(mticker.StrMethodFormatter('{x} km'))
ax.xaxis.set_minor_formatter(
    mticker.FuncFormatter(lambda x, pos: str(x-5))

（原始碼、2x.png、png）

`Axes.set_title` 新增 y 關鍵字參數以控制自動定位 #

set_title 嘗試自動定位標題，以避免頂部 x 軸上的任何裝飾。這並不總是理想的，因此現在 y 是 set_title 的明確關鍵字參數。它預設為 None，表示使用自動定位。如果提供了一個值（例如，3.0 之前的預設值為 y=1.0），則會關閉自動定位。這也可以透過新的 rcParameter rcParams["axes.titley"] （預設值：None）設定。

（原始碼、2x.png、png）

使用 `axis.tick_top()` 時，偏移文字現在設定到頂部 #

解決了即使刻度在頂部，冪指標（例如 1e4）仍停留在底部的問題。

設定等高線標籤的 zorder #

clabel 現在接受一個 zorder 關鍵字參數，使其更容易設定等高線標籤的 zorder。如果未指定，clabel 的預設 zorder 過去總是 3（即 Text 的預設 zorder），而與傳遞給 contour/contourf 的 zorder 無關。clabel 的新預設 zorder 已變更為（2 + zorder 傳遞給 contour / contourf）。

其他變更 #

新的 `Axes.axline` 方法 #

新增了一個新的 axline 方法，用於繪製穿過兩點的無限長直線。

fig, ax = plt.subplots()

ax.axline((.1, .1), slope=5, color='C0', label='by slope')
ax.axline((.1, .2), (.8, .7), color='C3', label='by points')

ax.legend()

（原始碼、2x.png、png）

`imshow` 現在會將深度為 1 的 3D 陣列強制轉換為 2D #

從這個版本開始，大小為 MxNx1 的陣列將會被強制轉換為 MxN 以進行顯示。這表示諸如 plt.imshow(np.random.rand(3, 3, 1)) 之類的命令將不再返回圖像形狀無效的錯誤訊息。

更好地控制 `Axes.pie` 正規化 #

先前，如果 sum(x) > 1，Axes.pie 會將輸入值 x 正規化，但如果總和小於 1，則不會執行任何操作。這可能會造成混淆，因此新增了一個明確的關鍵字參數 normalize。預設情況下，會保留舊的行為。

透過傳遞 normalize，可以明確控制是否進行任何重新縮放，或是否應建立部分圓餅圖。如果停用正規化，且 sum(x) > 1，則會引發錯誤。

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

日期使用現代紀元 #

Matplotlib 使用 dates.date2num (透過 matplotlib.units) 將日期轉換為自紀元以來的日數。先前，使用 0000-12-31T00:00:00 的紀元，因此 0001-01-01 會轉換為 1.0。如此遙遠的過去的紀元表示現代日期無法保留微秒，因為 2000 年乘以 64 位元浮點數的 2^(-52) 解析度得出 14 微秒。

在此，我們將預設紀元變更為更合理的 UNIX 預設值 1970-01-01T00:00:00，對於現代日期，其解析度為 0.35 微秒。（無法實現更高的解析度，因為我們依賴 datetime.datetime 作為日期定位器）。可透過 get_epoch 取得紀元，且有一個新的 rcParams["date.epoch"] (預設值: '1970-01-01T00:00:00') rcParam。使用者也可以呼叫 set_epoch，但必須在任何日期轉換或繪圖使用之前設定。

如果您的資料以舊紀元的序數浮點數儲存，您可以使用下列公式將它們轉換為新的序數

new_ordinal = old_ordinal + mdates.date2num(np.datetime64('0000-12-31'))

線條現在接受 `MarkerStyle` 實例作為輸入 #

與 scatter 類似，plot 和 Line2D 現在接受 MarkerStyle 實例作為 marker 參數的輸入

plt.plot(..., marker=matplotlib.markers.MarkerStyle("D"))

字型 #

透過絕對路徑選取字型的簡單語法 #

現在可以透過將絕對 pathlib.Path 傳遞至 Text 的 font 關鍵字引數來選取字型。

改良的字型粗細偵測 #

Matplotlib 現在能夠更好地從字型的中繼資料判斷字型的粗細，從而可以更準確地區分同一系列中的字型。

rcParams 改良 #

`matplotlib.rc_context` 可以用作裝飾器 #

matplotlib.rc_context 現在可以用作裝飾器（從技術上講，它現在作為 contextlib.contextmanager 實作），例如，

@rc_context({"lines.linewidth": 2})
def some_function(...):
    ...

用於控制預設「提高視窗」行為的 rcParams #

新的組態選項 rcParams["figure.raise_window"] (預設值: True) 允許在呼叫 show 或 pause 時停用提高繪圖視窗的功能。目前不支援 MacOSX 後端。

將廣義的 `mathtext.fallback` 新增至 rcParams #

新的 rcParams["mathtext.fallback"] (預設值: 'cm') rcParam。接受 "cm"、"stix"、"stixsans" 或 "none" 以關閉回退。rcParam mathtext.fallback_to_cm 已被棄用，但如果使用，將會覆寫新的回退。

將 `contour.linewidth` 新增至 rcParams #

新的組態選項 rcParams["contour.linewidth"] (預設值: None) 允許以浮點數控制等高線的預設線條寬度。當設定為 None 時，線條寬度會回復為 rcParams["lines.linewidth"] (預設值: 1.5)。當 linewidths 引數傳遞至 contour 且未設定為 None 時，組態值會如常被覆寫。

3D 軸改良 #

`Axes3D` 不再扭曲 3D 繪圖以符合 2D 長寬比 #

先前使用 Axes3D 製作的繪圖會被拉伸以符合正方形邊界框。由於此拉伸是在從 3D 到 2D 的投影之後完成的，因此如果使用非正方形邊界框，則會導致影像失真。從 3.3 版開始，不再發生這種情況。

目前，Axes3D 不支援在資料空間中設定長寬比的模式（透過 set_aspect），但未來可能會支援。如果您想模擬在資料空間中具有相等的長寬比，請將資料限制的比率設定為符合 get_box_aspect 的值。若要控制這些比率，請使用 set_box_aspect 方法，該方法接受比率作為 X:Y:Z 的 3 元組。預設長寬比為 4:4:3。

3D 軸現在支援次要刻度 #

ax = plt.figure().add_subplot(projection='3d')

ax.scatter([0, 1, 2], [1, 3, 5], [30, 50, 70])

ax.set_xticks([0.25, 0.75, 1.25, 1.75], minor=True)
ax.set_xticklabels(['a', 'b', 'c', 'd'], minor=True)

ax.set_yticks([1.5, 2.5, 3.5, 4.5], minor=True)
ax.set_yticklabels(['A', 'B', 'C', 'D'], minor=True)

ax.set_zticks([35, 45, 55, 65], minor=True)
ax.set_zticklabels([r'$\alpha$', r'$\beta$', r'$\delta$', r'$\gamma$'],
                   minor=True)

ax.tick_params(which='major', color='C0', labelcolor='C0', width=5)
ax.tick_params(which='minor', color='C1', labelcolor='C1', width=3)

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

Home/Forward/Backward 按鈕現在可與 3D 軸一起使用 #

互動工具改進 #

游標文字現在使用與指向精度匹配的有效位數 #

先前，游標文字顯示的 x/y 位置通常會包含比滑鼠指向精度（通常是一個像素）多得多的有效位數。現在已針對線性比例尺修正此問題。

GTK/Qt 縮放矩形現在為黑白 #

這使其即使在深色背景上也能看見。

事件處理簡化 #

backend_bases.key_press_handler 和 backend_bases.button_press_handler 事件處理常式現在可以直接使用 canvas.mpl_connect("key_press_event", key_press_handler) 和 canvas.mpl_connect("button_press_event", button_press_handler) 連接到畫布，而不必編寫填入（現在是可選的）*canvas* 和 *toolbar* 參數的包裝函式。