# Documentation

### This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

# Histogram

Generate histogram of input or sequence of inputs

## Library

Statistics

`dspstat3`

## Description

The Histogram block computes the frequency distribution of the elements in the input. You must use the Find the histogram over parameter to specify whether the block computes the histogram for `Each column` of the input or of the `Entire input`. The Running histogram check box allows you to select between basic operation and running operation, as described below.

The block distributes the elements of the input into the number of discrete bins specified by the Number of bins parameter, `n`.

`y = histogram(u,n) % Equivalent MATLAB code `

The Histogram block sorts all complex input values into bins according to their magnitude.

The histogram value for a given bin represents the frequency of occurrence of the input values bracketed by that bin. You specify the upper boundary of the highest-valued bin in the Upper limit of histogram parameter, BM, and the lower boundary of the lowest-valued bin in the Lower limit of histogram parameter, Bm. The bins have equal width of

`$\Delta =\frac{{B}_{M}-{B}_{m}}{n}$`

and centers located at

`${B}_{m}+\left(k+\frac{1}{2}\right)\Delta \begin{array}{cccc}& & & k=0,1,2,...,n-1\end{array}$`

Input values that fall on the border between two bins are placed into the lower valued bin; that is, each bin includes its upper boundary. For example, a bin of width 4 centered on the value 5 contains the input value 7, but not the input value 3. Input values greater than the Upper limit of histogram parameter or less than Lower limit of histogram parameter are placed into the highest valued or lowest valued bin, respectively.

The values you enter for the Upper limit of histogram and Lower limit of histogram parameters must be real-valued scalars. `NaN` and `inf` are not valid values for the Upper limit of histogram and Lower limit of histogram parameters.

### Basic Operation

When the Running histogram check box is not selected, the Histogram block computes the frequency distribution of the current input.

When you set the Find the histogram over parameter to `Each column`, the Histogram block computes a histogram for each column of the M-by-N matrix independently. The block outputs an n-by-N matrix, where n is the Number of bins you specify. The jth column of the output matrix contains the histogram for the data in the jth column of the M-by-N input matrix.

When you set the Find the histogram over parameter to `Entire input`, the Histogram block computes the frequency distribution for the entire input vector, matrix or N-D array. The block outputs an n-by-1 vector, where n is the Number of bins you specify.

### Running Operation

When you select the Running histogram check box, the Histogram block computes the frequency distribution of both the past and present data for successive inputs. The block resets the histogram (by emptying all of the bins) when it detects a reset event at the optional Rst port. See Resetting the Running Histogram for more information on how to trigger a reset.

When you set the Find the histogram over parameter to `Each column`, the Histogram block computes a running histogram for each column of the M-by-N matrix. The block outputs an n-by-N matrix, where n is the Number of bins you specify. The jth column of the output matrix contains the running histogram for the jth column of the M-by-N input matrix.

When you set the Find the histogram over parameter to `Entire input`, the Histogram block computes a running histogram for the data in the first dimension of the input. The block outputs an n-by-1 vector, where n is the Number of bins you specify.

 Note:   When the Histogram block is used in running mode and the input data type is non-floating point, the output of the histogram is stored as a `uint32` data type. The largest number that can be represented by this data type is `232-1`. If the range of the `uint32` data type is exceeded, the output data will wrap back to 0.

### Resetting the Running Histogram

The block resets the running histogram whenever a reset event is detected at the optional Rst port. The reset signal and the input data signal must be the same rate.

You specify the reset event using the Reset port menu:

• `None` — Disables the Rst port

• `Rising edge` — Triggers a reset operation when the Rst input does one of the following:

• Rises from a negative value to a positive value or zero

• Rises from zero to a positive value, where the rise is not a continuation of a rise from a negative value to zero (see the following figure)

• `Falling edge` — Triggers a reset operation when the `Rst` input does one of the following:

• Falls from a positive value to a negative value or zero

• Falls from zero to a negative value, where the fall is not a continuation of a fall from a positive value to zero (see the following figure)

• `Either edge` — Triggers a reset operation when the `Rst` input is a ```Rising edge``` or `Falling edge` (as described earlier)

• `Non-zero sample` — Triggers a reset operation at each sample time that the `Rst` input is not zero

## Examples

### Real Input Data

The bin boundaries created by the Histogram block are determined by the data type of the input:

• Bin boundaries for real, double-precision input are cast into the data type `double`.

• Bin boundaries for real, fixed-point input are cast into the `int8` data type.

