Main Content

wordDocumentImportOptions

Microsoft Word ドキュメント ファイルのインポート オプション オブジェクト

R2021b 以降

このページをすべて展開する

    説明

    WordDocumentImportOptions オブジェクトでは、MATLAB® が構造化された表形式データを Microsoft® Word ドキュメント ファイルからインポートする方法を指定できます。オブジェクトには、エラーおよび欠損データの処理を含む、データのインポート プロセスを制御するプロパティが含まれています。

    作成

    WordDocumentImportOptions オブジェクトは、関数 wordDocumentImportOptions (ここで説明します) または関数 detectImportOptions により作成できます。

    • wordDocumentImportOptions は、インポートの要件に基づいてインポート プロパティを定義する場合に使用します。

    • detectImportOptions は、filename で指定した Microsoft Word ドキュメント ファイルの内容に基づいてインポート プロパティを検出して入力する場合に使用します。

      opts = detectImportOptions(filename)

    構文

    opts = wordDocumentImportOptions
    opts = wordDocumentImportOptions('NumVariables',numVars)
    opts = wordDocumentImportOptions(___,Name,Value)

    説明

    opts = wordDocumentImportOptions は、1 つの変数をもつ WordDocumentImportOptions オブジェクトを作成します。

    opts = wordDocumentImportOptions('NumVariables',numVars) は、numVars で指定した数の変数をもつオブジェクトを作成します。

    例

    opts = wordDocumentImportOptions(___,Name,Value) は、1 つ以上の名前と値の引数を使用して、WordDocumentImportOptions オブジェクトの追加プロパティを指定します。

    入力引数

    すべて展開する

    変数の数。正のスカラー整数として指定します。

    プロパティ

    すべて展開する

    変数プロパティ

    変数名。文字ベクトルの cell 配列または string 配列として指定します。VariableNames プロパティには、変数のインポート時に使用する名前が含まれます。

    データに N 個の変数が含まれているが変数名が指定されない場合、VariableNames プロパティには {'Var1','Var2',...,'VarN'} が含まれます。

    スペースおよび非 ASCII 文字を含む変数名など、無効な MATLAB 識別子を変数名としてサポートするには、VariableNamingRule の値を 'preserve' に設定します。

    例: opts.VariableNames は、現在の (検出された) 変数名を返します。

    例: opts.VariableNames(3) = {'Height'} は 3 番目の変数の名前を Height に変更します。

    データ型: char | string | cell

    変数名を保持するかどうかのフラグ。"modify" または "preserve" として指定します。

    • "modify" — 無効な変数名 (関数 isvarname で判定) を、有効な MATLAB 識別子に変換。

    • "preserve" — スペースや非 ASCII 文字を含む変数名など、有効な MATLAB 識別子ではない変数名を保持。

    R2019b 以降、変数名と行名には、スペースや非 ASCII 文字など任意の文字を含めることができます。また、英字だけでなく任意の文字で始めることができます。変数名と行名は、有効な MATLAB 識別子 (関数 isvarname で判定) である必要はありません。これらの変数名と行名を保持するには、VariableNamingRule の値を "preserve" に設定します。VariableNamingRule の値を "modify" から "preserve" に変更すると、変数名が更新されなくなります。

    変数のデータ型。一連の有効なデータ型の名前を含む文字ベクトルの cell 配列または string 配列として指定します。VariableTypes プロパティは、変数のインポート時に使用するデータ型を指定します。

    VariableTypes プロパティを更新するには、関数 setvartype を使用します。

    例: opts.VariableTypes は、現在の変数のデータ型を返します。

    例: opts = setvartype(opts,'Height',{'double'}) は、変数 Height のデータ型を double に変更します。

    インポートする変数のサブセット。文字ベクトル、string スカラー、文字ベクトルの cell 配列、string 配列、または数値インデックスの配列として指定します。

    SelectedVariableNames は VariableNames プロパティに含まれる名前のサブセットでなければなりません。既定では、SelectedVariableNames には VariableNames プロパティからのすべての変数名が含まれます。つまり、すべての変数がインポートされることを意味します。

    特定の変数のみをインポートするには、SelectedVariableNames プロパティを使用します。SelectedVariableNames プロパティを使用して変数のサブセットを指定し、readtable を使用してそのサブセットのみをインポートします。

    スペースおよび非 ASCII 文字を含む変数名など、無効な MATLAB 識別子を変数名としてサポートするには、VariableNamingRule の値を 'preserve' に設定します。

    例: opts.SelectedVariableNames = {'Height','LastName'} は、インポート操作のために 2 つの変数 Height と LastName のみを選択します。

    例: opts.SelectedVariableNames = [1 5] は、インポート操作のために最初の変数と 5 番目の変数の 2 つの変数のみを選択します。

    例: T = readtable(filename,opts) は、opts オブジェクトの SelectedVariableNames プロパティで指定された変数のみを含む table を返します。

    データ型: uint16 | uint32 | uint64 | char | string | cell

    型固有の変数のインポート オプション。変数インポート オプション オブジェクトの配列として返されます。配列には、VariableNames プロパティで指定された各変数に対応するオブジェクトが含まれます。配列の各オブジェクトには、特定のデータ型でのデータのインポートをサポートするプロパティが含まれます。

    変数オプションは、数値、テキスト、logical、datetime または categorical のデータ型をサポートします。

    変数の現在の (または検出された) オプションをクエリするには、関数 getvaropts を使用します。

    変数にオプションを設定してカスタマイズするには、関数 setvaropts を使用します。

    例: opts.VariableOptions は、データの各変数に対応する VariableImportOptions オブジェクトの集合を返します。

    例: getvaropts(opts,'Height') は、変数 Height の VariableImportOptions オブジェクトを返します。

    例: opts = setvaropts(opts,'Height','FillValue',0) は変数 Height の FillValue プロパティを 0 に設定します。

    位置プロパティ

    table データの XPath 式。文字ベクトルまたは string スカラーとして指定します。読み取り関数は、これを使用して出力 table のデータを選択します。TableSelector には有効な XPath Version 1.0 の式を指定しなければなりません。

    次の表に、Microsoft Word ドキュメント ファイル内の table を選択するための XPath 式の例をいくつか示します。

    説明TableSelector
    テキスト "Cash dividends" を含む table"//w:tbl[contains(.,'Cash dividends')]"
    行数が 10 を超える 2 番目の table"//w:tbl[count(w:tr)>10][2]"
    ヘッダー cell が "Description" と完全に一致する table"//w:tbl[w:tr[1]/w:tc='Description']"

    例: 'TableSelector',"//w:tbl[contains(.,'Cash dividends')]"

    データの場所。正のスカラー整数または正のスカラー整数の N- 行 -2 列の配列として指定します。これらの形式の 1 つを使用して DataRows を指定します。

    次として指定

    説明

    n

    データが含まれる "最初の行" を指定します。n を使用して値を指定すると、DataRows プロパティの値が [n inf] に設定されます。インポート関数は n とファイル終端の間のすべての行を読み取ります。

    n はゼロより大きい正の整数にしなければなりません。

    [n1 n2]

    データが含まれる "行の範囲" を指定します。n1 はデータが含まれる最初の行で、n2 はデータが含まれる最後の行です。

    配列 [n1 n2] 内の値は非ゼロの正の整数で、n2 は n1 より大きくなければなりません。

    [n1 n2; n3 n4;...]

    "複数の行範囲" を指定して、N の異なる行範囲を含む N 行 2 列の配列で読み取ります。

    有効な複数の行範囲の配列は、次でなければなりません。

    • 行の範囲は昇順で指定する。すなわち、配列で指定された最初の行範囲は、他の行範囲より、ファイル内で先に出現する。

    • オーバーラップしない行範囲のみを含む。

    複数の行範囲を指定するときは、配列内で最後の行範囲の末尾を指定する場合にのみ Inf を使用します。たとえば、[1 3; 5 6; 8 Inf] とします。

    例: opts.DataRows = 5 は、DataRows プロパティを [5 inf] の値に設定します。行 5 からファイル終端までのデータ行をすべて読み取ります。

    例: opts.DataRows = [2 6] は、行 2 から行 6 までを読み取るプロパティを設定します。

    例: opts.DataRows = [1 3; 5 6; 8 inf] は 1、2、3、5、6 の各行と 8 からファイル終端までのすべての行を読み取るプロパティを設定します。

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

    行名の位置。正のスカラー整数として指定します。RowNamesColumn プロパティは行名を含む列の位置を指定します。

    RowNamesColumn を 0 として指定した場合は、行名をインポートしません。それ以外の場合、行名を指定された列からインポートします。

    例: opts.RowNamesColumn = 2;

    データ型: single | double | uint8 | uint16 | uint32 | uint64

    変数の名前を含む行。非負の整数として指定します。VariableNamesRow プロパティは変数名がある位置の行番号を指定します。

    VariableNamesRow が 0 の場合は、変数名をインポートしません。それ以外の場合、指定された行から変数名をインポートします。

    例: opts.VariableNamesRow = 6;

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

    変数の単位を含む行。非負の整数として指定します。

    VariableUnitsRow が 0 の場合、変数の単位はインポートされません。それ以外の場合、指定した行から変数の単位がインポートされます。

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

    変数の説明を含む行。非負の整数として指定します。

    VariableDescriptionsRow が 0 の場合、変数の説明はインポートされません。それ以外の場合、指定した行から変数の説明がインポートされます。

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

    置換ルール

    欠損データを管理する方法。次の表のいずれかの値として指定します。

    欠損ルール動作
    'fill'

    欠損データを FillValue プロパティの内容に置き換えます。

    FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、setvaropts を参照してください。

    'error'インポートを停止し、欠損しているレコードとフィールドを示すエラー メッセージを表示します。
    'omitrow'欠損データを含む行を除外します。
    'omitvar'欠損データを含む変数を除外します。

    例: opts.MissingRule = 'omitrow';

    データ型: char | string

    データ内の空行を処理する手続き。"skip"、"read"、または "error" として指定します。インポート関数は空白を空として解釈します。

    空行のルール動作
    "skip"空行をスキップします。
    "read"空行をインポートします。インポート関数は、VariableOptions、MissingRule、およびその他の関連するプロパティに指定された値を使用して、空の行を解析します。
    "error"エラー メッセージを表示し、インポート操作を中止します。

    インポート エラーを処理する方法。次の表のいずれかの値として指定します。

    インポート エラー ルール動作
    'fill'

    エラーが発生したデータを FillValue プロパティの内容に置き換えます。

    FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、setvaropts を参照してください。

    'error'インポートを停止し、エラーの原因となるレコードとフィールドを示すエラー メッセージを表示します。
    'omitrow'エラーが発生した行を除外します。
    'omitvar'エラーが発生した変数を除外します。

    例: opts.ImportErrorRule = 'omitvar';

    データ型: char | string

    データ内の余分な列を処理する方法。次の表のいずれかの値として指定します。

    余分な列のルール動作
    'addvars'

    余分な列をインポートするには、新しい変数を作成します。余分な列が N 列ある場合、新しい変数を 'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN' としてインポートします。データの余分な列は VariableTypes が char であるものとしてインポートされます。

    'ignore'データの余分な列を無視します。
    'wrap'データの余分な列を新しいレコードにラップします。このアクションで変数の数は変わりません。
    'error'エラー メッセージを表示し、インポート操作を中止します。

    データ型: char | string

    列がマージされたセルの処理方法。次の表のいずれかの値として指定します。

    インポート ルール動作
    "placeleft"

    一番左のセルにデータを配置し、残りのセルは FillValue プロパティの内容で埋めます。

    FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、getvaropts を参照してください。

    "placeright"

    一番右のセルにデータを配置し、残りのセルは FillValue プロパティの内容で埋めます。

    FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、getvaropts を参照してください。

    "duplicate"

    すべてのセルにデータを複製します。

    "omitrow"マージされたセルがある行を除外します。
    "error"エラー メッセージを表示し、インポート操作を中止します。

    例: "MergedCellColumnRule","placeright"

    行がマージされたセルの処理方法。次の表のいずれかの値として指定します。

    インポート ルール動作
    "placetop"

    一番上のセルにデータを配置し、残りのセルは FillValue プロパティの内容で埋めます。

    FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、getvaropts を参照してください。

    "placebottom"

    一番下のセルにデータを配置し、残りのセルは FillValue プロパティの内容で埋めます。

    FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、getvaropts を参照してください。

    "duplicate"

    すべてのセルにデータを複製します。

    "omitvar"行がマージされた変数を除外します。
    "error"エラー メッセージを表示し、インポート操作を中止します。

    例: "MergedCellRowRule","duplicate"

    オブジェクト関数

    例

    すべて折りたたむ

    ライブ スクリプトを開く

    Microsoft Word ドキュメント ファイルのインポート オプションを作成し、インポートする table を指定してから、データを読み取ります。

    ファイル MaintenanceReport.docx には table が 2 つ含まれています。2 つ目の table の最後の行に、table の変数と一致しない、列がマージされたセルがあります。

    WordDocumentImportOptions オブジェクトを作成します。

    • table から 5 つの変数を読み取ります。

    • XPath クエリ "//w:tbl[contains(.,'Description')]" を使用して、"Description" という単語を含む最初の table を読み取ります。

    • 最初の行から変数名を読み取ります。

    • 列がマージされたセルがある行の読み取りをスキップします。

    opts = wordDocumentImportOptions( ...
    'NumVariables',5, ...
    'TableSelector',"//w:tbl[contains(.,'Description')]", ...
    'VariableNamesRow',1, ...
    'MergedCellColumnRule','omitrow')
    opts = 
  WordDocumentImportOptions with properties:

   Replacement Properties:
                MissingRule: "fill"
            ImportErrorRule: "fill"
               EmptyRowRule: "skip"
       MergedCellColumnRule: "omitrow"
          MergedCellRowRule: "placetop"
           ExtraColumnsRule: "addvars"

   Variable Import Properties: Set types by name using setvartype
              VariableNames: ["Var1"    "Var2"    "Var3"    "Var4"    "Var5"]
              VariableTypes: ["char"    "char"    "char"    "char"    "char"]
      SelectedVariableNames: ["Var1"    "Var2"    "Var3"    "Var4"    "Var5"]
            VariableOptions: [1-by-5 matlab.io.VariableImportOptions] 
	Access VariableOptions sub-properties using setvaropts/getvaropts
         VariableNamingRule: "preserve"

   Location Properties:
              TableSelector: "//w:tbl[contains(.,'Description')]"
                   DataRows: [1 Inf]
           VariableNamesRow: 1
           VariableUnitsRow: 0
    VariableDescriptionsRow: 0
             RowNamesColumn: 0

    関数 readtable でオプション オブジェクトを使用して、Microsoft Word ドキュメント ファイルから table を読み取ります。

    filename = "MaintenanceReport.docx";
T = readtable(filename,opts)
    T=4×5 table
                                  Description                                         Category             Urgency           Resolution            Cost   
    _______________________________________________________________________    ______________________    ___________    ____________________    __________

    {'Description'                                                        }    {'Category'          }    {'Urgency'}    {'Resolution'      }    {'Cost'  }
    {'Items are occasionally getting stuck in the scanner spools.'        }    {'Mechanical Failure'}    {'Medium' }    {'Readjust Machine'}    {'$45'   }
    {'Loud rattling and banging sounds are coming from assembler pistons.'}    {'Mechanical Failure'}    {'Medium' }    {'Readjust Machine'}    {'$35'   }
    {'There are cuts to the power when starting the plant.'               }    {'Electronic Failure'}    {'High'   }    {'Full Replacement'}    {'$16200'}

    バージョン履歴

    R2021b で導入

    参考

    | |

    トピック