head

Get top rows of array or table

Syntax

head(A)

head(A,k)

B = head(___)

Description

head(A) displays the first eight rows of array, table, or timetable A in the Command Window without storing a value.

head(A,k) displays the first k rows of A.

B = head(___) returns the requested rows of A for either of the previous syntaxes. The data type of B is the same as the data type of A.

Examples

Display First Eight Rows of Matrix

Create a matrix with 100 rows, and display the first eight rows of the matrix.

If you do not specify an output argument, head does not return a value. It only displays the top of the matrix.

A = repmat((1:100)',1,4);
head(A)

     1     1     1     1
     2     2     2     2
     3     3     3     3
     4     4     4     4
     5     5     5     5
     6     6     6     6
     7     7     7     7
     8     8     8     8

Display First Three Rows of Table

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"

Return First Eight Rows of Table

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"

Input Arguments

A — Input data

array | cell array | table | timetable

Input data, specified as an array, cell array, table, or timetable.

k — Number of rows to extract

positive integer

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

Extended Capabilities

Tall Arrays

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

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

You can use head and tail with tall arrays of any valid underlying data type (single, double, int8, datetime, table, and so on).

If you are unsure whether the result returned by gather(A) will fit in memory, then use gather(head(A)) or gather(tail(A)). These commands still fully evaluate the tall array A but return only a small subset of the result in memory.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The head function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

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).

Version History

Introduced in R2016b

R2023a: Get top rows of array

Display or return the top rows of a vector, matrix, multidimensional array, or cell array using head. In previous releases, head supports only tables, timetables, and tall arrays.

R2022b: Calling head without specified output argument does not store output in ans

When you call head without a specified output argument, head displays the selected rows of the table but does not store the output in the ans variable. In previous releases, calling head without a specified output argument causes the output to be stored in ans.

Calling head in a live script is usually not recommended. Instead, display the table or timetable by typing the variable name with no semicolon. The Live Editor provides a widget that enables you to examine the entire table or timetable. However, if you do call head in a live script, it is recommended that you assign the output to a variable so that the live script creates a widget for the output.