The following example shows the differences in the output of the Histogram block based on the data type of the input.

To create this model you need the following blocks.

BlockLibraryQuantity

Constant

2

Display

Sinks

2

Histogram

Statistics

2

The parameter settings for the Double Precision Input Constant block are:

• Constant value = ```double([1 2 3 4 5]')```

• Interpret vector parameters as 1-D = Clear this check box.

• Sampling mode = ```Sample based```

• Sample time = `inf`

The parameter settings for the Fixed-Point Input Constant block are:

• Constant value = ```int8([1 2 3 4 5]')```

• Interpret vector parameters as 1-D = Clear this check box.

• Sampling mode = ```Sample based```

• Sample time = `inf`

The parameter settings for both Histogram blocks are:

• Lower limit of histogram = `1`

• Upper limit of histogram = `3`

• Number of bins = `5`

• Find the histogram over = ```Entire input```

• Normalized = Clear this check box.

• Running histogram = Clear this check box.

Connect the blocks as shown in the following figure, and run your model.

Running the fixed-point model generates the following warning:

```Warning: The bin width resulting from the specified parameters is less than the precision of the input data type. This might cause unexpected results. Since bin width is calculated by ((upper limit - lower limit)/number of bins), you could increase upper limit or decrease lower limit or number of bins```.

This warning alerts you that it is not a good use case to have a histogram where 2 or more bin boundaries are the same. As the warning suggests, increasing the range of the limits of the histogram, or decreasing the number of bins, can correct this problem.

## Dialog Box

The Main pane of the Histogram block dialog appears as follows.

Lower limit of histogram

Enter a real-valued scalar for the lower boundary, Bm, of the lowest-valued bin. `NaN` and `inf` are not valid values for Bm. Tunable.

Upper limit of histogram

Enter a real-valued scalar for the upper boundary, BM, of the highest-valued bin. `NaN` and `inf` are not valid values for BM. Tunable.

Number of bins

The number of bins, n, in the histogram.

Find the histogram over

Specify whether the block finds the histogram over the entire input or along each column of the input.

 Note:   The ```Inherited (this choice will be removed - see release notes)``` option will be removed in a future release.
Normalized

When selected, the output vector, v, is normalized such that `sum(v) = 1`.

Use of this parameter is not supported for fixed-point signals.

Running histogram

Set to enable the running histogram operation, and clear to enable basic histogram operation. For more information, see Basic Operation and Running Operation.

Reset port

The type of event that resets the running histogram. For more information, see Resetting the Running Histogram. The reset signal and the input data signal must be the same rate. This parameter is enabled only when you select the Running histogram check box. For more information, see Running Operation.

The Data Types pane of the Histogram block dialog appears as follows.

 Note:   The fixed-point parameters listed are only used for fixed-point complex inputs, which are distributed by squared magnitude.
Rounding mode

Select the rounding mode for fixed-point operations.

Overflow mode

Select the overflow mode for fixed-point operations.

Product output data type

Specify the product output data type. See Multiplication Data Types for illustrations depicting the use of the product output data type. You can set it to:

• A rule that inherits a data type, for example, ```Inherit: Inherit via internal rule```. For more information on this rule, see Inherit via Internal Rule.

• An expression that evaluates to a valid data type, for example, `fixdt([],16,0)`

Click the Show data type assistant button to display the Data Type Assistant, which helps you set the Product output data type parameter.

Accumulator data type

Specify the accumulator data type. You can set this parameter to:

• A rule that inherits a data type, for example, ```Inherit: Inherit via internal rule```. For more information on this rule, see Inherit via Internal Rule.

• An expression that evaluates to a valid data type, for example, `fixdt([],16,0)`

Click the Show data type assistant button to display the Data Type Assistant, which helps you set the Accumulator data type parameter.

Lock data type settings against changes by the fixed-point tools

Select this parameter to prevent the fixed-point tools from overriding the data types you specify on the block mask.

## Supported Data Types

PortSupported Data Types

In

• Double-precision floating point

• Single-precision floating point

• Fixed point (signed and unsigned)

• 8-, 16-, and 32-bit signed integers

• 8-, 16-, and 32-bit unsigned integers

Output

• Double-precision floating point

• Single-precision floating point

• 32-bit unsigned integers

Rst

• Double-precision floating point

• Single-precision floating point

• Boolean

• 8-, 16-, and 32-bit signed integers

• 8-, 16-, and 32-bit unsigned integers

 Sort DSP System Toolbox `hist` MATLAB