Histogram - Histogram appearance and behavior - MATLAB (original) (raw)
Histogram Properties
Histogram appearance and behavior
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
Categories
Data Types: cell | categorical | string | pattern
Data
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 specifyInf 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
This property is read-only.
Bin values, returned as a numeric vector. IfNormalization is 'count' (the default), then the kth element inValues specifies how many elements ofData fall in the kth 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, theValues property can instead contain a normalized variant of the bin counts.
Bin counts, specified as a vector. Use this input to pass bin counts tohistogram 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. IfNormalization is 'count', thenValues and BinCounts are equivalent.
Example: histogram('BinEdges',-2:2,'BinCounts',[5 8 15 9])
Example: histogram('Categories',{'Yes','No','Maybe'},'BinCounts',[22 18 3])
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 andBinEdges.
If you specify BinCounts, thenBinCountsMode is automatically set to'manual'. Similarly, if you specifyData, then BinCountsMode is automatically set to 'auto'.
Color and Styling
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: `histogram`(X,'EdgeAlpha',0.5) creates a histogram plot with semi-transparent bar edges.
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64
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 at1. 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 theColorOrder 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 to0, which also disables automatic color selection.
Legend
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 usingsprintf 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
DisplayNameproperty to the same value. - If you do not specify the text as an input argument to thelegend function, then the legend uses the text in the
DisplayNameproperty. The default value ofDisplayNameis one of these values.- For numeric inputs,
DisplayNameis 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, thenDisplayNameis empty,''. - For categorical array inputs,
DisplayNameis empty,''.
- For numeric inputs,
If the DisplayName property does not contain any text, then the legend generates a character vector. The character vector has the form 'dataN', whereN 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
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, seeDataTipTemplate Properties.
For an example of modifying data tips, see Create Custom Data Tips.
Note
The DataTipTemplate object is not returned byfindobj or findall, and it is not copied by copyobj.
Callbacks
Callback Execution Control
This property is read-only.
Parent/Child
Parent, specified as an Axes,PolarAxes, Group, orTransform object.
Identifiers
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.
Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value to serve as an identifier for an object. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.
Version History
Introduced in R2014b
You can create histograms with percentages on the vertical axis by setting theNormalization property to'percentage'.
Opt out of automatic color selection for Histogram objects by setting theSeriesIndex 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.
Control how Histogram objects vary in color by setting theSeriesIndex property. This property is useful when you want to match the colors of different objects in the axes.
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.