Update documentation

alexisthual · Sep 11, 2024 · 208c12c · 208c12c
1 parent 7fdb166
commit 208c12c
Show file tree

Hide file tree

Showing 55 changed files with 630 additions and 537 deletions.
diff --git a/_downloads/1523dc16ed9a8dffc1c2678846f55459/plot_4_aligning_high_res_volumes.zip b/_downloads/1523dc16ed9a8dffc1c2678846f55459/plot_4_aligning_high_res_volumes.zip
diff --git a/_downloads/19dfa3e5f893fcf16e74960f28b3627c/plot_3_memory_usage_callback.zip b/_downloads/19dfa3e5f893fcf16e74960f28b3627c/plot_3_memory_usage_callback.zip
diff --git a/_downloads/47bd84e94b335cd9a3f29cd13b336111/plot_2_2_coarse_to_fine.zip b/_downloads/47bd84e94b335cd9a3f29cd13b336111/plot_2_2_coarse_to_fine.zip
diff --git a/_downloads/4c6146945f23a93cc3bc716ff867265e/plot_1_dense.zip b/_downloads/4c6146945f23a93cc3bc716ff867265e/plot_1_dense.zip
diff --git a/_downloads/61c9d1a8beca40e5a105e78bef0f24cf/plot_2_1_lmds.zip b/_downloads/61c9d1a8beca40e5a105e78bef0f24cf/plot_2_1_lmds.zip
diff --git a/_downloads/6e97675b0ab53044f823cb6fe9dd1677/plot_3_aligning_low_res_volumes.zip b/_downloads/6e97675b0ab53044f823cb6fe9dd1677/plot_3_aligning_low_res_volumes.zip
diff --git a/_downloads/8286133830fa66b8c77fdd6ace5f3f8a/plot_2_aligning_brain_sparse.zip b/_downloads/8286133830fa66b8c77fdd6ace5f3f8a/plot_2_aligning_brain_sparse.zip
diff --git a/_downloads/9cb173495c0f600fc6ae125273c8b1a3/plot_1_aligning_brain_dense.zip b/_downloads/9cb173495c0f600fc6ae125273c8b1a3/plot_1_aligning_brain_dense.zip
diff --git a/_downloads/a4612008c7410b3117795a31bdae9df9/plot_1_pearson_correlation.zip b/_downloads/a4612008c7410b3117795a31bdae9df9/plot_1_pearson_correlation.zip
diff --git a/_downloads/cfc772dac5e29505ca3d818c85f1da44/plot_2_simple_crossval.zip b/_downloads/cfc772dac5e29505ca3d818c85f1da44/plot_2_simple_crossval.zip
diff --git a/_images/sphx_glr_plot_1_aligning_brain_dense_003.png b/_images/sphx_glr_plot_1_aligning_brain_dense_003.png
diff --git a/_images/sphx_glr_plot_1_aligning_brain_dense_004.png b/_images/sphx_glr_plot_1_aligning_brain_dense_004.png
diff --git a/_images/sphx_glr_plot_1_pearson_correlation_001.png b/_images/sphx_glr_plot_1_pearson_correlation_001.png
diff --git a/_images/sphx_glr_plot_1_pearson_correlation_thumb.png b/_images/sphx_glr_plot_1_pearson_correlation_thumb.png
diff --git a/_sources/auto_examples/00_basics/index.rst.txt b/_sources/auto_examples/00_basics/index.rst.txt
@@ -22,7 +22,7 @@ can be used in combination with sparse solvers for the FUGW loss.
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we sample 2 toy distributions and compute a dense fugw alignment between them....">
+    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we sample 2 toy distributions and compute a dense fugw alignment between them. Dense alignments are typically used when both aligned distributions have less than 10k points.">
 
 .. only:: html
 
@@ -39,7 +39,7 @@ can be used in combination with sparse solvers for the FUGW loss.
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we show how to derive an embedding which approximates the kernel matrix of geo...">
+    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we show how to derive an embedding which approximates the kernel matrix of geodesic distances on a given mesh. This technique is useful when trying to align distributions with a large number of points. Indeed, the kernel matrix of pairwise distances won&#x27;t fit in memory, but an embedding computed in the right dimension can probably estimate it.">
 
 .. only:: html
 
@@ -56,7 +56,7 @@ can be used in combination with sparse solvers for the FUGW loss.
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we sample 2 toy distributions and compute a sparse fugw alignment between them...">
+    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we sample 2 toy distributions and compute a sparse fugw alignment between them. Sparse alignments are typically used when both aligned distributions have more than 10k points.">
 
 .. only:: html
 

