Area Plot

An area plot, also known as a stacked area chart, is a data visualization that uses multiple filled areas stacked on top of one another to represent the cumulative contribution of distinct categories over a continuous interval or time period. Area plots always start the y-axis at zero, because the height of each line at any point is exactly equal to its contribution to the whole, and the proportion of each category’s contribution must be represented faithfully.

Area plots are appropriate when the data contain a continuous response variable that directly depends on a continuous explanatory variable, such as time. Further, the response variable can be broken down into contributions from each of several independent categories, and those categories are represented by an additional categorical variable.

What are area plots useful for?

  • Visualizing trends over time: Area plots are great for displaying the trend of a single continuous variable. The filled areas can make it easier to see the magnitude of changes and trends compared to line plots.
  • Displaying cumulative totals: Area plots are effective in showing cumulative totals over a period. They can help in understanding the contribution of different categories to the total amount and how these contributions evolve.
  • Comparing multiple categories: Rather than providing a single snapshot of the composition of a total, area plots show how contributions from each category change over time.

Examples

A basic area plot

Visualize the relationship between two variables by passing each column name to the x and y arguments.

import deephaven.plot.express as dx
gapminder = dx.data.gapminder()

# subset to get a specific group
usa_population = gapminder.where("Country == `United States`")

area_plot = dx.area(usa_population, x="Year", y="Pop")

Area by group

Area plots are unique in that the y-axis demonstrates each groups’ total contribution to the whole. Pass the name of the grouping column(s) to the by argument.

import deephaven.plot.express as dx
gapminder = dx.data.gapminder()

# subset to get several countries to compare
large_countries_population = gapminder.where("Country in `United States`, `India`, `China`")

# cumulative trend showing contribution from each group
area_plot_group = dx.area(large_countries_population, x="Year", y="Pop", by="Country")

API Reference

Returns an area chart

Returns: DeephavenFigure A DeephavenFigure that contains the area chart

ParametersTypeDefaultDescription
tablePartitionedTable |
Table |
DataFrame
A table to pull data from.
xstr |
list[str] |
None
NoneA column or list of columns that contain x-axis values.
ystr |
list[str] |
None
NoneA column or list of columns that contain y-axis values.
bystr |
list[str] |
None
NoneA column or list of columns that contain values to plot the figure traces by. All values or combination of values map to a unique design. The variable by_vars specifies which design elements are used. This is overriden if any specialized design variables such as color are specified
by_varsstr |
list[str] |
None
'color'A string or list of string that contain design elements to plot by. Can contain size, color, pattern_shape, and symbol. If associated maps or sequences are specified, they are used to map by column values to designs. Otherwise, default values are used.
colorstr |
list[str] |
None
NoneA column or list of columns that contain color values. The value is used for a plot by on color. See color_discrete_map for additional behaviors.
pattern_shapestr |
list[str] |
None
NoneA column or list of columns that contain pattern shape values. The value is used for a plot by on pattern shape. See pattern_shape_map for additional behaviors.
symbolstr |
list[str] |
None
NoneA column or list of columns that contain symbol values. The value is used for a plot by on symbol. See symbol_map for additional behaviors.
sizestr |
list[str] |
None
NoneA column or list of columns that contain size values. If only one column is passed, and it contains numeric values, the value is used as a size. Otherwise, the value is used for a plot by on size. See size_map for additional behaviors.
textstr |
None
NoneA column that contains text annotations.
hover_namestr |
None
NoneA column that contains names to bold in the hover tooltip.
labelsdict[str, str] |
None
NoneA dictionary of labels mapping columns to new labels.
color_discrete_sequencelist[str] |
None
NoneA list of colors to sequentially apply to the series. The colors loop, so if there are more series than colors, colors will be reused.
color_discrete_mapdict[str | tuple[str], str] |
None
NoneIf dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to colors.
pattern_shape_sequencelist[str] |
None
NoneA list of patterns to sequentially apply to the series. The patterns loop, so if there are more series than patterns, patterns will be reused.
pattern_shape_mapdict[str | tuple[str], str] |
None
NoneIf dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to patterns.
symbol_sequencelist[str] |
None
NoneA list of symbols to sequentially apply to the markers in the series. The symbols loop, so if there are more series than symbols, symbols will be reused.
symbol_mapstr |
tuple[str, dict[str | tuple[str], dict[str | tuple[str], str]]] |
dict[str | tuple[str], str] |
None
NoneIf dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to symbols. If "identity", the values are taken as literal symbols. If "by" or ("by", dict) where dict is as described above, the symbols are forced to by
size_sequencelist[int] |
None
NoneA list of sizes to sequentially apply to the markers in the series. The sizes loop, so if there are more series than symbols, sizes will be reused.
size_mapstr |
tuple[str, dict[str | tuple[str], dict[str | tuple[str], str]]] |
dict[str | tuple[str], str] |
None
NoneIf dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to sizes. If "identity", the values are taken as literal sizes. If "by" or ("by", dict) where dict is as described above, the sizes are forced to by
xaxis_sequencelist[str] |
None
NoneA list of x axes to assign series to. Odd numbers starting with 1 are created on the bottom x axis and even numbers starting with 2 are created on the top x axis. Axes are created up to the maximum number specified. The axes loop, so if there are more series than axes, axes will be reused.
yaxis_sequencelist[str] |
None
NoneA list of y axes to assign series to. Odd numbers starting with 1 are created on the left y axis and even numbers starting with 2 are created on the top y axis. Axes are created up to the maximum number specified. The axes loop, so if there are more series than axes, axes will be reused.
markersboolFalseTrue to draw markers on the line, False to not. Default False
groupnormstr |
None
NoneSet to 'fraction' to plot the fraction out of the total value of all points at that x value, 'percent' to take the fraction and multiply by 100. Note that if multiple y axes are specified, the groupnorm is taken per axis.
log_xbool |
list[bool]
FalseA boolean or list of booleans that specify if the corresponding axis is a log axis or not. The booleans loop, so if there are more series than booleans, booleans will be reused.
log_ybool |
list[bool]
FalseA boolean or list of booleans that specify if the corresponding axis is a log axis or not. The booleans loop, so if there are more series than booleans, booleans will be reused.
range_xlist[int] |
list[list[int]] |
None
NoneA list of two numbers or a list of lists of two numbers that specify the range of the x axes. None can be specified for no range The ranges loop, so if there are more axes than ranges, ranges will be reused.
range_ylist[int] |
list[list[int]] |
None
NoneA list of two numbers or a list of lists of two numbers that specify the range of the y axes. None can be specified for no range The ranges loop, so if there are more axes than ranges, ranges will be reused.
yaxis_titleslist[str] |
None
NoneA list of titles to sequentially apply to the y axes. The titles do not loop.
xaxis_titleslist[str] |
None
NoneA list of titles to sequentially apply to the x axes. The titles do not loop.
line_shapestr'linear'The line shape for all lines created. One of 'linear', 'spline', 'vhv', 'hvh', 'vh', 'hv'. Default 'linear'
titlestr |
None
NoneThe title of the chart
templatestr |
None
NoneThe template for the chart.
unsafe_update_figureCallable<function default_callback>An update function that takes a plotly figure as an argument and optionally returns a plotly figure. If a figure is not returned, the plotly figure passed will be assumed to be the return value. Used to add any custom changes to the underlying plotly figure. Note that the existing data traces should not be removed. This may lead to unexpected behavior if traces are modified in a way that break data mappings.