matlab-import-export-data

MATLAB データのインポート／エクスポート

MATLAB のデータ I/O に関するガイダンスです。区切り文字、ロケール、形式固有の注意点、よくあるエラーメッセージに対する適切なパターンを説明します。

使用する場面

• MATLAB で readtable／writetable／detectImportOptions を使って CSV、Excel、Parquet、JSON ファイルを読み書きする場合
• データ I/O のエラー（誤解を招くメッセージ、「ファイルが見つかりません」のさまざまなパターン）のトラブルシューティング
• URL や認証が必要な REST API エンドポイントからデータを読み込む場合
• 英語以外のロケールのデータ（ヨーロッパ式の小数、セミコロン）をインポートする場合
• インポートしたデータに気付かないうちに破損が生じていないか検証する場合（NaN、65535、型の拡張）
• 圧縮ファイルや、識別子として使えないキーを含む JSON を読み込む場合
• テキストファイルを読み書きする場合（fopen／fgetl／fprintf ではなく、readlines／writelines を使用してください）
• XML ファイルを読み書きする場合（従来の JAXP ではなく、MAXP プロバイダーを使用してください）

使用しない場面

• メモリに収まらない可能性がある大容量ファイル、または tall 配列、データストア、並列ワークフローの選択（matlab-choose-big-data-solution スキルを使用してください）
• ODBC／JDBC を介したデータベースアクセス（リレーショナルデータベースの読み書きやクエリ）（matlab-use-database スキルを使用してください）
• 解析前のデータ削減を目的とした、大容量 CSV／Parquet／JSON ファイルへの SQL ベースのクエリ（matlab-use-duckdb スキルを使用してください）
• MDF／MF4／BLF／ASC ログファイルの車両データ、または CAN／LIN バスのデコード（matlab-import-export-vehicle-data スキルを使用してください）
• CAN／CAN FD／J1939 を使用した車両ネットワーク通信の設定（matlab-use-vehicle-network スキルを使用してください）
• センサーフュージョンのワークフロー向けのトラッキングデータのインポート（matlab-import-tracking-data スキルを使用してください）
• 医用画像データ（DICOM、NIfTI、Analyze 形式）（matlab-process-images スキルを使用してください）
• 市場データや金融データのフィード（matlab-access-datafeed スキルを使用してください）
• Simulink のデータロギングや信号 I/O（Simulink 固有のワークフローを使用してください）
• 画像や音声ファイルの I/O（imread、audioread。対象分野が異なります）
• ストリーミングやリアルタイムのデータ取得（Data Acquisition Toolbox を使用してください）
• ファイルシステム操作、パス操作、フォルダーの走査

一般原則

• インポート後に検証します。 インポートしたデータが想定どおりであることを確認するため、アサーション形式のチェックを 2～3 件追加します。
• テキストと Excel のインポートでは、常に TextType="string" を設定します。 string 型は、char や文字ベクトルの cell 配列より効率的で扱いやすい型です。設定が必要なのは、区切り付きテキストとスプレッドシート形式のみです。XML、JSON、その他の形式では、デフォルトですでに string が返されます。
• 拡張子から形式を判別できない URL から読み込む場合は、FileType を指定します。 MIME タイプの判定で処理できるケースもありますが、API エンドポイントや標準外の URL では、形式を明示する必要があります（トピック 4 を参照）。readtable と併せて detectImportOptions を使用する場合は、FileType を detectImportOptions に渡してください。インポートオプションオブジェクトを指定した場合、readtable は FileType を受け付けません。
• 欠損値のプレースホルダーは読み込み時に処理します。 インポート後に standardizeMissing を呼び出すのではなく、readtable の TreatAsMissing を使用してください。
• 圧縮ファイルから直接読み込みます。 readtable、readmatrix、readtimetable などの読み込み関数は、手動で展開しなくても ZIP、GZ、TAR ファイルのパスを直接受け付けます（R2025a 以降）。
• ヨーロッパ形式の CSV では、小数点に , を使うため、区切り文字に ; を使います。 文脈からヨーロッパ形式のデータだと判断できる場合は、Delimiter と DecimalSeparator の両方を設定してください。

