Python classes reference


class hiplot.Experiment(datapoints: Optional[List[Datapoint]] = None, parameters_definition: Optional[Dict[str, ValueDef]] = None, colormap: Optional[str] = None)[source]

Object that can be rendered by HiPlot. It essential contains a list of metrics, but also some options on how to render it.

See Experiment.display() to display an Experiment in an ipython notebook.

  • datapoints – All the measurements we have. One datapoint corresponds to one line in the parallel plot and to one line in the table.

  • parameters_definition – Characteristics of the columns (ordering, type, etc…)

  • colormap – Colormap to use

  • colorby – Default column to color by

  • weightcolumn – If rows have different weights, use this column as the weight (default to 1 if not specified)

  • enabledDisplays – Ordered displays to enable (by default all are enabled)


import hiplot as hip
data = [{'param': 1, 'loss': 10, 'hidden_field': 'value1', 'c': 'red'},
    {'param': 2, 'loss': 5, 'hidden_field': 'value2', 'c': 'black'}]
exp = hip.Experiment.from_iterable(data)
display(force_full_width: bool = False, store_state_key: Optional[str] = None, **kwargs: Any) ExperimentDisplayed[source]

Displays an experiment in an ipython notebook.

  • force_full_width – allows to force to have 100% width on Jupyter Notebooks only.

  • store_state_key – a string identifier for the HiPlot instance. If not None, HiPlot will store dynamic modifications (removing/reordering columns…) in the URL, and restore them when calling display with the same value for store_state_key - see Remembering state between runs


An ExperimentDisplayed object that can be used to interact with the visualization - only implemented for Jupyter notebook. See Interactions with displayed visualization

display_data(plugin: str) Dict[str, Any][source]

Retrieve data dictionary for a plugin, which can be modified.


plugin – Name of the plugin


    "axis_x": "time",
    "axis_y": "loss"
display_st(*, ret: str, key: Optional[str] = None) Any[source]
display_st(*, ret: List[str], key: Optional[str] = None) List[Any]
display_st(*, key: Optional[str] = None) None

Displays an experiment in a Streamlit app - see HiPlot component for Streamlit

This function can be pretty slow, see Improving performance with streamlit caching (EXPERIMENTAL) to learn how to make it faster.

  • key – Unique key for the streamlit component. It is strongly recommended to give some unique string.

  • ret – Specify what HiPlot should return.


Return value depends on ret


brush_extents = exp.display_st(key="hiplot2", ret="brush_extents")
brush_extents, selected_uids = exp.display_st(key="hiplot3", ret=["brush_extents", "selected_uids"])
static from_csv(file: Union[Path, str, IO[str]]) Experiment[source]

Creates a HiPlot experiment from a CSV file.


file – CSV file path

static from_dataframe(dataframe: pd.DataFrame) Experiment[source]

Creates a HiPlot experiment from a pandas DataFrame.


dataframe – Pandas DataFrame

static from_iterable(it: Iterable[Dict[str, Any]]) Experiment[source]

Creates a HiPlot experiment from an iterable/list of dictionnaries. This is the easiest way to generate an hiplot.Experiment object.


it – A list (or iterable) of dictionnaries


