General organization
The general workflow of this project is the following:
-
turning the recommendation guidelines into spreadsheets
-
turning the spreadsheets into a "schema" representation
-
using a "front-end" user-interface that will read those schema and serve a web-app to the user.
To execute that work, this project is organized around several "repositories":
-
the eCOBIDAS repository centralises most of the information and workflow to convert the guidelines into a checklist webapp,
-
the Reproschema user interface contains the "front-end" code of the user interface to render the checklist webapp,
-
the ReproSchema repository contains the formal "definition" of the terms used to describe the content of the checklist as a schema,
-
the repositories containing a) an instance of the user interface and b) a schema to serve a specific checklist :
-
the one for the MRI version based of the Neurovault metadata "checklist" hosted on the OHBM Github organization and that serves this checklist,
-
the one for the PET imaging version that serves this checklist,
-
-
the google drive where we work synchronously on the spreadsheets,
-
an associated zotero library to keep track of references related to this project,
-
a project on the open-science framework that allows to "connect" all those elements together in one place.
the eCOBIDAS repository
This repository hosts the workflow that will turn the reports published by the Committee on Best Practices in Data Analysis and Sharing (COBIDAS) of the organization for human brain mapping (OHBM) into a checklists for improving methods and results reporting in (f)MRI, (i)EEG, MEG.
By extension, this workflow can also be used on other types of guidelines (like the ones for PET imaging and eyetracking).
.
├── .github <-- continuous integration "scripts"
├── activities <-- deprecated: ignore this
├── communication <-- abstracts and presentations about the project
├── docs <-- content of the documentation
├── inputs <-- checklists spreadsheets as CSV files, boilerplate for method section generation
├── schema <-- deprecated: ignore this
├── schemas <-- where the schemas are kept locally
├── python <-- python package to convert the CSV spreadsheets into schemas
└── tests <-- python script to test that the schema files are valid JSON-LD
In the schemas folder you might find different folders some of them with the following names:
├── protocols <-- schema for the checklists putting together several "sections" together
├── activities <-- schema of the different "sections"of the checklistss with their items
└── response_options <-- contains the pre-set list of response options to some checklist items
Spreadsheet content and organization
The first step of the workflow involves taking the recommendation guidelines and converting that into a spreadsheet that contains all the items of the future checklist.
This step is by far the most labor intensive and has its dedicated page in the documentation
Converting the spreadsheet into a schema
Most of that is covered in the section on
how the checklist is rendered and in the
README in the python
folder.
How is the Reproschema organized
The first step of the workflow involves taking a spreadsheet that contains all the items of the checklist and turning that into a representation that can efficiently link the metadata about each item to the data imputed by the user. We are using the ReproSchema initiative from ReproNim to do this. Basically, it means turning your 'dumb' spreadsheet into an equivalent but 'smarter' representation of it: a bunch of hierarchically organized json files that link to each other.
On top of the inherent advantages of this schema representation:
-
its use simplifies the rendering of the checklist by using the reproschema-ui made for it,
-
this representation allows specification of user interface option that can simplify the user experience: it allows us to specify the conditions that will make certain items visible or not and thus will prevent users to be presented with items that are not relevant to them (e.g answer PET related when they have only run an fMRI study).
The reproschema is organized in a hierarchical manner with several levels, the main ones being
-
The lowest level is the
item level
where there is one question for each item with an expected format for the user interface: is this yes / no question (boolean), a multiple choice, a float or an integer... -
The second level is the
activity level
that contains a set of items. In the original repronim project this would constitute usually a questionnaire: like all the items of the Edinburgh handedness inventory would constitute one activity. In our case, we are using it to define to break a checklist into sub-sections of a method section like preprocessing, design, participants... -
The highest level is the
protocol level
that contains a set of activities. At the moment this level is under-used in our checklist but could be used to define activity sets for different use case: fMRI, MEEG, pre-registration...
If you want to know more about Reproschema, we suggest you have look at the documentation
We are also trying to extend the content of the documentation of the reproschema. You can keep track of this in this pull request and here on github