outerjoin

2 つの table または timetable の間の外部連結

構文

T = outerjoin(Tleft,Tright)

T = outerjoin(Tleft,Tright,Name,Value)

[T,ileft,iright] = outerjoin(___)

説明

T = outerjoin(Tleft,Tright) は、キー変数を使用し、Tleft と Tright の "外部連結" として table または timetable、T を作成します。外部連結は、キー変数の値が一致しているテーブルの行を組み合わせますが、一方の入力 table のキー変数が他方の入力 table のキー変数と一致していない行も含みます。たとえば、Tleft に Key1 と Var1 という名前の変数があり、Tright に変数 Key1 と Var2 がある場合、T=outerjoin(Tleft,Tright) は Key1 をキー変数として使用します。

既定では、キー変数は次のとおりです。

• 両方の入力が table であるか、Tleft が timetable で Tright が table の場合は、Tleft と Tright 内の同じ名前の変数。

• Tleft と Tright がともに timetable である場合は、行時間のベクトル。

一致しているキー変数の値の順序は、左右のテーブルで同じである必要はありません。外部連結は、2 つのテーブルのキー変数の間で 1 対多と多対 1 の照合を実行できます。つまり、左のテーブルのキー変数に 1 回出現する値について、一致する値が右のテーブルに複数存在できます。同様に、右のテーブルのキー変数に 1 回出現する値について、一致する値が左のテーブルの複数存在できます。

外部連結は table と timetable の特定の組み合わせでしか実行できません。

• Tleft が table の場合、Tright は table でなければなりません。outerjoin は T を table として返します。

• Tleft が timetable の場合、Tright は table と timetable のいずれかにできます。outerjoin はいずれかの入力の組み合わせに対して timetable として T を返します。

T = outerjoin(Tleft,Tright,Name,Value) は、1 つ以上の Name,Value のペア引数で指定された追加オプションを使用して外部連結操作を実行します。

[T,ileft,iright] = outerjoin(___) は、インデックス ベクトル ileft および iright も返します。これらのベクトルは、T の行と Tleft および Tright の行の間の対応をそれぞれ示します。この構文では、前述の構文の入力引数のいずれかを使用できます。

例

1 つの変数を共有するテーブルの外部連結操作

table Tleft を作成します。

Tleft = table([5;12;23;2;15;6],...
        {'cheerios';'pizza';'salmon';'oreos';'lobster';'pizza'},...
        'VariableNames',{'Age','FavoriteFood'},...
        'RowNames',{'Amy','Bobby','Holly','Harry','Marty','Sally'})

Tleft=6×2 table
             Age    FavoriteFood
             ___    ____________

    Amy       5     {'cheerios'}
    Bobby    12     {'pizza'   }
    Holly    23     {'salmon'  }
    Harry     2     {'oreos'   }
    Marty    15     {'lobster' }
    Sally     6     {'pizza'   }

FavoriteFood という 1 つの変数を Tleft と共有するテーブル Tright を作成します。

Tright = table({'cheerios';'oreos';'pizza';'salmon';'cake'},...
         [110;160;140;367;243],...
         {'A-';'D';'B';'B';'C-'},...
         'VariableNames',{'FavoriteFood','Calories','NutritionGrade'})

Tright=5×3 table
    FavoriteFood    Calories    NutritionGrade
    ____________    ________    ______________

    {'cheerios'}      110           {'A-'}    
    {'oreos'   }      160           {'D' }    
    {'pizza'   }      140           {'B' }    
    {'salmon'  }      367           {'B' }    
    {'cake'    }      243           {'C-'}    

関数 outerjoin を使用して、テーブル Tleft および Tright のデータを含む新規テーブル T を作成します。

T = outerjoin(Tleft,Tright)