diff --git a/_sources/auto_examples/00_basics/plot_1_dense.rst.txt b/_sources/auto_examples/00_basics/plot_1_dense.rst.txt
@@ -88,7 +88,7 @@ Let us generate random training data for the source and target distributions
 
  .. code-block:: none
 
-    /usr/local/lib/python3.8/site-packages/torch/distributions/wishart.py:271: UserWarning:
+    /usr/local/lib/python3.8/site-packages/torch/distributions/wishart.py:272: UserWarning:
 
     Singular sample detected.
 
@@ -237,13 +237,13 @@ using a sinkhorn solver
 
  .. code-block:: none
 
-    [05:21:35] Validation data for feature maps is not provided. Using  dense.py:202
+    [21:02:18] Validation data for feature maps is not provided. Using  dense.py:199
                training data instead.                                               
-               Validation data for anatomical kernels is not provided.  dense.py:229
+               Validation data for anatomical kernels is not provided.  dense.py:226
                Using training data instead.                                         
 
 
-    [05:21:36] BCD step 1/10   FUGW loss:      0.029136842116713524     dense.py:568
+    [21:02:19] BCD step 1/10   FUGW loss:      0.029136842116713524     dense.py:568
                Validation loss:        0.029136842116713524                         
 
 
@@ -255,31 +255,31 @@ using a sinkhorn solver
                Validation loss:        0.022854337468743324                         
 
 
-    [05:21:37] BCD step 4/10   FUGW loss:      0.02232404239475727      dense.py:568
+    [21:02:20] BCD step 4/10   FUGW loss:      0.02232404239475727      dense.py:568
                Validation loss:        0.02232404239475727                          
 
 
                BCD step 5/10   FUGW loss:      0.04798972234129906      dense.py:568
                Validation loss:        0.04798972234129906                          
 
 
-    [05:21:38] BCD step 6/10   FUGW loss:      0.02343880571424961      dense.py:568
+               BCD step 6/10   FUGW loss:      0.02343880571424961      dense.py:568
                Validation loss:        0.02343880571424961                          
 
 
-               BCD step 7/10   FUGW loss:      0.019214436411857605     dense.py:568
+    [21:02:21] BCD step 7/10   FUGW loss:      0.019214436411857605     dense.py:568
                Validation loss:        0.019214436411857605                         
 
 
                BCD step 8/10   FUGW loss:      0.01873275265097618      dense.py:568
                Validation loss:        0.01873275265097618                          
 
 
-    [05:21:39] BCD step 9/10   FUGW loss:      0.01861358806490898      dense.py:568
+               BCD step 9/10   FUGW loss:      0.01861358806490898      dense.py:568
                Validation loss:        0.01861358806490898                          
 
 
-               BCD step 10/10  FUGW loss:      0.018613653257489204     dense.py:568
+    [21:02:22] BCD step 10/10  FUGW loss:      0.018613653257489204     dense.py:568
                Validation loss:        0.018613653257489204                         
 
 
@@ -485,9 +485,9 @@ between source and target
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 6.244 seconds)
+   **Total running time of the script:** (0 minutes 6.441 seconds)
 
-**Estimated memory usage:**  79 MB
+**Estimated memory usage:**  131 MB
 
 
 .. _sphx_glr_download_auto_examples_00_basics_plot_1_dense.py:
@@ -504,6 +504,10 @@ between source and target
 
       :download:`Download Python source code: plot_1_dense.py <plot_1_dense.py>`
 
+    .. container:: sphx-glr-download sphx-glr-download-zip
+
+      :download:`Download zipped: plot_1_dense.zip <plot_1_dense.zip>`
+
 
 .. only:: html
 

diff --git a/_sources/auto_examples/00_basics/plot_2_1_lmds.rst.txt b/_sources/auto_examples/00_basics/plot_2_1_lmds.rst.txt
@@ -258,9 +258,9 @@ is well approximated by the kernel matrix derived from the embeddings:
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 8.750 seconds)
+   **Total running time of the script:** (0 minutes 9.027 seconds)
 
-**Estimated memory usage:**  82 MB
+**Estimated memory usage:**  134 MB
 
 
 .. _sphx_glr_download_auto_examples_00_basics_plot_2_1_lmds.py:
@@ -277,6 +277,10 @@ is well approximated by the kernel matrix derived from the embeddings:
 
       :download:`Download Python source code: plot_2_1_lmds.py <plot_2_1_lmds.py>`
 
+    .. container:: sphx-glr-download sphx-glr-download-zip
+
+      :download:`Download zipped: plot_2_1_lmds.zip <plot_2_1_lmds.zip>`
+
 
 .. only:: html
 

