DOCSEARCHbyAlgolia
Submit Docs

Chemiscope 1.1.0

repository·main·Indexed 41 days ago

https://github.com/lab-cosmo/chemiscope

An interactive structure-property explorer for materials and molecular databases. Chemiscope allows users to correlate structural descriptors with physical properties and provides a library of reusable components for building custom interfaces. It can be integrated as a Python notebook widget in Jupyter, JupyterLab, marimo, and Google Colab, or used as a standalone web application and Streamlit component.

Tokens
44.1K
Snippets
141
Records
197
Agent score
51%

What's inside Chemiscope

  1. Overview of Chemiscope capabilities

    main

    Chemiscope is an interactive structure-property explorer designed for large databases of materials and molecules (up to hundreds of thousands of structures). It enables researchers to find correlations between chemical structures and their properties by linking a 3D structure viewer with an interactive scatter plot.

    Key Features:

    • Linked Visualization: Interactively select points in a scatter plot to view corresponding structures in a 3D viewer (based on 3dmol.js), and vice versa.
    • Property Mapping: Visualize properties associated with structures (e.g., total energy, band gap) or individual atoms (e.g., atomic charges, coordination numbers) via scatter plot axes, point coloring, or point sizing.
    • Advanced 3D Rendering: Supports coloring atoms by atomic properties and displaying data as "shapes" (e.g., vectors for forces, ellipsoids for tensorial quantities).
    • Performance Optimization: Uses optimized data structures and dynamic resampling in the scatter plot (based on plotly.js) to maintain fast interaction even with large datasets. Supports dynamic loading of structures from external files to minimize initial load times.

  2. What is Chemiscope?

    main

    Chemiscope is an interactive graphical tool designed for the exploration of materials and molecular databases. It allows users to correlate local and global structural descriptors with physical properties of chemical systems.

    Key Features:

    • Dual-Panel Interface:
      • Left Panel: Displays 2D or 3D scatter plots where each point represents a chemical entity. Users can map properties or structural descriptors to the axes, color, and point style.
      • Right Panel: Displays the 3D atomic structure of the selected entity, including periodic repetition for crystals.
    • Atom-Centred Environments: Unlike many similar tools, Chemiscope can visualize maps where points correspond to atom-centred environments rather than just whole molecules or crystals. This is particularly useful for analyzing atomic properties like nuclear chemical shieldings or machine-learning decompositions.
    • High Performance: Built using WebGL, it can handle datasets containing up to a million points in 2D mode, with responsive user interaction.

  3. Dataset files for chemiscope examples

    main

    The python/examples/data/ directory contains .xyz files used to demonstrate the chemiscope.explore functionality. These files contain small subsets of structures from well-known materials and molecular datasets, suitable for testing the interactive structure-property explorer.

    Available example datasets:

    • explore_c-gap-20u.xyz: 5 structures from the C-GAP-20U dataset.
    • explore_qm9.xyz: 5 structures from the QM9 dataset.
    • explore_mc3d.xyz: 5 structures from the MC3D crystals dataset.

  4. Use the chemiscope Python module for notebook visualizations

    main

    The chemiscope Python package is used to prepare JSON input files and visualize them as interactive notebook widgets. It acts as a bridge between chemical data structures and the chemiscope web visualization engine.

    Supported structure formats include:

    • ase.Atoms
    • stk.BuildingBlock
    • MDAnalysis.AtomGroup

  5. Structure of the Chemiscope `settings` dictionary

    main

    The settings object must be a JSON-serializable dictionary. It controls the configuration of the 2D property-map panel, 3D viewer panels, and selection behavior.

    Top-level keys include:

    • map: Configuration for the 2D property-map panel.
    • structure: A list of objects, where each object defines a 3D viewer panel.
    • pinned: A list of environment indices pinned into viewers (default is [0]).
    • target: Determines what selections refer to. Options are "structure" or "atom". Note that "atom" requires environments to be present in the dataset.
    # Example top-level structure