T=7×5 table
    Age    FavoriteFood_Tleft    FavoriteFood_Tright    Calories    NutritionGrade
    ___    __________________    ___________________    ________    ______________

    NaN       {0×0 char  }          {'cake'    }          243         {'C-'    }  
      5       {'cheerios'}          {'cheerios'}          110         {'A-'    }  
     15       {'lobster' }          {0×0 char  }          NaN         {0×0 char}  
      2       {'oreos'   }          {'oreos'   }          160         {'D'     }  
     12       {'pizza'   }          {'pizza'   }          140         {'B'     }  
      6       {'pizza'   }          {'pizza'   }          140         {'B'     }  
     23       {'salmon'  }          {'salmon'  }          367         {'B'     }  

テーブル T には、Tleft のキー変数 FavoriteFood_Tleft、Tright のキー変数 FavoriteFood_Tright に対応する別々の変数が含まれています。

キー変数ペアの 1 つの変数へのマージ

table Tleft を作成します。

Tleft = table({'a' 'b' 'c' 'e' 'h'}',[1 2 3 11 17]',...
        'VariableNames',{'Key1' 'Var1'})

Tleft=5×2 table
    Key1     Var1
    _____    ____

    {'a'}      1 
    {'b'}      2 
    {'c'}      3 
    {'e'}     11 
    {'h'}     17 

変数 Key1 に table Tleft と共通する値をもつ table Tright を作成します。ただし、table Tright には、Tleft には存在しない Key1 の値を含む行もあります。

Tright = table({'a','b','d','e'}',[4;5;6;7],...
         'VariableNames',{'Key1' 'Var2'})

Tright=4×2 table
    Key1     Var2
    _____    ____

    {'a'}     4  
    {'b'}     5  
    {'d'}     6  
    {'e'}     7  

関数 outerjoin を使用して、テーブル Tleft および Tright のデータを含む新規テーブル T を作成します。出力テーブル T の 1 つの変数にキー値をマージします。

T = outerjoin(Tleft,Tright,'MergeKeys',true)

T=6×3 table
    Key1     Var1    Var2
    _____    ____    ____

    {'a'}      1       4 
    {'b'}      2       5 
    {'c'}      3     NaN 
    {'d'}    NaN       6 
    {'e'}     11       7 
    {'h'}     17     NaN 

Tleft から取得したテーブル T の変数では、Tright と一致しない行に欠損値が含まれます。同様に、Tright から取得した T の変数では、Tleft と一致しなかった行に欠損値が含まれます。

テーブルの外部連結操作と値へのインデックス

table Tleft を作成します。

Tleft = table({'a' 'b' 'c' 'e' 'h'}',[1 2 3 11 17]',...
        'VariableNames',{'Key1' 'Var1'})

Tleft=5×2 table
    Key1     Var1
    _____    ____

    {'a'}      1 
    {'b'}      2 
    {'c'}      3 
    {'e'}     11 
    {'h'}     17 

変数 Key1 に table Tleft と共通する値をもつ table Tright を作成します。ただし、table Tright には、Tleft には存在しない Key1 の値を含む行もあります。

Tright = table({'a','b','d','e'}',[4;5;6;7],...
         'VariableNames',{'Key1' 'Var2'})

Tright=4×2 table
    Key1     Var2
    _____    ____

    {'a'}     4  
    {'b'}     5  
    {'d'}     6  
    {'e'}     7  

関数 outerjoin を使用して、テーブル Tleft および Tright のデータを含む新規テーブル T を作成します。キー変数 Key1 に共通の値がある行を一致させますが、キー値が一致しない行も保持します。

また、インデックス ベクトル ileft および iright が返されます。これらのベクトルは、T の行と Tleft および Tright の行の間の対応をそれぞれ示します。

[T,ileft,iright] = outerjoin(Tleft,Tright)

T=6×4 table
    Key1_Tleft    Var1    Key1_Tright    Var2
    __________    ____    ___________    ____

    {'a'     }      1     {'a'     }       4 
    {'b'     }      2     {'b'     }       5 
    {'c'     }      3     {0×0 char}     NaN 
    {0×0 char}    NaN     {'d'     }       6 
    {'e'     }     11     {'e'     }       7 
    {'h'     }     17     {0×0 char}     NaN 