トピック

1. インポート関数の選択（区切り文字とロケールの処理）

ヨーロッパ形式のデータを示す文脈上の手がかり（ドイツ語／フランス語／イタリア語のオフィス、セミコロン区切りのファイル、ヨーロッパ言語の列名など）がある場合は、Delimiter、DecimalSeparator、Encoding（ウムラウトやアクセント記号には UTF-8）を事前に設定してください。

opts = detectImportOptions("messdaten.csv", ...
    "Delimiter", ";", "DecimalSeparator", ",", "Encoding", "UTF-8");
T = readtable("messdaten.csv", opts);

パス形式のデータ（/data/exp_01/run_003/results.mat）を含むファイルでは、実際の区切り文字を明示的に設定してください。パス列から / が検出される場合があります。

opts = detectImportOptions("fileList.csv");
opts.Delimiter = ",";
T = readtable("fileList.csv", opts);

単位の接尾辞が付いた数値データ（例：6.53e+001dB、-9.00e+001°）には、textscan や regexp の代わりに TrimNonNumeric（R2022a 以降）を使用して、数値以外の文字を削除してください。

T = readtable("circuit_output.txt", "Delimiter", {"\t", ","}, ...
    "NumHeaderLines", 1, "TrimNonNumeric", true);

TrimNonNumeric は名前と値のペアとして readtable に直接渡すことも、接尾辞のある列が特定の列だけの場合は、setvaropts(opts, vars, "TrimNonNumeric", true) を使って変数ごとに設定することもできます。

---

2. エラーメッセージの解釈

MATLAB の I/O エラーメッセージは範囲が広く、具体的な問題ではなく一般的な分類を示す場合があります。

エラーメッセージ	実際に考えられる原因	対処方法
"Entry may be password-protected or encrypted"	unzip 用の一時ディレクトリのディスク容量不足（R2020a～R2023b で確認）	tempdir で空き容量を確認し、空き容量を増やすか、一時ディレクトリを変更します
"Unrecognized file extension"	URL に認識可能なファイル拡張子がない	FileType の名前と値のペアを明示的に指定します（トピック 4 を参照）

---

3. インポートの検証とデータの忠実性

Excel または Parquet からインポートした後、気付かないうちにデータが破損していないか確認してください。

• Excel の Inf → 65535：Inf と -Inf はどちらも 65535 として書き込まれます。物理的に不自然と思われる値が正確に 65535 の場合、Inf を表している可能性があります。

• Excel の複素数 → NaN：Excel では複素数を保存できません。スプレッドシートで列全体が NaN になっている場合、ソースに複素数データが含まれている可能性があります。

• null を含む Parquet 整数列 → 暗黙の型昇格：整数列（int8/16/32/64、uint8/16/32/64）に null 値が含まれると、parquetread はその列を double に昇格させます（MATLAB の整数型には欠損値の表現がありません）。int64/uint64 では、2^53 を超える値の精度が気付かないうちに失われます。parquetinfo のスキーマと class(T.col) を比較して検出してください。回避策として、ReadSize="file" を指定した parquetDatastore と readall を使用すると、整数型が保持され、null は 0 としてインポートされます。null がない場合、すべての整数型は parquetread で正確に往復変換されます。

• Excel の結合セル → 予期しない値：結合セルによって、値の重複やデータの欠落が気付かないうちに発生することがあります。MergedCellColumnRule と MergedCellRowRule を使用して、解釈方法を制御してください。

T = readtable("report.xlsx", ...
    "MergedCellColumnRule", "placeleft", "MergedCellRowRule", "placetop");

対策：Excel に書き込む前に、複素数を実数列と虚数列に分割します。

