Skip to main content

Chart cells

Chart cells let you visualize and explore the dataframes in a Hex project, without writing code.

A Chart cell allows editors to interactively explore and aggregate a dataframe, creating rich visualizations to share with app users.

Charts can also be used to filter data with visual filtering. Selecting points of interest in a chart will return a filtered dataframe, which can be used downstream in the project.

tip

Chart cells got a glow-up in December 2022. Chart cells created before this use the Legacy Chart Editor. We recommend porting these cells across to the new Chart Editor UI to take advantage of a more intuitive UI, and new features, including chart selections and custom color palettes.

Adding a Chart cell

Add a chart cell to your project by:

  1. Select Chart from the Add cell menu bar, under the Visualize subheader.
  1. Choosing Visualize in chart in the dataframe menu.

Configuring a Chart cell

  1. Choose the dataframe you’d like to visualize in the Data input.
  2. Choose the chart type in the Type input.
  3. Map the columns in your datasets to the axes of your chart in the Data tab of the configuration panel. Note that Hex will automatically choose columns based on the chart type you choose, and your dataset, but these values can be changed using the Column dropdowns

Truncating dates and timestamps

Date and timestamp columns can be truncated to a time period (e.g. hour, day, month) when added to a chart. When combined with an aggregate function, this allows chart editors to interactively explore data at different time grains.

Aggregating data

Hex's chart cells allow you to apply aggregates to your rows, such as sum, count and max functions. This provides an interactive way to explore data when grouping by different columns, without having to reshape the data upstream.

Note that the chart cell can take any size of dataframe as an input, and will render the first 5000 rows of the resulting dataset after aggregates are applied.

Group by a column

For most chart types, you can specify a column to group your data by.

This column will be represented as entries in your legend, with each unique value rendered with a different color.

Change a column's data type

Columns in a chart will render as one of three data types: string, number, and datetime. The selected datatype is indicated via an icon in-line with the column name. These data types are inherited from the source dataframe, and impact how the data is rendered.

At times, you may need to override a column's datatype to ensure your chart renders correctly. You can do this by selecting the data type icon to switch it. This most commonly required when an upstream field is not correctly being interpreted as a datetime type.

Alternatively, consider changing the datatype upstream, for example by casting the column to a timestamp type with dataframe SQL (see the DuckDB docs on timestamp functions for more information).

select
strptime(release_date, '%b %d %Y') < '2010-01-01' as release_date,
* exclude (release_date)
from movies

This will ensure any cells downstream of your dataframe will treat the data correctly.

Ordering data

The chart cell offers a number of options for ordering your data:

  • Axes that plot a number or datetime variable can be sorted in ascending or descending order.
  • Axes that plot a string variable can be sorted:
    • In alphabetical order (ascending or descending).
    • In order from most to least (Y-axis ascending) or least to most (Y-axis descending).
    • In a custom sort order.
  • When grouping data by a column, the order of these values is set in the Style panel of the configuration panel.
  • When using multi-series charts, series can be reordered via drag and drop interactions.

Plot multiple columns in a Chart cell

Hex offers two ways to plot multiple columns from a dataframe in a chart cell:

  1. Add series: This option is useful if the two columns should be plotted on the same axis, and share the same unit of measurement, for example comparing revenue and profit. Any number of columns in your dataframe can be added to a chart this way. To add a series, click the + Add series button from the Data tab.
tip

If you find yourself adding many columns to your chart this way, consider reshaping your data into a tidy format upstream in Hex, and using the Group by field to create a multi-series chart. Check out this tutorial for an example.

  1. Add axis: This option is useful if the two columns should be plotted on different axes, and reflect different units of measurement, for example comparing revenue (in dollars) and number of orders. Only two axes (left and right) can be added to a chart, however each can have multiples series associated with the axis. To add an axis, click the + Add Y-axis button from the Data tab.

Series can be reordered, or assigned to a separate axis, through a drag and drop interaction.

info

Only columns from the same dataframe can be plotted in chart cells. If you need to chart columns from different dataframes, consider joining the data upstream in Hex. Check out this tutorial for an example.

Visual filtering