ileft = 6×1

     1
     2
     3
     0
     4
     5

iright = 6×1

     1
     2
     0
     3
     4
     0

インデックス ベクトル ileft および iright には、それぞれテーブル Tleft または Tright の行に対応しないテーブル T の行を示すゼロが含まれます。

テーブルの左外部連結操作と値へのインデックス

table Tleft を作成します。

Tleft = table({'a' 'b' 'c' 'e' 'h'}',[1 2 3 11 17]',...
        'VariableNames',{'Key1' 'Var1'})

Tleft=5×2 table
    Key1     Var1
    _____    ____

    {'a'}      1 
    {'b'}      2 
    {'c'}      3 
    {'e'}     11 
    {'h'}     17 

変数 Key1 に table Tleft と共通する値をもつ table Tright を作成します。ただし、table Tright には、Tleft には存在しない Key1 の値を含む行もあります。

Tright = table({'a','b','d','e'}',[4;5;6;7],...
         'VariableNames',{'Key1' 'Var2'})

Tright=4×2 table
    Key1     Var2
    _____    ____

    {'a'}     4  
    {'b'}     5  
    {'d'}     6  
    {'e'}     7  

関数 outerjoin を使用して、テーブル Tleft および Tright のデータを含む新規テーブル T を作成します。キー値が Tleft の行と一致しない Tright の行を無視します。

また、インデックス ベクトル ileft および iright が返されます。これらのベクトルは、T の行と Tleft および Tright の行の間の対応をそれぞれ示します。

[T,ileft,iright] = outerjoin(Tleft,Tright,'Type','left')

T=5×4 table
    Key1_Tleft    Var1    Key1_Tright    Var2
    __________    ____    ___________    ____

      {'a'}         1     {'a'     }       4 
      {'b'}         2     {'b'     }       5 
      {'c'}         3     {0×0 char}     NaN 
      {'e'}        11     {'e'     }       7 
      {'h'}        17     {0×0 char}     NaN 

ileft = 5×1

     1
     2
     3
     4
     5

iright = 5×1

     1
     2
     0
     4
     0

ileft のすべての値は非ゼロであり、T のすべての行に Tleft に対応する行があることを示しています。

timetable の外部連結操作

2 つの timetable、Tleft と Tright を作成します。これらには共通する行時間がいくつかありますが、各 timetable には他方の timetable にはない行時間も含まれています。

