ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

write

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

説明

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 データとして読み取ることができます。また、その逆も可能です。

分散 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);

入力引数

すべて折りたたむ

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

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

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

write は、Amazon S3™、Windows Azure® Storage Blob、Hadoop® 分散ファイル システム (HDFS™) などのリモートの場所をサポートしています。詳細については、リモート データの操作 (MATLAB)を参照してください。

例: location = '../../dir/data'

例: location = 'C:\Users\MyName\Desktop'

例: location = 'hdfs://myHadoopCluster/some/output/folder'

例: location = 's3://bucketname/some/output/folder'

データ型: char | string

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

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

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

データ型: char | string

名前と値のペアの引数

オプションの Name,Value の引数ペアをコンマ区切りで指定します。Name は引数名で、Value は対応する値です。Name は引用符で囲まなければなりません。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を任意の順序で指定できます。

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

一般オプション

すべて折りたたむ

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

'FileType' の名前と値のペアを location 引数と共に使用して、書き込むファイルの種類を指定します。既定で、write は適切なファイル タイプの自動検出を試みます。writelocation 引数または 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' と関数ハンドルで構成されるコンマ区切りのペアとして指定します。指定した関数は D からデータのブロックを受け取り、出力ファイルの作成を受け持ちます。名前と値のペアの引数 'WriteFcn' を使用して、データを様々な形式で書き込むことができます (出力形式が write で直接サポートされていない場合も含む)。

関数シグネチャ

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

function myWriter(info, data)

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

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

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

ファイルの命名

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

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

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

info には、PartitionIndexNumPartitionsBlockIndexInPartitionIsFinalBlock など、パーティションに関連するいくつかのフィールドが含まれます。これらのフィールドは、単一のファイルを書き込み、そこに追加していく場合に便利です。これは、多くのブロックに分割された大きなパーティションをもつ配列で一般的に行われるタスクです。カスタム書き込み関数はブロックごとに 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);
それぞれのブロックについて、関数 dataWriterinfo 構造体の推奨ファイル名を使用し、writetable を呼び出してスプレッドシート ファイルを書き出します。推奨ファイル名では、location 引数で指定されているファイル命名パターンが考慮されます。

データ型: function_handle

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

すべて折りたたむ

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

インジケーター

動作

true

変数名を出力の列見出しとして含める。これは既定の動作です。

false

変数名を出力に含めない。

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

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

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

データ型: char | string

テキスト ファイルのみ

すべて折りたたむ

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

指定子

フィールドの区切り記号

','

'comma'

コンマ。これは既定の動作です。

' '

'space'

空白

'\t'

'tab'

タブ

';'

'semi'

セミコロン

'|'

'bar'

縦棒

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

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

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

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

ファイルに関連付けられた文字エンコード スキーム。'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 スカラーで構成されるコンマ区切りのペアとして指定します。ワークシート名にコロン (:) を含めることはできません。スプレッドシート ファイルのシートの名前を調べるには、[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 ファイルのみ

すべて折りたたむ

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

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

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

一般的に、'Snappy' による圧縮は読み取りと書き込みのパフォーマンスが優れていますが、'Brotli' は通常、より小さいファイルサイズを生成します。

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

制限

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

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

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

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

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

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

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

ヒント

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

参考

| |

トピック

R2017a で導入