update overview sections

docs/basic_functionalities/overview_of_ui.md

+# Organisation of the user interface
+
+At its core, the viewer presents a 3D view of a brain. 
+The precise layout of the 3D view depends on the select reference space. 
+
+For volumetric reference spaces, it presents 2D views of three orthogonal planes in the reference template, combined with a rotatable 3D overview of the brain surface indicating the location of these planes.
+The planes default to the coronal, sagittal and axial plane, and can be freely adjusted in position and orientation to select arbitrary oblique views. 
+
+![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/siibra-explorer-waxholm.png){ style="width:300px"}
+
+The volumetric views support ultrahigh-resolution data, and can be zoomed in if the underlying image data allows. Each of the 3 planar views can be maximized using the "[ ]" icon in each view.
+
+![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/siibra-explorer-v1border.png){ style="width:300px"}
+
+For pure surface spaces, such as the fsaverage space, the viewer shows only a 3D view.
+
+![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/siibra-explorer-surfaceview.png){ style="width:300px"}
+
+At the bottom of the window, you find buttons to switch between different species, different reference templates, and different parcellation maps. Note that buttons may be hidden in case that only one option is available.
+
+![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/siibra-explorer-chips.png){ style="width:700px"}
+
+At the top right of the viewer, there are several icons guiding you to additional functionalites.
+
+![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/siibra-explorer-tools.png){ style="width:250px"}
+
+From left to right you find
+
+- The help button. Here you find information about keyboard shortcuts and terms of use. You can also launch the interactive quick tour, which is launched automatically when you use siibra-explorer for the first time.
+- The download button, which will download the reference template and parcellation map currently displayed in the viewer
+- The plugin menu, which allows you to launch interactive plugins (see “Advanced functionalities” below)
+- The login menu, which allows you to login with an EBRAINS account to access some custom functionalities for sharing.
+

docs/core_elements/reference_spaces.md → docs/concepts.md

-# Multiple reference spaces
+# Key concepts of an atlas in siibra
 
+A typical brain atlas consists of 
+
+- a reference coordinate space with a brain reference template, typically a structural image of the brain
+- a parcellation map, which labels coordinates in the reference space with an identifier of a brain region,
+- a taxonomy, which defines the names of brain regions used by the parcellation, and links them to the identifiers used in the parcellation map.
+
+siibra extends this basic concept by linking multiple spaces and parcellation maps with complementary properties, and combining them with multimodal data features that capture characteristic aspects of brain organisation for locations in the brain.
+
+**Labelled maps vs probability maps.**
+The above describes what siibra calls a "labelled map", where each location in the brain is uniquely labelled to belong to exactly one brain region. However, siibra also supports "statistical maps", where each location in the brain is mapped to multiple brain regions with different weights (or probabilities). Each coordinate is then not mapped to a single label, but to a vector of weights, one per brain region. The weights for a specific brain region across all coordinates in the brain then form the statistical (or probabilistic) map for this single region, and the statistical maps of multiple regions may overlap.# Datasets linked to locations in the brain
+
+
+**Multiple reference spaces.**
 siibra supports different parcellation maps for a given reference space, but also different reference coordinate spaces for a given species. The human brain atlas in EBRAINS provides parcellation maps in 
 
 - the MNI 152 space[^1], which is defined by a multi-subject average of structural MRI scans defined at a resolution of about 1mm,
-
 - the freesurfer fsaverage space[^2], which is a pure surface space defined over the vertices of a surface mesh of an average brain,
-
 - the BigBrain histological space[^3] which is the anatomical space of a single subject brain that was 3D reconstructed from more than 7000 histological sections at an isotropic resolution of 20 micrometers.
 
 siibra-explorer is designed visualize any of these different types efficiently, by allowing to zoom into very high resolution images, and by offering both volumetric and surface-based viewing modes.
 
