write

出力場所への分散データの書き込み

構文

write(location,D)

write(filepattern,D)

write(___,Name,Value)

説明

write(location,D) は、分散配列 D の値をフォルダー location 内のファイルに書き込みます。データは、datastore(location) を使用して読み取るために適した効率的なバイナリ形式で保存されます。第 1 次元に沿って分散していない場合、MATLAB^® は、datastore を使用して結果ファイルを読み取れるように、データを書き込み前に再分散します。

write(filepattern,D) は filepattern からのファイル拡張子を使用して、出力形式を決定します。filepattern は、ファイルの書き込み先のフォルダーを含み、その後にワイルドカード * を含むファイル名が続かなければなりません。このワイルドカードは、一意のファイル名を生成するためにインクリメントされる数値を表します (例: write('folder/myfile_*.csv',D))。

write(___,Name,Value) は、前述の任意の構文を使用して、1 つ以上の名前と値のペアの引数による追加オプションを指定します。たとえば、'FileType' と有効なファイル タイプ ('mat'、'seq'、'parquet'、'text' または 'spreadsheet') を使用して、ファイル タイプを指定できます。また、'WriteFcn' と関数ハンドルを使用して、データを処理するカスタム書き込み関数を指定できます。

例

分散配列の書き込み

この例では、分散配列をファイル システムに書き込み、データ ストアを使用して読み取る方法を説明します。

分散配列を作成して出力フォルダーに書き込みます。

d = distributed.rand(5000,1);
location = 'hdfs://myHadoopCluster/some/output/folder';
write(location, d);

書き込まれたファイルから分散配列を再作成します。

ds = datastore(location);
d1 = distributed(ds);

ファイル パターンを使用した分散配列の書き込み

この例では、ファイル パターンを使用して様々な形式で分散配列を書き込む方法を説明します。

分散テーブルを作成し、多くのアプリケーションで読み取り可能なテキストベースのシンプルな形式で書き込みます。

dt = distributed(array2table(rand(5000,3)));
location = "/tmp/CSVData/dt_*.csv";
write(location, dt);

書き込まれたファイルから分散テーブルを再作成します。

ds = datastore(location);
dt1 = distributed(ds);

tall データおよび分散データの書き込みと読み込み

分散データを書き込み、tall データとして読み取ることができます。また、その逆も可能です。

分散 timetable を作成し、ディスクに書き込みます。

dt = distributed(array2table(rand(5000,3)));
location = "/tmp/CSVData/dt_*.csv";
write(location, dt);

書き込まれたファイルから tall table を作成します。

 ds = datastore(location);
 tt = tall(ds);

あるいは、tall データから書き込まれたデータを、分散データとして読み取ることができます。tall timetable を作成してディスクに書き込みます。

tt = tall(array2table(rand(5000,3)));
location = "/tmp/CSVData/dt_*.csv";
write(location, tt);

分散 timetable に再度読み取ります。

 ds = datastore(location);
 dt = distributed(ds);

書き込み関数を使用した分散配列の書き込み

この例では、カスタム書き込み関数を使用して分散配列をファイル システムに書き込む方法を説明します。

スプレッドシート ファイルを書き出すシンプルな書き込み関数を作成します。

function dataWriter(info, data)
       filename = info.SuggestedFilename;
       writetable(data, filename, "FileType", "spreadsheet");
end

分散テーブルを作成し、カスタム書き込み関数を使用してディスクに書き込みます。

dt = distributed(array2table(rand(5000,3)));
location = "/tmp/MyData/tt_*.xlsx";
write(location, dt, "WriteFcn", @dataWriter);

入力引数

location — データを書き込むためのフォルダーの場所

文字ベクトル | string

データを書き込むためのフォルダーの場所。文字ベクトルまたは string として指定します。location には、絶対パスまたは相対パスを指定できます。指定するフォルダーは、次のオプションのいずれかです。

• 他のファイルを含まない既存の空のフォルダー

• write が作成する新規フォルダー

