start tutorial

Author: gpiantoni

.gitignore

@@ -4,3 +4,4 @@ htmlcov/
 
 tests/analysis/generated/
 tests/analysis/output/
+tests/tutorial/output/

docs/gridgen/bin/parameters.html

@@ -511,8 +511,7 @@ <h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
     return parameters
 
 
-if __name__ == &#39;__main__&#39;:
-
+def main():
     md = [
         &#39;## Parameters&#39;,
         &#39;&#39;,
@@ -525,7 +524,11 @@ <h1 class="title">Module <code>gridgen.bin.parameters</code></h1>
     parameters_file = PKG_PATH / &#39;docs&#39; / &#39;parameters.md&#39;
 
     with parameters_file.open(&#39;w&#39;) as f:
-        f.write(&#39;\n&#39;.join(md))</code></pre>
+        f.write(&#39;\n&#39;.join(md))
+
+
+if __name__ == &#39;__main__&#39;:
+    main()</code></pre>
 </details>
 </section>
 <section>
@@ -642,6 +645,31 @@ <h2 id="returns">Returns</h2>
     return out</code></pre>
 </details>
 </dd>
+<dt id="gridgen.bin.parameters.main"><code class="name flex">
+<span>def <span class="ident">main</span></span>(<span>)</span>
+</code></dt>
+<dd>
+<div class="desc"></div>
+<details class="source">
+<summary>
+<span>Expand source code</span>
+</summary>
+<pre><code class="python">def main():
+    md = [
+        &#39;## Parameters&#39;,
+        &#39;&#39;,
+        &#39;Parameters should be saved as a `json` file.&#39;,
+        &#39;You can pass the parameters with the command `gridgen parameters.json func` where `func` is one of the possible functions (`grid2d`, `ecog`, `fit` etc).&#39;,
+        &#39;You can also use the command `gridgen parameters.json parameters` to generate a template `parameters.json` file.&#39;,
+        &#39;&#39;,
+        ]
+    md = md + help_template(TEMPLATE)
+    parameters_file = PKG_PATH / &#39;docs&#39; / &#39;parameters.md&#39;
+
+    with parameters_file.open(&#39;w&#39;) as f:
+        f.write(&#39;\n&#39;.join(md))</code></pre>
+</details>
+</dd>
 <dt id="gridgen.bin.parameters.parse_parameters"><code class="name flex">
 <span>def <span class="ident">parse_parameters</span></span>(<span>parameters, function, output_dir=None)</span>
 </code></dt>
@@ -788,9 +816,10 @@ <h1>Index</h1>
 </ul>
 </li>
 <li><h3><a href="#header-functions">Functions</a></h3>
-<ul class="">
+<ul class="two-column">
 <li><code><a title="gridgen.bin.parameters.convert_to_path" href="#gridgen.bin.parameters.convert_to_path">convert_to_path</a></code></li>
 <li><code><a title="gridgen.bin.parameters.help_template" href="#gridgen.bin.parameters.help_template">help_template</a></code></li>
+<li><code><a title="gridgen.bin.parameters.main" href="#gridgen.bin.parameters.main">main</a></code></li>
 <li><code><a title="gridgen.bin.parameters.parse_parameters" href="#gridgen.bin.parameters.parse_parameters">parse_parameters</a></code></li>
 <li><code><a title="gridgen.bin.parameters.prepare_template" href="#gridgen.bin.parameters.prepare_template">prepare_template</a></code></li>
 <li><code><a title="gridgen.bin.parameters.validate_template" href="#gridgen.bin.parameters.validate_template">validate_template</a></code></li>

docs/img/grid2d.png

@@ -0,0 +1,63 @@
+# Tutorial
+**gridgen** consists of some functions (commands) that allow you to:
+  - create the 2d grid (`grid2d`)
+  - compute the power spectral density (PSD) at each electrode (`ecog`)
+  - create the 3d grid (`grid3d`)
+  - fit the 3d grid onto the surface, by fitting the ecog values (`fit`)
+  - compare the results (`matlab`)
+
+In addition, you need to pass the parameters for your analysis.
+Parameters are structured in a json format.
+A description of the parameters can be found in [Parameters](parameters.md).
+
+You can also generate an template `json` file with all the necessary parameters with the command:
+
+```bash
+gridgen parameters.json parameters
+```
+
+Then you need to populate the values in parameters.
+Note that each command requires different set of parameters. f.e.
+
+```bash 
+gridgen parameters.json grid2d
+```
+
+only requires the parameter `grid2d` while the command:
+
+```bash 
+gridgen parameters.json grid3d
+```
+
+requires the parameters `grid3d`, `mri`, `initial` (and possibly `morphology` and `functional`).
+This information is described in [Parameters](parameters.md) and `gridgen` will throw an error if the parametes are not complete.
+
+## grid2d
+The first step is to create a 2d grid.
+This grid will only give us the electrode labels and no additional information (so, no information about electrode spacing).
+You can create a grid with the parameters (called `parameters.json`):
+
+```json
+{
+  "grid2d": {
+    "n_rows": 4,
+    "n_columns": 3,
+    "direction": "TBLR",
+    "chan_pattern": "chan{}"
+    }
+}
+```
+
+By convention, the wires are at the bottom. 
+`chan_pattern` is used to generate the channel labels. 
+`chan{}` will create `chan1`, `chan2`, `chan3` and `chan{:03d}` will create `chan001`, `chan002`, `chan003` (see [Python string formatting](https://docs.python.org/3/library/string.html#formatspec)).
+
+```bash 
+gridgen parameters.json grid2d
+```
+
+which will create a file called `grid2d_labels.tsv` like this:
+
+![grid2d_labels.tsv](img/grid2d.png)
+
+

docs/tutorial.md

@@ -485,8 +485,7 @@ def parse_parameters(parameters, function, output_dir=None):
     return parameters
 
 
-if __name__ == '__main__':
-
+def main():
     md = [
         '## Parameters',
         '',
@@ -500,3 +499,7 @@ def parse_parameters(parameters, function, output_dir=None):
 
     with parameters_file.open('w') as f:
         f.write('\n'.join(md))
+
+
+if __name__ == '__main__':
+    main()

gridgen/bin/parameters.py

@@ -4,6 +4,7 @@
 TEST_PATH = Path(__file__).resolve().parent
 ANALYSIS_PATH = TEST_PATH / 'analysis'
 DATA_PATH = ANALYSIS_PATH / 'data'
+TUTORIAL_PATH = TEST_PATH / 'tutorial'
 
 SMOOTH_FILE = DATA_PATH / 'lh_smooth.pial'
 PIAL_FILE = DATA_PATH / 'lh.pial'

tests/paths.py

@@ -1,13 +1,15 @@
 from gridgen.bin.command import main, _JSONEncoder_path
 from gridgen.bin.parameters import REQUIRED
+from gridgen.bin.parameters import main as main_parameters
 from json import dump
+
 from .paths import OUTPUT_PATH, ECOG_FILE, T1_FILE, SMOOTH_FILE, PIAL_FILE, FUNC_FILE
 
 EXAMPLES = {
     "grid2d": {
         "n_rows": 3,
         "n_columns": 2,
-        "direction": "TBLR",
+        "direction": "RLBT",
         "chan_pattern": "chan{}"
         },
     "ecog": {
@@ -67,3 +69,7 @@ def test_cmd():
             dump(params, f, indent=2, cls=_JSONEncoder_path)
 
         main([str(param_json), cmd])
+
+
+def test_help():
+    main_parameters()

tests/test_command.py

@@ -0,0 +1,14 @@
+from .paths import TUTORIAL_PATH
+from gridgen.bin.command import main
+
+
+output = str(TUTORIAL_PATH / 'output')
+
+def test_grid2d():
+    param_json = TUTORIAL_PATH / 'grid2d.json'
+    main([
+        str(param_json),
+        '--output_dir',
+        str(output),
+        'grid2d'
+        ])

tests/test_tutorial.py

@@ -0,0 +1,8 @@
+{
+  "grid2d": {
+    "n_rows": 4,
+    "n_columns": 3,
+    "direction": "TBLR",
+    "chan_pattern": "chan{}"
+    }
+}