+**Relationships between spaces.**
+Some parcellations maps, especially the Julich-Brain cytoarchitectonic maps[^4], are available in all those spaces, this way providing a natural link across those spaces and different spatial scales. An additional link is available through spatial transformations[^5], which map coordinates in one space to their most likely corresponding coordinate in another. These spatial transformations are used by siibra-explorer when you change the reference space, in order to preserve the currently viewed region of interest.
+
+**Datasets linked to locations in the brain.**
+siibra provides access to data features anchored to locations in the brain. Locations can be defined in very different ways, such as  by specification of a brain region (thus only providing a semantic definition), a coordinate in a reference space, or a bounding box in a reference space. Data features represent datasets hosted on a public repository, typically but not exclusively the EBRAINS Knowledge Graph. A growing share of linked datasets are directly interpreted by siibra-explorer, which means that siibra-explorer offers direct access to the underlying data: Further than just displaying information about the dataset, siibra can visualize the data itself and allows to download it. These directly interpreted features are categorized into molecular, cellular, functional, fibres, connectivity and macrostructural. Many additional datasets are linked to brain regions, which only provide a metadata description and link to the corresponding dataset page on their original repository. 
+
+
 [^1]: Fonov V, Evans A, McKinstry R, Almli C, Collins D. Unbiased nonlinear average age-appropriate brain templates from birth to adulthood. NeuroImage. 2009;47:S102. doi:10.1016/S1053-8119(09)70884-5. *More precisely, siibra supports the MNI ICBM 152 2009c nonlinear asymmetric template, as well as the Colin 27 single subject average.*
 
 [^2]: Dale AM, Fischl B, Sereno MI. Cortical Surface-Based Analysis: I. Segmentation and Surface Reconstruction. NeuroImage. 1999;9(2):179-194. doi:[10.1006/nimg.1998.0395](https://doi.org/10.1006/nimg.1998.0395)
 
-[^3]: Amunts K, Lepage C, Borgeat L, Mohlberg H, Dickscheid T, Rousseau ME, Bludau S, Bazin PL, Lewis LB, Oros-Peusquens AM, Shah NJ, Lippert T, Zilles K, Evans AC. BigBrain: An Ultrahigh-Resolution 3D Human Brain Model. Science. 2013;340(6139):1472-1475. doi:[10.1126/science.1235381](https://doi.org/10.1126/science.1235381)
+[^3]: Amunts K, Lepage C, Borgeat L, Mohlberg H, Dickscheid T, Rousseau ME, Bludau S, Bazin PL, Lewis LB, Oros-Peusquens AM, Shah NJ, Lippert T, Zilles K, Evans AC. BigBrain: An Ultrahigh-Resolution 3D Human Brain Model. Science. 2013;340(6139):1472-1475. doi:[10.1126/science.1235381](https://doi.org/10.1126/science.1235381)# Relationships between different reference spaces
\ No newline at end of file
+
+[^4]: Amunts K, Mohlberg H, Bludau S, Zilles K. Julich-Brain: A 3D probabilistic atlas of the human brain’s cytoarchitecture. Science. 2020;369(6506):988-992. doi:[10.1126/science.abb4588](https://doi.org/10.1126/science.abb4588)
+
+[^5]: Lebenberg J, Labit M, Auzias G, Mohlberg H, Fischer C, Rivière D, Duchesnay E, Kabdebon C, Leroy F, Labra N, Poupon F, Dickscheid T, Hertz-Pannier L, Poupon C, Dehaene-Lambertz G, Hüppi P, Amunts K, Dubois J, Mangin JF. A framework based on sulcal constraints to align preterm, infant and adult human brain images acquired in vivo and post mortem. Brain Struct Funct. 2018;223(9):4153-4168. doi:[10.1007/s00429-018-1735-9](10.1007/s00429-018-1735-9)

docs/core_elements/labelled_vs_probability.md

-# Labelled maps vs probability maps
-
-The above describes what siibra calls a "labelled map", where each location in the brain is uniquely labelled to belong to exactly one brain region. However, siibra also supports "statistical maps", where each location in the brain is mapped to multiple brain regions with different weights (or probabilities). Each coordinate is then not mapped to a single label, but to a vector of weights, one per brain region. The weights for a specific brain region across all coordinates in the brain then form the statistical (or probabilistic) map for this single region, and the statistical maps of multiple regions may overlap.
\ No newline at end of file

docs/core_elements/linked_datasets.md

-# Datasets linked to locations in the brain
-
-siibra provides access to data features anchored to locations in the brain. Locations can be defined in very different ways, such as  by specification of a brain region (thus only providing a semantic definition), a coordinate in a reference space, or a bounding box in a reference space. Data features represent datasets hosted on a public repository, typically but not exclusively the EBRAINS Knowledge Graph. A growing share of linked datasets are directly interpreted by siibra-explorer, which means that siibra-explorer offers direct access to the underlying data: Further than just displaying information about the dataset, siibra can visualize the data itself and allows to download it. These directly interpreted features are categorized into molecular, cellular, functional, fibres, connectivity and macrostructural. Many additional datasets are linked to brain regions, which only provide a metadata description and link to the corresponding dataset page on their original repository. 
-

docs/core_elements/overview.md

-# Core elements of an atlas in siibra
-
-A typical brain atlas consists of 
-
-- a reference coordinate space with a brain reference template, typically a structural image of the brain
-- a parcellation map, which labels coordinates in the reference space with an identifier of a brain region,
-- a taxonomy, which defines the names of brain regions used by the parcellation, and links them to the identifiers used in the parcellation map.
-
-siibra extends this basic concept by linking multiple spaces and parcellation maps with complementary properties, and combining them with multimodal data features that capture characteristic aspects of brain organisation for locations in the brain.

docs/core_elements/relationship_between_spaces.md

-# Relationships between different reference spaces
-
-Some parcellations maps, especially the Julich-Brain cytoarchitectonic maps[^4], are available in all those spaces, this way providing a natural link across those spaces and different spatial scales. An additional link is available through spatial transformations[^5], which map coordinates in one space to their most likely corresponding coordinate in another. These spatial transformations are used by siibra-explorer when you change the reference space, in order to preserve the currently viewed region of interest.
-
-[^4]: Amunts K, Mohlberg H, Bludau S, Zilles K. Julich-Brain: A 3D probabilistic atlas of the human brain’s cytoarchitecture. Science. 2020;369(6506):988-992. doi:[10.1126/science.abb4588](https://doi.org/10.1126/science.abb4588)
-
-[^5]: Lebenberg J, Labit M, Auzias G, Mohlberg H, Fischer C, Rivière D, Duchesnay E, Kabdebon C, Leroy F, Labra N, Poupon F, Dickscheid T, Hertz-Pannier L, Poupon C, Dehaene-Lambertz G, Hüppi P, Amunts K, Dubois J, Mangin JF. A framework based on sulcal constraints to align preterm, infant and adult human brain images acquired in vivo and post mortem. Brain Struct Funct. 2018;223(9):4153-4168. doi:[10.1007/s00429-018-1735-9](10.1007/s00429-018-1735-9)
\ No newline at end of file

docs/getting_started.md

 # Getting Started
 
-To launch siibra-explorer go to <https://atlases.ebrains.eu/viewer> in your web browser. 
+!!! tip "Launch siibra-explorer on EBRAINS"
+	To launch siibra-explorer, **<https://atlases.ebrains.eu/viewer>** in your web browser. 
 
 Recommended browsers are up-to-date versions of [Firefox](https://www.mozilla.org/firefox) and [Google chrome](https://www.google.com/chrome). Newer versions of [Apple Safari](https://www.apple.com/safari/) also work fairly well. Note that your hardware needs to support the WebGL2 standard, which should be the case for recent devices. If in doubt, check compatibility at <https://get.webgl.org/webgl2/>. 
 
 An overview and the basic functionalities of siibra-explorer is presented in the quick tour, which is automatically launched on first use. You can always revisit the quick tour via the help menu, which can be found under the `?` icon at the top right of the UI, or using the `?` / `h` keyboard shortcut. 
 
-Note that you can actually run siibra-explorer on most recent mobile devices!
-
+Using the browser on your table or mobile phone should work in many cases as well, try it out!
 ![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/siibra_explorer_in_mobile.png)

docs/index.md

@@ -12,7 +12,7 @@ siibra-explorer is a browser based 3D viewer for exploring brain atlases that co
 By selecting brain regions or zooming into user-defined regions of interest, you can find and access data features from different modalities which have been linked to the respective locations in the brain, including structural and functional connectivity, histological features such as cell and neurotransmitter densities, 2D and 3D images, and gene expressions. This way siibra-explorer allows you to explore and study brain organization in many different facets.
 
 !!! info "Check out siibra's Python and HTTP interfaces"
-    siibra stands for "**s**oftware **i**nterfaces for **i**nteracting with **br**ain **a**tlases" and includes a suite of tools of which siibra-explorer is the most immediate and intuitive entry point. If you are into programming and reproducibility however, don't miss [siibra-python](https://siibra-python.readthedocs.io) which provides all the functionality of the explorer (and more) in Python. If you are into application development, check out our http interface [siibra-api](https://siibra-api-stable.apps.hbp.eu/). 
+    siibra stands for "software interfaces for interacting with brain atlases" and includes a suite of tools of which siibra-explorer is the most immediate and intuitive entry point. If you are into programming and reproducibility however, don't miss [siibra-python](https://siibra-python.readthedocs.io) which provides all the functionality of the explorer (and more) in Python. If you are into application development, check out our http interface [siibra-api](https://siibra-api-stable.apps.hbp.eu/). 
 
 siibra-explorer has been developed in the frame of the [Human Brain Project](https://www.humanbrainproject.eu/en/). The main installation is hosted as a publicly accessible service inside the European research infrastructure [EBRAINS](https://ebrains.eu). All its contents are linked to publicly available curated datasets with rich metadata, mostly shared via the [EBRAINS Knowledge Graph](https://search.kg.ebrains.eu). The sourcecode of siibra-explorer is openly accessible at [github](http://github.com/fzj-inm1-bda/siibra-explorer). 
 

mkdocs.yml

@@ -13,6 +13,7 @@ markdown_extensions:
   - codehilite
   - footnotes
   - mdx_truly_sane_lists
+  - attr_list
 
 plugins:
   - search
@@ -20,24 +21,21 @@ plugins:
 nav:
   - Home: 'index.md'
   - Getting Started: 'getting_started.md'
-  - Core Elements of an Atlas in Siibra:
-    - Overview: "core_elements/overview.md"
-    - Labelled Maps vs Probability Maps: "core_elements/labelled_vs_probability.md"
-    - Multiple Reference Spaces: "core_elements/reference_spaces.md"
-    - Relationship betweeen Different Reference Spaces: "core_elements/relationship_between_spaces.md"
-    - Datasets Linked to Locations in the Brain: "core_elements/linked_datasets.md"
+  - Key concepts: 'concepts.md'
   - Basic Functionalities:
-    - Selecting Parcellation Maps: 'basic_functionalities/selecting_parcellation_maps.md'
-    - Exploring 3D Parcellation Maps: 'basic_functionalities/exploring_3d_parcellation_maps.md'
-    - Keyboard Shortcuts: 'basic_functionalities/helperOnePager.md'
-    - Storing and Sharing 3D Views: 'basic_functionalities/storing_and_sharing_3d_views.md'
-    - Selecting Brain Regions: 'basic_functionalities/selecting_brain_regions.md'
-    - Looking Up Coordinates in Reference Space: 'basic_functionalities/looking_up_coordinates.md'
-    - Finding Multimodal Data: 'basic_functionalities/finding_multimodal_data.md'
+    - Organisation of user interface: 'basic_functionalities/overview_of_ui.md'
+    - Selecting parcellation maps: 'basic_functionalities/selecting_parcellation_maps.md'
+    - Selecting parcellation maps: 'basic_functionalities/selecting_parcellation_maps.md'
+    - Exploring 3D parcellation maps: 'basic_functionalities/exploring_3d_parcellation_maps.md'
+    - Keyboard shortcuts: 'basic_functionalities/helperOnePager.md'
+    - Storing and sharing 3D views: 'basic_functionalities/storing_and_sharing_3d_views.md'
+    - Selecting brain regions: 'basic_functionalities/selecting_brain_regions.md'
+    - Looking up coordinates in reference space: 'basic_functionalities/looking_up_coordinates.md'
+    - Finding multimodal data: 'basic_functionalities/finding_multimodal_data.md'
   - Advanced functionalities:
-    - Annotating Structures in the Brain: "advanced_functionalities/annotating_structures.md"
-    - Differential Gene Expression Analysis: "advanced_functionalities/differential_gene_expression_analysis.md"
-    - Superimposing Local Files: "advanced_functionalities/superimposing_local_files.md"
+    - Annotating structures in the brain: "advanced_functionalities/annotating_structures.md"
+    - Differential gene expression analysis: "advanced_functionalities/differential_gene_expression_analysis.md"
+    - Superimposing local files: "advanced_functionalities/superimposing_local_files.md"
 
   - Release notes:
     - v2.14.0: 'releases/v2.14.0.md'