Line Plot
A line plot is a graphical representation that displays data points connected by straight lines, commonly employed in time series analysis to depict temporal trends or relationships in a dataset.
Line plots are appropriate when the data contain a continuous response variable that directly depends on a continuous explanatory variable. Further, line plots are preferable to scatter plots when the explanatory variables are ordered.
What are line plots useful for?
- Visualizing trends: Line plots excel at revealing trends and patterns in data, making them ideal for time series analysis and showcasing changes over a continuous range.
- Simplicity and clarity: Line plots offer a straightforward and uncluttered representation, enhancing readability and allowing developers to focus on the data’s inherent structure.
- Comparing multiple series: Line plots make it easy to compare multiple data series on the same graph, aiding in the identification of similarities and differences.
Examples
A basic line plot
Visualize the relationship between two variables by passing each column name to the x and y arguments.
import deephaven.plot.express as dx
my_table = dx.data.stocks()
# subset data for just DOG transactions
dog_prices = my_table.where("Sym = `DOG`")
line_plot = dx.line(dog_prices, x="Timestamp", y="Price")
Line by group
Create a line with a unique color for each group in the dataset by passing the grouping column name to the by argument.
import deephaven.plot.express as dx
my_table = dx.data.stocks()
# each line represents a group and has a unique color
line_plot = dx.line(my_table, x="Timestamp", y="Price", by="Sym")
API Reference
Returns a line chart
Returns: DeephavenFigure A DeephavenFigure that contains the line chart
| Parameters | Type | Default | Description |
|---|---|---|---|
| table | PartitionedTable | Table | DataFrame | A table to pull data from. | |
| x | str | list[str] | None | None | A column or list of columns that contain x-axis values. |
| y | str | list[str] | None | None | A column or list of columns that contain y-axis values. |
| by | str | list[str] | None | None | 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 |
| by_vars | str | list[str] | 'color' | A string or list of string that contain design elements to plot by. Can contain size, line_dash, width, color, and symbol. If associated maps or sequences are specified, they are used to map by column values to designs. Otherwise, default values are used. |
| size | str | list[str] | None | None | A 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. |
| line_dash | str | list[str] | None | None | A column or list of columns that contain line_dash values. The value is used for a plot by on line_dash. See line_dash_map for additional behaviors. |
| width | str | list[str] | None | None | A column or list of columns that contain width values. The value is used for a plot by on width. See width_map for additional behaviors. |
| color | str | list[str] | None | None | A 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. |
| symbol | str | list[str] | None | None | A column or list of columns that contain symbol values. The value is used for a plot by on symbol. See color_discrete_map for additional behaviors. |
| error_x | str | None | None | 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. |
| error_x_minus | str | None | None | 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. |
| error_y | str | None | None | 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. |
| error_y_minus | str | None | None | 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. |
| text | str | None | None | A column that contains text annotations. |
| hover_name | str | None | None | A column that contains names to bold in the hover tooltip. |
| labels | dict[str, str] | None | None | A dictionary of labels mapping columns to new labels. |
| color_discrete_sequence | list[str] | None | None | 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. |
| color_discrete_map | dict[str | tuple[str], str] | None | None | If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to colors. |
| line_dash_sequence | list[str] | None | None | A list of line dashes to sequentially apply to the series. The dashes loop, so if there are more series than dashes, dashes will be reused. |
| line_dash_map | dict[str | tuple[str], str] | None | None | If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to line_dash. |
| symbol_sequence | list[str] | None | None | A 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_map | str | tuple[str, dict[str | tuple[str], dict[str | tuple[str], str]]] | dict[str | tuple[str], str] | None | None | If 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_sequence | list[int] | None | None | A 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_map | str | tuple[str, dict[str | tuple[str], dict[str | tuple[str], str]]] | dict[str | tuple[str], str] | None | None | If 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 |
| width_sequence | list[int] | None | None | A list of widths to sequentially apply to the series. The widths loop, so if there are more series than widths, widths will be reused. |
| width_map | dict[str | tuple[str], str] | None | None | If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to width. |
| xaxis_sequence | list[str] | None | None | A 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_sequence | list[str] | None | None | A 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. |
| markers | bool | False | True to draw markers on the line, False to not. Default False |
| log_x | bool | list[bool] | False | 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. |
| log_y | bool | list[bool] | False | 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. |
| range_x | list[int] | list[list[int]] | None | None | 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. |
| range_y | list[int] | list[list[int]] | None | None | 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. |
| yaxis_titles | list[str] | None | None | A list of titles to sequentially apply to the y axes. The titles do not loop. |
| xaxis_titles | list[str] | None | None | A list of titles to sequentially apply to the x axes. The titles do not loop. |
| line_shape | str | 'linear' | The line shape for all lines created. One of 'linear', 'spline', 'vhv', 'hvh', 'vh', 'hv'. Default 'linear' |
| title | str | None | None | The title of the chart |
| template | str | None | None | The template for the chart. |
| render_mode | str | 'webgl' | Either "svg" or "webgl". The default is "webgl" as it leads to a more performant plot but there may be graphical bugs, in which case it is recommended to switch to "svg" |
| unsafe_update_figure | Callable | <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. |