Main Content

head

Get top rows of table, timetable, or tall array

Description

example

B = head(A) returns the first eight rows of table, timetable, or tall array A.

example

B = head(A,k) returns the first k rows of A.

example

head(___) displays the first eight, or the first k, rows of A without returning a value.

Examples

collapse all

Create a table by reading data from a spreadsheet. Display the size of the table, showing that it has 1468 rows.

T = readtable("outages.csv","TextType","string");
size(T)
ans = 1×2

        1468           6

Return another table that has the first eight rows of T.

T2 = head(T)
T2=8×6 table
      Region          OutageTime        Loss     Customers     RestorationTime           Cause      
    ___________    ________________    ______    __________    ________________    _________________

    "SouthWest"    2002-02-01 12:18    458.98    1.8202e+06    2002-02-07 16:50    "winter storm"   
    "SouthEast"    2003-01-23 00:49    530.14    2.1204e+05                 NaT    "winter storm"   
    "SouthEast"    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    "winter storm"   
    "West"         2004-04-06 05:44    434.81    3.4037e+05    2004-04-06 06:10    "equipment fault"
    "MidWest"      2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    "severe storm"   
    "West"         2003-06-18 02:49         0             0    2003-06-18 10:54    "attack"         
    "West"         2004-06-20 14:39    231.29           NaN    2004-06-20 19:16    "equipment fault"
    "West"         2002-06-06 19:28    311.86           NaN    2002-06-07 00:51    "equipment fault"

Create a table from a file with 1468 rows.

T = readtable("outages.csv","TextType","string");
size(T)
ans = 1×2

        1468           6

Display the first three rows. If you do not specify an output argument, head does not return a value. It only displays the top of the table.

head(T,3)
      Region          OutageTime        Loss     Customers     RestorationTime         Cause     
    ___________    ________________    ______    __________    ________________    ______________

    "SouthWest"    2002-02-01 12:18    458.98    1.8202e+06    2002-02-07 16:50    "winter storm"
    "SouthEast"    2003-01-23 00:49    530.14    2.1204e+05                 NaT    "winter storm"
    "SouthEast"    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    "winter storm"

Create a tall table. Then extract and view the first eight rows of data.

Create a tall table for the airlinesmall.csv data set. Select a subset of the table variables to work with.

varnames = ["Year","Month","ArrDelay","DepDelay","UniqueCarrier"];
ds = tabularTextDatastore("airlinesmall.csv","TreatAsMissing","NA",...
     "SelectedVariableNames",varnames,"TextType","string");
T = tall(ds)
T =

  Mx5 tall table

    Year    Month    ArrDelay    DepDelay    UniqueCarrier
    ____    _____    ________    ________    _____________

    1987     10          8          12           "PS"     
    1987     10          8           1           "PS"     
    1987     10         21          20           "PS"     
    1987     10         13          12           "PS"     
    1987     10          4          -1           "PS"     
    1987     10         59          63           "PS"     
    1987     10          3          -2           "PS"     
    1987     10         11          -1           "PS"     
     :        :         :           :              :
     :        :         :           :              :

To extract the first eight rows of data, use head. The result is a tall table with eight rows.

tt = head(T)
tt =

  8x5 tall table

    Year    Month    ArrDelay    DepDelay    UniqueCarrier
    ____    _____    ________    ________    _____________

    1987     10          8          12           "PS"     
    1987     10          8           1           "PS"     
    1987     10         21          20           "PS"     
    1987     10         13          12           "PS"     
    1987     10          4          -1           "PS"     
    1987     10         59          63           "PS"     
    1987     10          3          -2           "PS"     
    1987     10         11          -1           "PS"     

Collect the data into memory using the gather function. The result is an ordinary table with eight rows.

t8 = gather(tt)
t8=8×5 table
    Year    Month    ArrDelay    DepDelay    UniqueCarrier
    ____    _____    ________    ________    _____________

    1987     10          8          12           "PS"     
    1987     10          8           1           "PS"     
    1987     10         21          20           "PS"     
    1987     10         13          12           "PS"     
    1987     10          4          -1           "PS"     
    1987     10         59          63           "PS"     
    1987     10          3          -2           "PS"     
    1987     10         11          -1           "PS"     

Preview the first 20 rows of data in a tall table.

Create a tall table for the airlinesmall.csv data set. Select a subset of the variables to work with, and treat "NA" values as missing data so that datastore replaces them with NaN values. Use head to view the first 20 rows of data.

varnames = ["Year","Month","ArrDelay","DepDelay","UniqueCarrier"];
ds = tabularTextDatastore("airlinesmall.csv","TreatAsMissing","NA",...
     "SelectedVariableNames",varnames,"TextType","string");
T = tall(ds)
T =

  Mx5 tall table

    Year    Month    ArrDelay    DepDelay    UniqueCarrier
    ____    _____    ________    ________    _____________

    1987     10          8          12           "PS"     
    1987     10          8           1           "PS"     
    1987     10         21          20           "PS"     
    1987     10         13          12           "PS"     
    1987     10          4          -1           "PS"     
    1987     10         59          63           "PS"     
    1987     10          3          -2           "PS"     
    1987     10         11          -1           "PS"     
     :        :         :           :              :
     :        :         :           :              :
tt = head(T,20)
tt =

  20x5 tall table

    Year    Month    ArrDelay    DepDelay    UniqueCarrier
    ____    _____    ________    ________    _____________

    1987     10          8          12           "PS"     
    1987     10          8           1           "PS"     
    1987     10         21          20           "PS"     
    1987     10         13          12           "PS"     
    1987     10          4          -1           "PS"     
    1987     10         59          63           "PS"     
    1987     10          3          -2           "PS"     
    1987     10         11          -1           "PS"     
     :        :         :           :              :
     :        :         :           :              :

Collect the results into memory to view the data.

t20 = gather(tt)
t20=20×5 table
    Year    Month    ArrDelay    DepDelay    UniqueCarrier
    ____    _____    ________    ________    _____________

    1987     10          8          12           "PS"     
    1987     10          8           1           "PS"     
    1987     10         21          20           "PS"     
    1987     10         13          12           "PS"     
    1987     10          4          -1           "PS"     
    1987     10         59          63           "PS"     
    1987     10          3          -2           "PS"     
    1987     10         11          -1           "PS"     
    1987     10          3           3           "PS"     
    1987     10          2           1           "PS"     
    1987     10         16          15           "PS"     
    1987     10          3           9           "PS"     
    1987     10         39          15           "PS"     
    1987     10         57          32           "TW"     
    1987     10          0          -3           "TW"     
    1987     10        -14           0           "TW"     
      ⋮

Input Arguments

collapse all

Input array, specified as a table, timetable, or tall array.

Number of rows to extract, specified as a positive scalar integer. If A has fewer than k rows, then head returns all of A.

Output Arguments

collapse all

Requested rows, returned as a table, timetable, or tall array. The data type of B is the same as A.

Extended Capabilities

Version History

Introduced in R2016b

expand all