Plotting with matplotlib#

Matplotlib interface to CEBRA.

cebra.integrations.matplotlib.plot_overview(model, X, loss_kwargs={}, temperature_kwargs={}, embedding_kwargs={}, figsize=(15, 4), dpi=100, **kwargs)#

Plot an overview of a trained CEBRA model.

Parameters:

  • model (CEBRA) – The (fitted) CEBRA model to analyze to compute the different plots.

  • X (Union[ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], Tensor]) – The data matrix on which to compute the embedding to plot.

  • figsize (tuple) – Figure width and height in inches.

  • dpi (int) – Figure resolution.

  • kwargs – Optional arguments to customize the plots.

Return type:

Tuple[Figure, Tuple[Axes, Axes, Axes]]

Returns:

The axis matplotlib.axes.Axes.axis() of the plot.

Example

>>> import cebra
>>> import numpy as np
>>> X = np.random.uniform(0, 1, (100, 50))
>>> y = np.random.uniform(0, 10, (100, 5))
>>> cebra_model = cebra.CEBRA(max_iterations=10)
>>> cebra_model.fit(X, y)
CEBRA(max_iterations=10)
>>> fig = cebra.plot_overview(cebra_model, X, embedding_kwargs={"embedding_labels":"time"})
cebra.integrations.matplotlib.plot(model, which=typing.Literal['loss', 'temperature', 'embedding'], X=None, ax=None, **kwargs)#

Plot the required information.

Parameters:

  • model (CEBRA) – The (fitted) CEBRA model to analyze to compute the different plots.

  • which (str) – The required information to plot.

  • X (Union[ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], Tensor, None]) – The data matrix on which to compute the embedding to plot, needed only to display an embedding.

  • ax (Optional[Axes]) – Optional axis to create the plot on.

  • kwargs – Optional arguments to customize the plots or provide the embedding labels.

Example

>>> import cebra
>>> import numpy as np
>>> X = np.random.uniform(0, 1, (100, 50))
>>> y = np.random.uniform(0, 10, (100, 5))
>>> cebra_model = cebra.CEBRA(max_iterations=10)
>>> cebra_model.fit(X, y)
CEBRA(max_iterations=10)
>>> ax = cebra.plot(cebra_model, which="temperature")
Return type:

Axes

Returns:

The axis matplotlib.axes.Axes.axis() of the plot.

cebra.integrations.matplotlib.plot_temperature(model, ax=None, color='dodgerblue', linewidth=1, x_label=True, y_label=True, figsize=(7, 4), dpi=100, **kwargs)#

Plot the evolution of the temperature hyperparameter during model training.

Note

It will vary only when using temperature_mode, else the temperature stays constant.

The function makes use of matplotlib.pyplot.plot() and parameters from that function can be provided as part of kwargs.

Parameters:

  • model (CEBRA) – The (trained) CEBRA model.

  • ax (Optional[Axes]) – Optional axis to create the plot on.

  • color (str) – Line color.

  • linewidth (int) – Line width.

  • x_label (bool) – A boolean that specifies if the x-axis label should be displayed.

  • y_label (bool) – A boolean that specifies if the y-axis label should be displayed.

  • figsize (tuple) – Figure width and height in inches.

  • dpi (float) – Figure resolution.

  • kwargs – Optional arguments to customize the plots. See matplotlib.pyplot.plot() documentation for more details on which arguments to use.

Example

>>> import cebra
>>> import numpy as np
>>> X = np.random.uniform(0, 1, (100, 50))
>>> y = np.random.uniform(0, 10, (100, 5))
>>> cebra_model = cebra.CEBRA(max_iterations=10)
>>> cebra_model.fit(X, y)
CEBRA(max_iterations=10)
>>> ax = cebra.plot_temperature(cebra_model)
Return type:

Axes

Returns:

The axis matplotlib.axes.Axes.axis() of the plot.

cebra.integrations.matplotlib.plot_loss(model, label=None, ax=None, color='magenta', linewidth=1, x_label=True, y_label=True, figsize=(7, 4), dpi=100, **kwargs)#

Plot the evolution of loss during model training.

The function makes use of matplotlib.pyplot.plot() and parameters from that function can be provided as part of kwargs.