diff --git a/_sources/auto_examples/00_basics/plot_2_2_coarse_to_fine.rst.txt b/_sources/auto_examples/00_basics/plot_2_2_coarse_to_fine.rst.txt
@@ -91,7 +91,7 @@ Let us generate random training data for the source and target distributions
 
  .. code-block:: none
 
-    /usr/local/lib/python3.8/site-packages/torch/distributions/wishart.py:271: UserWarning:
+    /usr/local/lib/python3.8/site-packages/torch/distributions/wishart.py:272: UserWarning:
 
     Singular sample detected.
 
@@ -246,9 +246,9 @@ distributions you are trying to align.
 
  .. code-block:: none
 
-    [05:21:51] Validation data for feature maps is not provided. Using  dense.py:202
+    [21:02:34] Validation data for feature maps is not provided. Using  dense.py:199
                training data instead.                                               
-               Validation data for anatomical kernels is not provided.  dense.py:229
+               Validation data for anatomical kernels is not provided.  dense.py:226
                Using training data instead.                                         
 
 
@@ -264,70 +264,70 @@ distributions you are trying to align.
                Validation loss:        0.018442563712596893                         
 
 
-               BCD step 4/10   FUGW loss:      0.01579628325998783      dense.py:568
+    [21:02:35] BCD step 4/10   FUGW loss:      0.01579628325998783      dense.py:568
                Validation loss:        0.01579628325998783                          
 
 
-    [05:21:52] BCD step 5/10   FUGW loss:      0.015153789892792702     dense.py:568
+               BCD step 5/10   FUGW loss:      0.015153789892792702     dense.py:568
                Validation loss:        0.015153789892792702                         
 
 
                BCD step 6/10   FUGW loss:      0.014875941909849644     dense.py:568
                Validation loss:        0.014875941909849644                         
 
 
-               BCD step 7/10   FUGW loss:      0.014715257100760937     dense.py:568
+    [21:02:36] BCD step 7/10   FUGW loss:      0.014715257100760937     dense.py:568
                Validation loss:        0.014715257100760937                         
 
 
-    [05:21:53] BCD step 8/10   FUGW loss:      0.014592343010008335     dense.py:568
+               BCD step 8/10   FUGW loss:      0.014592343010008335     dense.py:568
                Validation loss:        0.014592343010008335                         
 
 
                BCD step 9/10   FUGW loss:      0.014477252028882504     dense.py:568
                Validation loss:        0.014477252028882504                         
 
 
-               BCD step 10/10  FUGW loss:      0.01438036747276783      dense.py:568
+    [21:02:37] BCD step 10/10  FUGW loss:      0.01438036747276783      dense.py:568
                Validation loss:        0.01438036747276783                          
-    /github/workspace/src/fugw/scripts/coarse_to_fine.py:474: UserWarning:
+    /github/workspace/src/fugw/scripts/coarse_to_fine.py:477: UserWarning:
 
     Sparse CSR tensor support is in beta state. If you miss a functionality in the sparse tensor support, please submit a feature request to https://github.com/pytorch/pytorch/issues. (Triggered internally at ../aten/src/ATen/SparseCsrTensorImpl.cpp:53.)
 
-               Validation data for feature maps is not provided. Using sparse.py:213
+               Validation data for feature maps is not provided. Using sparse.py:209
                training data instead.                                               
-               Validation data for anatomical kernels is not provided. sparse.py:257
+               Validation data for anatomical kernels is not provided. sparse.py:253
                Using training data instead.                                         
 
 
-    [05:21:56] BCD step 1/10   FUGW loss:      0.02047727443277836     sparse.py:660
+    [21:02:39] BCD step 1/10   FUGW loss:      0.02047727443277836     sparse.py:660
 
 
-    [05:21:58] BCD step 2/10   FUGW loss:      0.014399909414350986    sparse.py:660
+    [21:02:41] BCD step 2/10   FUGW loss:      0.014399909414350986    sparse.py:660
 
 
-    [05:22:00] BCD step 3/10   FUGW loss:      0.012644448317587376    sparse.py:660
+    [21:02:44] BCD step 3/10   FUGW loss:      0.012644448317587376    sparse.py:660
 
 
-    [05:22:02] BCD step 4/10   FUGW loss:      0.011991660110652447    sparse.py:660
+    [21:02:46] BCD step 4/10   FUGW loss:      0.011991660110652447    sparse.py:660
 
 
-    [05:22:04] BCD step 5/10   FUGW loss:      0.011676586233079433    sparse.py:660
+    [21:02:48] BCD step 5/10   FUGW loss:      0.011676586233079433    sparse.py:660
 
 
-    [05:22:07] BCD step 6/10   FUGW loss:      0.011500303633511066    sparse.py:660
+    [21:02:51] BCD step 6/10   FUGW loss:      0.011500303633511066    sparse.py:660
 
 
-    [05:22:09] BCD step 7/10   FUGW loss:      0.011388624086976051    sparse.py:660
+    [21:02:53] BCD step 7/10   FUGW loss:      0.011388624086976051    sparse.py:660
 
 
-    [05:22:11] BCD step 8/10   FUGW loss:      0.011310438625514507    sparse.py:660
+    [21:02:56] BCD step 8/10   FUGW loss:      0.011310438625514507    sparse.py:660
 
 
-    [05:22:14] BCD step 9/10   FUGW loss:      0.011251626536250114    sparse.py:660
+    [21:02:58] BCD step 9/10   FUGW loss:      0.011251626536250114    sparse.py:660
 
 
-    [05:22:16] BCD step 10/10  FUGW loss:      0.011205767281353474    sparse.py:660
+    [21:03:01] BCD step 10/10  FUGW loss:      0.011205767281353474    sparse.py:660
 
 
 
