Main Content

pivot

Summarize tabular data in pivoted table

Since R2023a

    Description

    A pivoted table provides a summary of tabular data—the column and row labels of a pivoted table are group names, and the data values are group counts or the result of another computation method. Pivoted tables are useful for analyzing and providing insights into large data sets and organizing data from another perspective, according to column and row groups. For more information, see Pivoting Operation or watch How to Create Pivot Tables in MATLAB (4 min, 11 sec).

    P = pivot(T,Columns=colvars,Rows=rowvars) returns a pivoted table that summarizes data in the table or timetable T. The groups in the grouping variables specified by colvars designate the variables in the pivoted table. The group names in the grouping variables specified by rowvars designate the values of the row labels of the pivoted table. The default data in P is the group counts of each combination of groups from colvars and rowvars. Empty categories are omitted from the pivoted table, where an empty category is a possible value of a categorical, logical, or binned numeric, duration, or datetime grouping variable that is not represented in the input table.

    You can use pivot functionality interactively by adding the Pivot Table task to a live script.

    example

    P = pivot(T,Columns=colvars) returns a pivoted table containing one row of group counts. The table variable names in P correspond to group names in the grouping variables specified by colvars.

    P = pivot(T,Rows=rowvars) returns a pivoted table containing one table variable of group counts. The values of the leftmost variables in P correspond to group names in the grouping variables specified by rowvars.

    P = pivot(___,Name=Value) specifies additional pivoting parameters using one or more name-value arguments with any of the input argument combinations in the previous syntaxes. For example, pivot(T,Columns=colvars,DataVariable="Sales") returns a pivoted table where the data values are the sums of the numeric data variable Sales.

    example

    Examples

    collapse all

    Compute the group counts for table data with two grouping variables.

    Create a table that contains information about 12 hospital patients.

    healthStatusOrder = ["Poor" "Fair" "Good" "Excellent"];
    HealthStatus = categorical(["Excellent"; "Fair"; "Good"; "Fair"; "Good"; "Good"; ...
        "Good"; "Good"; "Excellent"; "Excellent"; "Excellent"; "Poor"],healthStatusOrder);
    Smoker = logical([1; 0; 0; 0; 0; 0; 1; 0; 0; 0; 0; 0]);
    Location = ["County"; "VA"; "St. Mary's"; "VA"; "County"; "St. Mary's"; ...
        "VA"; "VA"; "St. Mary's"; "County"; "County"; "St. Mary's"];
    T = table(HealthStatus,Smoker,Location)
    T=12×3 table
        HealthStatus    Smoker      Location  
        ____________    ______    ____________
    
         Excellent      true      "County"    
         Fair           false     "VA"        
         Good           false     "St. Mary's"
         Fair           false     "VA"        
         Good           false     "County"    
         Good           false     "St. Mary's"
         Good           true      "VA"        
         Good           false     "VA"        
         Excellent      false     "St. Mary's"
         Excellent      false     "County"    
         Excellent      false     "County"    
         Poor           false     "St. Mary's"
    
    

    Find the number of patients reporting each unique combination of smoker status and health status. The variables in the pivoted table represent the unique values of the Smoker grouping variable. The rows in the pivoted table represent the unique values of the HealthStatus grouping variable.

    For example, the true variable in the pivoted table shows that one smoking patient reported Good health status and one smoking patient reported Excellent health status.

    P = pivot(T,Columns="Smoker",Rows="HealthStatus")
    P=4×3 table
        HealthStatus    false    true
        ____________    _____    ____
    
         Poor             1       0  
         Fair             2       0  
         Good             4       1  
         Excellent        3       1  
    
    

    Compute a summary statistic for filtered and grouped table data.

    Create a table from a file that contains information about 100 hospital patients.

    T = readtable("patients.xls",TextType="string");
    healthStatusOrder = ["Poor" "Fair" "Good" "Excellent"];
    T.SelfAssessedHealthStatus = categorical(T.SelfAssessedHealthStatus,healthStatusOrder);

    Create a table containing data for patients at the County General Hospital.

    T_cgh = T(T.Location=="County General Hospital",:)
    T_cgh=39×10 table
         LastName       Gender     Age            Location             Height    Weight    Smoker    Systolic    Diastolic    SelfAssessedHealthStatus
        ___________    ________    ___    _________________________    ______    ______    ______    ________    _________    ________________________
    
        "Smith"        "Male"      38     "County General Hospital"      71       176      true        124          93               Excellent        
        "Brown"        "Female"    49     "County General Hospital"      64       119      false       122          80               Good             
        "Taylor"       "Female"    31     "County General Hospital"      66       132      false       118          86               Excellent        
        "Anderson"     "Female"    45     "County General Hospital"      68       128      false       114          77               Excellent        
        "Martinez"     "Male"      37     "County General Hospital"      70       179      false       119          77               Good             
        "Robinson"     "Male"      50     "County General Hospital"      68       172      false       125          76               Good             
        "Lee"          "Female"    44     "County General Hospital"      66       146      true        128          90               Fair             
        "Walker"       "Female"    28     "County General Hospital"      65       123      true        129          96               Good             
        "Young"        "Female"    25     "County General Hospital"      63       114      false       125          76               Good             
        "Hernandez"    "Male"      36     "County General Hospital"      68       166      false       120          83               Poor             
        "King"         "Male"      30     "County General Hospital"      67       186      true        127          89               Excellent        
        "Green"        "Male"      44     "County General Hospital"      71       193      false       121          92               Good             
        "Mitchell"     "Male"      39     "County General Hospital"      71       164      true        128          92               Fair             
        "Campbell"     "Female"    37     "County General Hospital"      65       135      false       116          77               Fair             
        "Evans"        "Female"    39     "County General Hospital"      62       121      false       123          76               Good             
        "Edwards"      "Male"      42     "County General Hospital"      70       158      false       116          83               Excellent        
          ⋮
    
    

    Find the median age of nonsmoking and smoking patients per health status at the County General Hospital.

    P = pivot(T_cgh,Columns="Smoker",Rows="SelfAssessedHealthStatus",Method="median",DataVariable="Age")
    P=4×3 table
        SelfAssessedHealthStatus    false    true
        ________________________    _____    ____
    
               Poor                   36       43
               Fair                 42.5     41.5
               Good                   39       39
               Excellent              42       38
    
    

    Compute the group counts for table data with two discretized grouping variables.

    Create a timetable from a file that contains information about 1468 power outages.

    TT = readtimetable("outages.csv",TextType="string")
    TT=1468×5 timetable
           OutageTime         Region        Loss     Customers     RestorationTime           Cause      
        ________________    ___________    ______    __________    ________________    _________________
    
        2002-02-01 12:18    "SouthWest"    458.98    1.8202e+06    2002-02-07 16:50    "winter storm"   
        2003-01-23 00:49    "SouthEast"    530.14    2.1204e+05                 NaT    "winter storm"   
        2003-02-07 21:15    "SouthEast"     289.4    1.4294e+05    2003-02-17 08:14    "winter storm"   
        2004-04-06 05:44    "West"         434.81    3.4037e+05    2004-04-06 06:10    "equipment fault"
        2002-03-16 06:18    "MidWest"      186.44    2.1275e+05    2002-03-18 23:23    "severe storm"   
        2003-06-18 02:49    "West"              0             0    2003-06-18 10:54    "attack"         
        2004-06-20 14:39    "West"         231.29           NaN    2004-06-20 19:16    "equipment fault"
        2002-06-06 19:28    "West"         311.86           NaN    2002-06-07 00:51    "equipment fault"
        2003-07-16 16:23    "NorthEast"    239.93         49434    2003-07-17 01:12    "fire"           
        2004-09-27 11:09    "MidWest"      286.72         66104    2004-09-27 16:37    "equipment fault"
        2004-09-05 17:48    "SouthEast"    73.387         36073    2004-09-05 20:46    "equipment fault"
        2004-05-21 21:45    "West"         159.99           NaN    2004-05-22 04:23    "equipment fault"
        2002-09-01 18:22    "SouthEast"    95.917         36759    2002-09-01 19:12    "severe storm"   
        2003-09-27 07:32    "SouthEast"       NaN    3.5517e+05    2003-10-04 07:02    "severe storm"   
        2003-11-12 06:12    "West"         254.09    9.2429e+05    2003-11-17 02:04    "winter storm"   
        2004-09-18 05:54    "NorthEast"         0             0                 NaT    "equipment fault"
          ⋮
    
    

    Compute the total number of customers impacted by power outages for each region per year. The default computation method for the numeric variable Customers is "sum".

    P = pivot(TT,Columns="Region",Rows="OutageTime",RowsBinMethod="year",DataVariable="Customers")
    P=13×6 table
        year_OutageTime     MidWest      NorthEast     SouthEast     SouthWest        West   
        _______________    __________    __________    __________    __________    __________
    
             2002          5.0288e+06    3.3639e+06    1.2407e+06    2.7917e+06    6.2711e+05
             2003          1.6592e+06    2.2939e+06      6.14e+06    1.3498e+06    2.5174e+06
             2004          1.6618e+06    8.8251e+05    9.7505e+06     7.288e+05    2.4995e+06
             2005          4.0282e+05    2.1882e+06    4.4938e+06         63303    1.5852e+06
             2006           5.893e+06    4.5673e+06    6.1276e+06    2.8699e+05    8.8541e+06
             2007          1.2878e+06     5.713e+06    2.6545e+06         64318     2.774e+06
             2008          5.8309e+06    7.6436e+06    2.4609e+06      5.18e+05    1.1541e+06
             2009          1.7014e+06    5.4466e+06    3.0844e+06    1.3161e+05     1.421e+06
             2010           1.276e+06    1.5478e+07    6.3296e+06             0    4.5303e+06
             2011          2.6649e+06    6.4766e+06    2.5454e+06             0    1.9269e+06
             2012          1.3579e+06    1.1328e+07    4.8136e+06             0    1.4055e+06
             2013          5.3376e+05    5.7699e+06    3.8738e+06             0    1.1063e+06
             2014                   0             0             0             0             0
    
    

    Compute the group counts for table data with more than two grouping variables.

    Create a table from a file that contains information about 100 hospital patients.

    T = readtable("patients.xls",TextType="string");
    healthStatusOrder = ["Poor" "Fair" "Good" "Excellent"];
    T.SelfAssessedHealthStatus = categorical(T.SelfAssessedHealthStatus,healthStatusOrder);
    T
    T=100×10 table
         LastName      Gender     Age             Location              Height    Weight    Smoker    Systolic    Diastolic    SelfAssessedHealthStatus
        __________    ________    ___    ___________________________    ______    ______    ______    ________    _________    ________________________
    
        "Smith"       "Male"      38     "County General Hospital"        71       176      true        124          93               Excellent        
        "Johnson"     "Male"      43     "VA Hospital"                    69       163      false       109          77               Fair             
        "Williams"    "Female"    38     "St. Mary's Medical Center"      64       131      false       125          83               Good             
        "Jones"       "Female"    40     "VA Hospital"                    67       133      false       117          75               Fair             
        "Brown"       "Female"    49     "County General Hospital"        64       119      false       122          80               Good             
        "Davis"       "Female"    46     "St. Mary's Medical Center"      68       142      false       121          70               Good             
        "Miller"      "Female"    33     "VA Hospital"                    64       142      true        130          88               Good             
        "Wilson"      "Male"      40     "VA Hospital"                    68       180      false       115          82               Good             
        "Moore"       "Male"      28     "St. Mary's Medical Center"      68       183      false       115          78               Excellent        
        "Taylor"      "Female"    31     "County General Hospital"        66       132      false       118          86               Excellent        
        "Anderson"    "Female"    45     "County General Hospital"        68       128      false       114          77               Excellent        
        "Thomas"      "Female"    42     "St. Mary's Medical Center"      66       137      false       115          68               Poor             
        "Jackson"     "Male"      25     "VA Hospital"                    71       174      false       127          74               Poor             
        "White"       "Male"      39     "VA Hospital"                    72       202      true        130          95               Excellent        
        "Harris"      "Female"    36     "St. Mary's Medical Center"      65       129      false       114          79               Good             
        "Martin"      "Male"      48     "VA Hospital"                    71       181      true        130          92               Good             
          ⋮
    
    

    Find the number of nonsmoking and smoking patients declaring each health status per location. The pivoted table is 3-by-5 and contains nested variables that retain the hierarchy of the SelfAssessedHealthStatus and Smoker variables.

    P = pivot(T,Columns=["SelfAssessedHealthStatus" "Smoker"],Rows="Location")
    P=3×5 table
                 Location                  Poor             Fair             Good           Excellent  
        ___________________________    _____________    _____________    _____________    _____________
    
                                       false    true    false    true    false    true    false    true
                                       _____    ____    _____    ____    _____    ____    _____    ____
                                                                                                       
        "County General Hospital"        1       3        4       2        9       7        9       4  
        "St. Mary's Medical Center"      3       0        2       0       10       3        4       2  
        "VA Hospital"                    4       0        4       3        5       6       11       4  
    
    

    Access a data value by indexing into the pivoted table. For example, return the number of smoking patients reporting Fair health from the County General Hospital.

    num = P.Fair.true(P.Location == "County General Hospital")
    num = 
    2
    

    Alternatively, return a table containing only one level. Flatten the hierarchy of the SelfAssessedHealthStatus and Smoker grouping variables and concatenate their group names with an underscore.

    Pflat = pivot(T,Columns=["SelfAssessedHealthStatus" "Smoker"],Rows="Location",OutputFormat="flat")
    Pflat=3×9 table
                 Location              Poor_false    Poor_true    Fair_false    Fair_true    Good_false    Good_true    Excellent_false    Excellent_true
        ___________________________    __________    _________    __________    _________    __________    _________    _______________    ______________
    
        "County General Hospital"          1             3            4             2             9            7               9                 4       
        "St. Mary's Medical Center"        3             0            2             0            10            3               4                 2       
        "VA Hospital"                      4             0            4             3             5            6              11                 4       
    
    

    Compute the overall counts for each variable and row in a pivoted table.

    Create a table T that contains information about 12 hospital patients.

    healthStatusOrder = ["Poor" "Fair" "Good" "Excellent"];
    HealthStatus = categorical(["Excellent"; "Fair"; "Good"; "Fair"; "Good"; "Good"; ...
        "Good"; "Good"; "Excellent"; "Excellent"; "Excellent"; "Poor"],healthStatusOrder);
    Smoker = logical([1; 0; 0; 0; 0; 0; 1; 0; 0; 0; 0; 0]);
    Location = ["County"; "VA"; "St. Mary's"; "VA"; "County"; "St. Mary's"; ...
        "VA"; "VA"; "St. Mary's"; "County"; "County"; "St. Mary's"];
    T = table(HealthStatus,Smoker,Location)
    T=12×3 table
        HealthStatus    Smoker      Location  
        ____________    ______    ____________
    
         Excellent      true      "County"    
         Fair           false     "VA"        
         Good           false     "St. Mary's"
         Fair           false     "VA"        
         Good           false     "County"    
         Good           false     "St. Mary's"
         Good           true      "VA"        
         Good           false     "VA"        
         Excellent      false     "St. Mary's"
         Excellent      false     "County"    
         Excellent      false     "County"    
         Poor           false     "St. Mary's"
    
    

    Find the number of patients reporting each unique combination of smoker status and health status. To display the total number of patients reporting each smoker status and health status, include the variable and row totals in the pivoted table. Move the row labels in the HealthStatus variable into the RowNames property and display the pivoted table.

    P = pivot(T,Columns="Smoker",Rows="HealthStatus",IncludeTotals=true,RowLabelPlacement="rownames")
    P=5×3 table
                         false    true    Overall_count
                         _____    ____    _____________
    
        Poor               1       0            1      
        Fair               2       0            2      
        Good               4       1            5      
        Excellent          3       1            4      
        Overall_count     10       2           12      
    
    

    Return a subset of the pivoted table containing the specified row names.

    Psubset = P(["Good" "Excellent"],:)
    Psubset=2×3 table
                     false    true    Overall_count
                     _____    ____    _____________
    
        Good           4       1            5      
        Excellent      3       1            4      
    
    

    Compute the group counts for filtered and grouped timetable data. Include unrepresented groups in the pivoting operation.

    Create a timetable from a file that contains information about 1468 power outages.

    TT = readtimetable("outages.csv")
    TT=1468×5 timetable
           OutageTime          Region         Loss     Customers     RestorationTime            Cause       
        ________________    _____________    ______    __________    ________________    ___________________
    
        2002-02-01 12:18    {'SouthWest'}    458.98    1.8202e+06    2002-02-07 16:50    {'winter storm'   }
        2003-01-23 00:49    {'SouthEast'}    530.14    2.1204e+05                 NaT    {'winter storm'   }
        2003-02-07 21:15    {'SouthEast'}     289.4    1.4294e+05    2003-02-17 08:14    {'winter storm'   }
        2004-04-06 05:44    {'West'     }    434.81    3.4037e+05    2004-04-06 06:10    {'equipment fault'}
        2002-03-16 06:18    {'MidWest'  }    186.44    2.1275e+05    2002-03-18 23:23    {'severe storm'   }
        2003-06-18 02:49    {'West'     }         0             0    2003-06-18 10:54    {'attack'         }
        2004-06-20 14:39    {'West'     }    231.29           NaN    2004-06-20 19:16    {'equipment fault'}
        2002-06-06 19:28    {'West'     }    311.86           NaN    2002-06-07 00:51    {'equipment fault'}
        2003-07-16 16:23    {'NorthEast'}    239.93         49434    2003-07-17 01:12    {'fire'           }
        2004-09-27 11:09    {'MidWest'  }    286.72         66104    2004-09-27 16:37    {'equipment fault'}
        2004-09-05 17:48    {'SouthEast'}    73.387         36073    2004-09-05 20:46    {'equipment fault'}
        2004-05-21 21:45    {'West'     }    159.99           NaN    2004-05-22 04:23    {'equipment fault'}
        2002-09-01 18:22    {'SouthEast'}    95.917         36759    2002-09-01 19:12    {'severe storm'   }
        2003-09-27 07:32    {'SouthEast'}       NaN    3.5517e+05    2003-10-04 07:02    {'severe storm'   }
        2003-11-12 06:12    {'West'     }    254.09    9.2429e+05    2003-11-17 02:04    {'winter storm'   }
        2004-09-18 05:54    {'NorthEast'}         0             0                 NaT    {'equipment fault'}
          ⋮
    
    

    Filter the timetable for outages where the cause was a winter storm.

    TT.Cause = categorical(TT.Cause);
    TTwinter = TT(TT.Cause=="winter storm",:);

    Add a variable to the timetable that contains the duration of each power outage in days.

    TTwinter.OutageDuration = TTwinter.RestorationTime-TTwinter.OutageTime;
    TTwinter.OutageDuration.Format = "d"
    TTwinter=145×6 timetable
           OutageTime          Region         Loss     Customers     RestorationTime        Cause        OutageDuration
        ________________    _____________    ______    __________    ________________    ____________    ______________
    
        2002-02-01 12:18    {'SouthWest'}    458.98    1.8202e+06    2002-02-07 16:50    winter storm      6.1889 days 
        2003-01-23 00:49    {'SouthEast'}    530.14    2.1204e+05                 NaT    winter storm         NaN days 
        2003-02-07 21:15    {'SouthEast'}     289.4    1.4294e+05    2003-02-17 08:14    winter storm      9.4576 days 
        2003-11-12 06:12    {'West'     }    254.09    9.2429e+05    2003-11-17 02:04    winter storm      4.8278 days 
        2004-11-13 10:42    {'NorthEast'}       NaN    1.4227e+05    2004-11-19 02:31    winter storm       5.659 days 
        2004-12-06 23:18    {'SouthEast'}       NaN         37136    2004-12-14 03:21    winter storm      7.1688 days 
        2002-12-12 18:08    {'SouthEast'}    46.918    1.0698e+05    2002-12-14 18:43    winter storm      2.0243 days 
        2004-12-21 18:50    {'West'     }    112.05     7.985e+05    2004-12-29 03:46    winter storm      7.3722 days 
        2002-12-16 13:43    {'West'     }    70.752    4.8193e+05    2002-12-19 09:38    winter storm      2.8299 days 
        2004-12-26 22:18    {'NorthEast'}    255.45    1.0444e+05    2004-12-27 14:11    winter storm     0.66181 days 
        2003-12-17 15:11    {'NorthEast'}       NaN         66692    2003-12-19 07:22    winter storm      1.6743 days 
        2005-03-08 16:37    {'SouthEast'}    1339.2    4.3003e+05    2005-03-10 20:42    winter storm      2.1701 days 
        2002-03-26 01:59    {'MidWest'  }    388.04    5.6422e+05    2002-03-28 19:55    winter storm      2.7472 days 
        2003-12-22 03:40    {'West'     }    232.26    3.9462e+05    2003-12-24 16:32    winter storm      2.5361 days 
        2003-01-10 15:38    {'West'     }    185.85     2.757e+05    2003-01-12 05:48    winter storm      1.5903 days 
        2002-12-30 07:53    {'West'     }    119.78    1.0355e+05    2003-01-02 11:17    winter storm      3.1417 days 
          ⋮
    
    

    Compute the number of winter storm outages that occurred during each month of the year per the duration of the outage in days.

    Pwinter = pivot(TTwinter,Rows="RestorationTime",Columns="OutageDuration",RowsBinMethod="monthname",ColumnsBinMethod="day",RowLabelPlacement="rownames")
    Pwinter=9×16 table
                                               [0 days, 1 day)    [1 day, 2 days)    [2 days, 3 days)    [3 days, 4 days)    [4 days, 5 days)    [5 days, 6 days)    [6 days, 7 days)    [7 days, 8 days)    [8 days, 9 days)    [9 days, 10 days)    [10 days, 11 days)    [11 days, 12 days)    [12 days, 13 days)    [14 days, 15 days)    [18 days, 19 days]    <missing_day_OutageDuration>
                                               _______________    _______________    ________________    ________________    ________________    ________________    ________________    ________________    ________________    _________________    __________________    __________________    __________________    __________________    __________________    ____________________________
    
        January                                       5                 10                  5                   2                   4                   1                   1                   0                   1                    1                    2                     0                     2                     0                     0                          0              
        February                                     13                 12                  8                   5                   2                   3                   3                   2                   2                    1                    0                     1                     0                     1                     1                          0              
        March                                         3                  1                  6                   2                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                          0              
        April                                         1                  0                  1                   0                   1                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                          0              
        May                                           0                  0                  1                   0                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                          0              
        October                                       1                  1                  1                   0                   0                   1                   0                   0                   0                    0                    1                     0                     0                     0                     0                          0              
        November                                      3                  2                  0                   2                   2                   1                   0                   0                   0                    0                    0                     0                     0                     0                     0                          0              
        December                                      4                  1                  7                   3                   0                   1                   2                   2                   1                    0                    2                     0                     0                     1                     0                          0              
        <missing_monthname_RestorationTime>           0                  0                  0                   0                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                          2              
    
    

    Include groups in the pivoting operation for categories in RestorationTime and OutageDuration that are unrepresented in the input table. Including empty groups creates rows for June, July, August, and September in the pivoted table, where the value of every table cell in those rows is 0. Including empty groups also creates variables for outage durations that are not present in the data set, where the value of every table cell in those variables is 0. Do not include groups in the pivoted table for outages with an unknown restoration time.

    Pwinter2 = pivot(TTwinter,Rows="RestorationTime",Columns="OutageDuration",RowsBinMethod="monthname",ColumnsBinMethod="day",IncludeEmptyGroups=1,IncludeMissingGroups=0,RowLabelPlacement="rownames")
    Pwinter2=12×19 table
                     [0 days, 1 day)    [1 day, 2 days)    [2 days, 3 days)    [3 days, 4 days)    [4 days, 5 days)    [5 days, 6 days)    [6 days, 7 days)    [7 days, 8 days)    [8 days, 9 days)    [9 days, 10 days)    [10 days, 11 days)    [11 days, 12 days)    [12 days, 13 days)    [13 days, 14 days)    [14 days, 15 days)    [15 days, 16 days)    [16 days, 17 days)    [17 days, 18 days)    [18 days, 19 days]
                     _______________    _______________    ________________    ________________    ________________    ________________    ________________    ________________    ________________    _________________    __________________    __________________    __________________    __________________    __________________    __________________    __________________    __________________    __________________
    
        January             5                 10                  5                   2                   4                   1                   1                   0                   1                    1                    2                     0                     2                     0                     0                     0                     0                     0                     0         
        February           13                 12                  8                   5                   2                   3                   3                   2                   2                    1                    0                     1                     0                     0                     1                     0                     0                     0                     1         
        March               3                  1                  6                   2                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                     0                     0                     0                     0         
        April               1                  0                  1                   0                   1                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                     0                     0                     0                     0         
        May                 0                  0                  1                   0                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                     0                     0                     0                     0         
        June                0                  0                  0                   0                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                     0                     0                     0                     0         
        July                0                  0                  0                   0                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                     0                     0                     0                     0         
        August              0                  0                  0                   0                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                     0                     0                     0                     0         
        September           0                  0                  0                   0                   0                   0                   0                   0                   0                    0                    0                     0                     0                     0                     0                     0                     0                     0                     0         
        October             1                  1                  1                   0                   0                   1                   0                   0                   0                    0                    1                     0                     0                     0                     0                     0                     0                     0                     0         
        November            3                  2                  0                   2                   2                   1                   0                   0                   0                    0                    0                     0                     0                     0                     0                     0                     0                     0                     0         
        December            4                  1                  7                   3                   0                   1                   2                   2                   1                    0                    2                     0                     0                     0                     1                     0                     0                     0                     0         
    
    

    Input Arguments

    collapse all

    Input table, specified as a table or timetable.

    Grouping variables to designate pivoted table variables, specified as one of the indexing schemes in this table. This argument specifies the variables for Columns. Each variable in the pivoted table corresponds to one variable group. Variable groups are defined by rows that have the same unique combination of values in grouping variables in Columns.

    If you do not specify colvars, then the pivoted table contains only one variable.

    Indexing SchemeValues to SpecifyExamples

    Variable names

    • A string scalar or character vector

    • A string array or cell array of character vectors

    • A pattern object

    • "A" or 'A' — A variable named A

    • ["A" "B"] or {'A','B'} — Two variables named A and B

    • "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit

    Variable index

    • An index number that refers to the location of a variable in the table

    • A vector of numbers

    • A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 (false) values.

    • 3 — The third variable from the table

    • [2 3] — The second and third variables from the table

    • [false false true] — The third variable

    Function handle

    • A function handle that takes a table variable as input and returns a logical scalar

    • @isnumeric — All the variables containing numeric values

    Variable type

    • A vartype subscript that selects variables of a specified type

    • vartype("numeric") — All the variables containing numeric values

    Example: P = pivot(T,Columns="Var1",Rows="Var2")

    Example: P = pivot(T,Columns=["Var1" "Var2"],Rows="Var3")

    Grouping variables to designate pivoted table rows, specified as one of the indexing schemes in this table. This argument specifies the variables for Rows. Each row in the pivoted table corresponds to one row group. Row groups are defined by rows that have the same unique combination of values in grouping variables in Rows.

    If you do not specify rowvars, then the pivoted table contains only one row.

    Indexing SchemeValues to SpecifyExamples

    Variable names

    • A string scalar or character vector

    • A string array or cell array of character vectors

    • A pattern object

    • "A" or 'A' — A variable named A

    • ["A" "B"] or {'A','B'} — Two variables named A and B

    • "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit

    Variable index

    • An index number that refers to the location of a variable in the table

    • A vector of numbers

    • A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 (false) values.

    • 3 — The third variable from the table

    • [2 3] — The second and third variables from the table

    • [false false true] — The third variable

    Function handle

    • A function handle that takes a table variable as input and returns a logical scalar

    • @isnumeric — All the variables containing numeric values

    Variable type

    • A vartype subscript that selects variables of a specified type

    • vartype("numeric") — All the variables containing numeric values

    Example: P = pivot(T,Columns="Var1",Rows="Var2")

    Example: P = pivot(T,Columns="Var1",Rows=["Var2" "Var3"])

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: P = pivot(T,Columns=["Var1" "Var2"],Rows="Var3","DataVariable="Var4",Method="mean")

    Table variable to fill values of the pivoted table instead of group counts, specified as one of the indexing schemes in this table. The results of applying the computation method Method to the variable specified by DataVariable are the data values of the pivoted table.

    If you do not specify DataVariable, then the data values of the pivoted table are the group counts.

    Indexing SchemeExamples

    Variable name:

    • A string scalar or character vector

    • "A" or 'A' — A variable named A

    Variable index:

    • An index number that refers to the location of a variable in the table

    • A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values

    • 3 — The third variable from the table

    • [false false true] — The third variable

    Function handle:

    • A function handle that takes a table variable as input and returns a logical scalar

    • @isnumeric — One variable containing numeric values

    Variable type:

    • A vartype subscript that selects one variable of a specified type

    • vartype("numeric") — One variable containing numeric values

    To apply a computation method to multiple data variables, use the groupsummary function.

    Example: P = pivot(T,Columns="Var1",Rows="Var2",DataVariable="Var3")

    Computation method to apply to the data variable, specified as one of the values in this table. The results of applying the computation method to the variable specified by DataVariable are the data values of the pivoted table.

    The default value of Method depends on the value of DataVariable.

    • If the variable specified by DataVariable is numeric, then the default computation method is "sum".

    • If the variable specified by DataVariable is not numeric, then the default computation method is "count".

    • If DataVariable is not specified, then the computation method must be "count" or "percentage", where "count" is the default.

    Method

    Description
    "count"Group count
    "sum"Sum
    "percentage"Group percentage
    "mean"Mean
    "median"Median
    "mode"Mode
    "var"Variance
    "std"Standard deviation
    "min"Minimum
    "max"Maximum
    "range"Maximum minus minimum
    "nummissing"Number of missing elements
    "numunique"Number of distinct nonmissing elements
    "nnz"

    Number of nonzero and non-NaN elements

    You also can specify the computation method as a function handle that accepts groups of data in DataVariable and returns one output per group whose first dimension has length 1.

    The pivot function omits missing values in the input data when using the method names described here, with the exception of "nummissing". To include missing values, use a function handle for the method, such as @sum instead of "sum".

    To specify multiple computation methods for a data variable, use the groupsummary function.

    Example: P = pivot(T,Columns="Var1",Rows="Var2",DataVariable="Var3",Method="mean")

    Binning scheme for grouping variables specified by Columns, specified as one or more of the following binning methods. Grouping variables and binning scheme arguments must be the same size, or one of them can be scalar.

    • "none" — No binning.

    • Vector of bin edges — The bin edges define the bins. You can specify the edges as numeric values or as datetime values for datetime grouping variables.

    • Number of bins — The number determines how many equally spaced bins to create. You can specify the number of bins as a positive integer scalar.

    • Length of time (bin width) — The length of time determines the width of each bin. You can specify the bin width as a duration or calendarDuration scalar for datetime or duration grouping variables.

    • Name of time unit (bin width) — The name of the time unit determines the width of each bin. You can specify the bin width as one of the options in this table for datetime or duration grouping variables.

      ValueDescriptionData Type
      "second"

      Each bin is 1 second.

      datetime and duration
      "minute"

      Each bin is 1 minute.

      datetime and duration
      "hour"

      Each bin is 1 hour.

      datetime and duration
      "day"

      Each bin is 1 calendar day. This value accounts for daylight saving time shifts.

      datetime and duration
      "week"Each bin is 1 calendar week.datetime only
      "month"Each bin is 1 calendar month.datetime only
      "quarter"Each bin is 1 calendar quarter.datetime only
      "year"

      Each bin is 1 calendar year. This value accounts for leap days.

      datetime and duration
      "decade"Each bin is 1 decade (10 calendar years).datetime only
      "century"Each bin is 1 century (100 calendar years).datetime only
      "secondofminute"

      Bins are seconds from 0 to 59.

      datetime only
      "minuteofhour"

      Bins are minutes from 0 to 59.

      datetime only
      "hourofday"

      Bins are hours from 0 to 23.

      datetime only
      "dayofweek"

      Bins are days from 1 to 7. The first day of the week is Sunday.

      datetime only
      "dayname"Bins are full day names, such as "Sunday".datetime only
      "dayofmonth"Bins are days from 1 to 31.datetime only
      "dayofyear"Bins are days from 1 to 366.datetime only
      "weekofmonth"Bins are weeks from 1 to 6.datetime only
      "weekofyear"Bins are weeks from 1 to 54.datetime only
      "monthname"Bins are full month names, such as "January".datetime only
      "monthofyear"

      Bins are months from 1 to 12.

      datetime only
      "quarterofyear"Bins are quarters from 1 to 4.datetime only

    Example: P = pivot(T,Columns="Var1",Rows="Var2",ColumnsBinMethod=[-Inf 0 Inf])

    Example: P = pivot(T,Columns=["Var1" "Var2"],ColumnsBinMethod={"none","year"})

    Example: P = pivot(T,Columns="Var1",ColumnsBinMethod={"month","quarter"})

    Binning scheme for grouping variables specified by Rows, specified as one or more of the following binning methods. Grouping variables and binning scheme arguments must be the same size, or one of them can be scalar.

    • "none" — No binning.

    • Vector of bin edges — The bin edges define the bins. You can specify the edges as numeric values or as datetime values for datetime grouping variables.

    • Number of bins — The number determines how many equally spaced bins to create. You can specify the number of bins as a positive integer scalar.

    • Length of time (bin width) — The length of time determines the width of each bin. You can specify the bin width as a duration or calendarDuration scalar for datetime or duration grouping variables.

    • Name of time unit (bin width) — The name of the time unit determines the width of each bin. You can specify the bin width as one of the options in this table for datetime or duration grouping variables.

      ValueDescriptionData Type
      "second"

      Each bin is 1 second.

      datetime and duration
      "minute"

      Each bin is 1 minute.

      datetime and duration
      "hour"

      Each bin is 1 hour.

      datetime and duration
      "day"

      Each bin is 1 calendar day. This value accounts for daylight saving time shifts.

      datetime and duration
      "week"Each bin is 1 calendar week.datetime only
      "month"Each bin is 1 calendar month.datetime only
      "quarter"Each bin is 1 calendar quarter.datetime only
      "year"

      Each bin is 1 calendar year. This value accounts for leap days.

      datetime and duration
      "decade"Each bin is 1 decade (10 calendar years).datetime only
      "century"Each bin is 1 century (100 calendar years).datetime only
      "secondofminute"

      Bins are seconds from 0 to 59.

      datetime only
      "minuteofhour"

      Bins are minutes from 0 to 59.

      datetime only
      "hourofday"

      Bins are hours from 0 to 23.

      datetime only
      "dayofweek"

      Bins are days from 1 to 7. The first day of the week is Sunday.

      datetime only
      "dayname"Bins are full day names, such as "Sunday".datetime only
      "dayofmonth"Bins are days from 1 to 31.datetime only
      "dayofyear"Bins are days from 1 to 366.datetime only
      "weekofmonth"Bins are weeks from 1 to 6.datetime only
      "weekofyear"Bins are weeks from 1 to 54.datetime only
      "monthname"Bins are full month names, such as "January".datetime only
      "monthofyear"

      Bins are months from 1 to 12.

      datetime only
      "quarterofyear"Bins are quarters from 1 to 4.datetime only

    Example: P = pivot(T,Columns="Var1",Rows="Var2",RowsBinMethod=[-Inf 0 Inf])

    Example: P = pivot(T,Rows=["Var1" "Var2"],RowsBinMethod={"none","year"})

    Example: P = pivot(T,Rows="Var1",RowsBinMethod={"month","quarter"})

    Included bin edge for binning scheme, specified as either "left" or "right", indicating which end of the bin interval is inclusive when binning the grouping variables.

    You can specify IncludedEdge only if you also specify ColumnsBinMethod or RowsBinMethod. The value applies to all binning methods for all grouping variables.

    Example: P = pivot(T,Columns="Var1",ColumnsBinMethod=[0 5 10 15],IncludedEdge="right",Rows="Var2")

    Column hierarchy output format, specified as one of these values when more than one grouping variable is specified by Columns:

    • "nested" — Variables in the pivoted table contain nested tables. The pivoted table retains the hierarchy of groups in the grouping variables specified by Columns.

    • "flat" — Variables in the pivoted table contain one level. The pivoted table flattens the hierarchy of groups in the variables specified by Columns, and the variable names are the group names concatenated with an underscore.

    Example: P = pivot(T,Columns=["Var1" "Var2"],Rows="Var3",OutputFormat="flat")

    Option to include column and row totals, specified as a numeric or logical 0 (false) or 1 (true). If IncludeTotals is true, then the pivoted table includes an additional row containing the totals for each column and an additional variable containing the totals for each row. The pivot function computes the marginal totals by applying Method to all data values in DataVariable that correspond to that column or row.

    If you do not specify Columns, then the pivoted table contains only one variable and omits the additional variable of row totals. If you do not specify Rows, then the pivoted table contains only one row and omits the additional row of column totals.

    Example: P = pivot(T,Columns="Var1",IncludeTotals=true)

    Example: P = pivot(T,Rows="Var2",IncludeTotals=true)

    Example: P = pivot(T,Columns="Var1",Rows="Var2",IncludeTotals=true)

    Option to treat missing values as a group, specified as a numeric or logical 1 (true) or 0 (false). If IncludeMissingGroups is true, then pivot treats missing values, such as NaN, in a grouping variable specified by Columns or Rows as a group. If a grouping variable has no missing values, or if IncludeMissingGroups is false, then pivot does not treat missing values as a group.

    Example: P = pivot(T,Columns="Var1",Rows="Var2",IncludeMissingGroups=false)

    Since R2023b

    Option to include empty categories in the pivoting operation, specified as a numeric or logical 0 (false) or 1 (true). If IncludeEmptyGroups is false, then the pivoting operation omits empty groups. If IncludeEmptyGroups is true, then the pivoting operation includes empty groups.

    An empty group occurs when a possible value of a variable specified by Columns or Rows is not represented in the input table, such as in a categorical, logical, or binned numeric variable. For example, if no row in the input table has a value of true for a logical grouping variable, then true defines an empty group.

    Example: P = pivot(T,Columns="Var1",Rows="Var2",IncludeEmptyGroups=true)

    Since R2023b

    Placement of row labels in the pivoted table, specified as one of these values:

    • "variable" — Place row labels in the leftmost table variable of the pivoted table. If Rows specifies multiple grouping variables, place row labels in separate table variables.

    • "rownames" — Place the row labels to the left of the leftmost table variable. This option sets the RowNames property of the pivoted table to the row group names. If Rows specifies multiple grouping variables, the pivoted table concatenates the group names with an underscore.

    The row labels are defined by the group names in the grouping variables specified by Rows.

    Example: P = pivot(T,Rows="Var1",RowLabelPlacement="rownames")

    More About

    collapse all

    Pivoting Operation

    These tables illustrate pivoting operations.

    Sample Table TSyntax ExamplePivoted Table

    pivot(T,Columns="VarA",Rows="VarB")

    pivot(T,Columns=["VarA" "VarB"])

    pivot(T,Rows=["VarA" "VarB"])

    Sample Table TSyntax ExamplePivoted Table

    pivot(T,Columns="VarA",Rows="VarB",DataVariable="VarD",Method="numunique")

    pivot(T,Columns="VarA",Rows=["VarB" "VarC"],DataVariable="VarD",Method="mean")

    pivot(T,Columns=["VarA" "VarB"],Rows="VarC",DataVariable="VarD",Method="sum")

    Tips

    • The pivot function can apply the computation method to at most one data variable. To apply multiple computation methods or specify multiple data variables, use the groupsummary function.

    Alternative Functionality

    Live Editor Task

    You can use pivot functionality interactively by adding the Pivot Table task to a live script.

    Pivot Table task in the Live Editor

    Version History

    Introduced in R2023a

    expand all