Parameters:

  • model (CEBRA) – The (trained) CEBRA model.

  • label (Union[str, int, float, None]) – The legend for the loss trace.

  • ax (Optional[Axes]) – Optional axis to create the plot on.

  • color (str) – Line color.

  • linewidth (int) – Line width.

  • x_label (bool) – A boolean that specifies if the x-axis label should be displayed.

  • y_label (bool) – A boolean that specifies if the y-axis label should be displayed.

  • figsize (tuple) – Figure width and height in inches.

  • dpi (float) – Figure resolution.

  • kwargs – Optional arguments to customize the plots. See matplotlib.pyplot.plot() documentation for more details on which arguments to use.

Example

>>> import cebra
>>> import numpy as np
>>> X = np.random.uniform(size=(100, 50))
>>> y = np.random.uniform(size=(100, 5))
>>> cebra_model = cebra.CEBRA(max_iterations=10)
>>> cebra_model.fit(X, y)
CEBRA(max_iterations=10)
>>> ax = cebra.plot_loss(cebra_model)
Return type:

Axes

Returns:

The axis matplotlib.axes.Axes.axis() of the plot.

cebra.integrations.matplotlib.plot_embedding(embedding, embedding_labels='grey', ax=None, idx_order=None, markersize=0.05, alpha=0.4, cmap='cool', title='Embedding', figsize=(5, 5), dpi=100, **kwargs)#

Plot embedding in a 3D or 2D dimensional space.

If the embedding dimension is equal or higher to 3:

  • If idx_order is not provided, the plot will be 3D by default.

  • If idx_order is provided, and it has 3 dimensions, the plot will be 3D; if only 2 dimensions are provided, the plot will be 2D.

If the embedding dimension is equal to 2:

  • If idx_order is not provided, the plot will be 2D by default.

  • If idx_order is provided, and it has 3 dimensions, the plot will be 3D; if 2 dimensions are provided, the plot will be 2D.

This assumes that the dimensions provided to idx_order are within the range of the number of dimensions of the embedding (i.e., between 0 and cebra.CEBRA.output_dimension -1).

The function makes use of matplotlib.pyplot.scatter(), and parameters from that function can be provided as part of kwargs.

Parameters:

  • embedding (Union[ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], Tensor]) – A matrix containing the feature representation computed with CEBRA.

  • embedding_labels (Union[ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], Tensor, str, None]) –

    The labels used to map the data to color. It can be:

    • A vector that is the same sample size as the embedding, associating a value to each sample, either discrete or continuous.

    • A string, either time, which will color the embedding based on temporality, or a string that can be interpreted as an RGB(A) color, which will display the embedding uniformly with that color.

  • ax (Optional[Axes]) – Optional axis to create the plot on.

  • idx_order (Optional[Tuple[int]]) – A tuple (x, y, z) or (x, y) that maps a dimension in the data to a dimension in the 3D/2D embedding. The simplest form is (0, 1, 2) or (0, 1), but one might want to plot either those dimensions differently (e.g., (1, 0, 2)) or other dimensions from the feature representation (e.g., (2, 4, 5)).

  • markersize (float) – The marker size.

  • alpha (float) – The marker blending, between 0 (transparent) and 1 (opaque).

  • cmap (str) – The Colormap instance or registered colormap name used to map scalar data to colors. It will be ignored if embedding_labels is set to a valid RGB(A).

  • title (str) – The title on top of the embedding.

  • figsize (Tuple[int]) – Figure width and height in inches.

  • dpi (float) – Figure resolution.

  • kwargs – Optional arguments to customize the plots. See matplotlib.pyplot.scatter() documentation for more details on which arguments to use.

Return type:

Axes

Returns:

The axis matplotlib.axes.Axes.axis() of the plot.

Example

>>> import cebra
>>> import numpy as np
>>> X = np.random.uniform(0, 1, (100, 50))
>>> y = np.random.uniform(0, 10, (100, 5))
>>> cebra_model = cebra.CEBRA(max_iterations=10)
>>> cebra_model.fit(X, y)
CEBRA(max_iterations=10)
>>> embedding = cebra_model.transform(X)
>>> ax = cebra.plot_embedding(embedding, embedding_labels='time')
cebra.integrations.matplotlib.plot_consistency(scores, pairs=None, datasets=None, ax=None, cmap='binary', text_color='white', colorbar_label='Consistency score (%)', title=None, figsize=(5, 5), dpi=100, **kwargs)#

Plot the consistency matrix from the consistency scores obtained with consistency_score().