settings = {
    "map": { ... },
    "structure": [{ ... }],
    "pinned": [0],
    "target": "structure"
}

  6. How shape parameter layering and merging works

    main

    Chemiscope uses a layered approach to define shape parameters, allowing you to specify settings at different levels of granularity. Parameters are merged in the following order (more specific overrides less specific):

    global $\leftarrow$ structure[j] $\leftarrow$ atom[k]

    • global: Applies to every instance of the shape.
    • structure: An optional list of dictionaries, one per structure. The length of this list must exactly match the number of structures.
    • atom: An optional flat list of dictionaries covering ALL atoms across all structures. The length of this list must exactly match the total number of atoms in the dataset.

    Parameter Structure

    sShapes = {
    "my_shape": {
        "kind": "arrow",
        "parameters": {
            "global": {...},      # applies to every instance
            "structure": [ {...}, ... ],  # optional: one dict per structure
            "atom": [ {...}, ... ],       # optional: flat list over ALL atoms
        },
    }
}
    shapes = {
    "my_shape": {
        "kind": "arrow",
        "parameters": {
            "global": {...},      # applies to every instance
            "structure": [ {...}, ... ],  # optional: one dict per structure
            "atom": [ {...}, ... ],       # optional: flat list over ALL atoms
        },
    }
}

  7. Define input structures

    main

    The structures argument accepts a list of supported objects. Supported backends include:

    • ase.Atoms (via ase): Most common; supports extxyz, CIF, PDB, POSCAR, etc.
    • MDAnalysis.AtomGroup (via MDAnalysis): Ideal for biomolecules.
    • chemfiles Frame/Trajectory (via chemfiles >=0.10, <0.11).
    • stk.Molecule (via stk): Includes bonds but no cell or stored properties.
    • Hand-built dict: A manual schema for custom data.

    Hand-built structure dictionary schema

    {
    "size": 3,                       # required: number of atoms
    "names": ["O", "H", "H"],    # required: per-atom symbol/name
    "x": [0.0, 0.76, -0.76],         # required: Cartesian coords
    "y": [0.0, 0.59, 0.59],
    "z": [0.0, 0.0, 0.0],
    "cell": [a1,a2,a3, b1,b2,b3, c1,c2,c3],  # optional: flattened 3x3, row-major
    # optional: "bonds", "elements", "chains", "resnames", "resids", "hetatom"
}
    {
    "size": 3,
    "names": ["O", "H", "H"],
    "x": [0.0, 0.76, -0.76],
    "y": [0.0, 0.59, 0.59],
    "z": [0.0, 0.0, 0.0],
    "cell": [a1,a2,a3, b1,b2,b3, c1,c2,c3],
}

  8. Switch between local environments and entire structures

    main

    If a dataset includes at least two properties for both atoms and structures and has specified environments, a visualization display toggle becomes available.

    This toggle allows you to switch the entire application's context between:

    • Local environments
    • Entire structures

    Note: Toggling this mode will reset all panel settings (Map, Structure, and Info) to their default values, as the current input format does not support storing separate settings for both modes.

  9. Chemiscope implementation technologies

    main

    Chemiscope is built using web technologies, making it cross-platform and accessible via a browser without local installation.

    Core Stack:

    • Languages: TypeScript (compiled to JavaScript), HTML5, and CSS.
    • Graphics/Rendering: WebGL for graphical elements and Plotly.js for rendering and animating 2D and 3D plots.
    • Structure Visualization: The JavaScript version of Jmol is used to display atomic structures.
    • Deployment Modes:
      • Online Service: Available at http://chemiscope.org for visualizing datasets without installation.
      • Standalone Mode: The code and a predefined dataset can be merged into a single HTML file, which is useful for archival purposes (e.g., supplementary information for publications) or working with sensitive data in restricted environments.

  10. Integrate Chemiscope into different environments

    main

    Chemiscope 1.0 is designed to work across multiple Python-centric workflows:

    • Jupyter Notebooks: Rendered as an interactive widget with bidirectional communication between Python and JavaScript via traitlets.
    • Streamlit: A dedicated component that renders a viewer from an in-memory dataset and propagates user interactions (selections and settings) back to Python.
    • Sphinx Documentation: A Sphinx extension is available to embed interactive viewers alongside narrative text and executable examples for reproducible documentation.
    • Standalone Web App: Datasets can be exported to the JSON schema consumed by the JavaScript renderer for use at chemiscope.org.

  11. Define properties (structure vs atom targets)

    main

    Properties are provided as a dictionary keyed by name. You can use a full form (for metadata) or a shorthand (list of values).

    • target="structure": One value per frame.
    • target="atom": One value per atom (length must equal total atoms across all structures).
    • 2D Numpy Arrays: An $N imes M$ array becomes $M$ properties named name[1], name[2], etc.

    Property Formats

    # Full form
properties = {
    "energy": {
        "target": "structure",
        "values": [1.2, 0.9, 1.5],
        "units": "eV",
        "description": "DFT energy",
    },
}

# Shorthand
properties = {
    "volume": [12.0, 12.1, 11.9],
}
    properties = {
    "energy": {
        "target": "structure",
        "values": [1.2, 0.9, 1.5],
        "units": "eV",
        "description": "DFT energy",
    },
    "volume": [12.0, 12.1, 11.9],
}

  12. Use external structure files in chemiscope datasets

    main

    For large datasets or shared structures, you can use external structure files. The main chemiscope JSON file must follow the UserStructure interface, where the data field contains the path to the external structure file.

    Paths in the JSON file should be relative to the position of the main chemiscope JSON file. During the Sphinx build process, these external files are automatically copied to the documentation build folder.

    External files can be created manually or via the chemiscope.write_external_structures Python function.

    .. chemiscope:: ../datasets/showcase-external.json
    :mode: default
    :warning_timeout: 0