Skip to content

Commit c00bfd1

Browse files
gpiantonigpiantoni
committed
improve readme
1 parent a3ff868 commit c00bfd1

File tree

13 files changed

+539
-93
lines changed

13 files changed

+539
-93
lines changed

‎docs/README.md

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,33 @@
33
[![Python package](https://github.com/gpiantoni/gridgen/actions/workflows/python.yml/badge.svg)](https://github.com/gpiantoni/gridgen/actions/workflows/python.yml)
44
[![codecov](https://codecov.io/gh/gpiantoni/gridgen/branch/master/graph/badge.svg?token=6XL61XF65J)](https://codecov.io/gh/gpiantoni/gridgen)
55

6-
See [documentation](https://gpiantoni.github.io/gridgen)
6+
See [documentation](https://gpiantoni.github.io/gridgen) for instructions on how to install or follow the [tutorial](https://gpiantoni.github.io/gridgen/tutorial.html).
7+
8+
## Quick Start
9+
This package will allow you to create 3D meshes onto the convex hull (dura surface):
10+
11+
![grid3d](img/grid3d_1.png)
12+
13+
You can rotate the grid:
14+
15+
![grid3d rotation](img/grid3d_3.png)
16+
17+
or change the inter-electrode distance:
18+
19+
![grid3d interelec distance](img/grid3d_4.png)
20+
21+
You can also use the information from the pial surface (mesh) to compute the distance to the electrodes, in different ways:
22+
23+
![grid3d morphology](img/grid3d_2_morpho2d.png)
24+
![grid3d morphology](img/grid3d_2_morpho3d.png)
25+
26+
or to compute the spatial correlation between electrodes and voxels from an fMRI:
27+
28+
![grid3d angiogram](img/grid3d_6_scale.png)
29+
![grid3d angiogram](img/grid3d_6.png)
30+
31+
Finally, this script will allow you to fit the ECoG values onto the most likely area of the brain.
32+
33+
## References
34+
- [Piantoni, G et al. *"Size of the spatial correlation between ECoG and fMRI activity."* *NeuroImage* 242(2021): 118459](https://doi.org/10.1016/j.neuroimage.2021.118459)
35+
- [Branco, MP et al. *"GridLoc: An automatic and unsupervised localization method for high-density ECoG grids."* *NeuroImage* 179(2018): 225-234](https://doi.org/10.1016/j.neuroimage.2018.06.050

‎docs/gridgen/bin/index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ <h2 class="section-title" id="header-submodules">Sub-modules</h2>
3737
</dd>
3838
<dt><code class="name"><a title="gridgen.bin.parameters" href="parameters.html">gridgen.bin.parameters</a></code></dt>
3939
<dd>
40-
<div class="desc"></div>
40+
<div class="desc"><p>Specify the parameters for all the commands in gridgen</p></div>
4141
</dd>
4242
</dl>
4343
</section>

‎docs/gridgen/bin/parameters.html

Lines changed: 170 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
66
<meta name="generator" content="pdoc 0.8.1" />
77
<title>gridgen.bin.parameters API documentation</title>
8-
<meta name="description" content="" />
8+
<meta name="description" content="Specify the parameters for all the commands in gridgen" />
99
<link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.0/normalize.min.css' rel='stylesheet'>
1010
<link href='https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/8.0.0/sanitize.min.css' rel='stylesheet'>
1111
<link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet">
@@ -20,12 +20,14 @@
2020
<h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
2121
</header>
2222
<section id="section-intro">
23+
<p>Specify the parameters for all the commands in gridgen</p>
2324
<details class="source">
2425
<summary>
2526
<span>Expand source code</span>
2627
</summary>
2728
<pre><code class="python">#!/usr/bin/env python3
28-
29+
&#34;&#34;&#34;Specify the parameters for all the commands in gridgen
30+
&#34;&#34;&#34;
2931
from pathlib import Path
3032
from json import load
3133
from collections.abc import Iterable
@@ -211,13 +213,13 @@ <h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
211213
&#34;type&#34;: &#34;str&#34;,
212214
&#34;necessary&#34;: False,
213215
&#34;values&#34;: [&#39;gaussian&#39;, &#39;sphere&#39;, &#39;inverse&#39;],
214-
&#34;help&#34;: &#34;TODO&#34;,
216+
&#34;help&#34;: &#34;method to compute the value at each electrode. `sphere` is the sum of the voxels around the electrodes, within `kernel` distance. `gaussian` is the weighted average of the voxels around an electrode, weighted by a 3d gaussian kernel. With `inverse`, the weights are based on the inverse of the distance.&#34;,
215217
&#34;default&#34;: &#34;inverse&#34;,
216218
},
217219
&#34;kernel&#34;: {
218220
&#34;type&#34;: &#34;float&#34;,
219221
&#34;necessary&#34;: False,
220-
&#34;help&#34;: &#34;TODO&#34;,
222+
&#34;help&#34;: &#34;With method `sphere`, this is the size of the sphere. With method `gaussian`, this is the size of the sigma of the 3D weighting kernel. With method `inverse`, this is the exponent (1 -&gt; linear, 2 -&gt; quadratic).&#34;,
221223
&#34;default&#34;: 2,
222224
},
223225
},
@@ -355,6 +357,18 @@ <h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
355357

356358

357359
def prepare_template(temp):
360+
&#34;&#34;&#34;Prepare template by reading the TEMPLATE and converting it to markdown
361+
362+
Parameters
363+
----------
364+
temp : dict
365+
TEMPLATE (or its subfields)
366+
367+
Returns
368+
-------
369+
dict
370+
with default values and necessary
371+
&#34;&#34;&#34;
358372
out = {}
359373
for k, v in temp.items():
360374
if &#39;type&#39; in v:
@@ -379,6 +393,18 @@ <h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
379393

380394

381395
def help_template(temp):
396+
&#34;&#34;&#34;Prepare template by reading the TEMPLATE and converting it to markdown
397+
398+
Parameters
399+
----------
400+
temp : dict
401+
TEMPLATE (or its subfields)
402+
403+
Returns
404+
-------
405+
list of str
406+
dict converted to list, so that it can be exported to markdown
407+
&#34;&#34;&#34;
382408
modules = _invert_dict(REQUIRED)
383409

384410
out = []
@@ -426,6 +452,21 @@ <h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
426452

427453

428454
def validate_template(temp, d):
455+
&#34;&#34;&#34;Check whether the parameters passed in json file are in accordance with
456+
the template
457+
458+
Parameters
459+
----------
460+
temp : dict
461+
TEMPLATE of parameters
462+
d : dict
463+
actual parameters
464+
465+
Returns
466+
-------
467+
dict
468+
input dictionary, with checked values and added defaults if necessary
469+
&#34;&#34;&#34;
429470
out = {}
430471
for k, v in temp.items():
431472

@@ -476,6 +517,22 @@ <h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
476517

477518

478519
def parse_parameters(parameters, function, output_dir=None):
520+
&#34;&#34;&#34;Read the parameters file, for a specific command
521+
522+
Parameters
523+
----------
524+
parameters : str
525+
path to json file
526+
function : str
527+
one of the commands (grid2d, ecog, grid3d etc)
528+
output_dir : path
529+
path to use as output, if not specified in parameters
530+
531+
Returns
532+
-------
533+
dict
534+
complete parameters
535+
&#34;&#34;&#34;
479536
p_json = Path(parameters).resolve()
480537
with p_json.open() as f:
481538
parameters = load(f)
@@ -512,6 +569,7 @@ <h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
512569

513570

514571
def main():
572+
&#34;&#34;&#34;Simple function to create parameters.md&#34;&#34;&#34;
515573
md = [
516574
&#39;## Parameters&#39;,
517575
&#39;&#39;,
@@ -593,12 +651,34 @@ <h2 id="returns">Returns</h2>
593651
<span>def <span class="ident">help_template</span></span>(<span>temp)</span>
594652
</code></dt>
595653
<dd>
596-
<div class="desc"></div>
654+
<div class="desc"><p>Prepare template by reading the TEMPLATE and converting it to markdown</p>
655+
<h2 id="parameters">Parameters</h2>
656+
<dl>
657+
<dt><strong><code>temp</code></strong> :&ensp;<code>dict</code></dt>
658+
<dd>TEMPLATE (or its subfields)</dd>
659+
</dl>
660+
<h2 id="returns">Returns</h2>
661+
<dl>
662+
<dt><code>list</code> of <code>str</code></dt>
663+
<dd>dict converted to list, so that it can be exported to markdown</dd>
664+
</dl></div>
597665
<details class="source">
598666
<summary>
599667
<span>Expand source code</span>
600668
</summary>
601669
<pre><code class="python">def help_template(temp):
670+
&#34;&#34;&#34;Prepare template by reading the TEMPLATE and converting it to markdown
671+
672+
Parameters
673+
----------
674+
temp : dict
675+
TEMPLATE (or its subfields)
676+
677+
Returns
678+
-------
679+
list of str
680+
dict converted to list, so that it can be exported to markdown
681+
&#34;&#34;&#34;
602682
modules = _invert_dict(REQUIRED)
603683

604684
out = []
@@ -649,12 +729,13 @@ <h2 id="returns">Returns</h2>
649729
<span>def <span class="ident">main</span></span>(<span>)</span>
650730
</code></dt>
651731
<dd>
652-
<div class="desc"></div>
732+
<div class="desc"><p>Simple function to create parameters.md</p></div>
653733
<details class="source">
654734
<summary>
655735
<span>Expand source code</span>
656736
</summary>
657737
<pre><code class="python">def main():
738+
&#34;&#34;&#34;Simple function to create parameters.md&#34;&#34;&#34;
658739
md = [
659740
&#39;## Parameters&#39;,
660741
&#39;&#39;,
@@ -674,12 +755,42 @@ <h2 id="returns">Returns</h2>
674755
<span>def <span class="ident">parse_parameters</span></span>(<span>parameters, function, output_dir=None)</span>
675756
</code></dt>
676757
<dd>
677-
<div class="desc"></div>
758+
<div class="desc"><p>Read the parameters file, for a specific command</p>
759+
<h2 id="parameters">Parameters</h2>
760+
<dl>
761+
<dt><strong><code>parameters</code></strong> :&ensp;<code>str</code></dt>
762+
<dd>path to json file</dd>
763+
<dt><strong><code>function</code></strong> :&ensp;<code>str</code></dt>
764+
<dd>one of the commands (grid2d, ecog, grid3d etc)</dd>
765+
<dt><strong><code>output_dir</code></strong> :&ensp;<code>path</code></dt>
766+
<dd>path to use as output, if not specified in parameters</dd>
767+
</dl>
768+
<h2 id="returns">Returns</h2>
769+
<dl>
770+
<dt><code>dict</code></dt>
771+
<dd>complete parameters</dd>
772+
</dl></div>
678773
<details class="source">
679774
<summary>
680775
<span>Expand source code</span>
681776
</summary>
682777
<pre><code class="python">def parse_parameters(parameters, function, output_dir=None):
778+
&#34;&#34;&#34;Read the parameters file, for a specific command
779+
780+
Parameters
781+
----------
782+
parameters : str
783+
path to json file
784+
function : str
785+
one of the commands (grid2d, ecog, grid3d etc)
786+
output_dir : path
787+
path to use as output, if not specified in parameters
788+
789+
Returns
790+
-------
791+
dict
792+
complete parameters
793+
&#34;&#34;&#34;
683794
p_json = Path(parameters).resolve()
684795
with p_json.open() as f:
685796
parameters = load(f)
@@ -719,12 +830,34 @@ <h2 id="returns">Returns</h2>
719830
<span>def <span class="ident">prepare_template</span></span>(<span>temp)</span>
720831
</code></dt>
721832
<dd>
722-
<div class="desc"></div>
833+
<div class="desc"><p>Prepare template by reading the TEMPLATE and converting it to markdown</p>
834+
<h2 id="parameters">Parameters</h2>
835+
<dl>
836+
<dt><strong><code>temp</code></strong> :&ensp;<code>dict</code></dt>
837+
<dd>TEMPLATE (or its subfields)</dd>
838+
</dl>
839+
<h2 id="returns">Returns</h2>
840+
<dl>
841+
<dt><code>dict</code></dt>
842+
<dd>with default values and necessary</dd>
843+
</dl></div>
723844
<details class="source">
724845
<summary>
725846
<span>Expand source code</span>
726847
</summary>
727848
<pre><code class="python">def prepare_template(temp):
849+
&#34;&#34;&#34;Prepare template by reading the TEMPLATE and converting it to markdown
850+
851+
Parameters
852+
----------
853+
temp : dict
854+
TEMPLATE (or its subfields)
855+
856+
Returns
857+
-------
858+
dict
859+
with default values and necessary
860+
&#34;&#34;&#34;
728861
out = {}
729862
for k, v in temp.items():
730863
if &#39;type&#39; in v:
@@ -752,12 +885,40 @@ <h2 id="returns">Returns</h2>
752885
<span>def <span class="ident">validate_template</span></span>(<span>temp, d)</span>
753886
</code></dt>
754887
<dd>
755-
<div class="desc"></div>
888+
<div class="desc"><p>Check whether the parameters passed in json file are in accordance with
889+
the template</p>
890+
<h2 id="parameters">Parameters</h2>
891+
<dl>
892+
<dt><strong><code>temp</code></strong> :&ensp;<code>dict</code></dt>
893+
<dd>TEMPLATE of parameters</dd>
894+
<dt><strong><code>d</code></strong> :&ensp;<code>dict</code></dt>
895+
<dd>actual parameters</dd>
896+
</dl>
897+
<h2 id="returns">Returns</h2>
898+
<dl>
899+
<dt><code>dict</code></dt>
900+
<dd>input dictionary, with checked values and added defaults if necessary</dd>
901+
</dl></div>
756902
<details class="source">
757903
<summary>
758904
<span>Expand source code</span>
759905
</summary>
760906
<pre><code class="python">def validate_template(temp, d):
907+
&#34;&#34;&#34;Check whether the parameters passed in json file are in accordance with
908+
the template
909+
910+
Parameters
911+
----------
912+
temp : dict
913+
TEMPLATE of parameters
914+
d : dict
915+
actual parameters
916+
917+
Returns
918+
-------
919+
dict
920+
input dictionary, with checked values and added defaults if necessary
921+
&#34;&#34;&#34;
761922
out = {}
762923
for k, v in temp.items():
763924

0 commit comments

Comments
 (0)