collect_resitest8300.py 技術ドキュメント

プログラムの動作

collect_resitest8300.py は、Hall測定装置 (例えば 8310型) が出力するCSVファイルから、多層モデル解析に適した「primaryデータ」を抽出し、Excelファイルに追記するPythonプログラムです。

主な機能は以下の通りです。

  • CSVファイルの解析: cp932/Shift_JIS系の日本語CSVファイルを読み込み、ファイル内に含まれる複数温度・複数測定No.のブロック形式のデータを正確に解析します。

  • Excelへの出力:

    • 指定されたExcelファイルが存在しない場合は新規作成します。

    • 指定されたExcelファイルが存在する場合は、既存データに追記します（重複チェックや置換は行いません）。

    • 生成されるExcelファイルには、測定ごとの詳細データを含む primary シートと、処理したCSVファイルごとのメタデータを含む files シートがデフォルトで作成されます。

  • データ処理:

    • Hall係数は、キャリアタイプ (N/P) が判定できる場合にのみ符号付きの値に変換されます。

    • 装置CSV中の平均値、最小値、最大値から、半幅誤差と相対誤差が再計算され出力されます。

    • シートHall係数などの再計算値は出力されず、装置から得られた生データに近い形式を保持します。

    • 厚さ情報から、単位を cm に統一した厚さも計算されます。

    • シート抵抗値と比抵抗値から、それぞれシートコンダクタンスと導電率が計算されます。

    • ホールノイズや方向依存性などに基づき、簡易的な品質フラグ (good, warning, bad) が設定されます。

  • 柔軟な入力: 複数のCSVファイルを指定したり、ワイルドカードや再帰検索 (--recursive) を用いて一括処理したりできます。

  • ドライランモード: 実際にExcelに書き込むことなく、解析結果の概要をコンソールに表示して確認できます。

このプログラムは、大量のHall測定データを効率的に集約し、後続のデータ解析プロセス（特に多層モデル解析）への準備を容易にすることを目的としています。

原理

collect_resitest8300.py は、Hall測定装置の出力する特定のCSVフォーマットを解析するための、いくつかのロジックと計算に基づいています。

  1. CSVの読み込みとクリーンアップ:

    • read_csv_rows 関数は、指定された文字コード (デフォルトは cp932) でCSVファイルを読み込みます。

    • セル内のNUL文字 (\x00) や前後空白は clean_cell 関数によって除去されます。

  2. ブロック分割:

    • Hall測定装置のCSVは、「<<<比抵抗測定結果>>>」や「<<<ＡＣ磁場ホール測定結果>>>」のようなセクションタイトルで区切られたデータブロックから構成されます。

    • split_blocks 関数は、<<<...>>> 形式の行を検出して、CSVデータをヘッダー部分と複数の測定結果ブロックに分割します。

  3. データ抽出と解析:

    • グローバル情報: parse_global_info 関数は、ファイル冒頭のヘッダー部分から、「試料名」「測定年月日」「測定者」「コメント」「試料厚み」といったファイル共通の情報を抽出します。

    • 数値解析: parse_float 関数は、CSVセル内の数値文字列を解析します。装置の出力には「* 1.23E+4」や「#-3.0E-2」のように数値の前に警告記号が付与されることがあるため、単純な float() 変換ではなく、正規表現 $[-+]?(?:(?:\d+\.\d*)|(?:\.\d+)|(?:\d+))(?:[Ee][+-]?\d+)?$ を用いて数値部分のみを安全に抽出します。

    • 厚さの単位変換: thickness_to_cm 関数は、抽出された厚さの値と単位（mm, um, nm, A など）を元に、厚さを cm 単位に換算します。

  4. 比抵抗測定結果の解析 (parse_rho_result):

    • 「<<<比抵抗測定結果>>>」ブロックから、測定No.、測定温度、測定開始/終了時刻、設定電流、F値、比抵抗値、シート抵抗値、ノイズなどを抽出します。

  5. AC磁場ホール測定結果の解析 (parse_hall_result):

    • 「<<<ＡＣ磁場ホール測定結果>>>」ブロックから、測定No.、測定温度、測定開始/終了時刻、設定電流、磁場、ホール起電圧、位相、ノイズ、ドリフト率、方向依存性などを抽出します。

    • estimate_hall_measured_current 関数は、ブロック内の「端子間ホール起電圧」表の直前にある「電流 [A]」列から、実測電流の代表値を推定します。

  6. Hall係数の符号変換:

    • detect_carrier_sign 関数は、「キャリアタイプ」の文字列 (N または P) を解析し、Hall係数の符号を決定します。N型の場合は符号を負 (-1) に、P型の場合は正 (+1) に変換します。

    • Hall係数は装置から絶対値で出力されることがあるため、add_param_stats 関数でこの符号が適用されます。min/max 値も符号付きの範囲に変換されます（例: N型で絶対値が[1e3, 2e3]の場合、min=-2e3, max=-1e3 となります）。

  7. 誤差の計算:

    • add_param_stats 関数は、装置から提供される平均値 (\(V_{avg}\))、最小値 (\(V_{min}\))、最大値 (\(V_{max}\)) を用いて、半幅誤差 (\(Err\)) と相対誤差 (\(Err_{percent}\)) を計算します。 $\(Err = \frac{|V_{max} - V_{min}|}{2}\)\( \)\(Err_{percent} = \frac{Err}{|V_{avg}|} \times 100\%\)$

  8. シートコンダクタンスと導電率:

    • build_records_from_csv 関数内では、シート抵抗値 (\(R_s\)) と比抵抗値 (\(\rho\)) が抽出された場合、それぞれからシートコンダクタンス (\(G_s\)) と導電率 (\(\sigma\)) を計算してレコードに追加します。 $\(G_s = \frac{1}{R_s}\)\( \)\(\sigma = \frac{1}{\rho}\)$

  9. 品質フラグの生成:

    • make_quality_flag 関数は、Hall測定結果の「ノイズ」や「方向依存性」のパーセンテージ、および解析中に発生した警告に基づいて、簡易的な品質フラグ (good, warning, bad) を生成します。これはExcelでデータを視覚的に評価する際の補助となります。

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

