Skip to main content

Chart cells

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

info
  • Users will need Can Edit permissions to create and configure Chart cells.
  • Users with Can View App permissions and higher can interact with Chart cells in published Apps.

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 chart interactions. 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 a Legacy version of the chart editor, and many of the features outlined on this page do not apply. 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. The following chart types are supported:
    • Column charts
      • Grouped column
      • Stacked column
      • 100% stacked column
    • Bar charts
      • Grouped bar
      • Stacked bar
      • 100% stacked bar
    • Line & area charts
      • Line
      • Area
      • 100% stacked area
    • Other
      • Histogram
      • Scatter plot
      • Pie chart
  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.

tip

Aggregates utilize vega aggregate operations. Count aggregations are similar to a count(*) in SQL. If you are looking for a count of a specific field, use the Valid aggregation.

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.

tip

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.

Faceting​

Use faceting in a Chart cell to split your chart into multiple subplots. At the bottom of the Data tab, open the Faceting toggle, and select a column or columns to facet by, vertically and/or horizontally.

If you are only faceting horizontally, you have the option to wrap the subplots, and set the number of subplot columns.

info

Currently, faceting is not supported for multi-series Charts, nor for facets that create more than 100 subplots.

Adding data labels​

To add labels to a chart, open the Style heading and toggle on Data Labels. Further styling customizations are possible once the setting is enabled.

Interactive charts​

All Hex charts are interactive in both the Notebook view and Published App.

  • Hovering over a legend will highlight the respective data series
  • Clicking the legend, or clicking and dragging over a chart area, will select data points of interest
  • Users can then choose to keep or remove the records of interest.
  • Permissions permitting, users will be able to view the underlying data that makes up the records of interest - see View Data below.

Editors can use the filtered records returned by a Chart cell downstream, enabling powerful drilldown workflows for App Users.

In Notebook view​

  1. Interact with the chart to select data — a full list of interactions can be found below.
  2. Choose to keep or remove the selection.
  3. Use the returned dataframe in downstream cells, such as Table display cells or another Chart cell.

Note that filters applied by Editors in Notebook view do not show up in the Published App, and therefore cannot be altered by a user viewing the Published App. App users are able to add additional filters via chart interactions.

Once a filter is added to a chart, the cell will start returning the filtered records as a dataframe, named filter_result by default. This dataframe can be then be referenced in any downstream cells - for example, to show records of interest in a Table Display, or visualized a different way in a second Chart cell.

Editors can also choose to manually enable or disable whether a dataframe is returned from a 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.

In Published Apps​

In a Published App, users can interact with the chart to add additional filters.

If downstream cells use the returned dataframe, these cells will also be updated by any filters that are added.

Users can only add additional filters in a Published App, and cannot view or edit the filters applied by Editors in Notebook view.

View Data​

tip

This feature is available to workspaces on the Teams tier and higher.

Users with Can Explore permission on the project will be able View data to see the individual records that make up their selection.

From the resulting modal, users can explore (permission permitting), or download the data.

Alternately, users can click on the table icon in the upper right of a chart cell to view all records visualized in the chart.

Chart 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 uses 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 the workspace timezone, the project timezone, and the app session timezone. See this docs page for more information.

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.

On this page