Figure.colorbar(), pyplot.colorbar() – matplotlibドキュメント日本語訳

matplotlib /

matplotlib.figure.Figure.colorbar()メソッドのドキュメント日本語訳です。pyplotスタイルで対応する関数はmatplotlib.pyplot.colorbar()です。引数や返り値を調べる際に参考にしてください。

元の英文ドキュメントはmatplotlib 公式ドキュメント v3.3.3 です。これに、補足説明を適宜追加しています。

次のページも参考にしてみてください。

matplotlib.figure.Figure.colorbar または matplotlib.pyplot.colorbar

colorbar − カラーバーを作成します。

次の画像で、右端のバーが「カラーバー」です。

説明

colorbar(**kwargs)
colorbar(mappable, **kwargs)
colorbar(mappable, cax=cax, **kwargs)
colorbar(mappable, ax=ax, **kwargs)

ScalarMappableのインスタンス(mappable)に対して、カラーバーを作成します。

1つ目の書き方colorbar(**kwargs)は、pyplotスタイル(pyplot.colorbar())でのみ使えます。他の3つの書き方は、pyplotスタイルでも、オブジェクト指向スタイル(figure.Figure.colorbar())でも使えます。

パラメータ

mappable

カラーバーを描くmatplotlib.cm.ScalarMappable（例えば、AxesImage、 ContourSet、など）を指定します。この引数は、Figure.colorbar()メソッドでは指定が必須です。pyplot.colorbar関数ではオプションであり、現在の図(current image)がデフォルト値になります。

次のように即席のScalarMappableを使用することで、既存の描画部品(artist、アーティスト)にアタッチしていないカラーバーを作成することもできます。

fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax)

cax: Axes、オプション

カラーバーが描画されるaxesを指定します。(cax: child axesの略)

ax: Axes, list of Axes、オプション

親のaxesを指定します。指定されたaxesから、カラーバーのaxes用に領域が切り取られます。axesのリストが指定された場合、カラーバーのaxes用の領域を確保するためにすべてのAxesがリサイズされます。

use_gridspec: bool、オプション

caxがNoneの場合、Axesのインスタンスが新たに生成されcaxに指定されます。axがSubplotのインスタンスでuse_gridspecがTrueの場合は、gridspecモジュールを使用して、Subplotのインスタンスが生成されcaxに指定されます。

戻り値

colorbar: Colorbar

基本クラスのColorbarBaseも参照してください。

備考

キーワード引数(**kwargs)として、次の2種類が指定できます。

axesのプロパティ

プロパティ 型 default 説明
fraction float 0.15 カラーバー用に切り出す領域のサイズ。親のaxesの割合で指定する。
shrink float 1.0 カラーバーのサイズ(倍数)。caxが与えられた場合は無視される。
aspect float 20 アスペクト比。長い寸法の短い寸法に対する比率。caxが与えられた場合は無視される。
pad float 垂直の場合は0.05、水平の場合は0.15 カラーバーと図の隙間。親のaxesの割合で指定する。
anchor (float, float) 垂直の場合は(0.0, 0.5)、水平の場合は(0.5, 1.0) カラーバーのaxesのアンカーポイント。
panchor (float, float) or False 垂直の場合は(1.0, 0.5)、水平の場合は(0.5, 0.0) 親のaxesのアンカーポイント。Falseの場合は、親のAxesのアンカーは変更されません。

colorbarのプロパティ

プロパティ 値 説明
extend {‘neither’, ‘both’, ‘min’, ‘max’} 延長。’neither’でない場合は、範囲外の値に対して尖った端を作成します。これらは、set_underメソッドとset_overメソッドを使用してカラーマップに設定されます。’both’の例:
extendfrac {None, ‘auto’, length, lengths} 延長割合。Noneに設定すると、最小と最大の両方の三角形のカラーバー延長部が、カラーバー本体の5％の長さになります（これがデフォルト設定です）。’auto’に設定すると、spacingが’uniform’に設定されているときは、三角形のカラーバー延長部が内側の箱と同じ長さになります。spacingが’proportional’に設定されているときは、それぞれの隣接する内側の箱と同じ長さになります。数値(length)に設定すると、最小と最大の両方の三角形のカラーバー延長部の長さが、カラーバー本体の長さにこの数値をかけたものになります。2要素の数値のシーケンス(lengths、リスト/タプル)に設定すると、最小および最大のカラーバー延長部の長さが、カラーバー本体の長さにそれぞれの数値をかけたものになります。
extendrect bool 矩形延長。Falseの場合、カラーバーの最小および最大の延長部は三角形になります（デフォルト）。Trueの場合、拡張部分は長方形になります。
spacing {‘uniform’, ‘proportional’} ‘uniform’が指定されると、各離散色に同じスペースを与えます。’proportional’が指定されると、データ間隔と比例するようにスペースが与えられます。
ticks None or list of ticks or Locator 目盛り。Noneの場合、目盛りは入力から自動的に決定されます。
format None or str or Formatter Noneの場合、ScalarFormatterが使用されます。’％.3f’などのフォーマット文字列が指定されている場合は、それが使用されます。代わりにFormatterを指定することもできます。
drawedges bool 色の境界に線を引くかどうか。Trueの例:
label str カラーバーの長軸上のラベル。

以下のプロパティは、カラーがインデックスされているとき（mappableにnorm=NoNorm()があるとき）か、なにか普通ではない状況のときだけ役立つでしょう。

プロパティ 値 説明
boundaries None or sequence 境界値。
values None or sequence 指定するシーケンスは、boundariesに指定したシーケンスの長さよりも1だけ短くなくてはいけません。boundariesの隣り合う値で区切られた各領域について、対応するvaluesの色が使用されます。

(訳注: ここに記述されている以外にも使用できるキーワード引数(**kwargs)があります。引数は、内部で基本クラスColorbarBaseのコンストラクタに渡されますので、コンストラクタが受け取るパラメータが使えます。ColorbarBaseのドキュメントを参照してください。)

mappableがContourSetである場合、そのextendパラメータは自動的に含まれます。

shrinkパラメータは、axesに対してカラーバーのサイズを変更する簡単な方法です。caxがが指定された場合、caxがカラーバーのサイズを規定するので、shrinkやaspectパラメータは無視されることに注意してください。

より精密に調整するために、mappableインスタンスやカラーバーが描画されるaxesオブジェクトの位置を手動で指定できます。この場合、axesのプロパティを一切使用しないでください。

一部のベクター グラフィックス ビューア（svgおよびpdf）は、カラーバーのセグメント間に白い隙間を描画することが知られています。これは、Matplotlibではなく、ビューアのバグが原因です。回避策として、カラーバーはセグメントを重ねて描画できます。

cbar = colorbar()
cbar.solids.set_edgecolor("face")
draw()

ただし、これは他の状況では悪影響を及ぼします。たとえば、半透明の画像（alpha < 1）やカラーバー延長などでです。したがって、この回避策はデフォルトでは使用されません（issue#1188を参照）。

まとめ

matplotlib.figure.Figure.colorbar()あるいは、matplotlib.pyplot.colorbar()のドキュメントの日本語訳を紹介しました。モジュール本体はmatplotlib.colorbarで、これらのメソッドあるいは関数はラッパーとして使われます。

公式ドキュメントは十分に整備されておらず、意味がわかりにくいところが多いですが、そのような部分はソースコードをあわせて読むと良いでしょう。

 

次のページも参考にしてみてくださいね。

 

以上、Figure.colorbar(), pyplot.colorbar() – matplotlibドキュメント日本語訳でした。

参考

こんな記事も読まれています