Add documentation and examples.

Author: feilong

docs/_config.yml

@@ -0,0 +1,97 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: ""
+author: the brainplotlib developers and contributors
+logo: brainplotlib_logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: cache
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+# bibtex_bibfiles:
+#   - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/feilong/brainplotlib  # Online location of your book
+  path_to_book: docs  # Optional path to your book, relative to the repository root
+  branch: master  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+parse:
+  myst_substitutions:
+    gallery: |
+      ````{panels}
+      :column: col-4
+
+      <a href="/examples/save_image.html">
+      Save the high-res image
+      ^^^
+      ```{glue:} save_image
+      ```
+      </a>
+
+      ---
+
+      <a href="/examples/plot_colorbar.html">
+      Plot a colorbar
+      ^^^
+      ```{glue:} with_colorbar
+      ```
+      </a>
+
+      ---
+
+      <a href="/examples/different_cmaps.html">
+      Different colormaps
+      ^^^
+      ```{glue:} different_cmaps
+      ```
+      </a>
+
+      ````
+      ````{panels}
+      :column: col-4
+
+      <a href="/examples/different_resolutions.html">
+      Different data resolutions
+      ^^^
+      ```{glue:} different_resolutions
+      ```
+      </a>
+
+      ---
+ 
+      <a href="/examples/cortical_masks.html">
+      Handling cortical masks
+      ^^^
+      ```{glue:} cortical_masks
+      ```
+      </a>
+
+      ---
+
+      <a href="/examples/different_surfaces.html">
+      Alternative surface types
+      ^^^
+      ```{glue:} different_surfaces
+      ```
+      </a>
+
+      ````
+    gallery_link : |
+      ---
+      [**<< Go back to the gallery of examples**](/examples/index)

docs/_toc.yml

@@ -0,0 +1,15 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+parts:
+- caption: Examples
+  chapters:
+  - file: examples/index
+  - file: examples/save_image
+  - file: examples/plot_colorbar
+  - file: examples/different_cmaps
+  - file: examples/different_resolutions
+  - file: examples/cortical_masks
+  - file: examples/different_surfaces

docs/brainplotlib_logo.png

@@ -0,0 +1,93 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.11.5
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Handling cortical masks
+
+Not every vertex on surface belongs to the cerebral cortex.
+There are approximately 8.5% of vertices around the medial wall that are non-cortical.
+When analyzing fMRI data on surface, we usually want to focus on vertices of the cerebral cortex and mask out non-cortical vertices.
+This masking step changes the number of vertices and the shape of the data.
+
+```{margin} Different surface spaces
+If you use the cortical mask of the `fsaverage5` or `fsaverage6` surface instead of `fsaverage`, the number of cortical vertices would slightly differ.
+```
+For example, with the `icoorder5` resolution `fsaverage` surface there are 10242 vertices per hemisphere in total.
+After masking out the non-cortical vertices, there are 9372 and 9370 vertices for the left and right hemispheres, respectively.
+
+The `brain_plot` function automatically detects whether the data has been masked or not and render it accordingly.
+
+```{glue:} cortical_masks
+```
+
+```{code-cell}python
+import numpy as np
+from brainplotlib import brain_plot
+import matplotlib.pyplot as plt
+
+rng = np.random.default_rng(0)
+```
+
+```{code-cell}python
+:tags: ["remove-output"]
+fig, axs = plt.subplots(2, 2, dpi=300, figsize=([_/300 + 1 for _ in [1728, 1560]]))
+for i in range(2):
+    for j in range(2):
+        if (i, j) == (0, 0):
+            v = rng.random((588 + 587, ))
+            title = 'masked icoorder3'
+        elif (i, j) == (0, 1):
+            v = rng.random((642 * 2, ))
+            title = 'non-masked icoorder3'
+        elif (i, j) == (1, 0):
+            v = rng.random((9372 + 9370, ))
+            title = 'masked icoorder5'
+        elif (i, j) == (1, 1):
+            v = rng.random((10242 * 2, ))
+            title = 'non-masked icoorder5'
+
+        ax = axs[i][j]
+        img = brain_plot(v, vmax=1, vmin=0)
+        ax.imshow(img)
+        ax.axis('off')
+        ax.set_title(title)
+plt.show()
+```
+
+```{code-cell}python
+:tags: ["remove-cell"]
+from myst_nb import glue
+glue('cortical_masks', fig, display=False)
+```
+
+## Different forms of input
+
+The `brain_plot` function also handles different forms of input. The values to be plotted on surface can be one of:
+- Two NumPy arrays for the left and right hemispheres, respectively.
+- A list or tuple of NumPy arrays with two elements.
+- A concatenated NumPy array comprising data from both left and right hemispheres (left hemisphere first).
+
+The same image can be generated using different forms of input, as long as the actual data is the same.
+```{code-cell}python
+lh, rh = rng.random((588, )), rng.random((587, ))
+
+img1 = brain_plot(lh, rh, vmax=1, vmin=0)
+img2 = brain_plot([lh, rh], vmax=1, vmin=0)
+img3 = brain_plot(np.concatenate([lh, rh], axis=0), vmax=1, vmin=0)
+
+np.testing.assert_array_equal(img1, img2)
+np.testing.assert_array_equal(img1, img3)
+```
+
+{{ gallery_link }}

