xmlImportOptions

XML ファイルのインポート オプション オブジェクト

R2021a 以降

説明

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

作成

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

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

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

  opts = detectImportOptions(filename)

構文

opts = xmlImportOptions

opts = xmlImportOptions('NumVariables',numVars)

opts = xmlImportOptions(___,Name,Value)

説明

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

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

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

入力引数

numVars — 変数の数

正のスカラー整数

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

プロパティ

変数プロパティ

VariableNames — 変数名

文字ベクトルの cell 配列 | string 配列

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

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

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

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

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

データ型: char | string | cell

VariableNamingRule — 変数名を保持するかどうかのフラグ

"modify" (既定値) | "preserve"

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

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

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

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

データ型: char | string

VariableTypes — 変数のデータ型

文字ベクトルの cell 配列 | string 配列

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

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

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

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

SelectedVariableNames — インポートする変数のサブセット

文字ベクトル | string スカラー | 文字ベクトルの cell 配列 | string 配列 | 数値インデックスの配列

インポートする変数のサブセット。文字ベクトル、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

VariableOptions — 型固有の変数のインポート オプション

変数インポート オプション オブジェクトの配列

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

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

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

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

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

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

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

VariableDescriptionsSelector — 変数の説明の XPath 式

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

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

例: 'VariableDescriptionsSelector','/RootNode/ChildNode'

VariableSelectors — table 変数の XPath 式

文字ベクトルの cell 配列 | string 配列

table 変数の XPath 式。文字ベクトルの cell 配列または string 配列として指定します。読み取り関数は、これを使用して table 変数を選択します。VariableSelectors には有効な XPath Version 1.0 の式を指定しなければなりません。

例: 'VariableSelectors',{'/RootNode/ChildNode'}

例: 'VariableSelectors',"/RootNode/ChildNode"

例: 'VariableSelectors',["/RootNode/ChildNode1","/RootNode/ChildNode2"]

VariableUnitsSelector — 変数の単位の XPath 式

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

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

例: 'VariableUnitsSelector','/RootNode/ChildNode'

table プロパティ

RowNamesSelector — table 行の名前の XPath 式

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

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

例: 'RowNamesSelector','/RootNode/ChildNode'

RowSelector — table 行の XPath 式

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

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

例: 'RowSelector','/RootNode/ChildNode'

TableSelector — table データの XPath 式

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

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

例: 'TableSelector','/RootNode/ChildNode'

RegisteredNamespaces — 登録済みの XML 名前空間接頭辞のセット

string 配列

登録済みの XML 名前空間接頭辞のセット。RegisteredNamespaces と接頭辞の配列で構成されるコンマ区切りのペアとして指定します。読み取り関数は、XML ファイルの XPath 式を評価する際にこれらの接頭辞を使用します。名前空間接頭辞とそれに関連付けられた URL を N 行 2 列の string 配列として指定します。RegisteredNamespaces は、readstruct の StructSelector や readtable と readtimetable の VariableSelectors など、セレクターの名前と値の引数で指定された XPath 式も評価する場合に使用できます。

既定では、読み取り関数は XPath の評価に使用する名前空間接頭辞を自動的に検出して登録しますが、名前と値の引数 RegisteredNamespaces を使用して新しい名前空間接頭辞を登録することもできます。新しい名前空間接頭辞の登録は、名前空間 URL がある XML ノードについて、XML ファイルで名前空間接頭辞が宣言されていない場合などに便利です。

たとえば、名前空間接頭辞が含まれていない example.xml という名前の XML ファイルの XPath 式を評価するとします。'RegisteredNamespaces' を ["myprefix", "https://www.mathworks.com"] と指定して、接頭辞 myprefix を URL https://www.mathworks.com に割り当てます。

T = readtable("example.xml", "VariableSelector", "/myprefix:Data",...
 "RegisteredNamespaces", ["myprefix", "https://www.mathworks.com"])

例: 'RegisteredNamespaces',["myprefix", "https://www.mathworks.com"]

置換ルール

MissingRule — 欠損データを管理する方法

'fill' (既定値) | 'error' | 'omitrow' | 'omitvar'

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

欠損ルール	動作
'fill'	欠損データを FillValue プロパティの内容に置き換えます。 FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、setvaropts を参照してください。
'error'	インポートを停止し、欠損しているレコードとフィールドを示すエラー メッセージを表示します。
'omitrow'	欠損データを含む行を除外します。
'omitvar'	欠損データを含む変数を除外します。

例: opts.MissingRule = 'omitrow';

データ型: char | string

ImportErrorRule — インポート エラーを処理する方法

'fill' (既定値) | 'error' | 'omitrow' | 'omitvar'

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