@@ -619,9 +619,9 @@ between source and target
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 33.021 seconds)
+   **Total running time of the script:** (0 minutes 34.834 seconds)
 
-**Estimated memory usage:**  146 MB
+**Estimated memory usage:**  212 MB
 
 
 .. _sphx_glr_download_auto_examples_00_basics_plot_2_2_coarse_to_fine.py:
@@ -638,6 +638,10 @@ between source and target
 
       :download:`Download Python source code: plot_2_2_coarse_to_fine.py <plot_2_2_coarse_to_fine.py>`
 
+    .. container:: sphx-glr-download sphx-glr-download-zip
+
+      :download:`Download zipped: plot_2_2_coarse_to_fine.zip <plot_2_2_coarse_to_fine.zip>`
+
 
 .. only:: html
 

diff --git a/_sources/auto_examples/00_basics/sg_execution_times.rst.txt b/_sources/auto_examples/00_basics/sg_execution_times.rst.txt
@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:48.015** total execution time for 3 files **from auto_examples/00_basics**:
+**00:50.301** total execution time for 3 files **from auto_examples/00_basics**:
 
 .. container::
 
@@ -33,11 +33,11 @@ Computation times
      - Time
      - Mem (MB)
    * - :ref:`sphx_glr_auto_examples_00_basics_plot_2_2_coarse_to_fine.py` (``plot_2_2_coarse_to_fine.py``)
-     - 00:33.021
-     - 146.3
+     - 00:34.834
+     - 212.0
    * - :ref:`sphx_glr_auto_examples_00_basics_plot_2_1_lmds.py` (``plot_2_1_lmds.py``)
-     - 00:08.750
-     - 81.6
+     - 00:09.026
+     - 133.5
    * - :ref:`sphx_glr_auto_examples_00_basics_plot_1_dense.py` (``plot_1_dense.py``)
-     - 00:06.244
-     - 79.2
+     - 00:06.441
+     - 131.5
diff --git a/_sources/auto_examples/01_brain_alignment/index.rst.txt b/_sources/auto_examples/01_brain_alignment/index.rst.txt
@@ -17,7 +17,7 @@ This subsection gives an exhaustive overview of brain alignment pipelines which
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we align 2 low-resolution left hemispheres using 4 fMRI feature maps (z-score ...">
+    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we align 2 low-resolution left hemispheres using 4 fMRI feature maps (z-score contrast maps).">
 
 .. only:: html
 
@@ -34,7 +34,7 @@ This subsection gives an exhaustive overview of brain alignment pipelines which
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we show how to use this package to align 2 high-resolution left hemispheres us...">
+    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we show how to use this package to align 2 high-resolution left hemispheres using fMRI feature maps (z-score contrast maps). Note that, since we want this example to run on CPU, we stick to rather low-resolution meshes (around 10k vertices per hemisphere) but that this package can easily scale to resolutions above 150k vertices per hemisphere. In this case, with appropriate hyper-parameters and solver parameters, it takes less than 10 minutes to compute a mapping between 2 such distributions using a V100 Nvidia GPU.">
 
 .. only:: html
 
@@ -51,7 +51,7 @@ This subsection gives an exhaustive overview of brain alignment pipelines which
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we align 2 low-resolution brain volumes using 4 fMRI feature maps (z-score con...">
+    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we align 2 low-resolution brain volumes using 4 fMRI feature maps (z-score contrast maps).">
 
 .. only:: html
 
@@ -68,7 +68,7 @@ This subsection gives an exhaustive overview of brain alignment pipelines which
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we align 2 low-resolution brain volumes using 4 fMRI feature maps (z-score con...">
+    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we align 2 low-resolution brain volumes using 4 fMRI feature maps (z-score contrast maps).">
 
 .. only:: html