データはコンピューターのローカル フォルダー、共有ネットワークのフォルダー、リモートの場所に書き込めます。リモートの場所には Amazon S3™、Windows Azure^® Storage Blob、Hadoop^® 分散ファイル システム (HDFS™) などがあります。リモートの場所でのデータの読み取りと書き込みの詳細については、リモート データの操作を参照してください。

例: location = '../../dir/data' は、相対ファイル パスを指定します。

例: location = 'C:\Users\MyName\Desktop\data' は、Windows^® デスクトップ フォルダーへの絶対パスを指定します。

例: location = 'file:///path/to/data' は、フォルダーへの絶対 URI のパスを指定します。

例: location = 'hdfs://myHadoopCluster/some/output/folder' は、HDFS URL を指定します。

例: location = 's3://bucketname/some/output/folder' は、Amazon S3 の場所を指定します。

データ型: char | string

D — 入力配列

分散配列

入力配列。分散配列として指定します。

filepattern — ファイル命名パターン

string | 文字ベクトル

ファイル命名パターン。string または文字ベクトルとして指定します。ファイル命名パターンには、ファイルの書き込み先のフォルダーと、その後にワイルドカード * を含むファイル名が含まれていなければなりません。write はワイルドカードを連続する数字に置き換えて確実に一意のファイル名を生成します。

例: write('folder/data_*.txt',D) は分散配列 D を folder 内の一連の .txt ファイルとして書き込みます。ファイル名は data_1.txt、data_2.txt と続きます。

データ型: char | string

名前と値の引数

オプションの引数ペアを Name1=Value1,...,NameN=ValueN として指定します。ここで、Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後になければなりませんが、ペアの順序は重要ではありません。

R2021a 以前は、名前と値をそれぞれコンマを使って区切り、Name を引用符で囲みました。

例: write('C:\myData', D, 'FileType', 'text', 'WriteVariableNames', false) は、分散配列 D を、列見出しとして変数名を使用しないテキスト ファイルのコレクションとして C:\myData に書き込みます。

一般オプション

FileType — ファイル タイプ

'auto' (既定値) | 'mat' | 'parquet' | 'seq' | 'text' | 'spreadsheet'

ファイル タイプ。'FileType' と、許可されたファイル タイプ ('auto'、'mat'、'parquet'、'seq'、'text' または 'spreadsheet') のいずれかで構成されるコンマ区切りのペアとして指定します。

'FileType' の名前と値のペアを location 引数と共に使用して、書き込むファイルの種類を指定します。既定で、write は適切なファイル タイプの自動検出を試みます。write が location 引数または filepattern 引数の拡張子からファイル タイプを判定できる場合、名前と値のペアの引数 'FileType' を指定する必要はありません。write は、次の拡張子からファイル タイプを判定できます。

• MATLAB データ ファイルの場合、.mat

• Parquet ファイルの場合、.parquet または .parq

• シーケンス ファイルの場合、.seq

• 区切りテキスト ファイルの場合、.txt、.dat または .csv

• スプレッドシート ファイルの場合、.xls、.xlsx、.xlsb、.xlsm、.xltx または .xltm

例: write('C:\myData', D, 'FileType', 'text')

WriteFcn — カスタム書き込み関数

関数ハンドル

カスタム書き込み関数。'WriteFcn' と関数ハンドルで構成されるコンマ区切りのペアとして指定します。指定した関数は D からデータのブロックを受け取り、出力ファイルの作成を受け持ちます。名前と値のペアの引数 'WriteFcn' を使用して、データを様々な形式で書き込むことができます (出力形式が write で直接サポートされていない場合も含む)。

関数シグネチャ

カスタム書き込み関数は、info と data の 2 つの入力引数を受け入れなければなりません。

function myWriter(info, data)

• data は、D からのデータ ブロックを含みます。

• info は、データ ブロックに関する情報を含むフィールドをもつ構造体です。これらのフィールドを使用して、最終的な場所でグローバルに一意の新しいファイル名を作成することができます。構造体フィールドは次のとおりです。

  フィールド	説明
  RequiredLocation	一時出力フォルダーへの完全修飾パス。すべての出力ファイルはこのフォルダーに書き込まれなければなりません。
  RequiredFilePattern	出力ファイル名に必要なファイル パターン。フォルダー名のみが指定されている場合、このフィールドは空になります。
  SuggestedFilename	場所と命名の要件を満たし、グローバルに一意な完全修飾ファイル名。
  PartitionIndex	書き込まれる分散配列のパーティションのインデックス。
  NumPartitions	分散配列のパーティションの総数。
  BlockIndexInPartition	パーティション内での現在のデータ ブロックの位置。
  IsFinalBlock	現在のブロックがパーティションの最終ブロックである場合は true。