docs/examples/cortical_masks.md

@@ -0,0 +1,54 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.11.5
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Use different colormaps
+
+This example shows how to use different colormaps.
+
+```{glue:} different_cmaps
+```
+
+```{code-cell}python
+import numpy as np
+from brainplotlib import brain_plot
+import matplotlib.pyplot as plt
+
+rng = np.random.default_rng(0)
+v = rng.random((1175, ))
+```
+```{margin} Change the colormap
+The `cmap` parameter of `brain_plot` can use any `matplotlib` colormaps in a similar way as `plt.plot`.
+```
+```{code-cell}python
+:tags: ["remove-output"]
+fig, axs = plt.subplots(2, 2, dpi=300, figsize=([_/300 + 1 for _ in [1728, 1560]]))
+cmaps = ['viridis', 'jet', 'bwr', 'plasma']
+for i in range(2):
+    for j in range(2):
+        ax = axs[i][j]
+        cmap = cmaps[i*2+j]
+        img = brain_plot(v, vmax=1, vmin=0, cmap=cmap)
+        ax.imshow(img)
+        ax.axis('off')
+        ax.set_title(cmap)
+plt.show()
+```
+```{code-cell}python
+:tags: ["remove-cell"]
+from myst_nb import glue
+glue('different_cmaps', fig, display=False)
+```
+
+{{ gallery_link }}

docs/examples/different_cmaps.md

@@ -0,0 +1,68 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.11.5
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Different data resolutions
+
+This example is about different input data resolutions.
+
+```{glue:} different_resolutions
+```
+
+Neuroimaging data on cortical surface has different spatial resolutions:
+
+| name | resolution | # of vertices per hemishere |
+| --- | --- | --- |
+| icoorder7 | 0.7 mm | 163842 |
+| icoorder6 | 1.5 mm | 40962 |
+| icoorder5 | 3 mm | 10242 |
+| icoorder4 | 6 mm | 2562 |
+| icoorder3 | 13 mm | 642 |
+
+Typical the data resolution is between `icoorder7` (usually anatomical scans) and `icoorder5` (usually functional scans). `icoorder3` resolution is often used in defining connectivity targets for [connectivity hyperalignment](https://doi.org/10.1371/journal.pcbi.1006120) and in examples.
+
+The number of cortical vertices **per hemisphere** can be computed based on icoorder: $ n_v = 4^{icoorder} \times 10 + 2 $, where $n_v$ is the number of vertices.
+
+The `brain_plot` function automatically handles various data resolution between `icoorder7` and `icoorder3`. When the input data has a lower resolution than `icoorder7`, it's automatically upsampled to the `icoorder7` resolution in a nearest-neighbor manner based on the [Voronoi diagram](https://en.wikipedia.org/wiki/Voronoi_diagram). The data is always visualized using the `icoorder7` high-resolution surface (i.e., `fsaverage`).
+
+```{code-cell}python
+import numpy as np
+from brainplotlib import brain_plot
+import matplotlib.pyplot as plt
+
+rng = np.random.default_rng(0)
+```
+```{code-cell}python
+:tags: ["remove-output"]
+fig, axs = plt.subplots(2, 2, dpi=300, figsize=([_/300 + 1 for _ in [1728, 1560]]))
+icoorders = [3, 5, 6, 7]
+for i in range(2):
+    for j in range(2):
+        ax = axs[i][j]
+        icoorder = icoorders[i*2+j]
+        nv = 4**icoorder * 10 + 2
+        v = rng.random((nv * 2, ))
+        img = brain_plot(v, vmax=1, vmin=0, cmap='coolwarm')
+        ax.imshow(img)
+        ax.axis('off')
+        ax.set_title(f'icoorder{icoorder}')
+plt.show()
+```
+```{code-cell}python
+:tags: ["remove-cell"]
+from myst_nb import glue
+glue('different_resolutions', fig, display=False)
+```
+
+{{ gallery_link }}

docs/examples/different_resolutions.md

@@ -0,0 +1,52 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.11.5
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Use different types of surface
+
+By default `brain_plot` uses the `inflated` surface.
+This can be changed to the `pial`, `white`, or `midthickness` (average of `pial` and `white`) surface using the `surf_type` parameter.
+
+```{glue:} different_surfaces
+```
+
+```{code-cell}python
+import numpy as np
+from brainplotlib import brain_plot
+import matplotlib.pyplot as plt
+
+rng = np.random.default_rng(0)
+v = rng.random((1175, ))
+```
+```{code-cell}python
+:tags: ["remove-output"]
+fig, axs = plt.subplots(2, 2, dpi=300, figsize=([_/300 + 1 for _ in [1728, 1560]]))
+surf_types = ['inflated', 'midthickness', 'pial', 'white']
+for i in range(2):
+    for j in range(2):
+        ax = axs[i][j]
+        surf_type = surf_types[i*2+j]
+        img = brain_plot(v, vmax=1, vmin=0, cmap='rainbow', surf_type=surf_type)
+        ax.imshow(img)
+        ax.axis('off')
+        ax.set_title(f'{surf_type} surface')
+plt.show()
+```
+```{code-cell}python
+:tags: ["remove-cell"]
+from myst_nb import glue
+glue('different_surfaces', fig, display=False)
+```
+
+{{ gallery_link }}