インポート エラー ルール	動作
'fill'	エラーが発生したデータを FillValue プロパティの内容に置き換えます。 FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、setvaropts を参照してください。
'error'	インポートを停止し、エラーの原因となるレコードとフィールドを示すエラー メッセージを表示します。
'omitrow'	エラーが発生した行を除外します。
'omitvar'	エラーが発生した変数を除外します。

例: opts.ImportErrorRule = 'omitvar';

データ型: char | string

RepeatedNodeRule — 繰り返し XML ノードの処理方法

'addcol' (既定値) | 'ignore' | 'error'

table の特定の行における繰り返し XML ノードの処理方法。'addcol'、'ignore'、または 'error' として指定します。

繰り返しノードの規則	動作
'addcol'	table の変数ヘッダーの下に繰り返しノード用の列を追加します。'RepeatedNodeRule' の値を 'addcol' と指定しても、table に繰り返しノードに対する別個の変数は作成されません。
'ignore'	繰り返しノードはスキップしてインポートします。
'error'	エラー メッセージを表示し、インポート操作を中止します。

例: 'RepeatedNodeRule','ignore'

例

インポート オプションを使用した XML ファイルの読み込み

XML ファイル用の XML インポート オプションを作成し、インポートする変数を指定してから、データを読み取ります。

XML ファイル students.xml には、Student という名前の 4 つの兄弟ノードがあり、それぞれに同じ子ノードと属性が含まれています。

type students.xml

<?xml version="1.0" encoding="utf-8"?>
<Students>
    <Student ID="S11305">
        <Name FirstName="Priya" LastName="Thompson" />
        <Age>18</Age>
        <Year>Freshman</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">591 Spring Lane</Street>
            <City>Natick</City>
            <State>MA</State>
      </Address>
      <Major>Computer Science</Major>
      <Minor>English Literature</Minor>
   </Student>
   <Student ID="S23451">
        <Name FirstName="Conor" LastName="Cole" />
        <Age>18</Age>
        <Year>Freshman</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">4641 Pearl Street</Street>
            <City>San Francisco</City>
            <State>CA</State>
        </Address>
        <Major>Microbiology</Major>
        <Minor>Public Health</Minor>
    </Student>
    <Student ID="S119323">
        <Name FirstName="Morgan" LastName="Yang" />
        <Age>21</Age>
        <Year>Senior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">30 Highland Road</Street>
            <City>Detriot</City>
            <State>MI</State>
        </Address>
        <Major>Political Science</Major>
   </Student>
   <Student ID="S201351">
        <Name FirstName="Salim" LastName="Copeland" />
        <Age>19</Age>
        <Year>Sophomore</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">3388 Moore Avenue</Street>
            <City>Fort Worth</City>
            <State>TX</State>
        </Address>
        <Major>Business</Major>
        <Minor>Japanese Language</Minor>
   </Student>
   <Student ID="S201351">
        <Name FirstName="Salim" LastName="Copeland" />
        <Age>20</Age>
        <Year>Sophomore</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">3388 Moore Avenue</Street>
            <City>Fort Worth</City>
            <State>TX</State>
        </Address>
        <Major>Business</Major>
        <Minor>Japanese Language</Minor>
    </Student>
    <Student ID="54600">
        <Name FirstName="Dania" LastName="Burt" />
        <Age>22</Age>
        <Year>Senior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">22 Angie Drive</Street>
            <City>Los Angeles</City>
            <State>CA</State>
        </Address>
        <Major>Mechanical Engineering</Major>
        <Minor>Architecture</Minor>
   </Student>
    <Student ID="453197">
        <Name FirstName="Rikki" LastName="Gunn" />
        <Age>21</Age>
        <Year>Junior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">65 Decatur Lane</Street>
            <City>Trenton</City>
            <State>ME</State>
        </Address>
        <Major>Economics</Major>
        <Minor>Art History</Minor>
   </Student>
</Students>

ファイルから XMLImportOptions オブジェクトを作成します。VariableSelectors の値を //@FirstName と指定して、FirstName 要素ノードを table 変数としてインポートするように選択します。

opts = xmlImportOptions("VariableSelectors","//@FirstName");

readtable をオプション オブジェクトと共に使用して、指定した変数をインポートします。

T = readtable("students.xml",opts)

T=7×1 table
       Var1   
    __________

    {'Priya' }
    {'Conor' }
    {'Morgan'}
    {'Salim' }
    {'Salim' }
    {'Dania' }
    {'Rikki' }

XML ファイルの table としての読み取り

XML ファイルの内容を table にインポートします。

students.xml ファイルには、Student という名前の 7 つの兄弟ノードがあり、それぞれに同じ子ノードと属性が含まれています。

type students.xml