>>> import hiplot as hip
>>> hip.Experiment.from_iterable([{"p": "a"}, {"p": "b"}])
<hiplot.experiment.Experiment object at 0x7f0f2e13c590>
static from_optuna(study: Experiment[source]

Creates a HiPlot experiment from a Optuna Study.


study – Optuna Study

static merge(xp_dict: Dict[str, Experiment]) Experiment[source]

Merge several experiments into a single one

remove_missing_parents() Experiment[source]

Sets hiplot.Datapoint.from_uid to None when set to a non-existing Datapoint.

to_csv(file: Union[Path, str, IO[str], StreamWriter]) None[source]

Dumps this Experiment as a .csv file. Information about display_data, parameters definition will be lost.


file – Path/handle to a file to write

to_html(file: Optional[Union[Path, str, IO[str], StreamWriter]] = None, **kwargs: Any) str[source]

Returns the content of a standalone .html file that displays this experiment without any dependency to HiPlot server or static files.


file – Path/handle to a file to write (optional)


A standalone HTML code to display this Experiment.

to_streamlit(key: Optional[str] = None, ret: Optional[Union[str, List[str]]] = None) ExperimentStreamlitComponent[source]

Streamlit only: creates a copy of the Experiment that you can cache, which only exposes the display_st method - see Improving performance with streamlit caching (EXPERIMENTAL)

  • key – Unique key for the streamlit component.

  • ret – Specify what HiPlot should return.


A component object that be rendered with component.display()


import streamlit as st
import hiplot as hip

def get_experiment():
    # Create your hiplot experiment as usual
    big_exp = hip.Experiment.from_iterable(...)
    # ... and cache the component
    return big_exp.to_streamlit(key="hipl", ret=["brush_extents", "selected_uids"])

exp = get_experiment() # This will be cached the second time
brush_extents, selected_uids = exp.display()
validate() Experiment[source]

Makes sure that this object is valid. Raises a hiplot.ExperimentValidationError otherwise. Experiments with circular references, non-existent parents, or without datapoints are invalid.

class hiplot.Displays[source]

See Experiment.display_data() and Frontend rendering settings


Distribution plot data


Parallel plot data


Rows table data

XY = 'XY'

XY scatter/line plot data


class hiplot.Datapoint(values: Dict[str, Union[bool, int, float, str]], *, uid: Optional[str] = None, from_uid: Optional[str] = None)[source]

A datapoint represents a single measurement of metrics - for instance a model checkpoint that is evaluated. It can have a parent if it originates from another one (offspring).

  • uid – A unique identifier for this datapoint

  • values – A dictionary with arbitrary metrics/values

  • from_uid – The uid of the parent Datapoint (tp.Optional)


import hiplot as hip
dp1 = hip.Datapoint(uid="parent", values={"loss": 0.0})
dp2 = hip.Datapoint(uid="child", from_uid="parent", values={
    "loss": 1.0,
    "another_metric": 0.0  # Different datapoints can have different metrics
hip.Experiment(datapoints=[dp1, dp2]).display()  # Render in an ipython notebook
validate() None[source]

Makes sure this object is valid - throws an hiplot.ExperimentValidationError exception otherwise.


class hiplot.ExperimentDisplayed[source]

Class that allows to communicate with a displayed HiPlot visualization in a Jupyter notebook. Read more in Interactions with displayed visualization

abstract get_brush_extents() Dict[str, Dict[str, Any]][source]

Returns a dictionary, where keys corresponds to columns currently brushed in parallel plot, and values contain information about the current brush.

abstract get_selected() List[Datapoint][source]

Returns a list of currently rendered datapoints in the parallel plot

Columns type/scales

class hiplot.ValueType(value)[source]

Defines how we render a column (scaling, and color scheme)

CATEGORICAL = 'categorical'

Categorical value

NUMERIC = 'numeric'

Numeric value on a linear scale. Supports integers, floats, NaNs and inf

NUMERIC_LOG = 'numericlog'

Same as hiplot.ValueType.NUMERIC, displayed on a logarithmic scale.

NUMERIC_PERCENTILE = 'numericpercentile'

Same as hiplot.ValueType.NUMERIC, displayed on a percentile scale.

TIMESTAMP = 'timestamp'

Timestamps in seconds (only integers)

class hiplot.ValueDef(value_type: Optional[ValueType] = None, colors: Optional[Dict[Any, str]] = None, colormap: Optional[str] = None, label_css: Optional[str] = None)[source]

Provides a custom type, color, etc.. for a column.

  • type – See hiplot.ValueType for possible values

  • colors – Categorical scales only: mapping from value to HTML color (either rgb(R, G, B) or #RRGGBB)

  • colormap – Numerical scales only: D3 scale to use (default scale is interpolateTurbo). For example "interpolateSinebow". To inverse the colormap, append #inverse to the name (eg "interpolateSinebow#inverse")

  • label_css – Space-separated bootstrap CSS classes to apply on the label when supported

  • label_html – HTML code used to render the column name

See hiplot.Experiment.parameters_definition

force_range(minimum: float, maximum: float) ValueDef[source]

Enforces the range of the column.


class hiplot.ExperimentFetcherDoesntApply[source]
class hiplot.ExperimentValidationError[source]

HiPlot server

hiplot.run_server(fetchers: List[Callable[[str], Experiment]], host: str = '', port: int = 5005, debug: bool = False) None[source]

Runs the HiPlot server, given a list of ExperimentFetchers - functions that convert a URI into a hiplot.Experiment