Jupyter notebooks¶

Chemiscope can be used as a widget in Jupyter notebooks, that should work in both Jupyter classic and JupyterLab. The widget can be created in default mode (showing both a structure and a map panel), or used to display only structures or only properties.

Once created, it is possible to interact with the widget using a traitlet interface, modeled after Jupyter widgets.

Creating a chemiscope widget¶

chemiscope.show(frames=None, properties=None, meta=None, environments=None, shapes=None, settings=None, mode='default', warning_timeout=10000)¶

Show the dataset defined by the given frames and properties (optionally meta, environments and shapes as well) using an embedded chemiscope visualizer inside a Jupyter notebook. These parameters have the same meaning as in the chemiscope.create_input() function.

The mode keyword also allows overriding the default two-panels visualization to show only a structure panel (mode = "structure") or the map panel (mode = "map"). These modes also make it possible to view a dataset for which properties (or frames) are not available. The widget displays warning messages, that disappear after the specified warning_timeout (in ms). Set to a negative value to disable warnings, and to zero to make them persistent.

When inside a jupyter notebook, the returned object will create a new chemiscope visualizer displaying the dataset. The object exposes a settings traitlet, that allows to modify the visualization options (possibly even linking the parameters to another widget). Printing the value of the settings property is also a good way to see a full list of the available options.

The returned object also have a save function that can be used to save the dataset to a .json or .json.gz file to load it in the main website later. The visualization options will be those used in the active widget, so this is also a good way to tweak the appearance of the visualization before saving it.

import chemiscope
from sklearn.decomposition import PCA
import ase.io

pca = PCA(n_components=3)

frames = ase.io.read(...)
properties = {
    "PCA": pca.fit_transform(some_data),
}

widget = chemiscope.show(frames, properties)
# display the dataset in a chemiscope visualizer inside the notebook
widget
# ...

# NB: due to how traitlet work, you should always set the value of
# the `settings` property. Only the properties that are explicitly
# indicated will be modified.
widget.settings = {"map": {"palette": "seismic"}}
widget.settings["map"]["palette"] = "viridis"  # << does nothing!

# Save the file for later use
widget.save("dataset.json")

chemiscope.show_input(path, mode='default', warning_timeout=10000)¶

Loads and shows the chemiscope input in path.

If path ends with .gz, the file is loaded as a gzip compressed JSON string. If path is a file-like object, it is read as JSON input.

Parameters:

path (str | Path | file-like) – load the chemiscope input from this path or file-like object
mode (str) – widget mode, either default, structure or map.
warning_timeout (float) – timeout (in ms) for warnings. Set to a negative value to disable warnings, and to zero to make them persistent.

import chemiscope

widget = chemiscope.show_input("dataset.json")

# or

with open("dataset.json", "r") as f:
    widget = chemiscope.show_input(f)