このプログラムを実行するには、openpyxl ライブラリが必要です。これはPythonの標準ライブラリではないため、以下のコマンドでインストールしてください。

pip install openpyxl

必要な入力ファイル

collect_resitest8300.py が処理する入力ファイルは、Hall測定装置（例えば、ResiTest 8300シリーズなどの8310型相当の装置）が出力するCSV形式の測定結果ファイルです。

  • ファイル形式: Comma Separated Values (CSV) 形式。

  • 文字コード: デフォルトでは cp932 (Shift_JIS) を想定しています。異なる文字コードのファイルを使用する場合は --encoding オプションで指定可能です。

  • データ構造: 1つのCSVファイル内に、複数の測定No.や測定温度に対応するデータブロック（例: <<<比抵抗測定結果>>> や <<<ＡＣ磁場ホール測定結果>>>）が含まれている形式を想定しています。

  • 内容: 各ブロックには、試料名、測定年月日、測定者、試料厚み、比抵抗値、シート抵抗値、Hall係数、キャリア濃度、移動度、ノイズ、ドリフト率、方向依存性などの情報が所定の形式で記述されています。数値データには、警告記号 (*, #) や単位 (%, V, A など) が付随する場合があります。

生成される出力ファイル

プログラムは、指定されたパスにExcelワークブック (.xlsx 形式) を生成または更新します。Excelファイルには、以下の2つのシートがデフォルトで含まれます。

  1. primary シート (デフォルト名):

    • 各測定ブロックから抽出された詳細なデータが、1測定行につき1行として記録されます。

    • 以下の情報が含まれます（抜粋）：

      • source_file, source_basename: 元のCSVファイルのパスとファイル名

      • imported_at: Excelにインポートされた日時

      • sample_name, operator, comment: 試料情報

      • measurement_date, measurement_time, measurement_datetime: 測定日時

      • measurement_no: 測定番号

      • thickness_value, thickness_unit, thickness_cm: 試料厚み（元の値、単位、cm換算値）

      • rho_T_K, hall_T_K: 比抵抗測定温度、Hall測定温度

      • sheet_resistance_ohm_sq, rho_ohm_cm: シート抵抗、比抵抗

      • sheet_conductance_S_sq, sigma_S_cm: シートコンダクタンス、導電率（プログラムで計算）

      • hall_voltage_V, hall_phase_deg, hall_noise_percent, hall_drift_percent, hall_direction_dependence_percent: ホール測定結果

      • carrier_type_raw, hall_sign_status: キャリアタイプとHall係数の符号変換状況

      • hall_coeff_cm3_C, carrier_density_cm3, mobility_cm2_Vs: Hall係数、キャリア濃度、移動度（平均、最小、最大、半幅誤差、相対誤差）

      • quality_flag: 簡易品質フラグ (good, warning, bad)

      • parser_warning: 解析中の警告

    • ヘッダー行は太字・背景色付きで装飾され、フィルタが有効になります。

    • 数値データは、測定No.を除き、基本的に指数表記 (例: 0.000000E+00) で書式設定されます。パーセンテージやF値は小数点以下3桁で表示されます。

    • 列幅はヘッダーの内容に応じて自動調整されます。

  2. files シート (デフォルト名):

    • 処理されたCSVファイルごとに1行のメタデータが記録されます。

    • 以下の情報が含まれます（抜粋）：

      • source_file, source_basename: 元のCSVファイルのパスとファイル名

      • file_size: ファイルサイズ (バイト)

      • modified_time: ファイルの最終更新日時

      • imported_at: Excelにインポートされた日時

      • sample_name, operator, comment, measurement_datetime, thickness_cm: ファイル全体に共通する情報

      • num_measurements: そのファイルから抽出された測定行の数

      • parser_warning: ファイル解析中に発生した警告

    • このシートも primary シートと同様に、ヘッダーの装飾、フィルタ、列幅調整、数値書式設定が適用されます。

    • --no-files-sheet オプションを指定すると、このシートは作成・追記されません。

コマンドラインでの使用例 (Usage)

collect_resitest8300.py は、コマンドライン引数を使用して実行されます。

python collect_resitest8300.py [-h] [--encoding ENCODING] [--recursive] [--dry-run] [--primary-sheet PRIMARY_SHEET] [--files-sheet FILES_SHEET] [--no-files-sheet] [--verbose] excel_file data_files [data_files ...]

  • excel_file:

    • 出力先のExcelファイルパスを指定します。ファイルが存在しない場合は新規作成され、存在する場合はデータが追記されます。

  • data_files:

    • 入力となるCSVファイルパス、またはワイルドカードパターンを1つ以上指定します。スペースで区切って複数指定できます。

オプション:

  • -h, --help: ヘルプメッセージを表示して終了します。

  • --encoding ENCODING: 入力CSVファイルの文字コードを指定します。デフォルトは cp932 です。

  • --recursive: data_files 引数で ** を使用した場合に、サブディレクトリを再帰的に検索することを有効にします。

  • --dry-run: Excelに書き込まず、解析結果の概要をコンソールに表示するだけで終了します。

  • --primary-sheet PRIMARY_SHEET: primaryデータを書き込むシート名を指定します。デフォルトは primary です。

  • --files-sheet FILES_SHEET: ファイル単位の履歴を書き込むシート名を指定します。デフォルトは files です。

  • --no-files-sheet: files シートを作成・追記しません。

  • --verbose: ファイルごとの読み取り件数を表示します。

コマンドラインでの具体的な使用例

1. 基本的な実行例

現在のディレクトリにあるすべてのCSVファイル (.CSV 拡張子) を Hall_summary.xlsx に追記します。

python collect_resitest8300.py Hall_summary.xlsx "*.CSV"

実行結果: Hall_summary.xlsx が存在しない場合は新規作成され、存在する場合には、指定されたCSVファイルから抽出された測定データが primary シートに、ファイル情報が files シートに追記されます。コンソールには処理されたファイル数と追記された行数が表示されます。

Excel written : Hall_summary.xlsx
Files parsed  : 3
Rows appended : 12

2. サブディレクトリを再帰的に検索する例

D:\data\ 以下にあるすべてのCSVファイル（サブディレクトリも含む）を Hall_summary.xlsx に追記します。

python collect_resitest8300.py Hall_summary.xlsx "D:\\data\\**\\*.CSV" --recursive

実行結果: D:\data\ ディレクトリとその配下のすべてのサブディレクトリから .CSV ファイルを検索し、その内容を Hall_summary.xlsx に追記します。

3. ドライランモードでの確認例

Excelに書き込まずに、解析結果の概要だけをコンソールで確認します。

python collect_resitest8300.py Hall_summary.xlsx "*.CSV" --dry-run

実行結果: Excelファイルは変更されませんが、解析された各測定レコードの主要な列 (source_basename, measurement_no, rho_T_K, hall_T_K, hall_coeff_cm3_C, quality_flag など) がタブ区切り形式でコンソールに出力されます。

Parsed records:
source_basename	measurement_no	rho_T_K	hall_T_K	sheet_resistance_ohm_sq	rho_ohm_cm	hall_voltage_V	carrier_type_raw	hall_sign_status	hall_coeff_cm3_C	carrier_density_cm3	sheet_carrier_density_cm2	mobility_cm2_Vs	quality_flag
sample1.CSV	1	3.000000E+02	3.000000E+02	1.230000E+02	1.230000E-01	1.000000E-05	N	N	-1.000000E+01	-6.240000E+17	-6.240000E+13	1.000000E+03	good
sample1.CSV	2	3.000000E+02	3.000000E+02	1.250000E+02	1.250000E-01	9.500000E-06	N	N	-9.800000E+00	-6.300000E+17	-6.300000E+13	9.800000E+02	good
sample2.CSV	1	7.700000E+01	7.700000E+01	5.000000E+02	5.000000E-01	2.500000E-05	P	P	5.000000E+01	1.250000E+17	1.250000E+13	8.000000E+02	warning

Total files   : 2
Total records : 3

4. 別のシート名を指定する例

primary シート名を HallData に、files シート名を FileHistory に変更して追記します。

python collect_resitest8300.py Hall_summary.xlsx "*.CSV" --primary-sheet HallData --files-sheet FileHistory

実行結果: Hall_summary.xlsx の中に、HallData と FileHistory という名前のシートが作成され、それぞれにデータが追記されます。