Timeline Plot
Timeline plots offer a way to visualize time-related data, displaying events, durations, or activities along a time axis. Developers can utilize these plots for applications that require users to understand temporal patterns and relationships, such as project management, event scheduling, and historical data analysis.
A timeline plot is appropriate when the data contain a categorical variable whose categories become relevant in different places across a timeline. An example may be the years that various members in a band have been active - some may have been active for the duration of the band’s career, others may have only appeared in the early days and then left, some may have passed away and been replaced, and so on. Timeline plots are often used to display this data, such as this timeline plot detailing the member composition of the band Metallica throughout the years.
Examples
A basic timeline plot
Visualize the amount of time that each category in a column met a specific criteria. Pass the start and end timestamp column names to the x_start and x_end arguments, and category column name to the y argument.
import deephaven.plot.express as dx
jobs = dx.data.jobs()
timeline_plot = dx.timeline(jobs, x_start="StartTime", x_end="EndTime", y="Job")
API Reference
Returns a timeline (otherwise known as a gantt chart)
Returns: DeephavenFigure A DeephavenFigure that contains the timeline chart
| Parameters | Type | Default | Description |
|---|---|---|---|
| table | PartitionedTable | Table | DataFrame | A table to pull data from. | |
| x_start | str | None | None | A column that contains starting x-axis values. Must be a java.time.Instant column. |
| x_end | str | None | None | A column that contains ending x-axis values. Must be a java.time.Instant column. |
| 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 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. |
| color | str | list[str] | None | None | 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. |
| pattern_shape | str | list[str] | None | None | 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. |
| y | str | None | None | A column that contains y-axis labels |
| 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 | 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 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 |
| pattern_shape_sequence | list[str] | None | None | 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. |
| pattern_shape_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 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 |
| color_continuous_scale | list[str] | None | None | A list of colors for a continuous scale |
| range_color | list[float] | None | None | A list of two numbers that form the endpoints of the color axis |
| color_continuous_midpoint | float | None | None | A number that is the midpoint of the color axis |
| opacity | float | None | None | Opacity to apply to all markers. 0 is completely transparent and 1 is completely opaque. |
| range_x | 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] | 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. |
| title | str | None | None | The title of the chart |
| template | str | None | None | The template for the chart. |
| 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. |