Python classes reference


class hiplot.Experiment(datapoints: Optional[List[hiplot.experiment.Datapoint]] = None, parameters_definition: Optional[Dict[str, hiplot.experiment.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…)


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) → hiplot.experiment.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 dictionnary 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

  • 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[pathlib.Path, str, IO[str]]) → hiplot.experiment.Experiment[source]

Creates a HiPlot experiment from a CSV file.


file – CSV file path

static from_dataframe(dataframe: Any) → hiplot.experiment.Experiment[source]

Creates a HiPlot experiment from a pandas DataFrame.


dataframe – Pandas DataFrame

static from_iterable(it: Iterable[Dict[str, Any]]) → hiplot.experiment.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 merge(xp_dict: Dict[str, Experiment]) → hiplot.experiment.Experiment[source]

Merge several experiments into a single one

remove_missing_parents() → hiplot.experiment.Experiment[source]

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

to_csv(file: Union[pathlib.Path, str, IO[str]]) → 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[pathlib.Path, str, IO[str]]] = 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.

validate() → hiplot.experiment.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 dictionnary 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 dictionnary, where keys corresponds to columns currently brushed in parallel plot, and values contain information about the current brush.

abstract get_selected() → List[hiplot.experiment.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 NUMERIC, displayed on a logarithmic scale.

NUMERIC_PERCENTILE = 'numericpercentile'

Same as NUMERIC, displayed on a percentile scale.

TIMESTAMP = 'timestamp'

Timestamps in seconds (only integers)

class hiplot.ValueDef(value_type: Optional[hiplot.experiment.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 – Possible values: ValueDef.CATEGORICAL, ValueDef.NUMERIC, …

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

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

See hiplot.Experiment.parameters_definition

force_range(minimum: float, maximum: float) → hiplot.experiment.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], hiplot.experiment.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