ファイルの命名

出力ファイルに使用されているファイル名によって、後で datastore でファイルを読み取るときの順序が決まります。ファイルの順序が重要である場合は、SuggestedFilename フィールドを使用してファイルに命名することをお勧めします。推奨される名前によってファイルの順序が確定するためです。推奨ファイル名を使用しない場合、カスタム書き込み関数はグローバルに一意で、正しく順序付けられたファイル名を作成しなければなりません。ファイル名は、RequiredFilePattern で概説されている命名パターンに従う必要があります。各ワーカーがそのローカル フォルダーに書き込む場合でも、ファイル名はワーカー間で一意であり、かつ正しく順序付けられていなければなりません。

複数のパーティションをもつ配列

分散配列は Parallel Computing Toolbox™ で配列の並列計算を容易に実行するために、パーティションに分割されます。分散配列を書き込むときに、各パーティションはさらに小さいブロックに分割されます。

info には、PartitionIndex、NumPartitions、BlockIndexInPartition、IsFinalBlock など、パーティションに関連するいくつかのフィールドが含まれます。これらのフィールドは、単一のファイルを書き込み、そこに追加していく場合に便利です。これは、多くのブロックに分割された大きなパーティションをもつ配列で一般的に行われるタスクです。カスタム書き込み関数はブロックごとに 1 回呼び出され、1 つのパーティション内のブロックは常に、1 つのワーカー上に順番に書き込まれます。ただし、異なるパーティションが異なるワーカーによって書き込まれる可能性があります。

関数の例

スプレッドシート ファイルを書き出すシンプルな書き込み関数は次のとおりです。

function dataWriter(info, data)
  filename = info.SuggestedFilename;
  writetable(data, filename, 'FileType', 'spreadsheet')
end

dataWriter をあるデータ D の書き込み関数として呼び出すには、次のコマンドを使用します。

D = distributed(array2table(rand(5000,3)));
location = '/tmp/MyData/D_*.xlsx';
write(location, D, 'WriteFcn', @dataWriter);

それぞれのブロックについて、関数 dataWriter は info 構造体の推奨ファイル名を使用し、writetable を呼び出してスプレッドシート ファイルを書き出します。推奨ファイル名では、location 引数で指定されているファイル命名パターンが考慮されます。

データ型: function_handle

テキスト ファイルまたはスプレッドシート ファイル

WriteVariableNames — 変数名を列見出しとして書き込むためのインジケーター

true または 1 (既定値) | false または 0

変数名を列見出しとして書き込むためのインジケーター。'WriteVariableNames' と、数値もしくは logical の 1 (true) または 0 (false) で構成されるコンマ区切りのペアとして指定します。

インジケーター	動作
true	変数名を出力の列見出しとして含める。これは既定の動作です。
false	変数名を出力に含めない。

DateLocale — 日付を書き込むためのロケール

文字ベクトル | string スカラー

日付を書き込むためのロケール。'DateLocale' と、文字ベクトルまたは string スカラーで構成されるコンマ区切りのペアとして指定します。datetime 値をファイルに書き込む場合、DateLocale を使用して write が月と曜日の名前と省略形を書き込むためのロケールを指定します。xx_YY の形式の文字ベクトルまたは string。xx は ISO 639-1 で定義された小文字 2 文字の言語コードで、YY は ISO 3166-1 alpha-2 で定義された大文字の国コードです。ロケールの一般的な値の一覧については、関数 datetime の Locale の名前と値のペア引数を参照してください。

Excel^® ファイルの場合、write は datetime 配列を含む変数を Excel の日付として書き込み、'DateLocale' パラメーターの値は無視します。datetime 変数に 1900 年または 1904 年よりも前の年が含まれている場合、write はその変数をテキストとして書き込みます。Excel の日付の詳細については、Differences between the 1900 and the 1904 date system in Excel を参照してください。

