Functions for plotting EXGBoost Booster models using Vega

Fundamentally, all this module does is convert a Booster into a format that can be ingested by Vega, and apply some default configuations that only account for a subset of the configurations that can be set by a Vega spec directly. The functions provided in this module are designed to have opinionated defaults that can be used to quickly visualize a model, but the full power of Vega is available by using the to_tabular/1 function to convert the model into a tabular format, and then using the plot/2 function to convert the tabular format into a Vega specification.

Default Vega Specification

The default Vega specification is designed to be a good starting point for visualizing a model, but it is possible to customize the specification by passing in a map of Vega properties to the plot/2 function. Refer to Custom Vega Specifications for more details on how to do this.

By default, the Vega specification includes the following entities to use for rendering the model:

• :width - The width of the plot in pixels
• :height - The height of the plot in pixels
• :padding - The padding in pixels to add around the visualization. If a number, specifies padding for all sides. If an object, the value should have the format [left: value, right: value, top: value, bottom: value]
• :leafs - Specifies characteristics of leaf nodes
• :inner_nodes - Specifies characteristics of inner nodes
• :links - Specifies characteristics of links between nodes

Custom Vega Specifications

The default Vega specification is designed to be a good starting point for visualizing a model, but it is possible to customize the specification by passing in a map of Vega properties to the plot/2 function. You can find the full list of Vega properties here.

It is suggested that you use the data attributes provided by the default specification as a starting point, since they provide the necessary data transformation to convert the model into a tree structure that can be visualized by Vega. If you would like to customize the default specification, you can use EXGBoost.Plotting.plot/1 to get the default specification, and then modify it as needed.

Once you have a custom specification, you can pass it to VegaLite.from_json/1 to create a new VegaLite struct, after which you can use the functions provided by the VegaLite module to render the model.

Specification Validation

You can optionally validate your specification against the Vega schema by passing the validate: true option to plot/2. This will raise an error if the specification is invalid. This is useful if you are creating a custom specification and want to ensure that it is valid. Note that this will only validate the specification against the Vega schema, and not against the VegaLite schema. This requires the [ex_json_schema] package to be installed.

Livebook Integration

This module also provides a Kino.Render implementation for EXGBoost.Booster which allows models to be rendered directly in Livebook. This is done by converting the model into a Vega specification and then using the Kino.Render implementation for Elixir's VegaLite API to render the model.

. The Vega specification is then passed to VegaLite

Plotting Parameters

This module exposes a high-level API for customizing the EXGBoost model visualization, but it is also possible to customize the Vega specification directly. You can also choose to pass in Vega Mark specifications to customize the appearance of the nodes and links in the visualization outside of the parameteres specified below. Refer to the Vega documentation for more details on how to do this.

• :style - The style to use for the visualization. Refer to EXGBoost.Plotting.Styles for a list of available styles. The default value is :dracula.

• :rankdir - Determines the direction of the graph. The default value is :tb.

• :autosize - Determines if the visualization should automatically resize when the window size changes The default value is "fit".

• :background (String.t/0) - The background color of the visualization. Accepts a valid CSS color string. For example: #f304d3, #ccc, rgb(253, 12, 134), steelblue. The default value is "#f5f5f5".

• :height (pos_integer/0) - Height of the plot in pixels The default value is 400.

• :width (pos_integer/0) - Width of the plot in pixels The default value is 600.

• :padding - The padding in pixels to add around the visualization. If a number, specifies padding for all sides. If an object, the value should have the format [left: value, right: value, top: value, bottom: value] The default value is 30.

• :leaves (keyword/0) - Specifies characteristics of leaf nodes The default value is [text: [align: :center, baseline: :middle, font_size: 13, font: "Calibri"], rect: [corner_radius: 2, opacity: 1]].

  • :text (keyword/0) - Accepts a keyword list of Vega text Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [align: :center, baseline: :middle, font_size: 13, font: "Calibri"].

  • :rect (keyword/0) - Accepts a keyword list of Vega rect Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [corner_radius: 2, opacity: 1].

• :splits (keyword/0) - Specifies characteristics of split nodes The default value is [text: [align: :center, baseline: :middle, font_size: 13, font: "Calibri"], rect: [corner_radius: 2, opacity: 1], children: [align: :right, baseline: :middle, font: "Calibri", font_size: 13]].

  • :text (keyword/0) - Accepts a keyword list of Vega text Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [align: :center, baseline: :middle, font_size: 13, font: "Calibri"].

  • :rect (keyword/0) - Accepts a keyword list of Vega rect Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [corner_radius: 2, opacity: 1].

  • :children (keyword/0) - Accepts a keyword list of Vega text Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [align: :right, baseline: :middle, font: "Calibri", font_size: 13].

• :node_width (pos_integer/0) - The width of each node in pixels The default value is 100.

• :node_height (pos_integer/0) - The height of each node in pixels The default value is 45.

• :space_between (keyword/0) - The space between the rectangular marks in pixels. The default value is [nodes: 10, levels: 100].

  • :nodes (pos_integer/0) - Space between marks within the same depth of the tree. The default value is 10.

  • :levels (pos_integer/0) - Space between each rank / depth of the tree. The default value is 100.

• :yes (keyword/0) - Specifies characteristics of links between nodes where the split condition is true The default value is [path: [], text: [align: :center, baseline: :middle, font_size: 13, font: "Calibri", text: "yes"]].

  • :path (keyword/0) - Accepts a keyword list of Vega path Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [].

  • :text (keyword/0) - Accepts a keyword list of Vega text Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [align: :center, baseline: :middle, font_size: 13, font: "Calibri", text: "yes"].

• :no (keyword/0) - Specifies characteristics of links between nodes where the split condition is false The default value is [path: [], text: [align: :center, baseline: :middle, font_size: 13, font: "Calibri", text: "no"]].

  • :path (keyword/0) - Accepts a keyword list of Vega path Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [].

  • :text (keyword/0) - Accepts a keyword list of Vega text Mark properties. Reference here for more details. Accepts either a string (expected to be valid Vega property names) or Elixir-styled atom. Note that keys are snake-cased instead of camel-case (e.g. Vega fontSize becomes font_size) The default value is [align: :center, baseline: :middle, font_size: 13, font: "Calibri", text: "no"].

• :validate (boolean/0) - Whether to validate the Vega specification against the Vega schema The default value is true.

• :index - The zero-indexed index of the tree to plot. If nil, plots all trees using a dropdown selector to switch between trees The default value is 0.

• :depth - The depth of the tree to plot. If nil, plots all levels (cick on a node to expand/collapse) The default value is nil.

Styles

Styles are a keyword-map that adhere to the plotting schema as defined in EXGBoost.Plotting. EXGBoost.Plotting.Styles provides a set of predefined styles that can be used to quickly customize the appearance of the visualization.

Refer to the EXGBoost.Plotting.Styles module for a list of available styles. You can pass a style to the :style option as an atom or string, and it will be applied to the visualization. Styles will override any other options that are passed for each option where the style defined a value. For example, if you pass :solarized_light as the style, and also pass :background as an option, the :background option will be ignored since the :solarized_light style defines its own value for :background.