<?xml version="1.0" encoding="utf-8"?>
<Students>
    <Student ID="S11305">
        <Name FirstName="Priya" LastName="Thompson" />
        <Age>18</Age>
        <Year>Freshman</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">591 Spring Lane</Street>
            <City>Natick</City>
            <State>MA</State>
      </Address>
      <Major>Computer Science</Major>
      <Minor>English Literature</Minor>
   </Student>
   <Student ID="S23451">
        <Name FirstName="Conor" LastName="Cole" />
        <Age>18</Age>
        <Year>Freshman</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">4641 Pearl Street</Street>
            <City>San Francisco</City>
            <State>CA</State>
        </Address>
        <Major>Microbiology</Major>
        <Minor>Public Health</Minor>
    </Student>
    <Student ID="S119323">
        <Name FirstName="Morgan" LastName="Yang" />
        <Age>21</Age>
        <Year>Senior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">30 Highland Road</Street>
            <City>Detriot</City>
            <State>MI</State>
        </Address>
        <Major>Political Science</Major>
   </Student>
   <Student ID="S201351">
        <Name FirstName="Salim" LastName="Copeland" />
        <Age>19</Age>
        <Year>Sophomore</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">3388 Moore Avenue</Street>
            <City>Fort Worth</City>
            <State>TX</State>
        </Address>
        <Major>Business</Major>
        <Minor>Japanese Language</Minor>
   </Student>
   <Student ID="S201351">
        <Name FirstName="Salim" LastName="Copeland" />
        <Age>20</Age>
        <Year>Sophomore</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">3388 Moore Avenue</Street>
            <City>Fort Worth</City>
            <State>TX</State>
        </Address>
        <Major>Business</Major>
        <Minor>Japanese Language</Minor>
    </Student>
    <Student ID="54600">
        <Name FirstName="Dania" LastName="Burt" />
        <Age>22</Age>
        <Year>Senior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">22 Angie Drive</Street>
            <City>Los Angeles</City>
            <State>CA</State>
        </Address>
        <Major>Mechanical Engineering</Major>
        <Minor>Architecture</Minor>
   </Student>
    <Student ID="453197">
        <Name FirstName="Rikki" LastName="Gunn" />
        <Age>21</Age>
        <Year>Junior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">65 Decatur Lane</Street>
            <City>Trenton</City>
            <State>ME</State>
        </Address>
        <Major>Economics</Major>
        <Minor>Art History</Minor>
   </Student>
</Students>

まず、detectImportOptions を使用して XMLImportOptions オブジェクトを作成し、XML ファイルの要素を検出します。Street 要素ノードの XPath 式として名前と値の引数 VariableSelectors を指定して、道路名だけを table に読み取ります。名前と値の引数 RegisteredNamespaces を設定して、既存の名前空間の URL にカスタムの名前空間接頭辞を登録します。

opts = detectImportOptions("students.xml",RegisteredNamespaces=["myPrefix","https://www.mathworks.com"], ...
    VariableSelectors="//myPrefix:Street");

次に、インポート オプション オブジェクトを指定して readtable を使用し、指定した変数をインポートします。

T = readtable("students.xml",opts)

T=7×1 table
          Street       
    ___________________

    "591 Spring Lane"  
    "4641 Pearl Street"
    "30 Highland Road" 
    "3388 Moore Avenue"
    "3388 Moore Avenue"
    "22 Angie Drive"   
    "65 Decatur Lane"  

ヒント

• インポートする XML 入力文書の要素を指定するには、XPath セレクターを使用します。たとえば、次の構造の XML ファイル myFile.xml をインポートするとします。

  <data>
      <table category="ones">
          <var>1</var>
          <var>2</var>
      </table>
      <table category="tens">
          <var>10</var>
          <var>20</var>
      </table>
  </data>
  

  次の表に、VariableSelectors や TableSelector などの XPath セレクターの名前と値の引数でサポートされる XPath 構文を示します。

  選択操作	構文	例	結果
  文書内の場所に関係なく、選択するノードに名前が一致するすべてのノードを選択する。	名前の前にスラッシュを 2 つ (//) 付ける。	data = readtable('myFile.xml', 'VariableSelectors', '//var')	data = 4×1 table var ___ 1 2 10 20
  要素ノードに属する属性の値を読み取る。	属性の前にアット マーク (@) を付ける。	data = readtable('myFile.xml', 'VariableSelectors', '//table/@category')	data = 2×1 table categoryAttribute _________________ "ones" "tens"
  一連のノードから特定のノードを選択する。	選択するノードのインデックスを大かっこ ([]) で囲んで指定する。	data = readtable('myFile.xml', 'TableSelector', '//table[1]')	data = 2×1 table var ___ 1 2
  演算の優先順位を指定する。	最初に評価する式を小かっこで囲む。	data = readtable('myFile.xml', 'VariableSelectors', '//table/var[1]')	data = 2×1 table var ___ 1 10
  		data = readtable('myFile.xml', 'VariableSelectors', '(//table/var)[1]')	data = table var ___ 1

バージョン履歴

R2021a で導入

参考

detectImportOptions | readtable | readtimetable