addvars

Add variables to table or timetable

Syntax

T2 = addvars(T1,var1,...,varN)

T2 = addvars(T1,var1,...,varN,'Before',location)

T2 = addvars(T1,var1,...,varN,'After',location)

T2 = addvars(___,'NewVariableNames',newNames)

Description

T2 = addvars(T1,var1,...,varN) adds the variables specified by var1,…,varN to the right of the last variable of T1. The input arguments var1,…,varN can include arrays of any type, tables, and timetables. All input arguments must have the same number of rows.

T2 = addvars(T1,var1,...,varN,'Before',location) inserts the variables to the left of the table variable indicated by location (see diagram). You can specify location as a variable name, or a numeric or logical index.

T2 = addvars(T1,var1,...,varN,'After',location) inserts the variables to the right of the table variable indicated by location.

T2 = addvars(___,'NewVariableNames',newNames) renames the added variables in T2 using the names specified by newNames. The number of names in newNames must be the same as the number of added variables. You can use this syntax with any of the input arguments of the previous syntaxes.

Examples

Add Variables

Create a table. Then add variables from the workspace to the table.

Load arrays from the patients.mat file. Create a table that contains the names, ages, heights, and weights of patients. Then display the first three rows.

load patients
T1 = table(LastName,Age,Height,Weight);
head(T1,3)

ans=3×4 table
      LastName      Age    Height    Weight
    ____________    ___    ______    ______

    {'Smith'   }    38       71       176  
    {'Johnson' }    43       69       163  
    {'Williams'}    38       64       131  

Add the workspace variables, Gender and Smoker, to the table.

T2 = addvars(T1,Gender,Smoker);
head(T2,3)

ans=3×6 table
      LastName      Age    Height    Weight      Gender      Smoker
    ____________    ___    ______    ______    __________    ______

    {'Smith'   }    38       71       176      {'Male'  }    true  
    {'Johnson' }    43       69       163      {'Male'  }    false 
    {'Williams'}    38       64       131      {'Female'}    false 

Insert Variables at Specified Locations

Create a table. Then insert variables before and after specified locations in the table.

Load arrays from the patients.mat file. Create a table that contains the names and genders of patients. Then display the first three rows.

load patients
T1 = table(LastName,Gender);
head(T1,3)

ans=3×2 table
      LastName        Gender  
    ____________    __________

    {'Smith'   }    {'Male'  }
    {'Johnson' }    {'Male'  }
    {'Williams'}    {'Female'}

Insert the workspace variable, Age, before the table variable, Gender. To refer to a table variable by name, specify its name as a character vector.

T2 = addvars(T1,Age,'Before','Gender');
head(T2,3)

ans=3×3 table
      LastName      Age      Gender  
    ____________    ___    __________

    {'Smith'   }    38     {'Male'  }
    {'Johnson' }    43     {'Male'  }
    {'Williams'}    38     {'Female'}

Insert more variables after Age. Since Age is a table variable in T2, specify its name as a character vector.

T3 = addvars(T2,Height,Weight,'After','Age');
head(T3,3)

ans=3×5 table
      LastName      Age    Height    Weight      Gender  
    ____________    ___    ______    ______    __________

    {'Smith'   }    38       71       176      {'Male'  }
    {'Johnson' }    43       69       163      {'Male'  }
    {'Williams'}    38       64       131      {'Female'}

Insert Smoker after the first table variable. You can specify variables by position in the table instead of by name.

T4 = addvars(T3,Smoker,'After',1);
head(T4,3)

ans=3×6 table
      LastName      Smoker    Age    Height    Weight      Gender  
    ____________    ______    ___    ______    ______    __________

    {'Smith'   }    true      38       71       176      {'Male'  }
    {'Johnson' }    false     43       69       163      {'Male'  }
    {'Williams'}    false     38       64       131      {'Female'}

Rename Variables

Create a table. Add variables and give them new names in the table.

First, create a table from workspace variables.

load patients
T1 = table(LastName,Age,Gender,Smoker);
head(T1,3)

ans=3×4 table
      LastName      Age      Gender      Smoker
    ____________    ___    __________    ______

    {'Smith'   }    38     {'Male'  }    true  
    {'Johnson' }    43     {'Male'  }    false 
    {'Williams'}    38     {'Female'}    false 

Combine Diastolic and Systolic into one matrix with two columns. Name the new table variable BloodPressure.

T2 = addvars(T1,[Diastolic Systolic],'NewVariableNames','BloodPressure');
head(T2,3)

ans=3×5 table
      LastName      Age      Gender      Smoker    BloodPressure
    ____________    ___    __________    ______    _____________

    {'Smith'   }    38     {'Male'  }    true        93    124  
    {'Johnson' }    43     {'Male'  }    false       77    109  
    {'Williams'}    38     {'Female'}    false       83    125  

Add Height and Weight as new table variables. Rename them Inches and Pounds.

T3 = addvars(T2,Height,Weight,'Before','Smoker','NewVariableNames',{'Inches','Pounds'});
head(T3,3)

ans=3×7 table
      LastName      Age      Gender      Inches    Pounds    Smoker    BloodPressure
    ____________    ___    __________    ______    ______    ______    _____________

    {'Smith'   }    38     {'Male'  }      71       176      true        93    124  
    {'Johnson' }    43     {'Male'  }      69       163      false       77    109  
    {'Williams'}    38     {'Female'}      64       131      false       83    125  

Input Arguments

T1 — Input table

table | timetable

Input table, specified as a table or timetable.

var1,...,varN — Variables to add to output table

arrays, tables, and timetables

Variables to add to the output table, specified as arrays, tables, and timetables. The variables specified by var1,...,varN all must have the same number of rows as the input table T1.

Example: T2 = addvars(T1,A) inserts the workspace variables A to the right of the last table variable.

Example: T2 = addvars(T1,X,Y,Z) inserts the workspace variables X, Y, and Z.

location — Location to insert added variables

character vector | string scalar | integer | logical array

Location to insert added variables, specified as a character vector, string scalar, integer, or logical array.

• If location is a character vector or string scalar, then it is the name of a variable in the input table T1.

• If location is the integer n, then it specifies the nth variable in T1.

• If location is a logical array, whose nth element is 1 (true), then it specifies the nth variable in T1. All other elements of location must be 0 (false).

Example: T2 = addvars(T1,Latitude,'Before','Longitude') insert the workspace variable Latitude to the left of the table variable named Longitude.

Example: T2 = addvars(T1,Y,Z,'After','X') inserts the workspace variables Y and Z to the right of the table variable named X.

newNames — Names of added variables

character vector | cell array of character vectors | string array

Names of the added variables, specified as a character vector, cell array of character vectors, or string array.

Example: T2 = addvars(T1,lat,lon,'NewVariableNames',{'Latitude','Longitude'}) inserts the workspace variables lat and lon and names the corresponding table variables 'Latitude' and 'Longitude'.

Limitations

• Use single quotes for the input names 'Before', 'After', and 'NewVariableNames'. To avoid confusion with variable inputs, do not use double-quoted string scalars (such as "Before") for these names.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

This function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• You cannot specify name-value arguments using Name=Value syntax when calling addvars within code intended for code generation.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).