tkdataio.py 技術ドキュメント

ライブラリの機能や目的

tkdataio.py は、軽量な表データ入出力ユーティリティを提供するPythonライブラリです。このライブラリの主な目的は、独立した小さな解析スクリプトを迅速に作成する際の補助モジュールとして機能することにあります。既存のより大規模なデータ解析ライブラリ（例: tkVariousData/tkFit）を置き換えることを意図しているわけではなく、手軽にデータ読み書きを行いたい場合に役立ちます。

具体的には、CSV、TSV、TXT、XLSXなどの様々な形式の表データを pandas.DataFrame として読み込んだり、Excelの複数シートに複数テーブルを保存したり、NumPyの型にも対応したJSONデータの保存・読み込み機能を提供します。これにより、データ解析ワークフローにおける一般的な入出力タスクを簡素化します。

importする方法

このライブラリを他のPythonプログラムから利用するには、次のようにインポートします。

import tkdataio

または、特定の関数のみをインポートすることも可能です。

from tkdataio import read_table, save_json

必要な非標準ライブラリとインストール方法

tkdataio.py を完全に利用するには、以下の非標準ライブラリが必要です。

pandas: 表データの読み書き、操作に必須です。特にExcelファイルの読み書きには openpyxl が必要となる場合があります。
numpy: 配列操作、数値計算に利用されます。

これらのライブラリは pip コマンドを使用してインストールできます。

pip install pandas numpy openpyxl

importできる変数と関数

変数

ColumnKey: 表データの列を指定するための型エイリアスです。整数（列のインデックス）または文字列（列名）のいずれかを受け入れます。
```
ColumnKey = Union[int, str]
```

関数

read_table(path: Union[str, Path], *, sheet_name=0) CSV、TSV、TXT、XLSX形式の表ファイルを pandas.DataFrame として読み込みます。
- 引数:
  - path (Union[str, Path]): 読み込むファイルのパス。
  - sheet_name (Union[str, int]): Excelファイルの場合に読み込むシートの名前またはインデックス。デフォルトは 0（最初のシート）。
- 戻り値: pandas.DataFrame: 読み込まれたデータ。
- 備考:
  - CSVファイルはカンマ区切り、TSV/TXT/DATファイルはタブ区切りとして読み込みます。空白区切りのファイルは直接サポートされていません（ユーザーが pandas を直接使用する必要があります）。
  - この関数は pandas および openpyxl ライブラリに依存します。これらがインストールされていない場合、ImportError を発生させます。
read_xy(path: Union[str, Path], x: ColumnKey = 0, y: ColumnKey = 1, *, sheet_name=0, xmin: float = -1e100, xmax: float = 1e100, dropna: bool = True) -> Tuple[np.ndarray, np.ndarray, str, str] 指定された表ファイルから2つの列 (x, y) をNumPy配列として抽出し、オプションでデータ範囲によるフィルタリングやNaN値の除去を行います。
- 引数:
  - path (Union[str, Path]): 読み込むファイルのパス。
  - x (ColumnKey): X軸データとして抽出する列のインデックス（整数）または列名（文字列）。デフォルトは 0（最初の列）。
  - y (ColumnKey): Y軸データとして抽出する列のインデックス（整数）または列名（文字列）。デフォルトは 1（2番目の列）。
  - sheet_name (Union[str, int]): read_table に渡されるExcelシート名。デフォルトは 0。
  - xmin (float): Xデータの最小値。これより小さいX値のデータは除外されます。デフォルトは -1e100（実質的に制限なし）。
  - xmax (float): Xデータの最大値。これより大きいX値のデータは除外されます。デフォルトは 1e100（実質的に制限なし）。
  - dropna (bool): True の場合、XまたはYのいずれかに非有限値（NaN, Inf）が含まれる行を除外します。デフォルトは True。
- 戻り値: Tuple[np.ndarray, np.ndarray, str, str]: 以下の4つの要素を含むタプル。
  1. xv (np.ndarray): X軸のデータ配列。
  2. yv (np.ndarray): Y軸のデータ配列。
  3. xlabel (str): X軸の列ラベル。
  4. ylabel (str): Y軸の列ラベル。
- 備考: 内部で read_table 関数を利用します。
write_excel_tables(path: Union[str, Path], tables: Mapping[str, object], *, index: bool = False) -> None 複数のテーブルデータをExcelファイルの複数シートに保存します。
- 引数:
  - path (Union[str, Path]): 保存するExcelファイルのパス。
  - tables (Mapping[str, object]): シート名（文字列）をキー、保存するテーブルデータ（pandas.DataFrame、dict、または2次元NumPy配列）を値とする辞書またはマッピング。
  - index (bool): True の場合、pandas.DataFrame のインデックスもExcelに書き出します。デフォルトは False。
- 戻り値: None
- 備考:
  - tables の値が dict の場合、キーが列名、値がその列のデータ（リストやスカラーなど）と解釈され、自動的に pandas.DataFrame に変換されます。この際、列の長さが異なる場合は None で埋められます。
  - この関数は pandas および openpyxl ライブラリに依存します。これらがインストールされていない場合、ImportError を発生させます。
  - シート名は31文字に切り詰められます。
save_json(path: Union[str, Path], data: object, *, indent: int = 2) -> None データをJSON形式でファイルに保存します。NumPyの配列や数値型は、標準のPython型に変換されて保存されます。
- 引数:
  - path (Union[str, Path]): 保存するJSONファイルのパス。
  - data (object): JSON形式で保存するデータ。
  - indent (int): JSONファイルのインデントレベル。デフォルトは 2。
- 戻り値: None
- 備考:
  - NumPyの ndarray はリストに、np.floating や np.integer はPythonの float や int に変換されます。
  - __dict__ 属性を持つオブジェクトもシリアライズを試みます。
  - JSONシリアライズ不可能な型が含まれる場合、TypeError を発生させます。
load_json(path: Union[str, Path]) -> object JSONファイルを読み込み、Pythonのオブジェクトに復元します。
- 引数:
  - path (Union[str, Path]): 読み込むJSONファイルのパス。
- 戻り値: object: JSONファイルから復元されたPythonオブジェクト。

main scriptとして実行したときの動作

tkdataio.py は、if __name__ == "__main__": ブロックを持たないため、このファイルを直接Pythonインタプリタで実行しても、特別な動作は行われません。ライブラリとして他のスクリプトからインポートして使用することを想定しています。