Histogram appearance and behavior
expand all in page
Histogram
properties control the appearance and behavior of the histogram. By changing property values, you can modify aspects of the histogram. Use dot notation to refer to a particular object and property:
h = histogram(randn(10,1));c = h.BinWidth;h.BinWidth = 2;
Bins
expand all
Categories
expand all
Data
expand all
Data
— Data to distribute among bins
vector | matrix | multidimensional array | categorical array
Data to distribute among bins, specified as a vector, matrix, multidimensional array, or categorical array. If Data
is not a vector, then histogram
treats it as a single column vector, Data(:)
, and plots a single histogram.
histogram
ignores all NaN
, NaT
, and undefined categorical values. Similarly, histogram
ignores Inf
and -Inf
values unless the bin edges explicitly specify Inf
or -Inf
as a bin edge. Although NaN
, NaT
, Inf
, -Inf
, and <undefined>
values are typically not plotted, they are still included in normalization calculations that include the total number of data elements, such as 'probability'
.
You can only specify categorical values for Data
if the histogram object was originally created using categoricals.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
| categorical
| datetime
| duration
Values
— Bin values
numeric vector
This property is read-only.
Bin values, returned as a numeric vector. If Normalization
is 'count'
(the default), then the k
th element in Values
specifies how many elements of Data
fall in the k
th bin interval (bin counts). The last bin includes values that are on either bin edge, but all other bins only include values that fall on the leading edge.
Depending on the value of Normalization
, the Values
property can instead contain a normalized variant of the bin counts.
BinCounts
— Bin counts
vector
Bin counts, specified as a vector. Use this input to pass bin counts to histogram
when the bin counts calculation is performed separately and you do not want histogram
to do any data binning.
The length of counts
must be equal to the number of bins.
For numeric histograms, the number of bins is
length(edges)-1
.For categorical histograms, the number of bins is equal to the number of categories.
Compared to the Values
property, BinCounts
is not normalized. If Normalization
is 'count'
, then Values
and BinCounts
are equivalent.
Example: histogram('BinEdges',-2:2,'BinCounts',[5 8 15 9])
Example: histogram('Categories',{'Yes','No','Maybe'},'BinCounts',[22 18 3])
BinCountsMode
— Selection mode for bin counts
'auto'
(default) | 'manual'
Selection mode for bin counts, specified as 'auto'
or 'manual'
. The default value is 'auto'
, so that the bin counts are automatically computed from Data
and BinEdges
.
If you specify BinCounts
, then BinCountsMode
is automatically set to 'manual'
. Similarly, if you specify Data
, then BinCountsMode
is automatically set to 'auto'
.
Color and Styling
expand all
EdgeAlpha
— Transparency of histogram bar edges
1
(default) | scalar in range [0,1]
Transparency of histogram bar edges, specified as a scalar value in the range [0,1]
. A value of 1
means fully opaque and 0
means completely transparent (invisible).
Example:
creates a histogram plot with semi-transparent bar edges. histogram
(X,'EdgeAlpha',0.5)
SeriesIndex
— Series index
positive integer | "none"
Series index, specified as a positive integer or "none"
. This property is useful for reassigning the face colors of Histogram
objects so that they match the colors of other objects.
By default, the SeriesIndex
property of a Histogram
object is a number that corresponds to its order of creation, starting at 1
. MATLAB uses the number to calculate indices for assigning colors when you call plotting functions. The indices refer to the rows of the arrays stored in the ColorOrder
property of the axes. Any objects in the axes that have the same SeriesIndex
number will have the same color.
A SeriesIndex
value of "none"
corresponds to a neutral color that does not participate in the indexing scheme.
How Manual Color Assignment Overrides SeriesIndex
Behavior
To manually control face color, set the FaceColor
property of the Histogram
object to a color value, such as a color name or an RGB triplet.
When you manually set the face color of a Histogram
object, MATLAB disables automatic color selection for that object and allows your color to persist, regardless of the value of the SeriesIndex
property.
To enable automatic selection again, set the SeriesIndex
property to positive integer, and set the FaceColor
property to "auto"
.
In some cases, MATLAB sets the SeriesIndex
value to 0
, which also disables automatic color selection.
Legend
expand all
DisplayName
— Text used by legend
variable name of Data
or ''
(default) | character vector
Text used by the legend, specified as a character vector. The text appears next to an icon of the histogram.
Example: 'Text Description'
For multiline text, create the character vector using sprintf
with the new line character \n
.
Example: sprintf('line one\nline two')
Alternatively, you can specify the legend text using the legend function.
If you specify the text as an input argument to the legend function, then the legend uses the specified text and sets the
DisplayName
property to the same value.If you do not specify the text as an input argument to the legend function, then the legend uses the text in the
DisplayName
property. The default value ofDisplayName
is one of these values.For numeric inputs,
DisplayName
is a character vector representing the variable name of the input data used to construct the histogram. If the input data does not have a variable name, thenDisplayName
is empty,''
.For categorical array inputs,
DisplayName
is empty,''
.
If the DisplayName
property does not contain any text, then the legend generates a character vector. The character vector has the form 'dataN'
, where N
is the number assigned to the histogram object based on its location in the list of legend entries.
If you edit interactively the character vector in an existing legend, then MATLAB updates the DisplayName
property to the edited character vector.
Interactivity
expand all
DataTipTemplate
— Data tip content
DataTipTemplate
object
Data tip content, specified as a DataTipTemplate
object. You can control the content that appears in a data tip by modifying the properties of the underlying DataTipTemplate
object. For a list of properties, see DataTipTemplate Properties.
For an example of modifying data tips, see Create Custom Data Tips.
Note
The DataTipTemplate
object is not returned by findobj
or findall
, and it is not copied by copyobj
.
Callbacks
expand all
Callback Execution Control
expand all
Parent/Child
expand all
Parent
— Parent
Axes
object | PolarAxes
object | Group
object | Transform
object
Parent, specified as an Axes
, PolarAxes
, Group
, or Transform
object.
Identifiers
expand all
Type
— Type of graphics object
'histogram'
| 'categoricalhistogram'
This property is read-only.
Type of graphics object, returned as either 'histogram'
or 'categoricalhistogram'
. Use this property to find all objects of a given type within a plotting hierarchy, such as searching for the type using findobj.
Version History
Introduced in R2014b
expand all
R2023b: Normalize using percentages
You can create histograms with percentages on the vertical axis by setting the Normalization
property to 'percentage'
.
R2023b: Opt out of automatic color selection with SeriesIndex="none"
Opt out of automatic color selection for Histogram
objects by setting the SeriesIndex
property to "none"
. When you specify "none"
, the Histogram
object has a neutral color.
To enable automatic color selection again, set the SeriesIndex
property to a positive whole number.
R2020a: Control automatic color selection with the SeriesIndex
property
Control how Histogram
objects vary in color by setting the SeriesIndex
property. This property is useful when you want to match the colors of different objects in the axes.
R2020a: UIContextMenu
property is not recommended
Starting in R2020a, using the UIContextMenu
property to assign a context menu to a graphics object or UI component is not recommended. Use the ContextMenu
property instead. The property values are the same.
There are no plans to remove support for the UIContextMenu
property at this time. However, the UIContextMenu
property no longer appears in the list returned by calling the get
function on a graphics object or UI component.
See Also
histogram
Topics
- Access Property Values
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- Deutsch
- English
- Français
- United Kingdom (English)
Contact your local office