例: 'DateLocale','ja_JP' または 'DateLocale',"ja_JP"

データ型: char | string

テキスト ファイルのみ

Delimiter — フィールドの区切り記号

',' または 'comma' | ' ' または 'space' | ...

フィールドの区切り記号。'Delimiter' と次の指定子のいずれかで構成されるコンマ区切りのペアとして指定します。

指定子	フィールドの区切り記号
',' 'comma'	コンマ。これは既定の動作です。
' ' 'space'	空白
'\t' 'tab'	タブ
';' 'semi'	セミコロン
'|' 'bar'	縦棒

名前と値のペアの引数 'Delimiter' は、区切り付きテキスト ファイルに対してのみ使用できます。

例: 'Delimiter','space' または 'Delimiter',"space"

QuoteStrings — 引用符付きテキスト書き込みのインジケーター

false (既定値) | true

引用符付きテキスト書き込みのインジケーター。'QuoteStrings' と、false または true のいずれかで構成されるコンマ区切りのペアとして指定します。'QuoteStrings' が true の場合、write はテキストを二重引用符で囲み、テキストの一部として表示される二重引用符をすべて 2 つの二重引用符に置き換えます。例は、引用符付きテキストの CSV ファイルへの書き込みを参照してください。

名前と値のペアの引数 'QuoteStrings' は、区切り付きテキスト ファイルでのみ使用できます。

Encoding — 文字エンコード スキーム

'UTF-8' | 'ISO-8859-1' | 'windows-1251' | 'windows-1252' | ...

ファイルに関連付けられた文字エンコード スキーム。'Encoding' と、'system' または次の表に示す値のような標準の文字エンコード スキーム名で構成されるコンマ区切りのペアとして指定します。エンコードを指定しない場合、またはエンコードを 'system' として指定した場合、関数 write はシステムの既定のエンコードを使用してファイルを書き込みます。

"Big5"	"ISO-8859-1"	"windows-874"
"Big5-HKSCS"	"ISO-8859-2"	"windows-949"
"CP949"	"ISO-8859-3"	"windows-1250"
"EUC-KR"	"ISO-8859-4"	"windows-1251"
"EUC-JP"	"ISO-8859-5"	"windows-1252"
"EUC-TW"	"ISO-8859-6"	"windows-1253"
"GB18030"	"ISO-8859-7"	"windows-1254"
"GB2312"	"ISO-8859-8"	"windows-1255"
"GBK"	"ISO-8859-9"	"windows-1256"
"IBM866"	"ISO-8859-11"	"windows-1257"
"KOI8-R"	"ISO-8859-13"	"windows-1258"
"KOI8-U"	"ISO-8859-15"	"US-ASCII"
	"Macintosh"	"UTF-8"
	"Shift_JIS"

例: 'Encoding','system' または 'Encoding',"system" ではシステムの既定のエンコードを使用します。

スプレッドシート ファイルのみ

Sheet — ターゲットのワークシート

文字ベクトル | string スカラー | 正の整数

ターゲットのワークシート。'Sheet' と、ワークシート名またはワークシート インデックスを示す正の整数を含む文字ベクトルまたは string スカラーで構成されるコンマ区切りのペアとして指定します。ワークシート名にコロン (:) を含めることはできません。スプレッドシート ファイルのシートの名前を調べるには、[status,sheets] = xlsfinfo(filename) を使用します。

シートが存在しない場合は、write がワークシート コレクションの最後に新しいシートを追加します。シートのインデックスがワークシート数より大きい場合、ワークブック内のワークシート数がシート インデックスと等しくなるまで、write は空のシートを追加します。いずれの場合でも、write は新しいワークシートが追加されたことを示す警告を表示します。

名前と値のペアの引数 'Sheet' は、スプレッドシート ファイルでのみ使用できます。

例: 'Sheet',2

例: 'Sheet', 'MySheetName'

データ型: char | string | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Parquet ファイルのみ

VariableCompression — Parquet の圧縮アルゴリズム

