tkplot.py ライブラリ技術ドキュメント
ライブラリの機能や目的
tkplot.py ライブラリは、Pythonの著名なグラフ描画ライブラリである matplotlib の機能を抽象化し、より扱いやすくすることを目的としています。特に、複数のサブプロットの管理、プロットデータの動的な更新、および基本的なグラフ描画操作を簡素化します。
このライブラリの主な機能は以下の通りです。
matplotlib.figure.Figureオブジェクトの生成と管理。複数のサブプロット（
matplotlib.axes.Axesオブジェクト）の追加、初期化、および管理。2次元ラインプロット、3次元ワイヤーフレームプロット、2次元等高線/塗りつぶし等高線プロットといった多様なグラフ描画機能。
既存のプロットデータの動的な更新機能。
グラフ表示の一時停止、表示、指定時間待機などの制御機能。
tkplot.py は、matplotlib を直接操作する際に発生する冗長なコード記述を削減し、特にGUIアプリケーションなどでの動的なデータ表示や、複数のグラフを効率的に管理する必要がある場面で、開発者の負担を軽減することを課題解決の目標としています。
importする方法
tkplot.py ライブラリは、Pythonプログラム内で以下のようにインポートできます。
tkPlot クラスを直接インポートする場合:
from tkplot import tkPlot
ライブラリ全体をインポートしてクラスを修飾子付きで利用する場合:
import tkplot
plotter = tkplot.tkPlot()
必要な非標準ライブラリとインストール方法
tkplot.py は、以下の非標準ライブラリに依存しています。これらのライブラリは、pip コマンドを使用してインストールできます。
matplotlib:
目的: グラフ描画機能の基盤を提供します。特に3Dプロットのためには
mpl_toolkits.mplot3dモジュールも利用します。インストール方法:
pip install matplotlib
tklib:
目的:
tkPlotクラスはtklib.tkobject.tkObjectを継承しており、その基本機能に依存します。インストール方法:
tklibは一般的なPythonパッケージリポジトリに存在しない可能性がありますが、もし存在する場合は以下のコマンドでインストールできます。pip install tklib
上記でインストールできない場合は、
tklibの提供元から直接入手するか、そのドキュメントを参照してインストールする必要があります。
importできる変数と関数
tkplot.py ライブラリからインポートできる主要な要素は tkPlot クラスです。
クラス: tkPlot
tkPlot クラスは、matplotlib の描画機能をカプセル化し、よりオブジェクト指向的に扱えるようにするクラスです。tklib.tkobject.tkObject を継承しています。
属性
tkPlot オブジェクトは以下の重要な属性を持ちます。
figure(matplotlib.figure.Figure): このオブジェクトが管理するmatplotlibのFigureオブジェクトです。すべてのサブプロットはこのFigure上に配置されます。axes(list of matplotlib.axes.Axes or None): 追加されたサブプロット（Axesオブジェクト）のリストです。各サブプロットはインデックスiaxesでアクセスされ、複数のサブプロットを管理するために使用されます。lines(list): 各Axesに追加された描画ラインオブジェクトのリストです。ただし、現在の実装では主に各Axesオブジェクトのlinelist属性が使われているため、tkPlotオブジェクトのlines属性は直接使用されていません。
メソッド
__init__(self, figsize = None, **kwargs)動作:
tkPlotオブジェクトを初期化します。新しいmatplotlib.figure.Figureオブジェクトを作成し、axesおよびlinesの内部リストを初期化します。親クラスであるtkObjectの初期化も行われます。引数:
figsize(tuple, optional): Figureの幅と高さを示すタプル(width, height)（インチ単位）。matplotlib.pyplot.figureに渡されます。デフォルトはNoneで、matplotlibのデフォルトサイズを使用します。**kwargs: 親クラスtkObjectの初期化メソッドに渡される追加のキーワード引数。
戻り値: なし
initialize(self, **kwargs)動作: 親クラス
tkObjectのinitializeメソッドを呼び出します。引数:
**kwargs:tkObject.initializeに渡されるキーワード引数。
戻り値: なし
__str__(self)動作: オブジェクトの文字列表現を返します。オブジェクトの
method属性が設定されている場合、「optimization object by [method]」という形式の文字列を返します。引数: なし
戻り値: (str) オブジェクトの文字列表現。
pause(self, duration = 0.001, **kwargs)動作:
matplotlib.pyplot.pauseを呼び出し、指定された時間だけプロットを一時停止し、GUIイベントを処理します。これは、動的なプロット更新時にフレームを描画し、GUIがフリーズするのを防ぐために非常に重要です。引数:
duration(float, optional): 一時停止する秒数。デフォルトは \(0.001\) 秒。**kwargs:plt.pauseに渡される追加のキーワード引数。
戻り値: なし
show(self, **kwargs)動作:
matplotlib.pyplot.showを呼び出し、現在のアクティブなFigureを表示します。このメソッドは通常、プログラムの最後に一度だけ呼び出され、すべてのウィンドウを開いたままにします。引数:
**kwargs:plt.showに渡される追加のキーワード引数。
戻り値: なし
sleep(self, duration)動作:
time.sleepを呼び出し、指定された時間だけプログラムの実行を中断します。引数:
duration(float): スリープする秒数。
戻り値: なし
adjust_list(self, n)動作:
self.axesリストのサイズが少なくともn+1になるように調整します。もし現在のリストの長さがn+1より小さい場合、差分の要素をNoneで埋めます。これは、指定されたインデックスnのサブプロットを確実に格納できるようにするために使用されます。引数:
n(int):self.axesリストに格納したいサブプロットの最大インデックス。
戻り値: なし
add_subplot(self, nrows = 1, ncols = 1, index = 0, **kwargs)動作:
matplotlib.figure.Figure.add_subplotを呼び出して新しいサブプロット（Axesオブジェクト）をFigureに追加します。このメソッドは、matplotlib.pyplot.subplotの動作を継承していますが、indexパラメータは \(0\) からカウントされる点が異なります（matplotlibのオリジナルは \(1\) から始まります）。追加されたAxesオブジェクトには、後続のプロットデータを管理するためのlinelist,xlist,ylist,zlistというカスタム属性が初期化されます。引数:
nrows(int, optional): グリッドの行数。デフォルトは \(1\)。ncols(int, optional): グリッドの列数。デフォルトは \(1\)。index(int, optional): グリッド内のサブプロットのインデックス（\(0\) から開始）。例えば、\(0\) は最初のサブプロット、 \(1\) は2番目のサブプロットです。デフォルトは \(0\)。**kwargs:Figure.add_subplotに渡される追加のキーワード引数。
戻り値: (matplotlib.axes.Axes) 追加されたAxesオブジェクト。
plot(self, iaxes = 0, xd = None, yd = None, color = 'blue', linestyle = '', linewidth = 0.5, fillstyle = 'full', marker = '', markersize = 5, **kwargs)動作: 指定されたAxesオブジェクトに2次元のラインプロットを描画します。描画されたラインオブジェクトは、対応するAxesの
linelistに追加され、データ (xd,yd, 空のzlist) も保存されます。引数:
iaxes(int, optional): プロットを描画するAxesのインデックス。デフォルトは \(0\)。xd(array-like, optional): X軸のデータ。matplotlib.axes.Axes.plotに渡されます。デフォルトはNone。yd(array-like, optional): Y軸のデータ。matplotlib.axes.Axes.plotに渡されます。デフォルトはNone。color(str, optional): ラインの色。デフォルトは'blue'。linestyle(str, optional): ラインのスタイル。デフォルトは''（実線）。linewidth(float, optional): ラインの幅。デフォルトは \(0.5\)。fillstyle(str, optional): マーカーの塗りつぶしスタイル。デフォルトは'full'。marker(str, optional): マーカーのスタイル。デフォルトは''（マーカーなし）。markersize(float, optional): マーカーのサイズ。デフォルトは \(5\)。**kwargs:Axes.plotに渡される追加のキーワード引数。
戻り値: (list of matplotlib.lines.Line2D) 描画されたラインオブジェクトのリスト。
plot_wireframe(self, iaxes = 0, xd = None, yd = None, zd = None, rstride = 2, cstride = 2)動作: 指定されたAxesオブジェクトに3次元のワイヤーフレームプロットを描画します。描画されたSurfaceオブジェクトは、対応するAxesの
linelistに追加され、データ (xd,yd,zd) も保存されます。この機能を利用するには、Axesが3Dプロット用に初期化されている必要があります（例:add_subplot(projection='3d')）。引数:
iaxes(int, optional): プロットを描画するAxesのインデックス。デフォルトは \(0\)。xd(array-like, optional): X軸のデータ。デフォルトはNone。yd(array-like, optional): Y軸のデータ。デフォルトはNone。zd(array-like, optional): Z軸のデータ。デフォルトはNone。rstride(int, optional): 行方向のストライド（サンプリング間隔）。デフォルトは \(2\)。cstride(int, optional): 列方向のストライド（サンプリング間隔）。デフォルトは \(2\)。
戻り値: (matplotlib.collections.PolyCollection) 描画されたワイヤーフレームオブジェクト。
plot_contour(self, iaxes = 0, xd = None, yd = None, zd = None, levels = 51, cmap = 'Spectral', **kwargs)動作: 指定されたAxesオブジェクトに2次元の等高線プロット（
contourまたはcontourf）を描画します。cmapが'line'の場合は等高線 (contour) を使用し、それ以外の場合は塗りつぶし等高線 (contourf) と指定されたカラーマップを使用します。描画されたContourオブジェクトは、対応するAxesのlinelistに追加され、データ (xd,yd,zd) も保存されます。引数:
iaxes(int, optional): プロットを描画するAxesのインデックス。デフォルトは \(0\)。xd(array-like, optional): X軸のデータ。デフォルトはNone。yd(array-like, optional): Y軸のデータ。デフォルトはNone。zd(array-like, optional): Z軸のデータ。デフォルトはNone。levels(int or array-like, optional): 等高線の数、または特定の等高線レベルのリスト。デフォルトは \(51\)。cmap(str, optional): カラーマップの名前。'line'の場合、contourを使用。それ以外の場合、contourfと指定されたカラーマップを使用。デフォルトは'Spectral'。**kwargs:Axes.contourまたはAxes.contourfに渡される追加のキーワード引数。特にaspectキーワードが渡された場合、Axesのアスペクト比が設定されます。
戻り値: (matplotlib.contour.ContourSet) 描画された等高線オブジェクト。
set_data(self, iaxes, ilines, idx, xt, yt)動作: 指定されたAxes上の既存のラインプロットのデータを更新します。これは、動的なプロット（アニメーションなど）を行う際に、新しいデータを効率的に反映するために使用されます。
引数:
iaxes(int): 更新するラインプロットを含むAxesのインデックス。ilines(int): Axesのlinelist内で更新するラインセットのインデックス。idx(int):linelist[ilines]がリストの場合、その中の具体的なラインオブジェクトのインデックス（通常は \(0\)）。xt(array-like): 新しいX軸のデータ。yt(array-like): 新しいY軸のデータ。
戻り値: なし
set_axtitle(self, iaxes, title)動作: 指定されたAxesオブジェクトのタイトルを設定します。
引数:
iaxes(int): タイトルを設定するAxesのインデックス。title(str): 設定するタイトル文字列。
戻り値: なし
main scriptとして実行したときの動作
tkplot.py はライブラリとして設計されており、Pythonの慣例である if __name__ == '__main__': ブロックを含んでいません。したがって、このファイルをPythonインタープリタで直接実行しても、特別な処理は行われません。通常、このライブラリは他のPythonスクリプトやアプリケーションからインポートされ、その機能が利用されることを想定しています。