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:

Create the dsp.Histogram object and set its properties.
Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects? (MATLAB).

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.

For more information on changing property values, see System Design in MATLAB Using System Objects (MATLAB).

`LowerLimit` — Lower boundary
`0` (default) | real scalar

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

`UpperLimit` — Upper boundary
`10` (default) | real scalar

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

`NumBins` — Number of bins in histogram
`11` (default) | positive integer

Specify the number of bins in the histogram.

`Dimension` — Dimension
`Column` (default) | `All`

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

`Normalize` — Enable output vector normalization
`false` (default) | `true`

Specify whether the histogram object normalizes the output vector, v, so that $s u m (v) = 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.

`RunningHistogram` — Enable calculation over successive calls to algorithm
`false` (default) | `true`

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.

`ResetInputPort` — Enable resetting in running histogram mode
`false` (default) | `true`

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.

`ResetCondition` — Reset condition for running histogram mode
`Non-zero` (default) | `Rising edge` | `Falling edge` | `Either edge`

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

`RoundingMethod` — Rounding method for fixed-point operations
`Floor` (default) | `Ceiling` | `Convergent` | `Nearest` | `Round` | `Simplest` | `Zero`

Specify the rounding method.

`OverflowAction` — Overflow action for fixed-point operations
`Wrap` (default) | `Saturate`

Specify the overflow action as Wrap or Saturate.

`ProductDataType` — Product word and fraction lengths
`Same as input` (default) | `Custom`

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

`CustomProductDataType` — Custom product word and fraction lengths
`numerictype([],32,30)` (default) | numerictype

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.

`AccumulatorDataType` — Accumulator word and fraction lengths
`Same as input` (default) | `Same as product` | `Custom`

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

`CustomAccumulatorDataType` — Custom accumulator word and fraction lengths
`numerictype([],32,30)` (default) | numerictype

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

`x` — Data input
vector | matrix | N-D array

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

`r` — Reset signal
scalar

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

`y` — Histogram output
scalar | vector

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

Common to All System Objects

`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]')

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

`dsp.Histogram` System object will be removed

Warns starting in R2019b

The dsp.Histogram System object will be removed in a future release. Use the histcounts function instead.

Update Code

This table shows typical usage of the System object and explains how to update existing code to use the equivalent function.

Discouraged Usage Recommended Replacement

Discouraged Usage	Recommended Replacement
x = [1 2 2 3 3 3 4 4 4 4]'; myhistogram = dsp.Histogram(1,4,4) n = myhistogram(x) n is the histogram. myhistogram = dsp.Histogram(1,5,4) n = myhistogram(x) If you are using a release prior to R2016b, replace `myhistogram(x)` with `step(myhistogram,x)`.	x = [1 2 2 3 3 3 4 4 4 4]'; [n,edges] = histcounts(x) n is the histogram, and edges is the bin edges. [n,edges] = histcounts(x,4,'BinLimits',[1 5],... 'BinEdges',[1 2.25 3.5 4.75 5])

x = [1 2 2 3 3 3 4 4 4 4]';
myhistogram = dsp.Histogram(1,4,4)
n = myhistogram(x)

n is the histogram.

myhistogram = dsp.Histogram(1,5,4)
n = myhistogram(x)

If you are using a release prior to R2016b, replace myhistogram(x) with step(myhistogram,x).

x = [1 2 2 3 3 3 4 4 4 4]';
[n,edges] = histcounts(x)

n is the histogram, and edges is the bin edges.

[n,edges] = histcounts(x,4,'BinLimits',[1 5],...
'BinEdges',[1 2.25 3.5 4.75 5])

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

This object has no tunable properties for code generation.
See System Objects in MATLAB Code Generation (MATLAB Coder).

Documentation

dsp.Histogram

Description

Note

Creation

Syntax

Description

Properties

LowerLimit — Lower boundary 0 (default) | real scalar

UpperLimit — Upper boundary 10 (default) | real scalar

NumBins — Number of bins in histogram 11 (default) | positive integer

Dimension — Dimension Column (default) | All

Normalize — Enable output vector normalization false (default) | true

RunningHistogram — Enable calculation over successive calls to algorithm false (default) | true

ResetInputPort — Enable resetting in running histogram mode false (default) | true

Dependencies

ResetCondition — Reset condition for running histogram mode Non-zero (default) | Rising edge | Falling edge | Either edge

Dependencies

Fixed-Point Properties

RoundingMethod — Rounding method for fixed-point operations Floor (default) | Ceiling | Convergent | Nearest | Round | Simplest | Zero

OverflowAction — Overflow action for fixed-point operations Wrap (default) | Saturate

ProductDataType — Product word and fraction lengths Same as input (default) | Custom

CustomProductDataType — Custom product word and fraction lengths numerictype([],32,30) (default) | numerictype

Dependencies

AccumulatorDataType — Accumulator word and fraction lengths Same as input (default) | Same as product | Custom

CustomAccumulatorDataType — Custom accumulator word and fraction lengths numerictype([],32,30) (default) | numerictype

Dependencies

Usage

Syntax

Description

Input Arguments

x — Data input vector | matrix | N-D array

r — Reset signal scalar

Dependencies

Output Arguments

y — Histogram output scalar | vector

Object Functions

Common to All System Objects

Examples

Compute Histogram of Sequence

Algorithms

Compatibility Considerations

dsp.Histogram System object will be removed

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

See Also

Functions

Introduced in R2012a

DSP System Toolbox Documentation

Support

`LowerLimit` — Lower boundary
`0` (default) | real scalar

`UpperLimit` — Upper boundary
`10` (default) | real scalar

`NumBins` — Number of bins in histogram
`11` (default) | positive integer

`Dimension` — Dimension
`Column` (default) | `All`

`Normalize` — Enable output vector normalization
`false` (default) | `true`

`RunningHistogram` — Enable calculation over successive calls to algorithm
`false` (default) | `true`

`ResetInputPort` — Enable resetting in running histogram mode
`false` (default) | `true`

`ResetCondition` — Reset condition for running histogram mode
`Non-zero` (default) | `Rising edge` | `Falling edge` | `Either edge`

`RoundingMethod` — Rounding method for fixed-point operations
`Floor` (default) | `Ceiling` | `Convergent` | `Nearest` | `Round` | `Simplest` | `Zero`

`OverflowAction` — Overflow action for fixed-point operations
`Wrap` (default) | `Saturate`

`ProductDataType` — Product word and fraction lengths
`Same as input` (default) | `Custom`

`CustomProductDataType` — Custom product word and fraction lengths
`numerictype([],32,30)` (default) | numerictype

`AccumulatorDataType` — Accumulator word and fraction lengths
`Same as input` (default) | `Same as product` | `Custom`

`CustomAccumulatorDataType` — Custom accumulator word and fraction lengths
`numerictype([],32,30)` (default) | numerictype

`x` — Data input
vector | matrix | N-D array

`r` — Reset signal
scalar

`y` — Histogram output
scalar | vector

`dsp.Histogram` System object will be removed

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.