Python classes reference

hiplot.Experiment

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

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.

Variables:

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

Example:

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

Displays an experiment in an ipython notebook.

Parameters:

• 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

Returns:

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]

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

Parameters:

plugin – Name of the plugin

Example:

exp.display_data(hip.Displays.XY).update({
    "axis_x": "time",
    "axis_y": "loss"
})

display_st(*, ret: str, key: Optional[str] = None) → Any

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.

Parameters:

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

• ret – Specify what HiPlot should return.

Returns:

Return value depends on ret

Example:

exp.display_st(key="hiplot1")
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

Creates a HiPlot experiment from a CSV file.

Parameters:

file – CSV file path

static from_dataframe(dataframe: pd.DataFrame) → Experiment

Creates a HiPlot experiment from a pandas DataFrame.

Parameters:

dataframe – Pandas DataFrame

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

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

Parameters:

it – A list (or iterable) of dictionnaries

Example:

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

static from_optuna(study: optuna.study.Study) → Experiment

Creates a HiPlot experiment from a Optuna Study.

Parameters:

study – Optuna Study

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

Merge several experiments into a single one

remove_missing_parents() → Experiment

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

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

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

Parameters:

file – Path/handle to a file to write

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

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

Parameters:

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

Returns:

A standalone HTML code to display this Experiment.

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

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)

Parameters:

• key – Unique key for the streamlit component.

• ret – Specify what HiPlot should return.

Returns:

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

Example:

import streamlit as st
import hiplot as hip

@st.cache
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

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

See Experiment.display_data() and Frontend rendering settings

DISTRIBUTION = 'DISTRIBUTION'

Distribution plot data

PARALLEL_PLOT = 'PARALLEL_PLOT'

Parallel plot data

TABLE = 'TABLE'

Rows table data

XY = 'XY'

XY scatter/line plot data

hiplot.Datapoint

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

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

Variables:

• uid – A unique identifier for this datapoint

• values – A dictionary with arbitrary metrics/values

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

Example:

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

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

hiplot.ExperimentDisplayed

class hiplot.ExperimentDisplayed

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]]

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]

Returns a list of currently rendered datapoints in the parallel plot

Columns type/scales

class hiplot.ValueType(value)

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)

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

Variables:

• 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

Enforces the range of the column.

Exceptions

class hiplot.ExperimentFetcherDoesntApply

class hiplot.ExperimentValidationError

HiPlot server

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

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