% Spreadsheet: check for Inf→65535 and complex→NaN
for i = 1:width(T)
    col = T.(T.Properties.VariableNames{i});
    if isnumeric(col) && all(isnan(col)) && height(T) > 0
        warning('Column "%s" is all-NaN — may contain complex numbers', ...
            T.Properties.VariableNames{i});
    end
    if isnumeric(col) && any(col == 65535)
        warning('Column "%s" contains 65535 — may represent Inf from Excel', ...
            T.Properties.VariableNames{i});
    end
end

% Parquet: detect null-triggered int64/uint64→double promotion (precision loss)
info = parquetinfo("data.parquet");
T = parquetread("data.parquet");
for i = 1:numel(info.VariableNames)
    if ismember(info.VariableTypes(i), ["int64","uint64"]) && isa(T.(info.VariableNames(i)), "double")
        warning('Column "%s" is %s in schema but double after read (nulls caused promotion)', ...
            info.VariableNames(i), info.VariableTypes(i));
    end
end

% Workaround: parquetDatastore preserves integer types (nulls become 0)
pds = parquetDatastore("data.parquet", "ReadSize", "file");
T = readall(pds);

Parquet データをフィルタリングする場合は、rowfilter（R2022a 以降）を使用して、述語を読み込み処理にプッシュダウンしてください。これにより、不要な行がメモリに読み込まれるのを防げます。

rf = rowfilter(["status", "age"]);
rf = rf.status == "active" & rf.age >= 18;
T = parquetread("users.parquet", "RowFilter", rf);

---

4. URL と REST API からの読み込み

MATLAB は API エンドポイントから形式を推測できないため、常に FileType を明示的に指定してください。

T = readtable("https://example.com/api/v2/export/measurements", "FileType", "text");

認証が必要なエンドポイントには、weboptions を使用してください。

opts = weboptions("Timeout", 30, ...
    "HeaderFields", {"Authorization", "Bearer " + token});
diopts = detectImportOptions(url, "WebOptions", opts);
T = readtable(url, diopts);

---

5. readtable／writetable のパターン

読み込み時に TextType と TreatAsMissing を指定してください。インポート後に convertvars／standardizeMissing を使う方法は避けてください：

T = readtable("data.csv", "TextType", "string", "TreatAsMissing", "not applicable");

時系列データには readtimetable を使用してください（R2019a+）。行時刻を含む timetable を直接作成できるため、別途 table2timetable で変換する必要がありません：

TT = readtimetable("sensor_log.csv", "RowTimes", "timestamp");

表形式の JSON は readtable で直接読み込んでください（R2026a+）。表形式の構造を持つ JSON ファイルには、jsondecode で手動解析する代わりに FileType="json" を使用してください：

T = readtable("data.json", "FileType", "json");

手動で展開せず、圧縮アーカイブから直接読み込んでください（R2025a+）：

T = readtable("data.csv.gz");
T = readtable("archive.zip/folder/data.csv");

インポート時に MissingRule と ImportErrorRule でエラー処理を制御してください（R2020b+）。NaN で何も通知せずに補完する代わりに、すぐにエラーを発生させたり、不正な行を除外したりできます：

T = readtable("data.csv", "MissingRule", "error");
T = readtable("data.csv", "ImportErrorRule", "omitrow");

構造体を CSV にエクスポートするには struct2table + writetable を使用してください。フィールドを手動で展開するループは使わないでください：

T = struct2table(data.Results);
writetable(T, "results.csv");

writetable は、ベクトル値のフィールドを番号付きの列（例：MemSet_1、MemSet_2）に自動的に展開します。JSON／XML 出力には、代わりに writestruct を使用してください（トピック 9 を参照）。

セル配列のエクスポートには writecell を使用してください（R2019a+）。先にテーブルへ変換しないでください：

writecell(results, "output.csv");

