# dsp.Histogram

(To be removed) Histogram of input or sequence of inputs

## Description

The `Histogram` object generates a histogram for an input or a sequence of inputs.

### Note

The `dsp.Histogram` System object™ will be removed in a future release. Use the `histcounts` function instead. For more information, see Compatibility Considerations.

To generate a histogram for an input or a sequence of inputs:

1. Create the `dsp.Histogram` object and set its properties.

2. Call the object with arguments, as if it were a function.

## Creation

### Syntax

``hist = dsp.Histogram``
``hist = dsp.Histogram(min,max,numbins)``
``hist = dsp.Histogram(Name,Value)``

### Description

````hist = dsp.Histogram` returns a histogram object, `hist`, that computes the frequency distribution of the elements in each input matrix.```
````hist = dsp.Histogram(min,max,numbins)` returns a histogram object, `hist`, with the `LowerLimit` property set to `min`, `UpperLimit` property set to `max`, and `NumBins` property set to `numbins`.```
````hist = dsp.Histogram(Name,Value)` returns a histogram object, `hist`, with each specified property set to the specified value. Enclose each property name in single quotes. Unspecified properties have default values.```

## Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the `release` function unlocks them.

If a property is tunable, you can change its value at any time.

Specify the lower boundary of the lowest-valued bin as a real-valued scalar. `NaN` and `Inf` are not valid values for this property.

Tunable: Yes

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

Specify the upper boundary of the highest-valued bin as a real-valued scalar. `NaN` and `Inf` are not valid values for this property.

Tunable: Yes

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

Specify the number of bins in the histogram.

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

Specify how the histogram calculation is performed over the data as `All` or `Column`.

Specify whether the histogram object normalizes the output vector, v, so that $sum\left(v\right)=1$. When you set this property to `true`, the output vector is normalized. When you set it to `false`, the object supports fixed-point operations and does not use this property for normalization.

Set this property to `true` to enable running histogram calculations for the input elements over successive calls to the algorithm. Set this property to `false` to compute a histogram for the current input.

Set this property to `true` to enable resetting the running histogram. When you set the property to `true`, specify a reset input to the object algorithm that resets the running histogram. When this property is `false`, the histogram object does not reset.

#### Dependencies

This property applies when you set the `RunningHistogram` property to `true`.

Specify the event that resets the running histogram as ```Rising edge```, `Falling edge`, `Either edge`, or `Non-zero`.

#### Dependencies

This property applies when you set the `ResetInputPort` property to `true`.

### Fixed-Point Properties

Specify the rounding method.

Specify the overflow action as `Wrap` or `Saturate`.

Specify the product fixed-point data type as `Same as input` or `Custom`.

Specify the product fixed-point type as a scaled `numerictype` object with a `Signedness` of `Auto`.

#### Dependencies

This property applies when you set the `ProductDataType` property to `Custom`.

Specify the accumulator fixed-point data type as one of ```Same as product```, `Same as input`, or `Custom` |.

Specify the accumulator fixed-point type as a scaled `numerictype` object with a `Signedness` of `Auto`.

#### Dependencies

This property applies when you set the `AccumulatorDataType` property to `Custom`.

## Usage

### Syntax

``y = hist(x)``
``y = hist(x,r)``

### Description

````y = hist(x)` returns a histogram `y` for the input data `x` . When the `RunningHistogram` property is `true`, `y` corresponds to the histogram of the input elements over successive calls to the algorithm.```
````y = hist(x,r)` resets the histogram state based on the reset signal, `r` and the object's `ResetCondition` property. You can reset the histogram state only when the `RunningHistogram` and the `ResetInputPort` properties are `true`.```

### Input Arguments

expand all

Data input, specified as a vector, matrix, or N-D array. If `x` is a matrix, each column is treated as an independent channel.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `fi`
Complex Number Support: Yes

Reset signal, specified as a scalar. The reset signal resets the histogram state based on the value of `r` and the object's `ResetCondition` property.

#### Dependencies

You can reset the histogram state only when the `RunningHistogram` and the `ResetInputPort` properties are `true`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `logical`

### Output Arguments

expand all

Histogram output of the input signal, returned as a scalar, vector, or matrix. The output depends on the setting of `Dimension`:

• `'Column'` –– The object computes the histogram value of each input channel. If the input is a column vector, the output is a scalar. If the input is a multichannel signal, the output signal is 1-by-N vector, where N is the number of input channels.

• `'All'` –– The object computes the histogram value over all input channels.

Data Types: `single` | `double` | `uint32`

## Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named `obj`, use this syntax:

`release(obj)`

expand all

 `step` Run System object algorithm `release` Release resources and allow changes to System object property values and input characteristics `reset` Reset internal states of System object

## Examples

### Compute Histogram of Sequence

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent `step` syntax. For example, `obj(x)` becomes `step(obj,x)`.

Compute a histogram with four bins, for possible input values 1 through 4.

```hist = dsp.Histogram(1,4,4); y = hist([1 2 2 3 3 3 4 4 4 4]')```
```y = 4×1 1 2 3 4 ```

## Algorithms

This object implements the algorithm, inputs, and outputs described on the Histogram block reference page. The object properties correspond to the block parameters, except:

• The Reset port block parameter corresponds to both the `ResetCondition` and the `ResetInputPort` object properties.

• The Find histogram over block parameter corresponds to the Dimension property of the object.

## Compatibility Considerations

expand all

Warns starting in R2019b