Legacy chart cells
Chart cells got a glow-up in December 2022. Chart cells created before this use the the legacy chart editor. We recommend porting these cells across to the new Chart cell to take advantage of a more intuitive UI, and new features, including chart selections and custom color palettes.
To create a plot, first add a Chart cell to your project using the Chart cell option in the cell creation dropdown then select the DataFrame you wish to visualize from the Data dropdown menu.
From there, you can assign columns to variables and configure the visual elements of the chart. See the Chart configuration section below for more details.
Chart cells can visualize up to 5,000 rows of data. This is a performance limit set by the underlying libraries that are used to create Chart cells. If a DataFrame containing more than 5,000 rows is selected to populate a Chart cell, the DataFrame will be truncated so that only the first 5,000 rows are visualized.
If the DataFrame you'd like to visualize is too large, try filtering or aggregating the results to get the DataFrame under 5,000 rows.
Under the hood we're using Vega, a high-level grammar of interactive graphics. Because our Chart cells are built off of this library we use much of the terminology of the Vega ecosystem. Learn more about Vega's grammar of graphics system here.
Check out this video demo for how to quickly visualize your data with Chart cells:
Once you've created a Chart cell you can configure it in the following ways:
Data: Specify the DataFrame you'd like to visualize.
Mark: Select the type of visualization you want. Currently we support Bar, Point, Line, Area, Arc, and Text marks. Mark details can be further customized by clicking the cog icon.
- Tooltips: True/False to display details of data points on mouse over
- Filled: True/False to fill marks.
- Orientation (Line & Bar type only): Horizontal or vertical plot orientation.
- Interpolate (Line type only): Type of interpolation to use. See here for details on options.
- Point (Line type only): True/False to overlay points on a line.
- Shape (Point type only): Choose the default shape of points.
- Size: (Point type only): Choose the default size of points.
- Inner radius: (Arc type only): A percentage from 0 to 100 representing the inner radius of the chart.
- Outer radius: (Arc type only): A percentage from 0 to 100 representing the outer radius of the chart.
- Pad angle: (Arc type only): Angle of gap between slices, in degrees.
- Angle: (Text type only): The rotation of the text, in degrees.
- Dx: (Text type only): The horizontal offset, in pixels, between the text and its anchor point
- Dy: (Text type only): The vertical offset, in pixels, between the text and its anchor point
- Radius: (Text type only): A percentage from 0 to 100 representing the distance from the center to the text. Useful for arc charts.
X-axis & Y-axis: Select the columns you'd like to encode to the x and y axis. The data encoded to each axis can be further customized by clicking the cog icon. In Text cells, this is referred to as "X position" and "Y position".
Type: Set the data type of the column that is linked to each axis. Data types are:
- Quantitative: Expresses some kind of quantity, typically this is numerical data.
- Temporal: Supported data are date-times and times such as
- Ordinal: Represents data with ranked order. Unlike with quantitative data, there is no relative degree of difference between ranks.
- Nominal: Also known as categorical data. Values are differentiated based on their names or categories. Gender, species, & genre are examples of nominal data.
Aggregate: You can apply aggregations to the data encoded to each axis. Full list of supported aggregation methods here (not including argmin and argmax).
More: If the axes type is Quantitative, you'll see an option to select More. From this menu, you can set the minimum and maximum axes values, as well as the bin size. Used with a bar plot, the bin size setting can be used to create a histogram, like in the example below:
Depending on the mark type you select, some further encoding options become available. These encodings will by default create a legend on the chart, which can be turned off using the Legend toggle in the encoding Cog icon.
Color: Select a column from the identified DataFrame to encode mark color on your plot. The data points in the example chart above are color coded by species of iris.
Size: Set the size of the marks in your chart according to the values in a column from the identified DataFrame.
Shape (Point charts only): Set the shape of the marks in your chart according to the values in a column from the identified DataFrame. The shape of the data points in the example chart above are coded by species of iris.
Dash (Line type only): Select a column from the identified DataFrame to encode line type on your plot.
Detail (Line type only): Group lines by a field without mapping to any visual properties (e.g lines of all the same color, width, etc).
Layers: You can create a new layer for your chart from the Layers sidebar. The new layer will be customizable using the same configuration options that are listed above.
To control how the data points overlap in the chart, you can reorder the layers by drag & dropping them within the Layers sidebar.
From the cog Config button in the lower left, you have the option to either combine the y axes or display them separately.
Chart cell timezones
If one, or both, of your chart axes plots a timestamp column, Hex will convert your timestamps to a target timezone.
In increasing precedence, this target timezone is set by:
Workspace timezone: By default, the target timezone is set by admins in workspace settings (more info).
Project timezone: The workspace timezone can be overridden by the project timezone, set in the Environment panel of the sidebar (see below image).
App session timezone: When viewing a published app, the project and workspace timezone can be overridden for a specific app session in the top right hand corner of the app (see below image). Note: this only persists for the current app session — if you revisit the app in the future, the app will revert to the project timezone.
The target timezone is also represented in the
hex_timezone built-in variable, which can be used to execute timezone-aware logic in both code and SQL cells.
If a timestamp does not have a timezone associated with it (i.e. it's a naive, or unaware timestamp), Chart cells will assume it represents UTC time before converting it to the target timezone. If you need to change this assumed input timezone, use the Config menu in the bottom left-hand corner of the cell.
Duplicate Chart cell as code
Find yourself doing this often? Let us know what you'd like to see in standard Chart cells by reaching out to [email protected]!
If you are familiar with Altair and/or Vega (the libraries we leverage to generate Chart cells) you are welcome to "eject" from a visually configured Chart cell and customize your charts further using the Vega-lite grammar.
Every Chart cell has a Duplicate as Python cell option in the dropdown on the upper right. This will add a new Python cell to the Project that contains the code used to generate the chart.
Though you will no longer be able to leverage the visual configuration options, you can get very detailed with your customization.