HistogramChart
A HistogramChart is a type of graph that represents the distribution of
numerical data. It’s constructed by dividing the entire range of values into a
series of intervals—known as bins and then counting how many values fall into
each interval. The bins are typically of equal size and are adjacent to each
other, with no gaps. Each bin is represented by a bar, where the height of the
bar reflects the frequency or count of data points within that interval
Import
import { HistogramChart } from '@dynatrace/strato-components-preview/charts';
Use cases
The HistogramChart expects an array of bins where each bin represents a
continuous range of values. A bin is defined by two key parameters: the range
(from and to), which determines its width, and the count or frequency (value),
which determines its height.
Uneven Bin Widths
The HistogramChart accommodates uneven bin widths, providing a clearer
representation of the data. Each bin corresponds to a specific range of values
and these ranges can vary from one bin to another.
Overlapped and Stacked Bins
In some instances of the HistogramChart, when bins are not perfectly aligned
along the x-axis, the resulting bars may overlap. Conversely, if a bar aligns
perfectly, it will be stacked.
ℹ️ If you are interested in how to prepare your data for passing it to the this article might
Size
By default, the chart will use all the available container size up to a maximum
height of 300 pixels. This maximum height can be changed by providing a value in
the height prop of the HistogramChart. If a number is passed to this prop
without any unit specified, it will be treated as px.
Series actions
A series action is a creator-defined interaction with a given data point in the
chart. Basic interactions include copying a series name and inspecting the
underlying data of a data point. In order to enable chart interactions, the
ChartSeriesAction subcomponent needs to be appended within the
HistogramChart. More subcomponents can be added within this component, for
instance ChartSeriesAction.Item, where you can provide a custom action that
will appear in the legend menu. That action can execute any custom logic in its
onSelect callback or get disabled via a disabled prop.
Change the chart color/s
The HistogramChart provides a set of predefined color palettes and it also
accepts custom color palettes. See coloring for more
details.
Apart from all these options for providing a color palette, the HistogramChart
also offers the ability to override colors for specific series. When a color
override is specified, it takes precedence over the color that would otherwise
be assigned from the color palette. However, it does not affect the colors
assigned to other series. This allows for fine-grained control over the
appearance of individual series within the chart. The desired color should be
specified in the color prop of a specific series.
Value representation
By default, values within a chart are displayed as is - with their absolute
value (e.g. 3.14 kB). However, this can be changed so that instead of absolute
values, relative values are used. Relative values indicate the proportion that a
given dimension contributes to the sum (100%) of a given histogram bin. The
valueRepresentation prop can be used to change this behavior. For series with
only a single dimension, the relative value is based on the maximum value within
the given series.
Legend
The purpose of the legend is to provide additional identifying information for the chart, without needing to interact with the legend directly.
Visibility
The legend of the HistogramChart is shown by default. In order to hide or show
the legend, you need to set the value of legend.hidden on the subcomponent.
Position
By default, the position of the legend of the HistogramChart is set
automatically. This option prioritizes the legend placement to the right of the
chart area. When the chart width is reduced, the legend is repositioned to the
area beneath the chart. It is also possible to explicitly set the chart's legend
position to right or bottom with the position prop.
Legend ratio
By default, the legend occupies 25% of the container width, in the case where
the legend is positioned on the right and 25% of the container height if the
legend position is on the bottom.
It is possible to override the default legend ratio by setting a custom
percentage value for the ratio prop. The expected value is in the range of
5-80. Values out of expected ranges will roll back to the default legend
ratio.
Chart interactions
Chart interactions enable additional possibilities for end users to interact
with the data plotted within the chart area. The interactive options currently
supported within the HistogramChart are zoom-x, zoom in, zoom out, and pan. To
incorporate these interactions, the ChartInteractions subcomponent must be
added to the HistogramChart. The chart interaction can then either be
triggered using keyboard shortcuts or by the optional chart toolbar. To enable
the toolbar with the chart interactions, the ChartToolbar subcomponent must be
added to the HistogramChart. To set initial position of the toolbar, the
placement prop can be used.
Explore
The explore functionality is the default mode and it allows you to inspect the
data within the chart. It includes an optional feature to select an area to zoom
along the x-axis. In order to enable this option it is necessary to add the
ChartInteractions.ZoomX subcomponent to the ChartInteractions component. You
can also pan with the mouse middle button in Explore mode by enabling the
ChartInteractions.Pan subcomponent.
You can optionally trigger this mode from the keyboard by pressing E while the
chart has focus.
Zoom-In and Zoom-Out
The zoom functionality within the HistogramChart allows users to zoom in to
the chart's plotted data by a fixed point along the x-axis. The chart supports
zoom in (incremental) and zoom out (decremental) actions.
In order to enable either of these zoom options on a chart it is necessary to
add the ChartInteractions.Zoom subcomponent to the ChartInteractions
component.
You can optionally zoom in/out different ways by first focusing the chart:
- Pressing
Cmd(Mac) orCtrl(Windows) + the mouse wheel, will generate a zoom in/out trigger. - Pressing
Cmd(Mac) orCtrl(Windows) + ↑ (Up Arrow) will zoom-in. - Pressing
Cmd(Mac) orCtrl(Windows) + ↓ (Down Arrow) will zoom-out.
Pan
Once a user has zoomed into the plotted data on a chart, panning can optionally
be enabled. Panning allows users to navigate left and right along the x-axis
whilst in a zoomed-in state. In order to enable this functionality, the
ChartInteractions.Pan subcomponent needs to be added to the
ChartInteractions component.
You can optionally trigger this mode from the keyboard by pressing P while the
chart has focus.
Once you have triggered this mode:
- Pressing ← (Left Arrow) will pan to the left. You can also press
Shiftto increase the speed of pan movement. - Pressing → (Right Arrow) will pan to the right. You can also press
Shiftto increase the speed of pan movement.
Reset
Reset will restore the chart to its initial state.
You can optionally trigger this action from the keyboard by pressing R while
the chart has focus.
- Double clicking on any part of the chart will trigger a reset.
It's also possible to programmatically trigger all the previously described
interactions by calling their methods on the HistogramChart instance
reference. The available options are: exploreMode, panMode, zoomIn,
zoomOut and reset.
Axes
To configure the axes of the HistogramChart, the HistogramChart.XAxis and
HistogramChart.YAxis subcomponents can be added. The label property sets the
axis label. Axis scale boundaries can be set with the min and max props.
Both XAxis and YAxis supports linear and log scales.
Both HistogramChart.XAxis and HistogramChart.YAxis subcomponents also
support data-max in the max property and data-min in the min property.
These special values allow for granular control over the Y-axis scale
boundaries. By default, the auto value is used for both min and max
properties. The auto mode automatically determines both the minimum and
maximum values of the Y-axis scale based on the data in the chart (similar to
data-min and data-max) and sets the Y-axis baseline to zero.
Multiple Y-axes
The HistogramChart supports multiple Y-axes. HistogramChart.YAxis provides a
position property which can be set to either left or right.
When you specify multiple Y-axes, the chart automatically assigns data series to Y-axes based on the unique units of the data. The first unique unit is assigned to the left Y-axis, and the second unique unit to the right Y-axis. Note that any additional data series with different units from those already used will not be displayed.
Currently, it's not possible to assign data series to specific Y-axes, nor is it possible to use the same unit for both Y-axes.
Tooltip
Tooltips are used to display additional detailed information about a selected
data point and can be enabled by adding the HistogramChart.Tooltip
subcomponent. The tooltip variant defines whether the tooltip should contain
data points from all bins (shared) for the selected bin, or just the closest one
(single). The seriesDisplayMode prop can be used to define whether the tooltip
should be comprised of a single line of information or multiple lines.
The sequence of the input data in the chart determines the arrangement of the tooltip series.
Single
Shared
Formatter
The unit for the HistogramChart, by default, will be appended to the specified
value. There are two other options in the formatter that allow for greater
customization. The first option enables you to prepend the unit to the value,
while the second option enables you to ignore the original unit and append a
custom string instead. Additionally, there is a custom formatter option
available to allow you to change the input unit to one of your choice, e.g.: if
the input unit is bits, you are able to switch and display the unit as
bytes, correctly formatted. The formatted value is applied in the axis ticks,
as well as in the tooltip and the axis magnifier. The use cases below outline
each of these scenarios.
The precision of the formatter will adapt automatically based on the data decimals if there is no precision configuration from the custom formatter option.
Annotations
Annotations are used to visualize specific events or contextual notes on the
HistogramChart in the form of markers placed in the bins position.
The marker represents an annotation at a certain bin. They can be either a value (a certain number) or a range (from-to object), depending on the data provided to the Annotation. Annotations within the same bin are grouped together under a single marker that displays the number of grouped annotations. Markers can be displayed on a single or multiple tracks. When there are more than three tracks, an overflow scroll is applied.
Add annotations to the chart
In order to visualize annotation data inside the HistogramChart, a
HistogramChart.Annotations component should be initialized. This component
should have at least one track, that contains a marker component per annotation
data point.
An annotation data point should contain the from-to bin information
(value: {from: number, to:number}) or a certain point (value: number), an
optional symbol, title, and description, which will be displayed in the
tooltip.
Marker content
When the symbol is provided, it will become the marker content by default.
When not, the title will be shown as marker content.
In case the content of the marker is bigger than the size of the marker (bin size in Histogram), it will expand to fit all the content inside, decoupling from the original scale. In these particular cases, it is encouraged to use the indicators, which will represent the real size of the bin.
Visual customization
Tracks and markers support visual customization in order to differentiate various types of annotations.
It's possible to set custom colors on both the track (to be applied to all
markers) and the marker level by using the color property on the respective
component. A marker's custom color has precedence over track's. This color can
be set to any Design System color token, as well as any rgb, hex or
CSS color.
The symbol property allows you to apply an icon, emoji, single letter, glyph,
or Design System icon to either an individual marker or to an entire track. When
applied to a track, this symbol will be used as the default.
When markers partially overlap one another, the order of the annotations defines which marker is displayed on top. Value annotations are always displayed above Range-based ones. It's also possible to customize the marker display order, by using the priority property. The higher the value of the priority property, the higher precedence the marker has. The priority property also affects the color of markers i.e. within a group, the color of the marker with the highest priority will be applied to the group.
It's possible to assign a label to a track using the label property. Be aware
that labels are hidden by default. To show a track's label, the showLabels
property has to be applied to the HistogramChart.Annotations component.
Visibility
An entire track can be hidden by adding the hidden property to the
HistogramAnnotations.Track component. The same configuration can be applied to
a marker, by setting the hidden property on the HistogramAnnotations.Marker
component.
When hovering a marker (with the cursor), an annotation indicator appears over
the chart area. The indicator's visibility can be customized on either a track
or marker level by using the indicatorsDisplay property:
- With the
autooption, the default behaviour is applied - indicators appear on hover. - The
alwaysoption sets indicators to always be visible within the chart area, regardless of the hovering behavior. - The
neveroption sets indicators to never be visible.
Thresholds
Thresholds are used to mark meaningful ranges or values on a HistogramChart
and they add contextual information to a numerical axis. There are two variants
of thresholds:
- a specific point represented on the Y-axis and a line across.
- a range - or filled area - represented by a pill on the Y-axis and a band across.
Point and Range
Both point and range can be represented by static or dynamic data sources. A static data source has a single value representing a point or a single key-value pair representing a fixed range. A dynamic data source has a data array containing more than one value or various key-value pairs.
There are three different types of threshold markers:
-
Range filled, where the value range is defined in order to display the threshold band. The upper and lower lines are not drawn unless the pill is hovered.
-
Range stroke-only variant, where a value range is defined in order to display the threshold band represented by upper and lower dashed lines. The upper and lower lines become continuous lines when the pill is hovered.
-
Point, where only one value is required to display the threshold. It's represented by a dashed line and when the point is hovered the line becomes a continuous line.
Dynamic Point
Dynamic Range
Dynamic Range Stroke Only
There is no limit defined for the number of threshold ranges or points that can
be used in a single HistogramChart.
By default, thresholds are positioned on the left axis and with the use of the
position prop, we can place thresholds on the right axis or on both, as
depicted below.
Left Axis
Right Axis
Dual Axis
Error state
The ErrorState subcomponent is responsible for handling errors in a graceful
manner, ultimately improving the overall user experience. Its primary function
is to catch any errors that may occur with the data and display a fallback UI
instead of crashing the entire application. The fallback UI occupies the full
width and height of the chart, ensuring that users are still provided with a
meaningful interface even in the presence of errors.
The ErrorState subcomponent offers a versatile feature that enables it to
handle both default and custom error messages. You can provide a custom message
through the ErrorState subcomponent, which will then override the default
error message. This flexibility allows developers to tailor error messages to
their specific needs and requirements, ensuring a more personalized and
informative user experience.
The ErrorState subcomponent provides the flexibility to format custom error
messages using HTML, which allows for enhanced customization and adaptability in
presenting error information. Furthermore, it is possible to incorporate the
original thrown error within your custom error message, ensuring that users
receive comprehensive and relevant information when an error occurs.
EmptyState
The EmptyState subcomponent serves as a fallback when there is no data
available to display in a chart. Its purpose is to provide a user-friendly way
of informing the user about the current situation. When there is no data, a
fallback UI is displayed occupying the full width and height of the chart, along
with a default message.
A feature of EmptyState is its ability to handle custom messages. It provides
the flexibility to format custom messages using HTML, which allows for enhanced
customization and adaptability in presenting error information.
Loading
The loading prop is a boolean value that can be passed to the HistogramChart
component to control its loading state. When the loading prop is set to true,
the loading indicator appears in the middle of the chart plot to inform the user
that the component is currently fetching or processing data. When the loading
prop is set to false, the component should display its regular content.
Download data as CSV
The HistogramChart component supports download data in CSV format using a
toolbar button. To enable this feature, a ChartToolbar subcomponent with
ChartToolbar.DownloadData inside of it must be provided to the
HistogramChart component. On click of the download button, raw data will be
downloaded as a CSV file.
The CSV file contains the following columns:
name- the name of the seriesunit- the unit of the seriesfrom- the start of the bin rangeto- the end of the bin rangevalue- the value of the bin
It's also possible to programmatically trigger the download of the CSV file by
calling the downloadData method on the HistogramChart instance reference.
Styling
The HistogramChart also accepts custom styling, which can be set using the
props className and/or style as in a regular html element.