From a632e69213b79acb85f483abe7a06e603be4fbaf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Henrik=20tom=20W=C3=B6rden?= <h.tomwoerden@indiscale.com>
Date: Mon, 20 Feb 2023 20:07:13 +0100
Subject: [PATCH] enhanced doc

---
 README.md                | 27 +++++++++++++++++++++++++++
 README_SETUP.md          |  7 +++++--
 src/bids-cfood/cfood.yml |  2 +-
 3 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index bfafa68..83f42ce 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,33 @@ that can read folder structures that comply with the
 Please read the [README_SETUP.md](README_SETUP.md) for instructions on how to
 setup this code.
 
+## Design
+The BIDS Standard defines rules for how data is stored in files and how those
+(and directories) must be named. Those rules can be checked with the
+`bids-validator`. The current implementation of this cfood and the corresponding
+[converter](https://gitlab.indiscale.com/caosdb/src/crawler-converters/bids-converter)
+does the following:
+- the `dataset_description.json` is parsed and translated to CaosDB Entities
+- the key value pairs of folder and file names (e.g. "sub-<sub-label>") are
+  parsed and the stored in appropriate Records
+- the contents of measurement folders such as 'eeg', 'func' or 'anat' are
+  assigned to DataAcquisition Records. Each Record shall reference the full
+  information for the acquisition. Thus files are typically grouped according
+  to their values of the 'acq', 'run', and possibly 'task' keys. If files
+  correspond to multiple acquisitions (the filename is missing some key value
+  pairs), then those files are referenced by all corresponding Records. This
+  grouping is done by the BIDS<datatype>DirConverter classes of the
+  bids-converter.
+- Based on the suffix of files parents for files are selected.
+- The data model references the corresponding BIDS documentation in the
+  description where appropriate.
+- The session folder may be omitted in BIDS. The crawler always creates at least
+  one session. See BIDSSubjectDirConverter classes of the bids-converter.
+
+
+## Notes
+- Currently the folders `sourcedata` and `derivates` are being ignored.
+- Currently parametric maps are ignored (ANAT)
 
 ## Further Reading
 
diff --git a/README_SETUP.md b/README_SETUP.md
index 222dcee..f822827 100644
--- a/README_SETUP.md
+++ b/README_SETUP.md
@@ -14,13 +14,17 @@ After you started a server that mounts the test data (possibly use `test-profile
 you can run `pytest `integrationtests`.
 
 ### Manual Tests
-You can crawl examples from the `bids-examples` submodule:
+You can crawl examples from the `bids-examples` submodule. The follwing shows it for the `eeg_matchingpennies` data set:
 ```sh
+# all commands are assumed to be run from the bids-cfood folder
 # add the model
 python -m caosadvancedtools.models.parser src/bids-cfood/model.yml --sync
 # insert files
 python -m caosadvancedtools.loadFiles  -p /examples /opt/caosdb/mnt/extroot/examples/eeg_matchingpennies
+# run crawler
+caosdb-crawler --debug -s update -i src/bids-cfood/identifiables.yml --remove-prefix /bids-examples --add-prefix /examples src/bids-cfood/cfood.yml   bids-examples/eeg_matchingpennies
 ```
+
 ## Usage
 You will need to copy (parts of) the cfood definition `./src/bids-cfood/cfood.yml`
 into your cfood.
@@ -28,4 +32,3 @@ into your cfood.
 
 
 
-sourcedata and derivates are being ignored.
diff --git a/src/bids-cfood/cfood.yml b/src/bids-cfood/cfood.yml
index 75c963e..a816455 100644
--- a/src/bids-cfood/cfood.yml
+++ b/src/bids-cfood/cfood.yml
@@ -531,7 +531,7 @@ project_level:
                         parent: "ElectrodeFile"
                       - suffix: "photo"
                         parent: "PhotoFile"
-            fmap: 
+            fmap:
               type: BIDSFMAPDirectory
               match: ^(?P<datatype>fmap)$
               subtree:
-- 
GitLab