表形式の XML は readtable で直接読み込んでください。行に対応する繰り返し要素を含む XML ファイルには、DOM を手動で解析する代わりに、RowNodeName と必要に応じて TableNodeName を指定して readtable を使用してください：

T = readtable("measurements.xml", ...
    "TableNodeName", "measurements", "RowNodeName", "measurement");

---

6. テキストファイルの I/O：fopen のパターンより readlines／writelines（R2020b+）

シンプルなテキストファイルの I/O には readlines／writelines を使用してください。ファイル全体を文字列配列として読み書きする場合は、fopen／fgetl／fprintf／fclose を避けてください：

% Reading: readlines returns a string array — no file handles needed
lines = readlines("config.txt");
matches = lines(contains(lines, "keyword"));

% Writing: writelines handles string arrays directly
messages = ["Starting process"; "Step 1 complete"; "Done"];
writelines(messages, "output.log");

% Line-by-line processing: read all then operate vectorially
lines = readlines("events.log");
lines = lines(lines ~= "");  % remove empties
parts = split(lines, "|");   % vectorized split
timestamps = parts(:,1);
levels = parts(:,2);

fopen／fgetl のループパターンは旧式です。readlines はよりシンプルで、空のファイルを適切に処理でき、ファイル全体に対するベクトル化文字列演算も可能です。

---

7. XML I/O：JAXP より MAXP

すべての XML 操作に MAXP プロバイダーを使用してください（R2024b+）。純粋な MATLAB で実装されており、Java は不要です：

% Reading XML with MAXP
import matlab.io.xml.dom.*
doc = parseFile(Parser, "settings.xml");
params = getElementsByTagName(doc, "parameter");
for i = 1:params.Length
    node = params.item(i);
    name = getAttribute(node, "name");
    value = getAttribute(node, "value");
end

% Writing XML with MAXP
import matlab.io.xml.dom.*
doc = Document("testResults");
root = getDocumentElement(doc);
for i = 1:height(T)
    tc = createElement(doc, "testcase");
    setAttribute(tc, "name", T.test_name(i));
    setAttribute(tc, "status", T.status(i));
    appendChild(root, tc);
end
xmlwrite("results.xml", doc);

旧式の JAXP インターフェイス（com.mathworks.xml.XMLUtils.createDocument、Java DOM オブジェクトでの getElementsByTagName、0 始まりの item() インデックスを使った getAttribute）は使用しないでください。MAXP は純粋な MATLAB で実装されており、Java は不要です。

---

8. 識別子として無効なキーを含む JSON（R2024b+）

JSON キーにスペース、ハイフン、その他 MATLAB の識別子として無効な文字が含まれる場合は、struct の代わりに dictionary を使用してください：

d = readdictionary("config.json");
val = d("my-custom-key");
d("new key with spaces") = 42;
writedictionary(d, "config.json");

jsondecode はそのようなキーを有効な識別子（例：my_custom_key）に変換するため、往復変換時に元のキー名が失われます。readdictionary／writedictionary はキーをそのまま保持します。

---

9. 構造体の I/O：jsondecode／xmlread より readstruct／writestruct（XML は R2020b+、JSON は R2023b+）

構造体ベースのファイル I/O には readstruct／writestruct を使用してください。目的が構造体の読み書きである場合は、fileread + jsondecode や xmlread + DOM の走査を使用しないでください：

% Reading JSON into a struct
config = readstruct("app_config.json");
host = config.database.host;

% Writing a struct to JSON
writestruct(config, "output_config.json");

% Reading XML into a struct
params = readstruct("device_config.xml");
rate = params.sensor.rate;

% Writing a struct to XML
writestruct(params, "params.xml");

readstruct／writestruct は JSON と XML を 1 回の呼び出しで処理し、入れ子になったフィールド構造を保持します。旧式のパターンは避けてください。JSON では fileread + jsondecode／jsonencode + fopen + fwrite、XML では xmlread + getElementsByTagName + getAttribute です。

---

Copyright 2026 The MathWorks, Inc.