Tleft = timetable(seconds([1;2;4;6]),[1 2 3 11]')

Tleft=4×1 timetable
    Time     Var1
    _____    ____

    1 sec      1 
    2 sec      2 
    4 sec      3 
    6 sec     11 

Tright = timetable(seconds([2;4;6;7]),[4 5 6 7]')

Tright=4×1 timetable
    Time     Var1
    _____    ____

    2 sec     4  
    4 sec     5  
    6 sec     6  
    7 sec     7  

外部連結で Tleft と Tright を組み合わせます。T1 は共通の行時間をもつ行を一致させますが、一致のない行も含みます。

T1 = outerjoin(Tleft,Tright)

T1=5×2 timetable
    Time     Var1_Tleft    Var1_Tright
    _____    __________    ___________

    1 sec         1            NaN    
    2 sec         2              4    
    4 sec         3              5    
    6 sec        11              6    
    7 sec       NaN              7    

Tleft と Tright を組み合わせ、Tleft のいずれの行時間にも一致しない行時間をもつ Tright の行は無視します。

T2 = outerjoin(Tleft,Tright,'Type','left')

T2=4×2 timetable
    Time     Var1_Tleft    Var1_Tright
    _____    __________    ___________

    1 sec         1            NaN    
    2 sec         2              4    
    4 sec         3              5    
    6 sec        11              6    

入力引数

Tleft — 左のテーブル

table | timetable

左のテーブル。table または timetable として指定します。

Tright — 右のテーブル

table | timetable

右のテーブル。table または timetable として指定します。

名前と値の引数

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

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

例: 'Keys',2 は、Tleft の 2 番目の変数と Tright の 2 番目の変数をキー変数として使用します。

Keys — キーとして使用する変数

正の整数 | 正の整数のベクトル | string 配列 | 文字ベクトル | 文字ベクトルの cell 配列 | pattern スカラー | logical ベクトル

キーとして使用する変数。'Keys' と、正の整数、正の整数のベクトル、string 配列、文字ベクトル、文字ベクトルの cell 配列、pattern スカラー、または logical ベクトルのいずれかで構成される、コンマ区切りのペアとして指定します。

名前と値のペアの引数 'Keys' を名前と値のペアの引数 'LeftKeys' および 'RightKeys' と共に使用することはできません。

行ラベルのベクトルをキーにすることができます。詳細については、アルゴリズムの節を参照してください。

例: 'Keys',[1 3] は、Tleft と Tright の最初の変数と 3 番目の変数をキー変数として使用します。

例: 'Keys',{'X','Y'} は、Tleft と Tright の X と Y という名前の変数をキー変数として使用します。

例: 'Keys','Row' は、Tleft と Tright の両方が行名をもつ table の場合、Tleft と Tright の行名のベクトルをキー変数として使用します。

LeftKeys — Tleft でキーとして使用する変数

正の整数 | 正の整数のベクトル | string 配列 | 文字ベクトル | 文字ベクトルの cell 配列 | pattern スカラー | logical ベクトル

Tleft でキーとして使用する変数。'LeftKeys' と、正の整数、正の整数のベクトル、string 配列、文字ベクトル、文字ベクトルの cell 配列、pattern スカラー、または logical ベクトルのいずれかで構成される、コンマ区切りのペアとして指定します。

名前と値のペアの引数 'LeftKeys' は名前と値のペアの引数 'RightKeys' と組み合わせて使用しなければなりません。'LeftKeys' および 'RightKeys' では、同じ数のキー変数を指定しなければなりません。outerjoin は、キーの値をその順序に基づいて組み合わせます。

行ラベルのベクトルをキーにすることができます。詳細については、アルゴリズムの節を参照してください。

例: 'LeftKeys',1 は、Tleft の最初の変数のみをキー変数として使用します。

RightKeys — Tright でキーとして使用する変数

正の整数 | 正の整数のベクトル | string 配列 | 文字ベクトル | 文字ベクトルの cell 配列 | pattern スカラー | logical ベクトル

Tright でキーとして使用する変数。'RightKeys' と、正の整数、正の整数のベクトル、string 配列、文字ベクトル、文字ベクトルの cell 配列、pattern スカラー、または logical ベクトルのいずれかで構成される、コンマ区切りのペアとして指定します。

名前と値のペアの引数 'RightKeys' は名前と値のペアの引数 'LeftKeys' と組み合わせて使用しなければなりません。'LeftKeys' および 'RightKeys' では、同じ数のキー変数を指定しなければなりません。outerjoin は、キーの値をその順序に基づいて組み合わせます。

行ラベルのベクトルをキーにすることができます。詳細については、アルゴリズムの節を参照してください。

例: 'RightKeys',3 は、Tright の 3 番目の変数のみをキー変数として使用します。

MergeKeys — キーのマージ フラグ

false (既定値) | true | 0 | 1

キーのマージ フラグ。'MergeKeys' と false、true、0 または 1 で構成されるコンマ区切りのペアとして指定します。

false	outerjoin は、テーブル Tleft と Tright からの各キー変数ペアに対して別々の 2 つの変数を出力テーブル T に含めます。 この動作は既定の動作です。
true	outerjoin は、テーブル Tleft と Tright からの各キー変数ペアに対して 1 つの変数を出力テーブル T に含めます。 outerjoin は Tleft と Tright からキー値をマージすることで 1 つの変数を作成します。Tleft に対応する行が存在する場合は Tleft から、そうでない場合は Tright から値を取ります。 'LeftVariables' または 'RightVariables' を指定してキー変数ペアから 1 つのキーのみを含める場合、outerjoin はマージしたキー (両方のキー変数の値を含む) を出力テーブルに含めます。 'LeftVariables' および 'RightVariables' を指定して、キー変数ペアからキーを両方とも除外した場合、outerjoin はマージしたキー変数を出力テーブルに含めません。

LeftVariables — T に含める Tleft の変数

正の整数 | 正の整数のベクトル | string 配列 | 文字ベクトル | 文字ベクトルの cell 配列 | pattern スカラー | logical ベクトル

T に含める Tleft の変数。'LeftVariables' と、正の整数、正の整数のベクトル、string 配列、文字ベクトル、文字ベクトルの cell 配列、pattern スカラー、または logical ベクトルのいずれかで構成される、コンマ区切りのペアとして指定します。

'LeftVariables' を使用すると、キー変数と出力 T の非キー変数を含めたり除外したりできます。

既定で、outerjoin には Tleft のすべての変数が含まれます。

RightVariables — T に含める Tright の変数

正の整数 | 正の整数のベクトル | string 配列 | 文字ベクトル | 文字ベクトルの cell 配列 | pattern スカラー | logical ベクトル

T に含める Tright の変数。'RightVariables' と、正の整数、正の整数のベクトル、string 配列、文字ベクトル、文字ベクトルの cell 配列、pattern スカラー、または logical ベクトルのいずれかで構成される、コンマ区切りのペアとして指定します。

'RightVariables' を使用すると、キー変数と出力 T の非キー変数を含めたり除外したりできます。

既定では、outerjoin には Tright のすべての変数が含まれます。

Type — 外部連結操作のタイプ

'full' (既定値) | 'left' | 'right'

外部連結操作のタイプ。'Type' と、'full' (完全外部連結)、'left' (左外部連結) または 'right' (右外部連結) のいずれかで構成されるコンマ区切りのペアとして指定します。

• 入力 Tleft と Tright の完全外部連結では、出力 T は両方の入力のすべての行を組み合わせ、空の table 要素を欠損値で埋めます。

  

• 左外部連結では、出力 T は Tleft のすべての行を含みますが、キー値が Tleft のいずれのキー値とも一致しない Tright の行は除外します。

  

• 右外部連結では、T は Tright のすべての行を含みますが、キー値が Tright のいずれのキー値とも一致しない Tleft の行は除外します。

  

既定では、outerjoin は完全な外部連結を行い、Tleft と Tright の両方からの一致しない行を含みます。

出力引数

T — Tleft と Tright からの外部連結

table

Tleft と Tright からの外部連結。テーブルとして返されます。出力テーブル T には、キー値の同じ組み合わせを共有するテーブル Tleft と Tright の行のペアごとに 1 つの行が格納されます。Tleft と Tright に同じ名前の変数がある場合、outerjoin は T の対応する変数名に一意の接尾辞を追加します。Tleft から取得した T の変数では、Tright と一致しなかった行に欠損値が含まれます。同様に、Tright から取得した T の変数では、Tleft と一致しなかった行に欠損値が含まれます。

(欠損値は、NaN、NaT、空の string、未定義の categorical 値など、さまざまなデータ型の "非数" と同等です。)

一般に、キー変数の値の組み合わせがすべて同じ行がテーブル Tleft に m 行、テーブル Tright に n 行存在する場合、テーブル T にはその組み合わせの行が m*n 行格納されます。T にはまた、各入力 table のキー値の組み合わせのうち、もう一方の入力 table の行と一致しないものに対応する行も格納されます。

T は、キー変数の値で並べ替えられた Tleft(ileft,LeftVars) と Tright(iright,RightVars) の水平連結を格納します。既定では、LeftVars は Tleft のすべての変数で構成され、RightVars は Tright のすべての変数で構成されます。そうでない場合、LeftVars は名前と値のペアの引数 'LeftVariables' で指定された変数で構成され、RightVars は名前と値のペアの引数 'RightVariables' で指定された変数で構成されます。

テーブルには、説明、変数単位、変数名、行名などの追加のメタデータを格納できます。詳細については、table のプロパティの節を参照してください。

ileft — Tleft のインデックス

列ベクトル

Tleft のインデックス。列ベクトルとして返されます。ileft の各要素は、出力テーブル T の行に対応するテーブル Tleft の行を示します。ベクトル ileft には、Tleft の行に対応しない T の行を示すゼロが含まれます。

iright — Tright のインデックス

列ベクトル

Tright のインデックス。列ベクトルとして返されます。iright の各要素は、出力テーブル T の行に対応するテーブル Tright の行を示します。ベクトル iright には、Tright の行に対応しない T の行を示すゼロが含まれます。

詳細

キー変数

入力 table Tleft および Tright 間のデータの照合と結合に使用される変数。

アルゴリズム

• 入力 table または timetable からの行ラベルのベクトルをキー変数として使用できます。行ラベルは、table の行名または timetable の行時間です。このベクトルをキーとして使用するには、(table の行名に対して) 'Row' として、行時間の timetable ベクトルの名前として、または T.Properties.DimensionNames{1} の値として指定します。ここで T は table または timetable です。

  一般的に、outerjoin は、入力 table Tleft から出力 table T に行ラベルをコピーします。

  • Tleft に行ラベルがない場合、T に行ラベルはありません。

  • Tleft に行ラベルがある場合、outerjoin は Tleft から行ラベルをコピーして T に行ラベルを作成します。

    • Tleft と Tright の両方からの行ラベルをキーの組として指定した場合、outerjoin は必要に応じて Tright からの行ラベルを T からの行ラベルにマージします。

    • Tleft の行ラベルをキーとして指定し、Tright の行ラベルをマッチング キーとして指定しなかった場合、outerjoin は必要に応じて T に既定の行ラベルを作成します。通常、既定の行ラベルは NaN または欠損値です。

    • Tleft と Tright の両方が table であるが、いずれの入力の行名もキーとして指定しなかった場合、outerjoin は T に行名を作成しません。

    • Tleft と Tright の両方が timetable であるが、どちらの入力の行時間もキーとして指定しなかった場合、outerjoin は Tleft から T に行時間をコピーします。また、必要に応じて、行時間として NaN または NaT が埋められます。

  Tleft の行ラベルを左キー、Tright の変数を右キーに使用して外部連結を実行することはできません。外部連結を実行するには、Tleft の行ラベルを table 変数に変換して、この新しい table 変数をキーとして使用します。

拡張機能

tall 配列

メモリの許容量を超えるような多数の行を含む配列を計算します。

outerjoin 関数は tall 配列を完全にサポートしています。詳細については、tall 配列を参照してください。

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限:

• 'MergeKeys' の値が true (logical 1) でない場合、入力 table に同じ名前のキー変数を含めることはできません。

• 通常、入力 table に同じ名前の非キー変数を含めることはできません。ただし、名前と値の引数 'LeftVariables' および 'RightVariables' を指定すると、入力 table のサブセットを連結できます。これらの引数を 'LeftVariables' と 'RightVariables' の両方に含まれる変数名がないようにして指定します。

• 以下の名前と値の引数の値は定数でなければなりません。

  • 'Keys'

  • 'LeftKeys'

  • 'RightKeys'

  • 'MergeKeys'

  • 'LeftVariables'

  • 'RightVariables'

  • 'Type'

• 以下の名前と値の引数の値は、パターン式をサポートしません。

  • 'Keys'

  • 'LeftKeys'

  • 'RightKeys'

  • 'LeftVariables'

  • 'RightVariables'

• 入れ子の table および timetable はサポートされていません。

スレッドベースの環境
MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

バージョン履歴

R2013b で導入

参考

関数

• join | innerjoin

ライブ エディター タスク

• table の連結