table

Methods

⌂ table

Method Reference: table.stack

table: tblB = stack (tblA, vars)
table: tblB = stack (tblA, {vars1, …, varsN})
table: tblB = stack (…, Name, Value)
table: [tblB, idxA] = stack (…)

Stack multiple table variables into a single table variable.

tblB = stack (tblA, vars) stacks the values from the variables vars in input tblA into a single variable in output table tblB. By default, the stacked variable in tblB is named by joining the names of the variables in tblA as defined by vars, and it inherits the units and description of the first variable in vars. Additionally, a new categorical variable is included in tblB that indicates which variable in tblA the stacked data in each row of tblB comes from. By default, this categorical variable is named by appending '_Indicator' to the name of the stacked variable. Variables in tblA that are not defined in vars for stacking are replicated in tblB. If tblA contains RowNames, these are not stacked.

tblB = stack (tblA, {vars1, …, varsN}) stacks multiple groups of variables, given as a cell array of variable references, producing one stacked data variable in tblB per group (each named and metadata-inherited from its own group). All groups must contain the same number of variables. In this case a single indicator variable, named 'Indicator' by default, holds the numeric position within each group of the source variable for each stacked value.

vars can be any of the following types.

  • a character vector specifying a single variable.
  • a cell array of character vectors specifying a single or multiple variables.
  • a string array specifying a single or multiple variables.
  • a numeric array of integer values indexing the variables to be stacked.
  • a logical vector of the same length as the width of the table tblA indexing as true the variables to be stacked.
  • a vartype object used to create a subscript that selects variables of a specified type.

tblB = stack (…, Name, Value) further specifies additional parameters for stacking table variables with the following Name-Value paired arguments.

  • 'ConstantVariables' specifies the variables other than vars to include in the output table. By default, all remaining variables not specified by vars are included in the output table. Specifying 'ConstantVariables' allows you to select specific variables to replicate in tblB. Row names in tblA are always replicated in tblB. You can specify 'ConstantVariables' in the same manner as with vars.
  • 'NewDataVariableName' specifies the name for the new data variable in the output table tblB. It can be a character vector, a string scalar, or a cellstring scalar.
  • 'IndexVariableName' specifies the name for the new indicator variable in the output table tblB. It can be a character vector, a string scalar, or a cellstring scalar.

[tblB, idxA] = stack (…) also returns an index vector, idxA, indicating the correspondence between the rows in tblB and the rows in tblA.

Source Code: table

Example: 1

stack reshapes wide data to tall: it stacks several data variables into a single variable and adds an indicator recording which one each value came from. Here the monthly columns collapse into one Value column.

 Name = {'Li'; 'Diaz'};
 Jan = [1; 2];
 Feb = [3; 4];
 T = table (Name, Jan, Feb)
T =
  2x3 table

      Name      Jan    Feb    
    ________    ___    ___    

    {'Li'  }      1      3    
    {'Diaz'}      2      4
 stack (T, {'Jan', 'Feb'}, ...
        'NewDataVariableName', 'Value', 'IndexVariableName', 'Month')
ans =
  4x3 table

      Name      Month    Value    
    ________    _____    _____    

    {'Li'  }      Jan        1    
    {'Li'  }      Feb        3    
    {'Diaz'}      Jan        2    
    {'Diaz'}      Feb        4

The unstacked variables (Name) are repeated down each group; the indicator Month is a categorical naming the source column. unstack reverses this.