To display the consistency map, datasets and pairs must be provided. The function is implemented so that it will first try to display the labels as if the scores were computed following a between-sujects comparison. If only one dataset is present or if the number of datasets doesn’t fit with the number of scores, then the function will display the labels as if the scores were computed following a between-runs comparison. If the number of pairs still doesn’t fit with that comparison, then an error is raised, asking the user to make sure that the formats of the scores, datasets and pairs are valid.

Tip

The safer way to use that function is to directly use as inputs the outputs from consistency_score().

The function makes use of matplotlib.pyplot.imshow() and parameters from that function can be provided as part of kwargs. For instance, we recommend that you bound the color bar using vmin and vmax. The scores are percentages between 0 and 100.

Parameters:

  • scores (Union[ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], Tensor, list]) – List of consistency scores obtained by comparing a set of CEBRA embeddings using consistency_score().

  • pairs (Union[list, ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], None]) – List of the pairs of datasets/runs whose embeddings were compared in scores.

  • datasets (Union[list, ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], None]) – List of the datasets whose embeddings were compared in scores. Each dataset is present once only in the list.

  • ax (Optional[Axes]) – Optional axis to create the plot on.

  • cmap (str) – Color map to use to color the m

  • text_color (str) – If None, then the scores values are not displayed, else, it corresponds to the color of the values displayed inside the grid.

  • colorbar_label (Optional[str]) – If None, then the color bar is not shown, else, it defines the corresponding title.

  • title (Optional[str]) – The title on top of the confusion matrix.

  • figsize (Tuple[int]) – Figure width and height in inches.

  • dpi (float) – Figure resolution.

  • kwargs – Optional arguments to customize the plots. See matplotlib.pyplot.imshow() documentation for more details on which arguments to use.

Return type:

Axes

Returns:

The axis matplotlib.axes.Axes.axis() of the plot.

Example

>>> import cebra
>>> import numpy as np
>>> embedding1 = np.random.uniform(0, 1, (1000, 5))
>>> embedding2 = np.random.uniform(0, 1, (1000, 8))
>>> labels1 = np.random.uniform(0, 1, (1000, ))
>>> labels2 = np.random.uniform(0, 1, (1000, ))
>>> dataset_ids = ["achilles", "buddy"]
>>> # between-datasets consistency, by aligning on the labels
>>> scores, pairs, datasets = cebra.sklearn.metrics.consistency_score(
...     embeddings=[embedding1, embedding2],
...     labels=[labels1, labels2],
...     dataset_ids=dataset_ids,
...     between="datasets"
... )
>>> ax = cebra.plot_consistency(scores, pairs, datasets, vmin=0, vmax=100)
cebra.integrations.matplotlib.compare_models(models, labels=None, ax=None, color=None, cmap='cebra', linewidth=1, x_label=True, y_label=True, figsize=(7, 4), dpi=100, **kwargs)#

Plot the evolution of loss during model training.

The function makes use of matplotlib.pyplot.plot() and parameters from that function can be provided as part of kwargs.

Parameters:

  • models (List[CEBRA]) – A list of trained CEBRA models.

  • labels (Optional[List[str]]) – A list of labels, associated to each model to be used in the legend of the plot.

  • ax (Optional[Axes]) – Optional axis to create the plot on.

  • color (Optional[str]) – Line color. If not None, then all the traces for all models will be of the same color.

  • cmap (str) – Color map from which to sample uniformly the quantitative list of colors for each trace. If color is different from then that parameter is ignored.

  • linewidth (int) – Line width.

  • x_label (bool) – A boolean that specifies if the x-axis label should be displayed.

  • y_label (bool) – A boolean that specifies if the y-axis label should be displayed.

  • figsize (tuple) – Figure width and height in inches.

  • dpi (float) – Figure resolution.

  • kwargs – Optional arguments to customize the plots. See matplotlib.pyplot.plot() documentation for more details on which arguments to use.

Example

>>> import cebra
>>> import numpy as np
>>> X = np.random.uniform(0, 1, (100, 50))
>>> y = np.random.uniform(0, 10, (100, 5))
>>> output_dimensions = [3, 8, 12, 32]
>>> models, labels = [], []
>>> for output_dimension in output_dimensions:
...     cebra_model = cebra.CEBRA(max_iterations=10,
...                               output_dimension=output_dimension)
...     cebra_model = cebra_model.fit(X, y)
...     models.append(cebra_model)
...     labels.append(f"Output dimension: {output_dimension}")
>>> ax = cebra.compare_models(models, labels)
Return type:

Axes

Returns:

The axis of the generated plot. If no ax argument was specified, it will be created by the function and returned here.