'snappy' (既定値) | 'brotli' | 'gzip' | 'uncompressed' | 文字ベクトルの cell 配列 | string ベクトル

Parquet の圧縮アルゴリズム。次の値のいずれかとして指定します。

• 'snappy'、'brotli'、'gzip' または 'uncompressed'。1 つの圧縮アルゴリズムを指定すると、write は同じアルゴリズムを使用してすべての変数を圧縮します。

• あるいは、各変数に使用する圧縮アルゴリズムの名前を含む文字ベクトルの cell 配列または string ベクトルを指定できます。

一般に、'snappy' は読み取りと書き込みのパフォーマンスが高く、'gzip' は CPU 処理時間が長くなりますが圧縮率が高く、'brotli' は通常、圧縮速度が低下しますが最小のファイル サイズで出力します。

例: write('C:\myData',D,'FileType','parquet','VariableCompression','brotli')

例: write('C:\myData', D, 'FileType', 'parquet', 'VariableCompression', {'brotli' 'snappy' 'gzip'})

VariableEncoding — エンコード スキームの名前

'auto' (既定値) | 'dictionary' | 'plain' | 文字ベクトルの cell 配列 | string ベクトル

エンコード スキームの名前。次の値のいずれかとして指定します。

• 'auto' — write は logical 変数に 'plain' エンコードを使用し、その他すべてに 'dictionary' エンコードを使用します。

• 'dictionary'、'plain' — あるエンコード スキームが指定された場合、write はそのスキームを使用してすべての変数をエンコードします。

• あるいは、各変数に使用するエンコード スキームの名前を含む文字ベクトルの cell 配列または string ベクトルを指定できます。

一般に、'dictionary' エンコードの方がファイル サイズは小さくなりますが、繰り返される値を多く含まない変数では 'plain' エンコードの方が高速になることがあります。ディクショナリのサイズまたは一意の値の数が過度に大きくなると、エンコードは自動的に plain エンコードに戻ります。Parquet エンコードの詳細については、Parquet encoding definitions を参照してください。

例: write('myData.parquet', D, 'FileType', 'parquet', 'VariableEncoding', 'plain')

例: write('myData.parquet', D, 'FileType', 'parquet', 'VariableEncoding', {'plain' 'dictionary' 'plain'})

Version — 使用する Parquet のバージョン

'2.0' (既定値) | '1.0'

使用する Parquet のバージョン。'1.0' または '2.0' のいずれかとして指定します。既定では、'2.0' が最も効率的なストレージを提供しますが、Parquet 形式をサポートする外部アプリケーションとの最も幅広い互換性を実現するために '1.0' を選択することもできます。

制限

write(location, D, 'FileType', type) の作成したファイルが元の配列 D を正確に表さない場合があります。datastore(location) を使用してチェックポイント ファイルを読み取る場合、結果の形式または内容は元の分散テーブルと異なることがあります。

'text' および 'spreadsheet' のファイル タイプの場合、write は以下のルールを使用します。

• write は longG 形式を使用して数値変数を出力し、categorical 変数、文字変数または string 変数を引用符なしのテキストとして出力する。

• 複数の列をもつ非テキスト変数の場合、write は複数のフィールドを区切り記号付きで各行に出力し、ファイルの最初の行で使用する適切な列見出しを構成する。

• write は、次元数が 2 を超える変数を 2 次元の変数として出力し、後続の次元はまとめられる。

• cell 値をもつ変数では、その内容が数値、logical 値、文字、categorical の場合、write は各 cell の内容を 1 行として、区切り記号付きの複数のフィールドに出力します。それ以外の場合は、1 つの空のフィールドを出力します。

分散配列の正確なチェックポイントを書き込む必要がある場合は、'text' または 'spreadsheet' のファイル タイプを使用しないでください。

ヒント

• 作業を進めるときに、関数 write を使用してデータの "チェックポイント" または "スナップショット" を作成します。これにより、ディスク上のファイルから直接、分散配列を再構成できるため、分散配列を生成したすべてのコマンドを再実行する必要がありません。

バージョン履歴

R2017a で導入

参考

datastore | distributed | tall

トピック

• 分散配列