table

Methods

⌂ table

Method Reference: table.unstack

table: tblB = unstack (tblA, vars, ivar)
table: tblB = unstack (…, Name, Value)
table: [tblB, idxA] = unstack (…)

Unstack a single table variable into multiple table variables.

tblB = unstack (tblA, vars, ivar) unstacks the values from the variables vars according to the indicator variable ivar in input tblA into multiple variables in output table tblB. The new (unstacked) variables in tblB are named according to the unique values of the indicator variable and the rows with matching indicator values are aggregated into the new (unstacked) variables. By default, numeric and duration data types are aggregated by summation, whereas from other data types the first unique element of each group is returned.

vars may specify one or more variables of any data type supported by the table class except for nested tables, whereas ivar must only specify a single variable, which must be numeric, logical, categorical, string, or cellstring. Both vars and ivar can be specified as follows:

  • 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 unstacked.
  • a logical vector of the same length as the width of the table tblA indexing as true the variables to be unstacked.
  • a vartype object used to create a subscript that selects variables of a specified type.

By default, all remaining variables in tblA which are not specified by vars and ivar are treated as grouping variables, in which case each unique combination of values in the grouping variables identifies a group of rows in tblA that is unstacked into one row of tblB.

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

  • 'GroupingVariables' specifies the variables that should be used as grouping variables. All valid schemes for indexing a table variable can be used. If grouping variables have missing values, the data from corresponding rows are not aggregated in the output table. Table row names cannot be assigned as a grouping variable, since these must be unique for each row, which would defeat the purpose of unstacking a table onto itself.
  • 'ConstantVariables' specifies the variables that are constant within each group. All valid schemes for indexing a table variable can be used. The values for these variables in the output are taken from the first row in each group in the input. By default, no variable is treated as constant unless specified. However, if the input table has row names, these effectively are treated as constant variables.
  • 'NewDataVariableNames' specifies the names for the new data variables in the output table tblB. It can be a character vector, a string scalar, or a cellstring scalar. By default, the names of the new unstacked data variables are based on the string representation of the unique values in the indicator variable ivar. If multiple variables are unstacked, then unstack generates composite names using both the values from the indicator variable and the name of the variable being unstacked. The number of names must match the number of unique values in the indicator variable.
  • 'AggregationFunction' specifies a function handle used to aggregate each group’s data into a single value. By default, @sum is applied on numeric data, whereas @unique is applied on all other supported data types, including duration and calendarDuration. In the latter case, if a group contains more than one distinct value for the same indicator value, the default aggregation errors, and an explicit 'AggregationFunction' that returns a scalar must be specified.
  • 'VariableNamingRule', specified as either 'modify' or 'preserve', defines the rule for naming the new unstacked variables in the output table tblB. 'modify' (default) forces all variable names to be valid Octave variable names. 'preserve' preserves the original names taken from the input table, which can have any Unicode characters, including spaces and non-ASCII characters.

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

Source Code: table

Example: 1

unstack reshapes tall data to wide — the inverse of stack. It spreads the values of one data variable across new columns, one per level of an indicator variable, grouping by the remaining variables.

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

    Name    Month    Value    
    ____    _____    _____    

      Li      Jan        1    
      Li      Feb        3    
    Diaz      Jan        2    
    Diaz      Feb        4
 unstack (T, 'Value', 'Month')
ans =
  2x3 table

    Name    Feb    Jan    
    ____    ___    ___    

      Li      3      1    
    Diaz      4      2

Each distinct Month becomes its own column, with one row per Name.