WIP

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/reference_spaces.md

+# 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.
+
+[^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)
\ No newline at end of file

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
 
-## System Requirements
-
-Any up to date modern browsers (Chrome, Firefox, Safari). In addition, your hardware needs to support WebGL2. 
-
-!!! Info
-	To check if your device and browser support WebGL2, visit <https://get.webgl.org/webgl2/>.
+To launch siibra-explorer go to <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/>. 
 
-## Launching siibra-explorer
+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. 
 
-To launch siibra-explorer go to <https://atlases.ebrains.eu/viewer> in your web browser. 
+Note that you can actually run siibra-explorer on most recent mobile devices!
 
-!!! info
-    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. 
+![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/siibra_explorer_in_mobile.png)

docs/index.md

 # Siibra Explorer
 
+> A web-based viewer for exploring multi-resolution 3D brain atlases
+
 ## Links
 
 - production: <https://atlases.ebrains.eu/viewer/>
@@ -7,4 +9,18 @@
 
 ## Overview 
 
-siibra-explorer is a browser based 3D viewer for exploring multi-resolution brain atlases and discovering data features linked from different repositories to anatomical locations, covering a broad range of neuroscientific data modalities . The viewer provides an intuitive way of navigating brain reference volumes and  3D parcellation maps from conventional millimeter scale down to microscopic resolution. You can select different species, brain reference spaces and parcellation maps, search region hierarchies, and select brain regions to access detailed information. Data features are dynamically retrieved for selected parcellation regions or 3D views. 
+siibra-explorer is a browser based 3D viewer for exploring brain atlases that cover different spatial resolutions and modalities. It is built around an interactive 3D view of the brain displaying a unique selection of detailed templates and parcellation maps for the human, macaque, rat or mouse brain, including BigBrain as a microscopic resolution human brain model at its full resolution of 20 micrometers. 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.
+
+| ![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/fsaverage_connectivity.png) | ![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/waxholmv4.png) | ![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/bigbrain_cortical.png) |
+| :-: | :-: | :-: |
+| A | B | C |
+
+*Figure 1: Example views of siibra-explorer’s user interface. A: Surface map of the human brain, displaying connection strengths of a region in the occipital pole to other brain regions. B: Volumetric map of the rat brain, showing the coronal, sagittal and axial planes with a 3D overview. C: Zoomed-in view to a coronal section displaying a border region in the visual system at microscopic detail.*
+
+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) on <https://atlases.ebrains.eu/viewer>. 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 software code of siibra-explorer is openly accessible on [github](http://github.com/fzj-inm1-bda/siibra-explorer). 
+
+!!! info
+    siibra stands for "**s**oftware **i**nterfaces for **i**nteracting with **br**ain **a**tlases" and includes a whole 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/). 
+
+!!! info
+    This documentation describes the functionalities of the software. Although it includes examples of brain templates, parcellation maps and multimodal data features, it does not  provide a catalogue of the atlas contents available in the public installation, since these are constantly growing and managed independently of the software. To see which contents are accessible, go and explore the viewer <https://atlases.ebrains.eu/viewer>. Learn more about EBRAINS brain atlases at <https://ebrains.eu/brain-atlases/reference-atlases>. 
\ No newline at end of file

docs/main_concepts/main_elements_of_the_viewer.md

-# Main elements of siibra-explorer
-
-(TBD)
-
-<!-- 
-
-At its core, the viewer presents a 3D view of a brain. Per default, you see a volume in three orthogonal planes, …. In some cases, you just see a brain surface. Navigation inside these views is dewscribed in [Navigating volumetric..]
-
-At the bottom of the viewer, you find element to select different species, parcellations and reference spaces. These are explained in …
-
-At the top right of the views, there are several icons guiding you to additional dunctionalites. [help] [plugins] [settings]
- -->

docs/main_concepts/what_makes_a_brain_atlas.md

-# What Makes a Brain Atlas
-
-siibra organizes atlases into the following conceptual structures:
-
-- Atlases. An atlas can be understood as a collection of complementary parcellations and reference spaces for a particular species, with links between brain regions, spatial locations and anatomically organized data features.
-
-- Reference spaces. A reference space defines a coordinate system in the brain. Since reference spaces can be of different type (e.g. volumetric or surface-based, single-subject of average subject), an atlas can support multiple reference spaces. Each reference space comes with at least one reference template, which is an image volume or mesh representing the brain structures in that space.
-
-- Parcellations. A parcellation defines a (searchable) hierarchy of brain regions and corresponding metadata, and thus represents a semantic object. Different parcellations may reflect different organizational principles of the brain, and thus an atlas can offer multiple, typically complementary parcellations. Each parcellation is linked to a set of corresponding parcellation maps.
-
-- Parcellation maps. The regions defined by a given parcellation can be mapped in multiple reference spaces. The actual parcellation maps are spatial objects. They take the form of image volumes or surface meshes, and can be of labelled type, where coordinates or vertices in the reference space have a single unique brain region label, or of statistical type, where coordinates are linked to one floating point value per brain region, reflecting the weight or probability of each region at the given coordinate. Since statistical maps of closeby brain regions usually overlap, they are typically accessed by selecting a specific region from a labelled map in siibra-explorer.
-
-- Regions. A region represents a subtree of a region hierarchy, and contains metadata about the parcellation it belongs to, the parcellation maps where it is included, related publications, and more. Each region has links to its parent and child regions.

mkdocs.yml

@@ -20,9 +20,12 @@ plugins:
 nav:
   - Home: 'index.md'
   - Getting Started: 'getting_started.md'
-  - Main Concepts:
-    - What Makes a Brain Atlas: 'main_concepts/what_makes_a_brain_atlas.md'
-    - Main Elements of siibra-explorer: 'main_concepts/main_elements_of_the_viewer.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"
   - Basic Functionalities:
     - Selecting Parcellation Maps: 'basic_functionalities/selecting_parcellation_maps.md'
     - Exploring 3D Parcellation Maps: 'basic_functionalities/exploring_3d_parcellation_maps.md'