documentation improvements

yjmantilla · Aug 23, 2021 · 6625bea · 6625bea
1 parent c6dde77
commit 6625bea
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 95 deletions.
diff --git a/README.rst b/README.rst
@@ -19,10 +19,19 @@ sovabids
 
 * sovabids is a python package for automating eeg2bids conversion. 
 
-* sovabids can be used through: 
-   a. its python API
-   b. its CLI entry points.
-   c. its JSON-RPC entry points (needs a server running the backend).
+* sovabids can be used through (click to see the examples): 
+   a. `its python API <https://sovabids.readthedocs.io/en/latest/auto_examples/lemon_example.html#using-the-python-api>`_ 
+   b. `its CLI entry points <https://sovabids.readthedocs.io/en/latest/auto_examples/lemon_example.html#using-the-cli-tool>`_
+   c. `its JSON-RPC entry points (needs a server running the backend) <https://sovabids.readthedocs.io/en/latest/auto_examples/rpc_example.html>`_
+   d. `its minimal web-app GUI <https://sovabids.readthedocs.io/en/latest/auto_examples/gui_example.html>`_
+
+.. note::
+
+   The advantage of the JSON-RPC way is that it can be used from other programming languages. 
+
+   Limitation:
+
+   Do notice that at the moment the files have to be on the same computer that runs the server.
 
 .. warning::
 

diff --git a/docs/source/rules_schema.rst b/docs/source/rules_schema.rst
@@ -296,98 +296,8 @@ path_analysis
 
 Is used to infer information from the path. Any of the fields from the previous objects are supported as long they consist of a single simple value (anything that is a single number or string). The pattern is applied to every file that has the *eeg_extension* mentioned before.
 
-There are 3 ways to do the *path_analysis*, by *paired example*, by a *regex pattern* , or  by a *placeholder pattern*.
+There are 3 ways to do the *path_analysis*, by a *regex pattern* , by a *placeholder pattern*, or by *paired example*.
 
-paired example
-""""""""""""""
-
-This is the easiest way to use the *path_analysis* functionality. The idea is to provide a *(source,target)* example.
-
-The *source* would be the filepath of any of the files you want to convert.
-
-The *target* would be the filepath of where you expect the file to go following the bids standard.
-
-The schema we want to arrive at is :
-
-.. code-block:: yaml
-    
-    non-bids:
-        path_analysis:
-            source: source_path example
-            target: target_path example
-
-This will be explained better with an example, suppose this is the source filepath example you want to use: 
-
-.. code-block:: text
-
-    data/lemon/V001/resting/010002.vhdr
-
-You fabricate by yourself where do you want it to go following the bids standard:
-
-.. code-block:: text
-
-    data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-resting_eeg.vhdr
-
-Sovabids will try to infer the pattern from this example.
-
-So your *path_analysis* object is wrote in the *Rules File* as:
-
-.. code-block:: yaml
-    
-    non-bids:
-        path_analysis:
-            source : data/lemon/V001/resting/010002.vhdr
-            target : data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-resting_eeg.vhdr
-
-.. warning::
-
-    Notice that we expect you to input a valid bids file as a target. That means the target you provide does follow the bids standard.
-
-.. warning::
-
-    Use the forward-slash as the path separator (``/``) in your path strings regardless of the symbol your OS uses. This is to avoid problems when reading strings. This applies to all of the modes of *path_analysis* :
-    paired example, regex patterns and placeholder patterns.
-
-.. warning::
-
-    Examples and ambiguity:
-
-
-    Notice the provided (source,target) pair is not ambiguous. This means that the values for each bids entity only appear once in the provided strings.
-
-    An example of an ambiguous pair would be:
-
-    .. code-block:: text
-
-        source='data/lemon/session001/taskT001/010002.vhdr'
-        target='data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-T001_eeg.vhdr'
-
-    Here session '001' is contained inside task 'T001' so sovabids has trouble finding the pattern.
-
-    sovabids developers are planning to include the possibility of giving a list of (source,target) pairs to resolve ambiguity automatically.
-    But for now, this is not yet included.
-
-    Do note that the (source,target) example pair is fictional, you can give a non-ambiguous example you imagined by yourself. It does not have to be a real file.
-
-    Following the previous ambiguous example:
-
-    .. code-block:: text
-
-        source='data/lemon/session001/taskT001/010002.vhdr'
-        target='data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-T001_eeg.vhdr'
-
-
-    You could give the following fictional non-ambiguous example: 
-
-    .. code-block:: text
-
-        source='data/lemon/session009/taskT001/010002.vhdr'
-        target='data_bids/sub-010002/ses-009/eeg/sub-010002_ses-009_task-T001_eeg.vhdr'
-    
-    Where since 009 is not found in any other part of the string, it is non ambiguous.
-
-    The session 009 may not actually exist on the dataset but for our purposes that does not matter.
-    We just care about finding a naming pattern here.
 
 regex pattern
 """""""""""""