Visual filtering allows users to interact with a chart to select different legend entries, or a range of values, and have those selections update other parts of an app, unlocking flexible drilldown workflows for app users.

In Logic View

  1. Ensure that the Visual Filtering toggle is enabled in the chart editor.
  2. Interact with the chart — a full list of interactions can be found below.
  3. Use the returned dataframe in downstream cells, such as Table display cells or another Chart cell.

In published apps

In a published app, app users will also be able to interact with the charts to select data, and have that selection update the results of any downstream cells.

Any active selections at the time of publishing will be the default selections for app users.

Visual filtering results

The filtered records will be returned as a dataframe, named filter_result by default. This dataframe can be used in downstream cells, for example in a Table Display cell to show specific records of interest, or visualized a different way in another Chart cell.

The filtered records are the records in the input dataframe that match the current selection of the chart. If your chart includes a date transformation or aggregation, this will not be reflected in the dataframe.

Visual filtering interactions

Selecting a range along the X-axis: Click and drag horizontally within the chart area to select multiple columns.

Selecting individual columns or column segments: Click an individual column (grouped column charts) or column segment (stacked bar charts) to select it. Use shift + click to add additional segments to your selection.

Selecting a legend entry: Click on a legend entry to highlight this series. Use shift + click to add additional series to your selection.

Reset a selection: Click within the chart area to reset your selection.

Chart style

Customize chart colors

Hex's chart cells provide fine-grained options for choosing colors.

To customize the colors of your chart:

  1. Open the Style heading, tab of the chart editor open the Color menu. The default color for each series for each bar, line, area or point will be shown.
  2. Click into the current color to customize it. You can choose a color from:
    • Palette: The currently active palette. Workspaces on the Team and Enterprise plan can update the palette used for charts by creating a custom color palette and setting it as the active palette.
    • Custom: Use a color from the provided swatches, or set a custom color. To set a custom color, click into the color code, and update it to your custom value. Color values can be formatted as hex strings, such as #F5C0C0 or AD8EB6, or as CSS color names, such as mediumpurple. You can also click on the color swatch to open and select a shade from the color picker.
  3. To reset your colors to the default palette and ordering, hover over the Color heading, and select Reset colors.

Additional customizations

The Style tab also lets you customize:

  • Column, Bar, Line, Area or Point style: Configure options for colors, order and opacity.
  • Chart and axis labels: Configure the labels rendered on your chart. By default, this map to the column names configured in the Data tab.
  • Axis style: Configure the style, tick count, and minimum and maximum values of your X- and Y-axes.
  • Legend (if applicable): Configure whether a legend is displayed, and the position on the chart.
  • Tooltip: Configure whether a tooltip is displayed. In Auto mode, the tooltip will show the values on the chart. You can further customize the tooltip values in Manual mode.

Chart cell timezones

If one or both, of your chart axes plots a timestamp column, Hex will convert timestamps to a target timezone, rendering them in this 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.

  • 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. 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.

Duplicate a Chart cell as code

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 your Project that uses a custom HexChart class to produce a rendered chart given a Vega-Lite specification, data, and options. If you're familiar with Vega-Lite, duplicating a Chart cell as code can be used to further customize a chart.

tip

Find yourself doing this often? Let us know what you'd like to see in standard Chart cells by reaching out to [email protected]!

The HexChart class has the following arguments:

  • vega_spec: A Vega-Lite specification. You can edit this to further customize your chart. Note that the generated spec often has additional complexity as a result of creating a more intuitive UI in the Chart cell.
  • server_aggregation (default: True): If True, supported Vega transforms are evaluated on the provided DataFrames before the data is charted.
  • row_limit (default: 5000): Maximum number of rows to include in the resulting Vega specification. If server_aggregation=True, then this limit is applied after supported transforms are evaluated. If server_aggregation=False, then this limit is applied to the input DataFrame. Increasing this limit to plot more results may have performance impacts on your project.
  • default_input_tz (default: 'UTC'): Name of timezone to be used for naive datetimes in input dataframes. This value is ignored if server_aggregation=False.
  • output_tz (default: hex_timezone): Name of timezone to be considered local for final data output. This is the timezone which is rendered in the produced chart.
  • dataframes_by_name: Dictionary of input dataframes used in a chart.