Accelerating the pace of engineering and science

• Trials

# hist

Histogram plot

## Syntax

• nelements = hist(___)
• [nelements,centers] = hist(___) example

## Description

example

hist(data) creates a histogram bar plot of data. Elements in data are sorted into 10 equally spaced bins along the x-axis between the minimum and maximum values of data. Bins are displayed as rectangles such that the height of each rectangle indicates the number of elements in the bin.

example

hist(data,nbins) sorts data into the number of bins specified by the scalar nbins.

example

hist(data,xvalues) sorts data into bins with intervals determined by the vector xvalues.

• If xvalues is a vector of evenly spaced values, then hist uses the values as the bin centers.

• If xvalues is a vector unevenly spaced values, then hist uses the midpoints between consecutive values as the bin edges.

The length of the vector, length(xvalues), determines the number of bins.

example

hist(axes_handle,___) plots into the axes specified by axes_handle instead of into the current axes (gca). The option axes_handle can precede any of the input argument combinations in the previous syntaxes.

nelements = hist(___) returns a row vector, nelements, indicating the number of elements in each bin.

example

[nelements,centers] = hist(___) returns an additional row vector, centers, indicating the location of each bin center on the x-axis. To plot the histogram, you can use bar(centers,nelements).

## Examples

expand all

### Create Histogram Bar Plot with Vector Input

```figure
data = [0,2,9,2,5,8,7,3,1,9,4,3,5,8,10,0,1,2,9,5,10];
hist(data)
```

hist sorts the values in data among 10 equally spaced bins between 0 and 10, the minimum and maximum values.

### Create Histogram Bar Plot with Matrix Input

Initialize the random-number generator to make the output of randn repeatable. Generate 1,000 normally distributed pseudorandom numbers and create a histogram bar plot.

```rng(0,'twister')
data = randn(1000,3);
figure
hist(data)
```

The values in data are sorted among 10 equally spaced bins between the minimum and maximum values. hist sorts the columns of data separately and plots each column with a different color.

### Specify Number of Bins

Initialize the random-number generator to make the output of randn repeatable. Generate 1,000 normally distributed pseudorandom numbers.

```rng(0,'twister')
data = randn(1000,1);
```

Create a histogram plot of data sorted into 50 equally spaced bins.

```figure
nbins = 50;
hist(data,nbins)
```

### Specify Bin Intervals

Create a figure divided into three subplots. Plot a histogram of the same data set in all three subplots using different bin intervals for each histogram.

First, initialize the random-number generator to make the output of randn repeatable. Generate 1,000 normally distributed pseudorandom numbers.

```rng(0,'twister')
data = randn(1000,1);
```

In the upper subplot specify the bin centers using a vector of evenly spaced values that span the values in data.

```figure
subplot(3,1,1)
xvalues1 = -4:4;
hist(data,xvalues1)
```

In the middle subplot specify the bin centers using a vector of evenly spaced values that do not span the values in data. Notice that the first and last bins extend to cover the minimum and maximum values in data.

```subplot(3,1,2)
xvalues2 = -2:2;
hist(data,xvalues2)
```

In the lower subplot set the bin intervals using a vector of unevenly spaced values. These unevenly spaced values are not used as the bin centers. MATLAB® indicates the specified values by markers along the x-axis.

```subplot(3,1,3)
xvalues3 = [-4,-2.5,0,0.5,1,3];
hist(data,xvalues3)
```

### Specify Axes for Histogram Bar Plot

Initialize the random-number generator to make the output of randn repeatable. Generate 1,000 normally distributed pseudorandom numbers.

```rng(0,'twister')
data = randn(1000,1);
```

Create a figure with handles to two subplots. In the upper subplot, plot a histogram of data sorted into 50 equally spaced bins. In the lower subplot, plot a histogram of the same data and use bins with centers at -3, 0, and 3.

```figure
s(1) = subplot(2,1,1);
s(2) = subplot(2,1,2);

hist(s(1),data,50)

xvalues = [-3,0,3];
hist(s(2),data,xvalues)
```

### Plot Histogram Using Bar Graph

Initialize the random-number generator to make the output of randn repeatable. Generate 1,000 normally distributed pseudorandom numbers.

```rng(0,'twister')
data = randn(1000,1);
```

Sort data into 10 equally spaced bins. Get the number of elements in each bin and the locations of the bin centers.

```[nelements,centers] = hist(data)
```
```nelements =

4    27    88   190   270   243   123    38    13     4

centers =

Columns 1 through 7

-2.8915   -2.2105   -1.5294   -0.8484   -0.1673    0.5137    1.1947

Columns 8 through 10

1.8758    2.5568    3.2379

```

Use bar to plot the histogram.

```figure
bar(centers,nelements)
```

### Change Histogram Color Properties

Initialize the random-number generator to make the output of randn repeatable. Generate 1,000 normally distributed pseudorandom numbers and create a histogram bar plot.

```figure
rng(0,'twister')
data = randn(1000,1);
hist(data)
```

Get the handle to the patch object that creates the histogram bar plot.

```h = findobj(gca,'Type','patch');
```

Use the handle to change the face color and the edge color of the bars plotted.

```set(h,'FaceColor',[0 .5 .5],'EdgeColor','w')
```

## Input Arguments

expand all

### data — Data to distribute among binsvector or matrix

Data to distribute among bins, specified as a vector or a matrix.

• If data is a vector, then one histogram is created.

• If data is a matrix, then a histogram is created separately for each column. Each histogram plot is displayed on the same figure with a different color.

If data contains NaN values, then hist ignores these values and does not include them in the bin counts.

If data contains the infinite values -inf or inf, then hist sorts -inf into the first bin and inf into the last bin. If you do not specify the bin intervals, then hist calculates the bin intervals using only the finite values in data.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

### nbins — Number of bins10 (default) | scalar

Number of bins, specified as a scalar.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

### xvalues — Values to calculate bin intervalsvector

Values to calculate bin intervals, specified as a vector.

• If the values in xvalues are equally spaced, then these values are the bin centers.

• If the values in xvalues are not equally spaced, then these values are indicated by markers along the x-axis, but are not the actual bin centers. Instead, MATLAB® calculates the bin edges as the midpoints between consecutive values in vector xvalues. To specify directly the bin edges use histc.

The first and last bins extend to cover the minimum and maximum values in data.

Use only finite values with xvalues. If xvalues contains -inf or inf, then hist does not populate the bins.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

### axes_handle — Axes handlehandle

Axes handle, which is the reference to an axes object. Use the gca function to get the handle to the current axes, for example, axes_handle = gca;.

## Output Arguments

expand all

### nelements — Number of elements in each binrow vector

Number of elements in each bin, returned as a row vector.

### centers — Bin centersrow vector

Bin centers, returned as a row vector. If used with the syntax [nelements,centers] = hist(data,xvalues), then the output centers is equal to the input xvalues.