tkvariousdata.py ライブラリ ドキュメント
このドキュメントは、Python言語で記述された tkvariousdata.py ライブラリの技術的な詳細について説明します。
ライブラリの機能や目的
tkvariousdata.py は、様々な形式の構造化データファイル（特にCSVおよびExcel）を効率的に読み込み、処理し、書き出すためのユーティリティ機能を提供するPythonライブラリです。科学技術計算やデータ分析の分野で頻繁に発生する、表形式データの取り扱いを簡素化することを目的としています。
主な機能:
多様なファイル形式のサポート: CSV (.csv) および Excel (.xlsx, .xlsm) ファイルからのデータ読み込みと書き込みをサポートします。
データの抽出とフィルタリング: 特定の列（ラベル名またはインデックスで指定）のデータを抽出し、数値範囲に基づいてフィルタリングする機能を提供します。
Excelテンプレートの利用: 既存のExcelテンプレートファイル（特にVBAを含む.xlsmファイル）を使用して、新しいデータを挿入し、グラフや既存データを整形する機能があります。
データ型変換: 文字列として読み込まれたデータを、可能な場合は自動的に整数型や浮動小数点型に変換します。
Pandas DataFrameとの連携: Pandas DataFrameオブジェクトから直接Excelファイルに出力する機能を提供し、既存のデータ分析ワークフローとの統合を容易にします。
解決する課題:
異なるファイル形式（CSV、Excel）間でのデータ連携における複雑さを軽減します。
手動でのファイル操作や、複雑なライブラリの低レベルAPIを直接操作することなく、統一されたインターフェースでデータを扱えるようにします。
特に、テンプレートを用いたレポート作成など、定型的なデータ出力プロセスを自動化するのに役立ちます。
importする方法
このライブラリの変数、関数、クラスは、以下の方法で他のPythonプログラムにインポートできます。
import tkvariousdata
# または、特定の要素を直接インポート
from tkvariousdata import tkVariousData, find_template, pattern_int, pattern_float
必要な非標準ライブラリとインストール方法
tkvariousdata.py が正しく動作するためには、いくつかの非標準ライブラリが必要です。これらは pip を使用してインストールできます。
numpy: 数値計算を効率的に行うためのライブラリです。
pip install numpy
pandas: データ構造とデータ分析ツールを提供するライブラリです。
pip install pandas
openpyxl: Excelファイル (.xlsx, .xlsm) の読み書きを行うためのライブラリです。
pip install openpyxl
また、このライブラリは tklib というカスタムライブラリに依存しています。tklib はこのドキュメントの範囲外ですが、tkvariousdata.py を使用する環境では tklib も利用可能である必要があります。
importできる変数と関数
変数
pattern_int型:
re.Patternオブジェクト説明: 整数形式の文字列 (
^[-+]?[0-9]+$) にマッチするための正規表現パターンです。文字列を整数に変換する際に使用されます。
pattern_float型:
re.Patternオブジェクト説明: 浮動小数点数形式の文字列 (
^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$) にマッチするための正規表現パターンです。文字列を浮動小数点数に変換する際に使用されます。
関数
find_template(template)動作: 指定されたテンプレートファイルパスを以下の順序で検索し、最初に見つかったファイルのフルパスを返します。
指定された
templateパスがそのまま存在するファイルか。スクリプトが実行されているディレクトリからの相対パスとして
templateが存在するか。tklib.tkprogvars.tkprog_X_pathで定義されたパス内の "excel/template" サブディレクトリにtemplateが存在するか。
引数:
template(str): 検索するテンプレートファイルのパスまたはファイル名。
戻り値:
(str または None): 見つかったテンプレートファイルの絶対パス。見つからなかった場合は
None。
クラス
class tkVariousData(tkDataFile)tklib.tkdatafile.tkDataFileを継承しており、ファイルパス管理や共通のユーティリティ機能を利用できます。__init__(self, path=None, mode='r', OpenFile=1, data_only=True, **args)動作:
tkVariousDataオブジェクトのコンストラクタです。データファイルパス、モード、および初期設定を初期化します。引数:
path(str, optional): 処理するデータファイル（CSVまたはExcel）のパス。デフォルトはNone。mode(str, optional): ファイルを開くモード（例: 'r' 読み込み、'w' 書き込み）。デフォルトは 'r'。OpenFile(int, optional): ファイルを即座に開くかどうかのフラグ。デフォルトは 1。data_only(bool, optional): Excelファイルを読み込む際、セルの数式ではなく表示されている値のみを読み込むか。デフォルトはTrue。**args: 親クラスtkDataFileのコンストラクタに渡される追加のキーワード引数。
戻り値: なし
__del__(self)動作: オブジェクトが破棄されるときに
Close()メソッドを呼び出し、開いているファイルを閉じます。引数: なし
戻り値: なし
__str__(self)動作: オブジェクトの文字列表現を返します。
引数: なし
戻り値: (str): オブジェクトのクラスパス。
Read_minimum_matrix(self, close_fp=False, force_numeric=True, usage=None)動作: オブジェクトの
pathに指定されたCSVまたはExcelファイルから、最小限のデータ行列を読み込みます。データはラベル行とデータリストの形式で返されます。引数:
close_fp(bool, optional): 読み込み完了後にファイルポインタを閉じるか。デフォルトはFalse。force_numeric(bool, optional): 可能な限り読み込んだデータを数値型（整数または浮動小数点数）に変換するか。デフォルトはTrue。usage(str, optional): エラーメッセージに含める用途を示す文字列。
戻り値:
tuple[list[str], list[list[Any]]): 最初の要素は列ラベルのリスト、2番目の要素は各列のデータがリストになったリスト。
エラー: サポートされていないファイルタイプの場合、
terminate関数でプログラムを終了します。
read_data(self, infile, xlabel=0, ylabel=1, xmin=None, xmax=None, usage=None)動作: 指定された入力ファイルからデータを読み込み、X軸とY軸に指定された列のデータを抽出します。オプションでX軸データに基づいてフィルタリングを行います。このメソッドは、
self.x、self.y、``self.included_index` など、オブジェクトの複数の属性を更新します。引数:
infile(str): 読み込む入力ファイルのパス。xlabel(int or str, optional): X軸データとして使用する列のインデックス（0から始まる）またはラベル名。デフォルトは 0。ylabel(int or str, optional): Y軸データとして使用する列のインデックスまたはラベル名。デフォルトは 1。xmin(float or None, optional): 抽出するXデータの最小値。これより小さいXデータは除外されます。デフォルトはNone（無制限）。xmax(float or None, optional): 抽出するXデータの最大値。これより大きいXデータは除外されます。デフォルトはNone（無制限）。usage(str, optional): エラーメッセージに含める用途を示す文字列。
戻り値:
tuple[list[str], list[list[Any]]): 最初の要素は全列ラベルのリスト、2番目の要素は全データリスト。
副作用:
self.labels,self.datalist,self.xlabel,self.ylabel,self.ndata_all,self.x,self.y,self.included_index,self.ndata,self.indexなどのインスタンス変数を設定します。
to_csv(self, outfile, labels, data_list, print_level=1)動作: 指定されたラベルとデータリストをCSVファイルに書き込みます。浮動小数点数は適宜、指数表記または一般形式でフォーマットされます。
引数:
outfile(str): 出力するCSVファイルのパス。labels(list[str]): CSVファイルのヘッダとして使用する列ラベルのリスト。data_list(list[list[Any]]): 書き込むデータ。各内部リストは1つの列のデータを含みます（例:[[col1_row1, col1_row2], [col2_row1, col2_row2]]）。print_level(int, optional): 処理メッセージの表示レベル。0の場合メッセージを表示しません。デフォルトは 1。
戻り値:
(bool): 書き込みが成功した場合は
True、失敗した場合はFalse。
reformat_workbook(self, wb)動作:
openpyxlのワークブックオブジェクトを整形します。具体的には、最初のシートのA1からE列の全セルをクリアし、ワークブック内のすべてのシートからグラフを削除します。引数:
wb(openpyxl.Workbook): 整形するExcelワークブックオブジェクト。
戻り値:
(
openpyxl.worksheet.worksheet.Worksheet): 整形されたワークブックの最初のシート。
to_excel_from_dataframe(self, outfile, df, template=None, isheet_create=0, print_level=1)動作:
pandas.DataFrameオブジェクトからデータを抽出し、指定されたExcelファイルに書き込みます。内部的にはto_excelメソッドを呼び出します。引数:
outfile(str): 出力するExcelファイルのパス。df(pandas.DataFrame): 書き込むデータを含むPandas DataFrameオブジェクト。template(str or None, optional): 使用するExcelテンプレートファイルのパス。デフォルトはNone。isheet_create(int, optional): 新しいデータシートを作成する位置のインデックス。0の場合、最初のシートとして作成されます。デフォルトは 0。print_level(int, optional): 処理メッセージの表示レベル。0の場合メッセージを表示しません。デフォルトは 1。
戻り値:
(bool): 書き込みが成功した場合は
True、失敗した場合はFalse。
to_excel(self, outfile, labels, data_list, template=None, isheet_create=0, print_level=1)動作: 指定されたラベルとデータリストをExcelファイルに書き込みます。テンプレートファイルを使用することも可能です。データが文字列の場合、可能な場合は自動的に数値型（整数または浮動小数点数）に変換されます。
引数:
outfile(str): 出力するExcelファイルのパス。labels(list[str] or list[list[str]]): Excelファイルのヘッダとして使用する列ラベルのリスト。ネストされたリストの場合、それらは結合されます。data_list(list[list[Any]] or list[list[list[Any]]]): 書き込むデータ。各内部リストは1つの列のデータを含みます。ネストされたリストの場合、それらは結合されます。template(str or None, optional): 使用するExcelテンプレートファイルのパス。テンプレートが指定され、.xlsm以外のoutfile拡張子が与えられた場合、自動的に.xlsmに変更されます。デフォルトはNone。isheet_create(int, optional): 新しいデータシートを作成する位置のインデックス。0の場合、最初のシートとして作成されます。デフォルトは 0。print_level(int, optional): 処理メッセージの表示レベル。0の場合メッセージを表示しません。デフォルトは 1。
戻り値:
(bool): 書き込みが成功した場合は
True、失敗した場合はFalse。
save(self, outfile, labels, data_list, print_level=1)動作: 出力ファイルパスの拡張子に基づいて、
to_excelまたはto_csvメソッドを呼び出し、データを保存します。サポートされる拡張子は.xlsxと.csvです。引数:
outfile(str): 出力ファイルパス。拡張子 (.xlsxまたは.csv) によって保存形式が決定されます。labels(list[str]): ファイルのヘッダとして使用する列ラベルのリスト。data_list(list[list[Any]]): 書き込むデータ。各内部リストは1つの列のデータを含みます。print_level(int, optional): 処理メッセージの表示レベル。0の場合メッセージを表示しません。デフォルトは 1。
戻り値:
(bool): 保存が成功した場合は
True、失敗した場合はFalse。
main scriptとして実行したときの動作
tkvariousdata.py のソースコードには、if __name__ == '__main__': ブロックが存在しません。したがって、このファイルを直接Pythonインタプリタで実行しても、特別なスクリプトとしての動作は定義されていません。このファイルは、他のPythonプログラムからインポートされて利用されるライブラリとして設計されています。