Add possibility to change the display mode (atom <-> structure) (#351)

Where to play around with modes:
```
npm i
npm run start
```
Open the `Chemical Shieldings` example

```
tox -e docs
python3 -m http.server
```
Open `examples/2-structure_map.html`

TODO:
- [x] change in EnvironmentInfo
- [x] change in map
- [x] change in structure
- [x] move mode out of indexer
- [x] add loader
- [x] change UI of toggle
- [x] testing (played with the examples from chemiscope.org & in
doc/examples)

After review:
- [x] UI: add titles to buttons; substruct height of buttons in the map;
reset color range
- [x] Code: document, delete usage of settings while changing the mode;
fully recreate mapOptions
- [x] ~~Display errors as errors instread of warning~~ --> throw error,
change logging in separate PR
- [x] Add `mode` to the settings

Note for exporting/importing of the dataset:
- If mode is changed and z-axes is not selected, we export NaN to JSON
as `z.min` and `z.max`; hence it breaks once someone wants to import
this dataset to the chemiscope. To do the import, it is necessary to
delete the z-axes from the json settings (or set 0).
- This bug to be fixed in the separate PR

---------

Co-authored-by: Guillaume Fraux <[email protected]>
Co-authored-by: Michele Ceriotti <[email protected]>
Co-authored-by: Michele Ceriotti <[email protected]>

docs/src/manual/input.rst

@@ -15,8 +15,8 @@ tl;dr if you would like to generate a simple chemiscope for your dataset, we
 have a `Google Colab notebook <https://colab.research.google.com/drive/1NU0gjtaHcB5Oc3NbFZiQYtctY2190hDu>`_
 that can help!
 
-Tools able to create chemiscope input
--------------------------------------
+Tools that can create chemiscope inputs
+---------------------------------------
 
 Note that chemiscope does not compute structural representations or
 dimensionality reduction, and the command line interface works iff
@@ -218,6 +218,10 @@ contains the following fields and values:
         //
         // Each value inside the settings group is optional
         "settings": {
+            // Visualization display target, either per atom-centered environments or per structure.
+            // Supported in default and structure visualizers; the atom visualizer uses the "atom" 
+            // target by default. To use "atom" target, make sure to provide a list of environments.
+            "target": "atom" | "structure",
             // settings related to the map
             "map": {
                 // x axis settings
@@ -282,7 +286,7 @@ contains the following fields and values:
                     "bonds": true,
                     // show the atoms
                     "atoms": true,
-                    //use space filling representation
+                    // use space filling representation
                     "spaceFilling": false,
                     // show atoms labels
                     "atomLabels": false,

docs/src/manual/panels.rst

@@ -49,4 +49,19 @@ currently selected environment.
 
     The environment information panel fully expanded
 
+The visualization display toggle becomes available when the dataset includes at
+least two properties for each target type—atoms and structures—and has specified
+environments. This toggle allows switching between display modes, either by local
+environments or by entire structures, across all panels (the map, the structure viewer,
+and the environment information display). Note that when toggling the visualization
+target, all the settings will be reset to their default values, as the chemiscope
+input format does not allow (yet) storing different visualization settings for the
+two modes.
+
+.. figure:: ../img/target-toggle.png
+
+    Visualisation target toggle
+
 .. _3Dmol.js: https://3dmol.csb.pitt.edu/
+
+

docs/src/manual/properties.rst

@@ -11,17 +11,18 @@ properties.
 Chemiscope can work with two kinds of entities: full structures, or
 atom-centred environments. A structure consists in a set of atoms, possibly
 representing the periodic repeat unit of an infinite structure. An
-environment consists in a set of atoms that surround a central atom.
+environment consists in a set of neighbors that surround a central atom,
+within a set cutoff radius.
 In both cases, these entities are fully defined by the position and nature
 of the atoms present in the structure, or in the neighborhood of the
 environment center.
 
 For each structure or environment, one may have computed *properties*,
 e.g. the cohesive energy of a molecule, or the NMR chemical shielding of
 a nucleus, or *structural representations*, i.e. functions of the
-spatial arrangement of the atoms that incorporate some fundamental
-symmetries to achieve a description of the structure that is as complete
-as possible, yet concise. Examples of such representations are for instance
+spatial arrangement of the atoms that achieve a description of the structure 
+that is as complete as possible, yet concise. 
+Examples of such representations are for instance
 `atom density representationis <soap>`_ or `Behler-Parrinello
 symmetry functions <Behler-Parrinello>`_. These representations are usually
 high-dimensional vectors, hard to visualize and interpret. For this reason, one

docs/src/manual/sharing.rst

@@ -33,8 +33,8 @@ In general, you can set the ``load`` GET parameter on ``https://chemiscope.org``
 to any url-encoded URL, and chemiscope will try to load the dataset from this
 URL.
 
-Saving visualization state
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Saving the visualization state
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can save the current visualization settings from the website using the
 *Load/Save* menu. This will allow you to download a JSON file, which you can use

python/chemiscope/explore.py

@@ -89,7 +89,7 @@ def soap_kpca_featurize(frames):
     .. _ase-io: https://wiki.fysik.dtu.dk/ase/ase/io/io.html
     .. _sklearn: https://scikit-learn.org/
     .. _dscribe: https://singroup.github.io/dscribe/latest/
-    .. _chemiscope-explore: https://chemiscope.org/docs/examples/explore.html
+    .. _chemiscope-explore: https://chemiscope.org/docs/examples/6-explore.html
     """
 
     # Validate inputs

src/dataset.ts

@@ -5,6 +5,7 @@
 
 import { Arrow, CustomShape, Cylinder, Ellipsoid, Sphere } from './structure/shapes';
 import { ShapeParameters } from './structure/shapes';
+import { DisplayTarget } from './indexer';
 
 /** A dataset containing all the data to be displayed. */
 export interface Dataset {
@@ -52,15 +53,23 @@ export interface Dataset {
 }
 
 /**
- * Type definition for settings that can be saved with a dataset. THey should be
+ * Type definition for settings that can be saved with a dataset. They should be
  * a simple object with string keys, scalar values, array values or nested
  * Settings objects.
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface Settings
     extends Record<
         string,
-        string | string[] | number | number[] | boolean | boolean[] | Settings | Settings[]
+        | undefined
+        | string
+        | string[]
+        | number
+        | number[]
+        | boolean
+        | boolean[]
+        | Settings
+        | Settings[]
     > {}
 
 /** Various metadata associated with a dataset */
@@ -281,6 +290,31 @@ export function validateDataset(o: JsObject): void {
     );
 }
 
+/**
+ * Determines the display target for the given dataset.
+ * @param dataset the dataset for which the display target is determined
+ */
+export function getTarget(dataset: Dataset): DisplayTarget {
+    const target = dataset.settings?.target as DisplayTarget | undefined;
+    const getTargetProps = (target: DisplayTarget) =>
+        Object.values(dataset.properties).filter((p) => p.target === target);
+
+    // Target is specified in settings
+    if (target !== undefined) {
+        if (target === 'atom' && dataset.environments === undefined) {
+            throw new Error('To use "atom" target, "settings.properties" should be provided');
+        }
+        if (getTargetProps(target).length < 2) {
+            throw new Error(
+                `The provided target (${target}) cannot be used. Make sure there are at least two corresponding properties ('settings.properties').`
+            );
+        }
+        return target;
+    }
+    const atomProperties = getTargetProps('atom');
+    return dataset.environments !== undefined && atomProperties.length > 1 ? 'atom' : 'structure';
+}
+
 function checkMetadata(o: JsObject) {
     if (!('name' in o)) {
         throw Error('missing "meta.name" key in the dataset');