@@ -457,6 +367,11 @@ So your *path_analysis* object is wrote in the *Rules File* as:
                 - entities.task
                 - entities.subject
 
+.. warning::
+
+    Use the forward-slash as the path separator (``/``) in your path strings regardless of the symbol your OS uses. This is to avoid problems when reading strings. This applies to all of the modes of *path_analysis* :
+    regex patterns, placeholder patterns and paired example.
+
 
 placeholder pattern
 """""""""""""""""""
@@ -553,6 +468,98 @@ What we need to write in the *Rules File* is then:
 
     It is advisable to include the folder just before the one that is of interest to you. This is so that the sofware is able to discriminate what is of interest in the first field. In this example we started from ``_data`` although in reality we are interested is in the next folder (``lemon``). If we do ``%dataset_description.Name%/ses-%entities.session%/%entities.task%/sub-%entities.subject%.vhdr`` (this is the same pattern but without the ``_data`` folder), the software will have trouble distinguishing what is of interest at the start of the string. This warning applies both to regex and placeholder patterns.
 
+
+paired example (EXPERIMENTAL)
+""""""""""""""""""""""""""""""
+
+.. warning::
+
+    This feature is experimental, is not well tested so it may not run correctly.
+
+This is the easiest way to use the *path_analysis* functionality. The idea is to provide a *(source,target)* example.
+
+The *source* would be the filepath of any of the files you want to convert.
+
+The *target* would be the filepath of where you expect the file to go following the bids standard.
+
+The schema we want to arrive at is :
+
+.. code-block:: yaml
+    
+    non-bids:
+        path_analysis:
+            source: source_path example
+            target: target_path example
+
+This will be explained better with an example, suppose this is the source filepath example you want to use: 
+
+.. code-block:: text
+
+    data/lemon/V001/resting/010002.vhdr
+
+You fabricate by yourself where do you want it to go following the bids standard:
+
+.. code-block:: text
+
+    data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-resting_eeg.vhdr
+
+Sovabids will try to infer the pattern from this example.
+
+So your *path_analysis* object is wrote in the *Rules File* as:
+
+.. code-block:: yaml
+    
+    non-bids:
+        path_analysis:
+            source : data/lemon/V001/resting/010002.vhdr
+            target : data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-resting_eeg.vhdr
+
+.. warning::
+
+    Notice that we expect you to input a valid bids file as a target. That means the target you provide does follow the bids standard.
+
+
+.. warning::
+
+    Examples and ambiguity:
+
+
+    Notice the provided (source,target) pair is not ambiguous. This means that the values for each bids entity only appear once in the provided strings.
+
+    An example of an ambiguous pair would be:
+
+    .. code-block:: text
+
+        source='data/lemon/session001/taskT001/010002.vhdr'
+        target='data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-T001_eeg.vhdr'
+
+    Here session '001' is contained inside task 'T001' so sovabids has trouble finding the pattern.
+
+    sovabids developers are planning to include the possibility of giving a list of (source,target) pairs to resolve ambiguity automatically.
+    But for now, this is not yet included.
+
+    Do note that the (source,target) example pair is fictional, you can give a non-ambiguous example you imagined by yourself. It does not have to be a real file.
+
+    Following the previous ambiguous example:
+
+    .. code-block:: text
+
+        source='data/lemon/session001/taskT001/010002.vhdr'
+        target='data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-T001_eeg.vhdr'
+
+
+    You could give the following fictional non-ambiguous example: 
+
+    .. code-block:: text
+
+        source='data/lemon/session009/taskT001/010002.vhdr'
+        target='data_bids/sub-010002/ses-009/eeg/sub-010002_ses-009_task-T001_eeg.vhdr'
+    
+    Where since 009 is not found in any other part of the string, it is non ambiguous.
+
+    The session 009 may not actually exist on the dataset but for our purposes that does not matter.
+    We just care about finding a naming pattern here.
+
 code_execution
 ^^^^^^^^^^^^^^
 

diff --git a/front/app/templates/ready.html b/front/app/templates/ready.html
@@ -5,4 +5,5 @@
 {% block content %}
 <h1 id="sovabids">YOUR FILES ARE READY!</h1>
 <a href="/download">Download files</a>
+<p>NOTICE: For linux-based systems the downloaded zip will have the files stored under a nested subdirectory structure.</p>
 {% endblock %}