# Bar Plot

A bar plot is a graphical representation of data that uses rectangular bars to display the values of different categories or groups. Bar plots aggregate the response variable across the entire dataset for each category, so that the y-axis represents the sum of the response variable per category.

Bar plots are appropriate when the data contain a continuous response variable that is directly related to a categorical explanatory variable. Additionally, if the response variable is a cumulative total of contributions from different subcategories, each bar can be broken up to demonstrate those contributions.

## What are bar plots useful for?

- **Comparing categorical data**: Bar plots are ideal for comparing the quantities or frequencies of different categories. The height of each bar represents the value of each category, making it easy to compare them at a glance.
- **Decomposing data by category**: When the data belong to several independent categories, bar plots make it easy to visualize the relative contributions of each category to the overall total. The bar segments are colored by category, making it easy to identify the contribution of each.
- **Tracking trends**: If the categorical explanatory variable can be ordered left-to-right (like day of week), then bar plots provide a visualization of how the response variable changes as the explanatory variable evolves.

## Examples

### A basic bar plot

Visualize the relationship between a continuous variable and a categorical or discrete variable by passing the column names to the `x` and `y` arguments.

```python order=bar_plot,tips
import deephaven.plot.express as dx
tips = dx.data.tips()

bar_plot = dx.bar(tips, x="Day", y="TotalBill")
```

Change the x-axis ordering by sorting the dataset by the categorical variable.

```python order=ordered_bar_plot,tips
import deephaven.plot.express as dx
tips = dx.data.tips()

# sort the dataset to get a specific x-axis ordering, sort() acts alphabetically
ordered_bar_plot = dx.bar(tips.sort("Day"), x="Day", y="TotalBill")
```

### Partition bars by group

Break bars down by group by passing the name of the grouping column(s) to the `by` argument.

```python order=bar_plot_smoke,bar_plot_sex,tips
import deephaven.plot.express as dx
tips = dx.data.tips()

sorted_tips = tips.sort("Day")

# group by smoker / non-smoker
bar_plot_smoke = dx.bar(sorted_tips, x="Day", y="TotalBill", by="Smoker")

# group by male / female
bar_plot_sex = dx.bar(sorted_tips, x="Day", y="TotalBill", by="Sex")
```

### Frequency of categories

Visualize the frequency of categories in a column by passing to either the `x` or `y` argument.

```python order=bar_plot_vertical,bar_plot_horizontal,tips
import deephaven.plot.express as dx

tips = dx.data.tips()

# count the number of occurrences of each day with a vertical bar plot
bar_plot_vertical = dx.bar(tips, x="Day")

# count the number of occurrences of each day with a horizontal bar plot
bar_plot_horizontal = dx.bar(tips, y="Day")
```

## API Reference

Returns a bar chart

**Returns:** `DeephavenFigure` A DeephavenFigure that contains the bar chart

<ParamTable param={{"module_name": "deephaven.plot.express.", "name": "bar", "parameters": [{"name": "table", "type": "PartitionedTable | Table | DataFrame", "description": "A table to pull data from."}, {"name": "x", "type": "str | list[str] | None", "description": "A column or list of columns that contain x-axis values. If only x is specified, the y-axis values are the count of each unique x value.", "default": "None"}, {"name": "y", "type": "str | list[str] | None", "description": "A column or list of columns that contain y-axis values. If only y is specified, the x-axis values are the count of each unique y value.", "default": "None"}, {"name": "by", "type": "str | list[str] | None", "description": "A 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", "default": "None"}, {"name": "by_vars", "type": "str | list[str]", "description": "A string or list of string that contain design elements to plot by. Can contain color and pattern_shape. If associated maps or sequences are specified, they are used to map by column values to designs. Otherwise, default values are used.", "default": "'color'"}, {"name": "filter_by", "type": "str | list[str] | bool | None", "description": "A column or list of columns that contain values to filter the chart by. If a boolean is passed and the table is partitioned, all partition key columns used to create the partitions are used. If no filters are specified, all partitions are shown on the chart.", "default": "None"}, {"name": "required_filter_by", "type": "str | list[str] | bool | None", "description": "A column or list of columns that contain values to filter the chart by. Values set in input filters or linkers for the relevant columns determine the exact values to display. If a boolean is passed and the table is partitioned, all partition key columns used to create the partitions are used. All required input filters or linkers must be set for the chart to display any data.", "default": "None"}, {"name": "color", "type": "str | list[str] | None", "description": "A column or list of columns that contain color values. If only one column is passed, and it contains numeric values, the value is used as a value on a continuous color scale. Otherwise, the value is used for a plot by on color. See color_discrete_map for additional behaviors.", "default": "None"}, {"name": "pattern_shape", "type": "str | list[str] | None", "description": "A 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.", "default": "None"}, {"name": "error_x", "type": "str | None", "description": "A column with x error bar values. These form the error bars in both the positive and negative direction if error_x_minus is not specified, and the error bars in only the positive direction if error_x_minus is specified. None can be used to specify no error bars on the corresponding series.", "default": "None"}, {"name": "error_x_minus", "type": "str | None", "description": "A column with x error bar values. These form the error bars in the negative direction, and are ignored if error_x is not specified.", "default": "None"}, {"name": "error_y", "type": "str | None", "description": "A column with x error bar values. These form the error bars in both the positive and negative direction if error_y_minus is not specified, and the error bars in only the positive direction if error_y_minus is specified. None can be used to specify no error bars on the corresponding series.", "default": "None"}, {"name": "error_y_minus", "type": "str | None", "description": "A column with y error bar values. These form the error bars in the negative direction, and are ignored if error_y is not specified.", "default": "None"}, {"name": "text", "type": "str | None", "description": "A column that contains text annotations.", "default": "None"}, {"name": "hover_name", "type": "str | None", "description": "A column that contains names to bold in the hover tooltip.", "default": "None"}, {"name": "labels", "type": "dict[str, str] | None", "description": "A dictionary of labels mapping columns to new labels.", "default": "None"}, {"name": "color_discrete_sequence", "type": "list[str] | None", "description": "A list of colors to sequentially apply to the series. The colors loop, so if there are more series than colors, colors will be reused.", "default": "None"}, {"name": "color_discrete_map", "type": "str | tuple[str, dict[str | tuple[str], dict[str | tuple[str], str]]] | dict[str | tuple[str], str] | None", "description": "If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to colors. If \"identity\", the values are taken as literal colors. If \"by\" or (\"by\", dict) where dict is as described above, the colors are forced to by", "default": "None"}, {"name": "pattern_shape_sequence", "type": "list[str] | None", "description": "A list of patterns to sequentially apply to the series. The patterns loop, so if there are more series than patterns, patterns will be reused.", "default": "None"}, {"name": "pattern_shape_map", "type": "str | tuple[str, dict[str | tuple[str], dict[str | tuple[str], str]]] | dict[str | tuple[str], str] | None", "description": "If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to patterns. If \"identity\", the values are taken as literal patterns. If \"by\" or (\"by\", dict) where dict is as described above, the patterns are forced to by", "default": "None"}, {"name": "color_continuous_scale", "type": "list[str] | None", "description": "A list of colors for a continuous scale", "default": "None"}, {"name": "range_color", "type": "list[float] | None", "description": "A list of two numbers that form the endpoints of the color axis", "default": "None"}, {"name": "color_continuous_midpoint", "type": "float | None", "description": "A number that is the midpoint of the color axis", "default": "None"}, {"name": "opacity", "type": "float | None", "description": "Opacity to apply to all markers. 0 is completely transparent and 1 is completely opaque.", "default": "None"}, {"name": "orientation", "type": "Literal['v', 'h'] | None", "description": "The orientation of the bars. If 'v', the bars are vertical. If 'h', the bars are horizontal. Defaults to 'v' if only x is specified. Defaults to 'h' if only y is specified. Defaults to 'v' if both x and y are specified unless x is passed only numeric columns and y is not.", "default": "None"}, {"name": "barmode", "type": "str", "description": "If 'relative', bars are stacked. If 'overlay', bars are drawn on top of each other. If 'group', bars are drawn next to each other.", "default": "'relative'"}, {"name": "log_x", "type": "bool", "description": "A 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.", "default": "False"}, {"name": "log_y", "type": "bool", "description": "A 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.", "default": "False"}, {"name": "range_x", "type": "list[int] | None", "description": "A 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.", "default": "None"}, {"name": "range_y", "type": "list[int] | None", "description": "A 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.", "default": "None"}, {"name": "text_auto", "type": "bool | str", "description": "If True, display the value at each bar. If a string, specifies a plotly texttemplate.", "default": "False"}, {"name": "title", "type": "str | None", "description": "The title of the chart", "default": "None"}, {"name": "template", "type": "str | None", "description": "The template for the chart.", "default": "None"}, {"name": "unsafe_update_figure", "type": "Callable", "description": "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.", "default": "<function default_callback>"}, {"name": "on_click", "type": "Callable[..., bool | None] | None", "description": "A callback function that is called when a point is clicked. The function receives a dict with 'points' (list of clicked point data) and 'modifiers' (keyboard state). On hierarchical charts (sunburst, treemap, icicle), return False to prevent drill-down. The return value is ignored on other chart types.", "default": "None"}, {"name": "on_press", "type": "Callable[..., bool | None] | None", "description": "Alias for on_click.", "default": "None"}, {"name": "on_double_click", "type": "Callable[..., None] | None", "description": "A callback function that is called on double-click. The function receives a dict with 'modifiers' (keyboard state). Fires in zoom/pan mode only; in select mode, on_deselect fires instead.", "default": "None"}, {"name": "on_double_press", "type": "Callable[..., None] | None", "description": "Alias for on_double_click.", "default": "None"}, {"name": "on_selected", "type": "Callable[..., None] | None", "description": "A callback function that is called when a box or lasso selection completes. The function receives a dict with 'points' (list of selected point data), 'range' (for box select), and 'modifiers'.", "default": "None"}, {"name": "on_deselect", "type": "Callable[..., None] | None", "description": "A callback function that is called when the selection is cleared (e.g., by double-clicking on an empty area).", "default": "None"}, {"name": "on_relayout", "type": "Callable[..., None] | None", "description": "A callback function that is called when the chart layout changes due to user interaction (pan, zoom, axis reset, etc.). The function receives a dict of the layout keys that changed.", "default": "None"}, {"name": "on_legend_click", "type": "Callable[..., bool | None] | None", "description": "A callback function that is called when a legend item is clicked. Return False to prevent the default trace visibility toggle. Return True or None to allow it.", "default": "None"}, {"name": "on_legend_double_click", "type": "Callable[..., bool | None] | None", "description": "A callback function that is called when a legend item is double-clicked. Return False to prevent the default isolate/show-all toggle. Return True or None to allow it.", "default": "None"}, {"name": "on_click_annotation", "type": "Callable[..., None] | None", "description": "A callback function that is called when an annotation is clicked. The function receives a dict with 'index', 'annotation', and 'modifiers'.", "default": "None"}, {"name": "on_web_gl_context_lost", "type": "Callable[..., None] | None", "description": "A callback function that is called when the WebGL rendering context is lost (e.g., GPU reclaims resources).", "default": "None"}]}} />