From 3a8aa0c62df8ef76afd1561408c78ceffba95de3 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Sun, 12 May 2024 12:37:55 -0400 Subject: [PATCH] [FIX] misc minor fixes to the documentation (#482) * add syntax highlighting where missing * move files in subfolders * rename files * update contributing info * format markdown * apply remark * fix links * fix file name * apply review suggestions * fix filenames in mkdocs.yml --- .gitignore | 7 +- .pre-commit-config.yaml | 1 + .remarkrc | 18 +++ README.md | 2 +- docs/41_create_new_protocol.md | 25 --- docs/43_create_new_assess.md | 105 ------------- ...{100_about_this_doc.md => CONTRIBUTING.md} | 13 +- docs/FAQ.md | 49 ++++++ docs/{98_FAQ.md => faq/semantic-web.md} | 87 +++------- docs/{99_glossary.md => glossary.md} | 0 docs/index.md | 18 +-- docs/{01_introduction.md => introduction.md} | 65 ++++---- ...ject_structure.md => project-structure.md} | 45 +++--- docs/{30_schema.md => schema.md} | 98 ++++++------ .../collecting-demographics-information.md} | 2 +- .../create-new-activity.md} | 65 ++++---- .../create-new-protocol.md} | 22 +-- .../tips-to-make-your-life-easier.md} | 9 +- .../translating-an-activity.md} | 2 +- .../using-reproschema.md} | 13 +- .../adopt-assessments.md} | 82 ++++++---- docs/user-guide/create-new-assess.md | 148 ++++++++++++++++++ docs/user-guide/create-new-protocol.md | 37 +++++ .../finalize-protocol.md} | 23 +-- .../setup-feedback.md} | 12 +- docs/{46_tools.md => user-guide/tools.md} | 15 +- makefile | 5 + mkdocs.yml | 36 ++--- npm-requirements.txt | 5 + scripts/editProperties.py | 2 +- 30 files changed, 568 insertions(+), 443 deletions(-) create mode 100644 .remarkrc delete mode 100644 docs/41_create_new_protocol.md delete mode 100644 docs/43_create_new_assess.md rename docs/{100_about_this_doc.md => CONTRIBUTING.md} (82%) create mode 100644 docs/FAQ.md rename docs/{98_FAQ.md => faq/semantic-web.md} (70%) rename docs/{99_glossary.md => glossary.md} (100%) rename docs/{01_introduction.md => introduction.md} (70%) rename docs/{20_project_structure.md => project-structure.md} (51%) rename docs/{30_schema.md => schema.md} (94%) rename docs/{55_collecting_demographics_information.md => tutorials/collecting-demographics-information.md} (99%) rename docs/{52_create_new_activity.md => tutorials/create-new-activity.md} (89%) rename docs/{51_create_new_protocol.md => tutorials/create-new-protocol.md} (91%) rename docs/{53_tips_to_make_your_life_easier.md => tutorials/tips-to-make-your-life-easier.md} (98%) rename docs/{54_translating_an_activity.md => tutorials/translating-an-activity.md} (99%) rename docs/{50_using_reproschema.md => tutorials/using-reproschema.md} (85%) rename docs/{42_adopt_assessments.md => user-guide/adopt-assessments.md} (58%) create mode 100644 docs/user-guide/create-new-assess.md create mode 100644 docs/user-guide/create-new-protocol.md rename docs/{45_finalize_protocol.md => user-guide/finalize-protocol.md} (50%) rename docs/{44_setup_feedback.md => user-guide/setup-feedback.md} (64%) rename docs/{46_tools.md => user-guide/tools.md} (73%) create mode 100644 makefile create mode 100644 npm-requirements.txt diff --git a/.gitignore b/.gitignore index beae22a618..3046e3a30c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,11 @@ .DS_Store -.idea/ activities/.DS_Store protocols/.DS_Store + +.idea/ + node_modules local_data + +package-lock.json +package.json diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f1ffa3edbe..7e38b9c78d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -10,6 +10,7 @@ repos: - id: check-json - id: check-ast - id: check-added-large-files + - id: check-merge-conflict - repo: https://github.com/psf/black rev: 24.3.0 hooks: diff --git a/.remarkrc b/.remarkrc new file mode 100644 index 0000000000..b0a518d8c2 --- /dev/null +++ b/.remarkrc @@ -0,0 +1,18 @@ +{ + "plugins": [ + "preset-lint-markdown-style-guide", + "preset-lint-recommended", + "remark-gfm", + ["lint-no-duplicate-headings", false], + ["lint-list-item-indent", "tab-size"], + ["lint-emphasis-marker", "consistent"], + ["lint-maximum-line-length", 500], + ["lint-maximum-heading-length", false], + ["lint-no-shortcut-reference-link", false], + ["remark-lint-unordered-list-marker-style", "-"], + ["lint-no-trailing-spaces"], + ["remark-lint-code-block-style", false], + ["lint-no-undefined-references", false], + ["remark-lint-heading-style", false] + ] +} diff --git a/README.md b/README.md index 535b1db922..c71c8692c5 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ following libraries via pip To make a new release: -``` +```bash python scripts/makeRelease.py python scripts/editProperties.py ``` diff --git a/docs/41_create_new_protocol.md b/docs/41_create_new_protocol.md deleted file mode 100644 index c40ca4c6ca..0000000000 --- a/docs/41_create_new_protocol.md +++ /dev/null @@ -1,25 +0,0 @@ -# Creating a Research Protocol Using Cookiecutter - -Ready for your first ReproSchema project?! We are going to use the [Reproschema Protocol Cookiecutter](https://github.com/ReproNim/reproschema-protocol-cookiecutter) to create a demo protocol. - -## Getting Started - -1. Prerequisite: Ensure you have Git and Cookiecutter installed on your system. If not, please refer to the installation guides for Git and Cookiecutter. -2. Generate Your Repository: Use the Reproschema Protocol Cookiecutter to create a new repository for your research protocol. Run the following command in your terminal: - -```bash -cookiecutter gh:ReproNim/reproschema-protocol-cookiecutter -``` - -3. Follow the prompts to customize your new protocol, more details see [here](https://github.com/ReproNim/reproschema-protocol-cookiecutter#step-1-generate-the-protocol-files) - -## Customizing Your Protocol - -Once you run the Cookiecutter command, you will be prompted to make choices for your protocol, ranging from 1-5. These choices generate corresponding activities in your repository. Here's what you can do with these activities: - -1. **Use as Templates:** The activities created based on your choices serve as templates. You can use these to understand the structure and elements within the activities folder. This is particularly useful if you're new to ReproSchema. By exploring these templates, you'll get a clearer picture of how activities are structured and what kind of information they contain. -2. **Delete and Start Fresh:** Alternatively, if you already have a clear idea of what your protocol needs, you can delete these generated activities. This allows you to start from scratch, creating activities that are tailored specifically to your research needs. - -The inclusion of activity choices aims to provide users with a practical understanding of how activities are structured within ReproSchema protocols. Whether you use these as a starting point or prefer to create your own from the ground up, these templates are there to guide you in structuring your research protocol effectively. - -We provide more detailed instructions for customizing your protocol in the following pages using [reproschema-demo-protocol](https://github.com/ReproNim/reproschema-demo-protocol) as an example. diff --git a/docs/43_create_new_assess.md b/docs/43_create_new_assess.md deleted file mode 100644 index c1fb2de30b..0000000000 --- a/docs/43_create_new_assess.md +++ /dev/null @@ -1,105 +0,0 @@ -# Creating New Assessments for Unique Research Needs - -This section provides the customized new assessments tailored to specific research needs. Our focus is on creating three distinct types of activities that are not readily available in the reproschema-library. These include: (1) clinical questions to gather clinical background information, (2) a speech task designed to collect audio data, and (3) an audio check to facilitate the speech task. - -For each of these new assessments, the folder structure within the repository will differ slightly from those directly adopted from the reproschema-library. Specifically, each activity has its own dedicated folder within the `activities` directory. For instance, the speech task resides in [`activities/4_speech`](https://github.com/ReproNim/reproschema-demo-protocol/tree/main/activities/4_speech). Within this folder, besides the primary schema file (e.g., `speech_schema`), there is an additional subfolder named `items`. This `items` folder contains individual questions or tasks pertaining to that specific activity. - -In the case of the speech task, the `items` folder might include a single task designed to prompt the participant to provide a speech sample. Similarly, for the clinical questions, their respective folders will contain `items` subfolders with corresponding questions tailored to elicit the required information. - -The structure of an item within the `items` folder of a ReproSchema activity is similar to the schema template, but with key differences that cater to the specifics of individual data collection elements. Here's an explanation of the provided template for a `country item`: - -1. **Context and type (@context, @type)**: The `@context` remains the same, pointing to the generic context of ReproSchema. The `@type` is now "reproschema:Field" instead of "reproschema:Activity". This change signifies that this template defines a single data collection field or question within an activity, as opposed to the overall structure of an activity. -2. **Identifier and descriptive fields (@id, prefLabel, description, etc.)**: `@id` serves as a unique identifier for the item, here named "country_item". prefLabel and description provide a human-readable name and a brief description of the item, similar to their use in the schema template. -3. **Question field (question)**: This field contains the actual question or prompt that will be presented to the participant. In this template, it reads: "This is an item where the user can select a country." -4. **UI configuration (ui)**: The ui section in the item template differs from the schema template. It specifies how the question will be presented to the user. The inputType is set to "selectCountry", indicating that the user interface will provide a country selection method. -5. **Response options (responseOptions)**: This section defines the nature and structure of the responses allowed for the item. In this example, it specifies the valueType as "xsd:string" and a maxLength of 50 characters. It also provides a URL to a list of choices, in this case, a JSON file containing country names. This link allows the questionnaire to dynamically fetch and display a list of countries as response options. - -```javascript -"responseOptions": { - "valueType": "xsd:string", - "maxLength": 50, - "choices": "https://raw.githubusercontent.com/samayo/country-json/master/src/country-by-name.json" -} -``` - -## Step 1: Specifying `inputType` and `responseOption` to gather precise data - -We have crafted ten items in the 'items' folder for the clinical questions assessment. Each item, such as `alcohol_consumption`, `height`, `weight`, etc., has its `ui` inputType and `responseOptions` specifically defined to suit the nature of the question. - -Take 'alcohol_consumption' as an example. The UI configuration and response options for this question are tailored to capture a straightforward piece of information: - -```javascript -"question": { - "en": "Have you drunk alcohol today?", - "es": "ΒΏHas bebido alcohol hoy?" - }, -"ui": { - "inputType": "radio" - }, -"responseOptions": { - "valueType": "xsd:string", - "multipleChoice": false, - "choices": [ - { - "name": { - "en": "Yes", - "es": "SΓ­" - }, - "value": 1 - }, - { - "name": { - "en": "No", - "es": "No" - }, - "value": 2 - } - ] -} -``` - -- The ui section sets the `inputType` to `"radio"`. This choice indicates that the question will be presented to the participant as a radio button selection, providing a simple and clear interface for response selection. -- In the responseOptions, the `valueType` is defined as `"xsd:string"`, signifying that the expected type of response is a string. The multipleChoice field is set to false, indicating that participants can only select one of the provided options. -- The `choices` array lists the possible responses. In this case, there are two: "Yes" and "No", each with a corresponding value (1 for Yes, 2 for No) and translations provided for English ("en") and Spanish ("es"). - -- For the speech task in our demo project, the configuration of ui `inputType` and `responseOptions` is distinctively tailored to facilitate audio data collection: - -```javascript -"ui": { - "inputType": "audioPassageRecord" -}, -"responseOptions": { - "valueType": "schema:AudioObject", - "minValue": 0, - "maxValue": 60000 -} -``` - -- In the ui section, the `inputType` is set to `"audioPassageRecord"`. This specific input type is designed to enable participants to record an audio passage directly within the questionnaire interface. -- The `responseOptions` are configured to accommodate the nature of audio data. -- The `valueType` is specified as "schema:AudioObject", indicating that the response will be an audio file. -- The fields `minValue` and `maxValue` define the allowable duration of the audio recording in milliseconds. In this case, the maximum duration is set to 60,000 milliseconds (or 1 minute). - -## Step 2: Integrating additional components for activity-specific needs - -We can integrate additional components tailored to the unique requirements of specific activities. For instance, considering the unique needs of our speech task, we add an 'audio check' component to confirm the functionality of the audio recording feature. - -1. Setting up an audio check for the speech task - - To ensure the effectiveness of our speech task, we create an activity for audio verification within the `activities` folder, naming it [`0_audio`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/0_audio/). - This folder contains the [`audio_check_schema`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/0_audio/audio_check_schema), a schema specifically designed to test and confirm that the audio recording system is operational and effective for participants. - -2. Contextual and properties configuration for audio check - -```javascript - "@context": [ - "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", - { - "voice": "https://raw.githubusercontent.com/ReproNim/reproschema-library/43e7afab312596708c0ad4dfd45b69c8904088ae/activities/VoiceTask/items/" - } -] -``` - - The @context section includes a specific context link under "voice", pointing to the repository with items relevant to voice and audio tasks: "" This targeted link ensures that the audio check activity aligns with the specific requirements of voice-related tasks. - - The ui's `addProperties` array is tailored for the audio check. We define a property `"variableName": "audio_check"` linked to `"isAbout": "voice:audio_check"`. diff --git a/docs/100_about_this_doc.md b/docs/CONTRIBUTING.md similarity index 82% rename from docs/100_about_this_doc.md rename to docs/CONTRIBUTING.md index 3358742d93..90b4457992 100644 --- a/docs/100_about_this_doc.md +++ b/docs/CONTRIBUTING.md @@ -1,15 +1,18 @@ -# About this documentation +# Contributing -This documentation is a work in progress and we wellcome any input: if something is missing or unclear, let us know by [opening an issue on our repository] (???). +## Contributing to the documentation -## Serving the doc locally +This documentation is a work in progress and we wellcome any input: +if something is missing or unclear, let us know by opening an issue on our repository. + +### Serving the doc locally This project uses [MkDocs](https://www.mkdocs.org/) tool with [Material theme](https://squidfunk.github.io/mkdocs-material/) and extra plugins to generate the website. To test locally, you will need to install the Python dependencies. To do that, type the following commands: -``` +```bash git clone https://github.com/ReproNim/reproschema.git cd reproschema pip install -r requirements.txt @@ -20,7 +23,7 @@ by `git clone git@github.com//reproschema.git` where `` is y Once done, you need to run MkDocs. Simply type: -``` +```bash mkdocs serve ``` diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000000..84545b3820 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,49 @@ +# FAQ + + + +## How can I visualize the schema for a `protocol` or an `activity`? + +If you want to see what the assessment that are already supported by the ReproSchema would look like using our ReproSchema user-interface, you can visualize them directly on [schema.repronim.org](https://schema.repronim.org/rl). + +If you just want to view a protocol or activity you are developing using the `reproschema-ui`, you can pass the URL of the schema to the `url` query parameter like this: + +```https://schema.repronim.org/ui/#/?url=url-to-your-schema``` + +If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema. For example, our demo protocol can be accessed at this URL: + +[https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema) + +But to get access to the raw content of that file you must click on the `Raw` button once you have opened that page on github that will open this URL: + +[https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema). + +If you want to visualize the graph represented by the JSON-LD file, we explain how to do this in [From JSON to JSON-LD](#from-json-to-json-ld). diff --git a/docs/98_FAQ.md b/docs/faq/semantic-web.md similarity index 70% rename from docs/98_FAQ.md rename to docs/faq/semantic-web.md index 63e54ffe3d..918d308c65 100644 --- a/docs/98_FAQ.md +++ b/docs/faq/semantic-web.md @@ -1,5 +1,3 @@ -# FAQ - ## What is the semantic web? When you request access to a certain document by clicking on a hyperlink, the computer will give a visual rendering of the html code of this document. But computer used to do that in pretty "silly" fashion: it would give you a human-readable version of the content, but the computer would not make the distinction if a certain element in the webpage (for example a paragraph) was referring to a person or a place or a song. @@ -8,8 +6,8 @@ What the semantic wed allows is to "inject" additional information into a webpag ### More info -- [wikipedia article on the semantic web](https://en.wikipedia.org/wiki/Semantic_Web) -- A short video intro to the semantic web by Manu Sporny: +- [wikipedia article on the semantic web](https://en.wikipedia.org/wiki/Semantic_Web) +- A short video intro to the semantic web by Manu Sporny: @@ -23,10 +21,10 @@ The same way that an element in webpage could be given "meaning" by tagging with Linked data has some basic principles behind it ([adapted from wikipedia](https://en.wikipedia.org/wiki/Linked_data)): -- Use Unique Resources identifiers (URI) to name (identify) things. -- Use HTTP URIs so that these things can be looked up. -- Provide useful information about what a name identifies when it's looked up. -- Refer to other things using their HTTP URI-based names when publishing data on the Web. +- Use Unique Resources identifiers (URI) to name (identify) things. +- Use HTTP URIs so that these things can be looked up. +- Provide useful information about what a name identifies when it's looked up. +- Refer to other things using their HTTP URI-based names when publishing data on the Web. ### A more concrete example @@ -52,8 +50,8 @@ Well "*So what?*" you might say. Well it also tells you which type of data this ### More info -- Here is [a TED talk](https://www.ted.com/talks/tim_berners_lee_the_next_web) by Tim Berners-Lee on linked data. -- A short video intro to linked data by Manu Sporny: +- Here is [a TED talk](https://www.ted.com/talks/tim_berners_lee_the_next_web) by Tim Berners-Lee on linked data. +- A short video intro to linked data by Manu Sporny: @@ -61,11 +59,14 @@ Well "*So what?*" you might say. Well it also tells you which type of data this ### What is JSON? -OK before we go for JSON-LD, let's start with JSON. JSON stands for JavaScript Object Notation and is just a specific format for a text file. This type of text file is very often used by website when they need to transmit information to one another. +OK before we go for JSON-LD, let's start with JSON. JSON stands for JavaScript Object Notation and is just a specific format for a text file. +This type of text file is very often used by website when they need to transmit information to one another. -If you want to see an example of how this works, here is [dummy example](http://dummy.restapiexample.com/api/v1/employees) of the response to a request made by one website to another about a list of employees. By default the output of this dummy example is presented in a way that is more pleasing to the human eye, but if you click on `Raw Data`, you will see the raw unformatted JSON file that was returned by the website. Copy-paste in a text editor, it should like the big ugly and scary one-liner below that we, mere mortals, have no idea what to do with, but that a computer has no problem making sense of. +If you want to see an example of how this works, here is [dummy example](http://dummy.restapiexample.com/api/v1/employees) of the response to a request made by one website to another about a list of employees. +By default the output of this dummy example is presented in a way that is more pleasing to the human eye, but if you click on `Raw Data`, you will see the raw unformatted JSON file that was returned by the website. +Copy-paste in a text editor, it should like the big ugly and scary one-liner below that we, mere mortals, have no idea what to do with, but that a computer has no problem making sense of. -**Insert image ???** + ```json @@ -73,9 +74,11 @@ If you want to see an example of how this works, here is [dummy example](http:// ``` -By the way, if you ever come across such monstrosity and you want to turn into something you as a human being can understand (or least read), you can copy-paste it in a validator-formatter like [jsonformatter](https://jsonformatter.curiousconcept.com/) or [jsonlint](https://jsonlint.com/). This will quickly tell you a) whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and b) it will highlight and help you navigate the nested and hierarchical nature of the JSON file. +By the way, if you ever come across such monstrosity and you want to turn into something you as a human being can understand (or least read), you can copy-paste it in a validator-formatter like [jsonformatter](https://jsonformatter.curiousconcept.com/) or [jsonlint](https://jsonlint.com/). This will quickly tell you +1. whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and +1. it will highlight and help you navigate the nested and hierarchical nature of the JSON file. -**Insert image ???** + OK but let's start with a much simpler example of a JSON file, like the one below which could be the content of JSON file returned by a website when asked about a certain person. @@ -110,7 +113,7 @@ You now have a valid JSON-LD. If you want to make sure it is valid, you can copy If you want to visualize a more complex graph, we can try that with one of the JSON-LD file that describe one of the `protocols` of the reproschema like the one [here](https://github.com/ReproNim/reproschema/blob/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld). Actually if you want to test get the raw content of the file you should click on `Raw`. You can then either use the raw content of the file or the URL of this raw file which should be something like: -``` +```text https://raw.githubusercontent.com/ReproNim/reproschema/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld ``` @@ -118,8 +121,8 @@ directly into the [JSON-LD playground](https://json-ld.org/playground/) to see w ### More info -- It would be a stretch to say that the [JSON-LD specifications](https://www.w3.org/TR/json-ld11/) make for a fascinating read that will keep you up at night (although they might but mostly out of frustration) but it is good to know that it is out there in case you eventually need to look something up -- Two short videos by Manu Sporny about JSON-LD and core mark up features JSON-LD: +- It would be a stretch to say that the [JSON-LD specifications](https://www.w3.org/TR/json-ld11/) make for a fascinating read that will keep you up at night (although they might but mostly out of frustration) but it is good to know that it is out there in case you eventually need to look something up +- Two short videos by Manu Sporny about JSON-LD and core mark up features JSON-LD: @@ -134,51 +137,3 @@ At the moment, all the assessments that support this standard are listed in [thi If you want to see those different tools in action using our user interface, you can explore them on [schema.repronim.org/](https://schema.repronim.org/rl/). The ReproSchema is also used to develop a checklist to [improve methods and results reporting in neuroimaging](https://github.com/ohbm/cobidas). - -**πŸ›  Work in progress πŸ› ** - -## Why should I use ReproSchema? - -**πŸ›  Work in progress πŸ› ** - -## Who is ReproSchema for? - -**πŸ›  Work in progress πŸ› ** - -## How can I know if a certain property is supported by ReproSchema? - -**πŸ›  Work in progress πŸ› ** - -## How can I add a property to my schema? - -**πŸ›  Work in progress πŸ› ** - -## How are these assessments licensed? - -**πŸ›  Work in progress πŸ› ** - -## How can I contribute to the project? - -**πŸ›  Work in progress πŸ› ** - -## An assessment tool I regularly use is not supported by ReproSchema: how can I add it? - -**πŸ›  Work in progress πŸ› ** - -## How can I visualize the schema for a `protocol` or an `activity`? - -If you want to see what the assessment that are already supported by the ReproSchema would look like using our ReproSchema user-interface, you can visualize them directly on [schema.repronim.org](https://schema.repronim.org/rl). - -If you just want to view a protocol or activity you are developing using the `reproschema-ui`, you can pass the URL of the schema to the `url` query parameter like this: - -```https://schema.repronim.org/ui/#/?url=url-to-your-schema``` - -If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema. For example, our demo protocol can be accessed at this URL: - -[https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema) - -But to get access to the raw content of that file you must click on the `Raw` button once you have opened that page on github that will open this URL: - -[https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema). - -If you want to visualize the graph represented by the JSON-LD file, we explain how to do this in [From JSON to JSON-LD](#from-json-to-json-ld). diff --git a/docs/99_glossary.md b/docs/glossary.md similarity index 100% rename from docs/99_glossary.md rename to docs/glossary.md diff --git a/docs/index.md b/docs/index.md index 3bdc905ec4..f33964d600 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,19 +7,17 @@ style="width: 350px; height: auto; display: block; margin-left: auto; margin-ri ## How to use this documentation -- If you want to know more about the ReproSchema project, its goals and the problems -it tries to solve: check out our [introduction](./01_introduction.md). +- If you want to know more about the ReproSchema project, its goals and the problems +it tries to solve: check out our [introduction](./introduction.md). -- The ReproSchema is related to the `Semantic Web` and relies on `linked data` +- The ReproSchema is related to the `Semantic Web` and relies on `linked data` and the `JSON-LD` format. If you are unfamiliar with such things, head over to -our [FAQ](./98_FAQ.md). You do not need an in depth understanding of what those +our [FAQ](./FAQ.md). You do not need an in depth understanding of what those things are to use the ReproSchema but some "big picture" conceptual understanding could save you from a lot of confusion. πŸ˜‰ -- Not sure how the project is organized? Check out the [project structure](./20_project_structure.md) -page. - -- Want more details on how the `Reproschema` itself is structured: check out our [schema page](./30_schema.md) +- Not sure how the project is organized? Check out the [project structure](./project-structure.md) page. +- Want more details on how the `Reproschema` itself is structured: check out our [schema page](./schema.md) ## Preparing the JSON for the activity Now let's create the `activities` folder, an activity file for the new -assessment tool we want to create. For this tutorial we will be using the short -form of the Edinburgh handedness inventory. +assessment tool we want to create. +For this tutorial we will be using the short form of the Edinburgh handedness inventory. ```bash # Type this in a terminal window @@ -77,8 +78,7 @@ mkdir activities touch activities/EHI/edinburgh_handedness_inventory_short.jsonld ``` -Now let's start by adding the following content in the activity file we have -just created. +Now let's start by adding the following content in the activity file we have just created. ```json { @@ -92,14 +92,14 @@ just created. } ``` -The content is for now very similar to the jsonld that defines our protocol. The -main difference is for the `@type` field that mentions that we are now -describing an activity as defined in the Reproschema. +The content is for now very similar to the jsonld that defines our protocol. +The main difference is for the `@type` field that mentions +that we are now describing an activity as defined in the Reproschema. Two other things we can add right away are: -- the references for this questionnaire, -- the "preamble" that is common to all items in this questionnaire. +- the references for this questionnaire, +- the "preamble" that is common to all items in this questionnaire. ```json { @@ -117,8 +117,7 @@ Two other things we can add right away are: ## Creating items -Now that we have a basic structure for this new activity, let us start adding -some items. +Now that we have a basic structure for this new activity, let us start adding some items. Let's first start with the item for `writing` @@ -145,10 +144,9 @@ The content for items starts like the ones we have seen so far but We can now add: -- the question for this item -- the response options -- and the `inputType` for for the user interface that will decide how this item - will displayed to the user. +- the question for this item +- the response options +- and the `inputType` for for the user interface that will decide how this item will displayed to the user. ```json { @@ -238,8 +236,7 @@ We can now add: ## In your own time: create a second item -For next step you can create on your own the `throwing` item of the -questionnaire. +For next step you can create on your own the `throwing` item of the questionnaire. ## Add the items to the activity @@ -310,11 +307,11 @@ git push Use the UI to visualize just the activity. -``` +```text https://www.repronim.org/reproschema-ui/#/activities/0?url=url-to-activity-schema ``` -``` +```text https://www.repronim.org/reproschema-ui/#/activities/0?url=https://raw.githubusercontent.com/your_user_name/depression_nimg_schema/activities/edinburgh_handedness_inventory_short.jsonld ``` diff --git a/docs/51_create_new_protocol.md b/docs/tutorials/create-new-protocol.md similarity index 91% rename from docs/51_create_new_protocol.md rename to docs/tutorials/create-new-protocol.md index 694fbebc1a..8f9205af2b 100644 --- a/docs/51_create_new_protocol.md +++ b/docs/tutorials/create-new-protocol.md @@ -46,9 +46,9 @@ Open the `depression_nimg_schema.jsonld` with a text editor and add the followin To explain a bit what all of this means: -- `@context` gives the URL where we can find the "definitions" of terms used in the reproschema. It is itself a json file that you [can view directly](https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic). -- `@type` just says what type of entity this jsonld file describes. In this case it is a `protocol` entity as defined by the reproschema. -- `@id` is the identity of this entity, its unique identifier. +- `@context` gives the URL where we can find the "definitions" of terms used in the reproschema. It is itself a json file that you [can view directly](https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic). +- `@type` just says what type of entity this jsonld file describes. In this case it is a `protocol` entity as defined by the reproschema. +- `@id` is the identity of this entity, its unique identifier. You can then use the preferred label field and the description to give more human readable ways to describe this entity. @@ -110,13 +110,13 @@ To get access to the raw content of that activity you must click on the `Raw` bu You can then pass the the URL of raw content to the UI using the following template: -``` +```text https://www.repronim.org/reproschema-ui/#/activities/0?url=url-to-activity-schema ``` So in the case of the PHQ-9, it would give this URL that we copy-paste in a browser to view the activity on its own. -``` +```text https://www.repronim.org/reproschema-ui/#/activities/0?url=https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema ``` @@ -180,12 +180,12 @@ The field `order` is there to indicate which activity should be presented first, Json files can get a bit long and you might sometimes forget a coma of a closing square brackets, so to make sure that your json file is correctly formatted you can use a linter. For example, you can test individual files on the [json linter website](https://jsonlint.com/). ??? "JSON-LD expansion" - You might notice that `rl:PHQ-9/PHQ9_schema` does not look like a typical URL and clearly does not match the one we fed the UI earlier (https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema). Well this is because we have defined, in the `@context` part of our jsonld, that the `rl` from `rl:PHQ-9/PHQ9_schema` will actually stand for `https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/`. This shorthand makes it faster for us to write URL but the UI will know how to `expand` this into an actual URL. + You might notice that `rl:PHQ-9/PHQ9_schema` does not look like a typical URL and clearly does not match the one we fed the UI earlier (`https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema`). + Well this is because we have defined, in the `@context` part of our jsonld, that the `rl` from `rl:PHQ-9/PHQ9_schema` will actually stand for `https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/`. + This shorthand makes it faster for us to write URL but the UI will know how to `expand` this into an actual URL. Similarly the `reproschema:Protocol` in `"@type": "reproschema:Protocol"` expands in `http://schema.repronim.org/Protocol` because `reproschema` has been indirectly defined in the context of `depression_nimg_schema.jsonld`. To be more precise `reproschema` is defined in the [base file](https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/base) which is part of the context of the [generic file](https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic) that our protocol points to. - - #### Starting to put things online to see how they look So now we want to put things online and see how things look. @@ -212,7 +212,7 @@ Now to move things to a github repository, you need to go and create an empty re The repository should have an URL that resembles this one where `your_user_name` is your actual Github username: -``` +```text https://github.com/your_user_name/depression_nimg_schema.git ``` @@ -230,13 +230,13 @@ git push -u origin master If everything worked normally, you should be able to use the reproschema-ui to visualize your protocol using the following template: -``` +```text https://www.repronim.org/reproschema-ui/#/?url=url-to-protocol-schema ``` So once again grab the URL of the **raw** content of your protocol and point the UI to it: -``` +```text https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com/your_user_name/depression_nimg_schema/master/protocol/depression_nimg_schema.jsonld ``` diff --git a/docs/53_tips_to_make_your_life_easier.md b/docs/tutorials/tips-to-make-your-life-easier.md similarity index 98% rename from docs/53_tips_to_make_your_life_easier.md rename to docs/tutorials/tips-to-make-your-life-easier.md index 9c7bd1f74d..4be79df074 100644 --- a/docs/53_tips_to_make_your_life_easier.md +++ b/docs/tutorials/tips-to-make-your-life-easier.md @@ -11,8 +11,7 @@ First, make sure your syntax is in correct jsonld format. Test all files with ```bash npm install -g jsonlint -grep -r "@context" . \ - | cut -d: -f1 | xargs -I fname jsonlint -q fname +grep -r "@context" . | cut -d: -f1 | xargs -I fname jsonlint -q fname ``` Or test individual files on the [json linter website](https://jsonlint.com/). @@ -53,7 +52,7 @@ described by a `yml` file. For example you could create a `validate.yml` file in this repository. -``` +```text β”œβ”€β”€ .git # hidden git folder β”œβ”€β”€ .github # hidden github folder β”‚ └── workflows @@ -70,7 +69,7 @@ For example you could create a `validate.yml` file in this repository. The content of `validate.yml` file would look like this. -```yml +```yaml name: validate protocol and activities # describes when this workfllow is triggered @@ -152,7 +151,7 @@ For example, you could create response set file to constrains the possible answers on the questions of the Edinburgh Handedness Inventory we have been working on by organizing things this way. -``` +```text activities β”œβ”€β”€ edinburgh_handedness_inventory_short.jsonld β”œβ”€β”€ leftRightValueConstraints.jsonld diff --git a/docs/54_translating_an_activity.md b/docs/tutorials/translating-an-activity.md similarity index 99% rename from docs/54_translating_an_activity.md rename to docs/tutorials/translating-an-activity.md index 4ff14e9228..2821261879 100644 --- a/docs/54_translating_an_activity.md +++ b/docs/tutorials/translating-an-activity.md @@ -6,7 +6,7 @@ Well there is an easy way to reuse the work we have already done to have the too First here is the list of the questions of the EHI in French. -``` +```text Quelle main utilisez vous de prΓ©fΓ©rence pour: 1) Γ‰crire (*) diff --git a/docs/50_using_reproschema.md b/docs/tutorials/using-reproschema.md similarity index 85% rename from docs/50_using_reproschema.md rename to docs/tutorials/using-reproschema.md index e391bbdf1e..dc3a1a8bb2 100644 --- a/docs/50_using_reproschema.md +++ b/docs/tutorials/using-reproschema.md @@ -11,9 +11,9 @@ Here we will show a step by step approach to create a new protocol that includes For this tutorial you will be using some other tools to put your work online. Here is what you will need to install or set up. -- [Git](https://git-scm.com/downloads) -- a [Github account](https://github.com/) -- a "decent" text editor like [atom](https://atom.io/) or [visual studio code](https://code.visualstudio.com/) and we do recommend that you look for extensions or packages that help you deal with json files. +- [Git](https://git-scm.com/downloads) +- a [Github account](https://github.com/) +- a "decent" text editor like [atom](https://atom.io/) or [visual studio code](https://code.visualstudio.com/) and we do recommend that you look for extensions or packages that help you deal with json files. We don't assume that you have in-depth knowledge of Git and Github for this tutorial so we will try to provide with the commands you need to type when it is required. Similarly, we will provide some of the commands to create directories and files though you could do many of those actions "by hand" with a couple of mouse clicks. @@ -26,10 +26,9 @@ To make this a bit less abstract, we will imagine we want to create a new protoc So we would want to have a set of questionnaires: -- to assess the severity of the depression of our participants, -- check which participants can go in an MRI scanner, -- estimate the handedness of the participants (because of the language lateralization organization of the brain). - +- to assess the severity of the depression of our participants, +- check which participants can go in an MRI scanner, +- estimate the handedness of the participants (because of the language lateralization organization of the brain). ## A note about this tutorial diff --git a/docs/42_adopt_assessments.md b/docs/user-guide/adopt-assessments.md similarity index 58% rename from docs/42_adopt_assessments.md rename to docs/user-guide/adopt-assessments.md index e32068faa9..1d09080126 100644 --- a/docs/42_adopt_assessments.md +++ b/docs/user-guide/adopt-assessments.md @@ -2,43 +2,52 @@ This part focuses on how to select and integrate assessments from the reproschema-library into your research protocol, an essential step in crafting a comprehensive study. The chosen assessments are to be placed in the `activities` folder within your repository. This folder serves as the central hub for various assessments or activities that collectively form your research protocol. -Each activity or assessment within this `activities` folder is typically structured around a file named with a suffix `_schema`. This file defines the overall framework of the assessment. Accompanying this, if an assessment comprises specific questions, these are organized in a subfolder titled `items` within the respective activity's directory. It's important to note that if an assessment is directly taken from the ReproSchema-library without any customization, the creation of an `items` subfolder is not necessary, as the itemized questions are predefined in the library. +Each activity or assessment within this `activities` folder is typically structured around a file named with a suffix `_schema`. +This file defines the overall framework of the assessment. +Accompanying this, if an assessment comprises specific questions, these are organized in a subfolder titled `items` within the respective activity's directory. +It's important to note that if an assessment is directly taken from the ReproSchema-library without any customization, the creation of an `items` subfolder is not necessary, as the itemized questions are predefined in the library. To illustrate this process, we will use two specific types of assessments from [reproschema-library](https://github.com/ReproNim/reproschema-library): `demographics` and `psychological questions`. The latter represents a composite assessment created from multiple pre-existing assessments within the library. This example demonstrates how to combine different elements from the library to construct a bespoke assessment tailored to the unique demands of your research protocol. ## Step 1: Understand the structure of a *_schema file through this [exemplar file](https://github.com/ReproNim/reproschema-protocol-cookiecutter/blob/main/%7B%7Bcookiecutter.protocol_name%7D%7D/activities/Activity1/activity1_schema) -1. **Context (@context)**: This field provides references to the context definitions. In this schema, it links to the generic context of ReproSchema and the specific context for the items in the repository, defined by the URL with the "rl" key. This context helps to interpret the terms used within the schema. -2. **Type (@type)**: Defined as "reproschema:Activity," this indicates the nature of the document, specifying that it is an activity within the ReproSchema framework. -3. **Identifier (@id)**: The unique identifier for this specific schema is "activity1_schema." This ID uniquely distinguishes this activity from others in the repository. -4. **PrefLabel**: This is the human-readable name of the activity, here given as "Screening." It serves as a clear and concise title for the activity. -5. **Description**: Provides a brief overview of the activity, in this case, "example of an activity." -6. **SchemaVersion and Version**: These fields indicate the versions of the ReproSchema being used ("1.0.0-rc2" means β€œ1.0.0 Release Candidate 2”) and the version of this particular activity schema ("0.0.1"), respectively. -7. **UI Configuration**: This section specifies how the activity will be presented to users. It includes: - - **addProperties**: Lists the variables and corresponding items collected in the activity. For example, the variable `document_upload_item` is about the item `items/document_upload_item` and is always visible (`isVis: true`). It allows for the item to be skipped (`reproschema:Skipped`). - - **order**: Dictates the sequence in which items will appear in the UI. Here, it specifies that "items/document_upload_item" will be the first (and only) item. - - **shuffle**: Indicates whether the order of items should be randomized. In this example, it is set to `false`, meaning the order is fixed. - - **allow**: Defines additional UI functionalities. Here, it includes `reproschema:AutoAdvance` for automatic progression and `reproschema:AllowExport` to enable data export. +1. **Context (@context)**: This field provides references to the context definitions. In this schema, it links to the generic context of ReproSchema and the specific context for the items in the repository, defined by the URL with the "rl" key. This context helps to interpret the terms used within the schema. + +1. **Type (@type)**: Defined as "reproschema:Activity," this indicates the nature of the document, specifying that it is an activity within the ReproSchema framework. + +1. **Identifier (@id)**: The unique identifier for this specific schema is "activity1_schema." This ID uniquely distinguishes this activity from others in the repository. + +1. **PrefLabel**: This is the human-readable name of the activity, here given as "Screening." It serves as a clear and concise title for the activity. + +1. **Description**: Provides a brief overview of the activity, in this case, "example of an activity." + +1. **SchemaVersion and Version**: These fields indicate the versions of the ReproSchema being used ("1.0.0-rc2" means β€œ1.0.0 Release Candidate 2”) and the version of this particular activity schema ("0.0.1"), respectively. + +1. **UI Configuration**: This section specifies how the activity will be presented to users. It includes: + - **addProperties**: Lists the variables and corresponding items collected in the activity. For example, the variable `document_upload_item` is about the item `items/document_upload_item` and is always visible (`isVis: true`). It allows for the item to be skipped (`reproschema:Skipped`). + - **order**: Dictates the sequence in which items will appear in the UI. Here, it specifies that "items/document_upload_item" will be the first (and only) item. + - **shuffle**: Indicates whether the order of items should be randomized. In this example, it is set to `false`, meaning the order is fixed. + - **allow**: Defines additional UI functionalities. Here, it includes `reproschema:AutoAdvance` for automatic progression and `reproschema:AllowExport` to enable data export. ## Step 2: Customizing the schema file for demographics using existing assessments from reproschema-library This step involves precise modifications, particularly in the `@context` and `addProperties` sections, to ensure the schema accurately reflects the demographic data you aim to collect. -1. **Adjusting the `@context` for Demographics**: +1. **Adjusting the `@context` for Demographics**: In addition to the standard ReproSchema context, we've added a specific link in the "@context" section for demographics: - ``` + ```json "demo": "https://raw.githubusercontent.com/ReproNim/reproschema-library/[commitID]/demographics_and_background_information_v1/items/" ``` Labeling this link as "demo" directs the schema to the location in the ReproSchema-library where items for demographics and background information are defined. We use the link with a specific commit ID to ensure the consistency of the assessment version. This contextual link allows the schema to access the detailed structures and definitions needed for each demographic item. -2. **Customizing "addProperties" for Demographic Variables**: +1. **Customizing "addProperties" for Demographic Variables**: In the "addProperties" section, we define each variable that corresponds to a demographic question. For example: - ``` + ```json { "variableName": "year_of_birth", "isAbout": "demo:year_of_birth" @@ -52,13 +61,17 @@ This step involves precise modifications, particularly in the `@context` and `ad ## Step 3: Integrating multiple assessments -Different from `demograpgics`, `psychological_questionnaire_schema` combines assessments, such as [PHQ-9](https://github.com/ReproNim/reproschema-library/tree/master/activities/PHQ-9), [GAD7](https://github.com/ReproNim/reproschema-library/tree/master/activities/GAD7), [PC-PTSD-5](https://github.com/ReproNim/reproschema-library/tree/master/activities/PC-PTSD-5), and [demographics](https://github.com/ReproNim/reproschema-library/tree/master/activities/demographics_and_background_information_v1/items) from [reproschema-library](https://github.com/ReproNim/reproschema-library). +Different from `demograpgics`, `psychological_questionnaire_schema` combines assessments, +such as [PHQ-9](https://github.com/ReproNim/reproschema-library/tree/master/activities/PHQ-9), +[GAD7](https://github.com/ReproNim/reproschema-library/tree/master/activities/GAD7), +[PC-PTSD-5](https://github.com/ReproNim/reproschema-library/tree/master/activities/PC-PTSD-5), +and [demographics](https://github.com/ReproNim/reproschema-library/tree/master/activities/demographics_and_background_information_v1/items) from [reproschema-library](https://github.com/ReproNim/reproschema-library). -1. **Contextual setup (@context)**: +1. **Contextual setup (@context)**: The @context section is expanded to include not only the generic ReproSchema context but also specific links to the ReproSchema-library. This enables the schema to access a broader range of predefined items and assessments. For the psychological questionnaire, two context links are established: - ``` + ```json "@context": [ "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", { @@ -70,13 +83,13 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass A link to the activities in the reproschema-library (`activities`: ) and a link for demographics items (`demo`: ), both are commit-specific. This indicates that we will combine different assessments from those two parts. -2. **Defining the activity (@type, @id, prefLabel, etc.)**: +1. **Defining the activity (@type, @id, prefLabel, etc.)**: The standard fields like @type, @id, prefLabel, description, preamble, schemaVersion, and version define the nature and purpose of the psychological questionnaire. -3. **UI configuration and integration of multiple assessments (ui)**: +1. **UI configuration and integration of multiple assessments (ui)**: - ``` + ```json "ui": { "addProperties": [ { @@ -130,19 +143,20 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass } ``` - In the addProperties section, we define each variable that corresponds to a specific assessment. For instance: - - `"variableName": "phq-9"` is linked to `"isAbout": "activities:PHQ-9/PHQ9_schema"`. This implies that the PHQ-9 schema (an assessment for depressive symptoms) from the reproschema-library is used in the current psychological questionnaire schema. - - Similarly, other assessments like `GAD-7` and `PC-PTSD-5` are included using their respective variable names and links to their schemas in the activities context. - - Additional variables related to clinical history in psychiatry are linked using the demo context, pointing to specific items within the demographics and background information section of the reproschema-library. + In the addProperties section, we define each variable that corresponds to a specific assessment. + For instance: + - `"variableName": "phq-9"` is linked to `"isAbout": "activities:PHQ-9/PHQ9_schema"`. This implies that the PHQ-9 schema (an assessment for depressive symptoms) from the reproschema-library is used in the current psychological questionnaire schema. + - Similarly, other assessments like `GAD-7` and `PC-PTSD-5` are included using their respective variable names and links to their schemas in the activities context. + - Additional variables related to clinical history in psychiatry are linked using the demo context, pointing to specific items within the demographics and background information section of the reproschema-library. - ``` - { - "variableName": "clinical_history_psychiatry", - "isAbout": "demo:clinical_history_psychiatry" - } - ``` + ```json + { + "variableName": "clinical_history_psychiatry", + "isAbout": "demo:clinical_history_psychiatry" + } + ``` - - The `order` array specifies the sequence in which these assessments will appear in the questionnaire, ensuring a logical flow for participants. - - The `shuffle` setting is `false`, maintaining the defined order, and allow includes functionalities like auto-advance between assessments and data export. + - The `order` array specifies the sequence in which these assessments will appear in the questionnaire, ensuring a logical flow for participants. + - The `shuffle` setting is `false`, maintaining the defined order, and allow includes functionalities like auto-advance between assessments and data export. See the outcome [here](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/2_psychological/psychological_questionnaire_schema) diff --git a/docs/user-guide/create-new-assess.md b/docs/user-guide/create-new-assess.md new file mode 100644 index 0000000000..4fa931cdf2 --- /dev/null +++ b/docs/user-guide/create-new-assess.md @@ -0,0 +1,148 @@ +# Creating New Assessments for Unique Research Needs + +This section provides the customized new assessments tailored to specific research needs. Our focus is on creating three distinct types of activities that are not readily available in the reproschema-library. +These include: +1. clinical questions to gather clinical background information, +1. a speech task designed to collect audio data, and +1. an audio check to facilitate the speech task. + +For each of these new assessments, the folder structure within the repository will differ slightly from those directly adopted from the reproschema-library. Specifically, each activity has its own dedicated folder within the `activities` directory. +For instance, the speech task resides in [`activities/4_speech`](https://github.com/ReproNim/reproschema-demo-protocol/tree/main/activities/4_speech). +Within this folder, besides the primary schema file (e.g., `speech_schema`), there is an additional subfolder named `items`. +This `items` folder contains individual questions or tasks pertaining to that specific activity. + +In the case of the speech task, the `items` folder might include a single task designed to prompt the participant to provide a speech sample. Similarly, for the clinical questions, their respective folders will contain `items` subfolders with corresponding questions tailored to elicit the required information. + +The structure of an item within the `items` folder of a ReproSchema activity is similar to the schema template, but with key differences that cater to the specifics of individual data collection elements. Here's an explanation of the provided template for a `country item`: + +1. **Context and type (@context, @type)**: + The `@context` remains the same, pointing to the generic context of ReproSchema. + The `@type` is now "reproschema:Field" instead of "reproschema:Activity". + This change signifies that this template defines a single data collection field or question within an activity, as opposed to the overall structure of an activity. + +1. **Identifier and descriptive fields (@id, prefLabel, description, etc.)**: + `@id` serves as a unique identifier for the item, here named "country_item". + prefLabel and description provide a human-readable name and a brief description of the item, similar to their use in the schema template. + +1. **Question field (question)**: + This field contains the actual question or prompt that will be presented to the participant. + In this template, it reads: "This is an item where the user can select a country." + +1. **UI configuration (ui)**: + The ui section in the item template differs from the schema template. + It specifies how the question will be presented to the user. + The inputType is set to "selectCountry", indicating that the user interface will provide a country selection method. + +1. **Response options (responseOptions)**: + This section defines the nature and structure of the responses allowed for the item. + In this example, it specifies the valueType as "xsd:string" and a maxLength of 50 characters. + It also provides a URL to a list of choices, in this case, a JSON file containing country names. + This link allows the questionnaire to dynamically fetch and display a list of countries as response options. + +```json +"responseOptions": { + "valueType": "xsd:string", + "maxLength": 50, + "choices": "https://raw.githubusercontent.com/samayo/country-json/master/src/country-by-name.json" +} +``` + +## Step 1: Specifying `inputType` and `responseOption` to gather precise data + +We have crafted ten items in the 'items' folder for the clinical questions assessment. Each item, such as `alcohol_consumption`, `height`, `weight`, etc., has its `ui` inputType and `responseOptions` specifically defined to suit the nature of the question. + +Take 'alcohol_consumption' as an example. +The UI configuration and response options for this question are tailored to capture a straightforward piece of information: + +```json +"question": { + "en": "Have you drunk alcohol today?", + "es": "ΒΏHas bebido alcohol hoy?" + }, +"ui": { + "inputType": "radio" + }, +"responseOptions": { + "valueType": "xsd:string", + "multipleChoice": false, + "choices": [ + { + "name": { + "en": "Yes", + "es": "SΓ­" + }, + "value": 1 + }, + { + "name": { + "en": "No", + "es": "No" + }, + "value": 2 + } + ] +} +``` + +- The ui section sets the `inputType` to `"radio"`. + This choice indicates that the question will be presented to the participant as a radio button selection, + providing a simple and clear interface for response selection. + +- In the responseOptions, the `valueType` is defined as `"xsd:string"`, signifying that the expected type of response is a string. + The multipleChoice field is set to false, indicating that participants can only select one of the provided options. + +- The `choices` array lists the possible responses. + In this case, there are two: "Yes" and "No", each with a corresponding value (1 for Yes, 2 for No) + and translations provided for English ("en") and Spanish ("es"). + +- For the speech task in our demo project, the configuration of ui `inputType` and `responseOptions` is distinctively tailored + to facilitate audio data collection: + +```json +"ui": { + "inputType": "audioPassageRecord" +}, +"responseOptions": { + "valueType": "schema:AudioObject", + "minValue": 0, + "maxValue": 60000 +} +``` + +- In the ui section, the `inputType` is set to `"audioPassageRecord"`. + This specific input type is designed to enable participants to record an audio passage directly within the questionnaire interface. + +- The `responseOptions` are configured to accommodate the nature of audio data. + +- The `valueType` is specified as "schema:AudioObject", indicating that the response will be an audio file. + +- The fields `minValue` and `maxValue` define the allowable duration of the audio recording in milliseconds. + In this case, the maximum duration is set to 60,000 milliseconds (or 1 minute). + +## Step 2: Integrating additional components for activity-specific needs + +We can integrate additional components tailored to the unique requirements of specific activities. For instance, considering the unique needs of our speech task, we add an 'audio check' component to confirm the functionality of the audio recording feature. + +1. Setting up an audio check for the speech task + + To ensure the effectiveness of our speech task, we create an activity for audio verification within the `activities` folder, naming it [`0_audio`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/0_audio/). + This folder contains the [`audio_check_schema`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/0_audio/audio_check_schema), a schema specifically designed to test and confirm that the audio recording system is operational and effective for participants. + +1. Contextual and properties configuration for audio check + +```json +"@context": [ + "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", + { + "voice": "https://github.com/ReproNim/reproschema-library/tree/master/activities/VoiceTask/items" + } +] +``` + +The `@context` section includes a specific context link under "voice", +pointing to the repository with items relevant to voice and audio tasks: +`https://github.com/ReproNim/reproschema-library/tree/master/activities/VoiceTask/items` +This targeted link ensures that the audio check activity aligns with the specific requirements of voice-related tasks. + +The ui's `addProperties` array is tailored for the audio check. +We define a property `"variableName": "audio_check"` linked to `"isAbout": "voice:audio_check"`. diff --git a/docs/user-guide/create-new-protocol.md b/docs/user-guide/create-new-protocol.md new file mode 100644 index 0000000000..972550655e --- /dev/null +++ b/docs/user-guide/create-new-protocol.md @@ -0,0 +1,37 @@ +# Creating a Research Protocol Using Cookiecutter + +Ready for your first ReproSchema project?! We are going to use the [Reproschema Protocol Cookiecutter](https://github.com/ReproNim/reproschema-protocol-cookiecutter) to create a demo protocol. + +## Getting Started + +1. **Prerequisite:** + Ensure you have Git and Cookiecutter installed on your system. If not, please refer to the installation guides for Git and Cookiecutter. + +1. **Generate your Repository:** + Use the Reproschema Protocol Cookiecutter to create a new repository for your research protocol. + Run the following command in your terminal: + + ```bash + cookiecutter gh:ReproNim/reproschema-protocol-cookiecutter + ``` + +1. Follow the prompts to customize your new protocol, + more details see [here](https://github.com/ReproNim/reproschema-protocol-cookiecutter#step-1-generate-the-protocol-files) + +## Customizing Your Protocol + +Once you run the Cookiecutter command, you will be prompted to make choices for your protocol, ranging from 1-5. These choices generate corresponding activities in your repository. Here's what you can do with these activities: + +1. **Use as templates:** + The activities created based on your choices serve as templates. + You can use these to understand the structure and elements within the activities folder. + This is particularly useful if you're new to ReproSchema. + By exploring these templates, you'll get a clearer picture of how activities are structured and what kind of information they contain. + +1. **Delete and start fresh:** + Alternatively, if you already have a clear idea of what your protocol needs, you can delete these generated activities. + This allows you to start from scratch, creating activities that are tailored specifically to your research needs. + +The inclusion of activity choices aims to provide users with a practical understanding of how activities are structured within ReproSchema protocols. Whether you use these as a starting point or prefer to create your own from the ground up, these templates are there to guide you in structuring your research protocol effectively. + +We provide more detailed instructions for customizing your protocol in the following pages using [reproschema-demo-protocol](https://github.com/ReproNim/reproschema-demo-protocol) as an example. diff --git a/docs/45_finalize_protocol.md b/docs/user-guide/finalize-protocol.md similarity index 50% rename from docs/45_finalize_protocol.md rename to docs/user-guide/finalize-protocol.md index 319e0dd511..af9c0b06e8 100644 --- a/docs/45_finalize_protocol.md +++ b/docs/user-guide/finalize-protocol.md @@ -1,16 +1,18 @@ # Finalizing the Protocol -After setting up individual activities, we return to the main [protocol schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/reproschema_demo_protocol_schema) to organize everything cohesively. This step involves structuring the 'DemoProtocol_schema' to include all the activities we have developed, defining their sequence and presentation within the overall research protocol. In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate each activity schema using the following approach: +After setting up individual activities, we return to the main [protocol schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/reproschema_demo_protocol_schema) to organize everything cohesively. +This step involves structuring the 'DemoProtocol_schema' to include all the activities we have developed, defining their sequence and presentation within the overall research protocol. +In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate each activity schema using the following approach: -1. Context and protocol definition +1. Context and protocol definition The `@context`, `@type`, `@id`, and descriptive fields (`prefLabel`, `description`, etc.) provide the foundational information about the protocol. -2. Inclusion of activities +1. Inclusion of activities The ui section's addProperties array is crucial. Here, each activity schema we've created is referenced under `isAbout`, with its respective `variableName` and `prefLabel`. For example, the `audio` activity is linked as -```javascript +```json { "isAbout": "../activities/0_audio/audio_check_schema", "variableName": "audio_check_schema", @@ -20,15 +22,16 @@ After setting up individual activities, we return to the main [protocol schema]( This structure is repeated for each activity, including audio check, demographics, psychological questions, clinical questions, speech task, and feedback. -3. [Order of presentation](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L50) +1. [Order of presentation](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L50) - The order array within ui specifies the sequence in which these activities will appear in the protocol. It's arranged to flow logically from consent, through various assessments, to the final feedback, ensuring a structured participant experience. For instance, the order starts with `../activities/0_audio/audio_check_schema` and progresses through to `../activities/5_feedback/feedback_schema`. + The order array within ui specifies the sequence in which these activities will appear in the protocol. + It's arranged to flow logically from consent, through various assessments, to the final feedback, ensuring a structured participant experience. For instance, the order starts with `../activities/0_audio/audio_check_schema` and progresses through to `../activities/5_feedback/feedback_schema`. -4. [Additional UI settings](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L23) - - 'shuffle' is set to false to maintain the specified order. - - 'allow' includes functionalities such as 'reproschema:AllowExport' for data exporting options. +1. [Additional UI settings](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L23) + - `"shuffle"` is set to false to maintain the specified order. + - `"allow"` includes functionalities such as `"reproschema:AllowExport"` for data exporting options. -5. Update [README.md](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/README.md) +1. Update [README.md](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/README.md) Give clear and concise instructions on what this protocol is about and how participants should use it. diff --git a/docs/44_setup_feedback.md b/docs/user-guide/setup-feedback.md similarity index 64% rename from docs/44_setup_feedback.md rename to docs/user-guide/setup-feedback.md index a5d7dc761c..906aa1fe15 100644 --- a/docs/44_setup_feedback.md +++ b/docs/user-guide/setup-feedback.md @@ -2,7 +2,7 @@ To conclude our protocol, we integrate a customized feedback activity. This choice of ending with participant feedback is just one of many possibilities, demonstrating the adaptability of ReproSchema to diverse research needs. -```javascript +```json { "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", "@type": "reproschema:Field", @@ -26,6 +26,10 @@ To conclude our protocol, we integrate a customized feedback activity. This choi The `feedback` item in this activity ([`5_feedback`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/5_feedback/items/feedback)) is specifically designed to gather open-ended responses, allowing participants to share their thoughts and suggestions: -- Item Structure: The item `feedback` is set up with an identification and purpose, indicated by its '@id' and descriptive fields. -- Question Prompt: The `question` is presented in both English and Spanish, encouraging participants to provide comments on their study experience. It’s formatted to be inclusive, giving participants the option to skip if they choose. -- UI Configuration for Open Responses: The choice of `textarea` as the `inputType` in the ui configuration facilitates extended text input, enabling participants to express detailed feedback comfortably. Accordingly, `valueType` in the `responseOptions` has been set as `"xsd:string"`. +- Item Structure: The item `feedback` is set up with an identification and purpose, indicated by its '@id' and descriptive fields. + +- Question Prompt: The `question` is presented in both English and Spanish, encouraging participants to provide comments on their study experience. + It’s formatted to be inclusive, giving participants the option to skip if they choose. + +- UI Configuration for Open Responses: The choice of `textarea` as the `inputType` in the ui configuration facilitates extended text input, enabling participants to express detailed feedback comfortably. + Accordingly, `valueType` in the `responseOptions` has been set as `"xsd:string"`. diff --git a/docs/46_tools.md b/docs/user-guide/tools.md similarity index 73% rename from docs/46_tools.md rename to docs/user-guide/tools.md index aa88a408ce..0f6079b68e 100644 --- a/docs/46_tools.md +++ b/docs/user-guide/tools.md @@ -45,7 +45,7 @@ To convert ReproSchema protocol to REDCap CSV format, use the following command reproschema reproschema2redcap ``` -- ``: The path to the root folder of a protocol. For example, to convert the reproschema-demo-protocol provided by ReproNim, you can use the following commands: +- ``: The path to the root folder of a protocol. For example, to convert the reproschema-demo-protocol provided by ReproNim, you can use the following commands: ```bash git clone https://github.com/ReproNim/reproschema-demo-protocol.git @@ -53,8 +53,9 @@ reproschema reproschema2redcap pwd ``` - In this case, the output from `pwd` (which shows your current directory path)should be your ``. -- ``: The name of the output CSV file where the converted data will be saved. + In this case, the output from `pwd` (which shows your current directory path)should be your ``. + +- ``: The name of the output CSV file where the converted data will be saved. ## `redcap2reproschema` Usage @@ -66,15 +67,15 @@ Before the conversion, ensure you have the following: **YAML Configuration File**: -- Download [templates/redcap2rs.yaml](https://github.com/ReproNim/reproschema-py/blob/ab7c051dbd4ebfce92917ce154a8053343a011e7/templates/redcap2rs.yaml) and fill it out with your protocol details. +- Download [templates/redcap2rs.yaml](https://github.com/ReproNim/reproschema-py/blob/ab7c051dbd4ebfce92917ce154a8053343a011e7/templates/redcap2rs.yaml) and fill it out with your protocol details. ### YAML File Configuration In the `templates/redcap2rs.yaml` file, provide the following information: -- **protocol_name**: This is a unique identifier for your protocol. Use underscores for spaces and avoid special characters. -- **protocol_display_name**: The name that will appear in the application. -- **protocol_description**: A brief description of your protocol. +- **protocol_name**: This is a unique identifier for your protocol. Use underscores for spaces and avoid special characters. +- **protocol_display_name**: The name that will appear in the application. +- **protocol_description**: A brief description of your protocol. Example: diff --git a/makefile b/makefile new file mode 100644 index 0000000000..12f1865921 --- /dev/null +++ b/makefile @@ -0,0 +1,5 @@ +remark: package.json + npx remark ./docs/*.md ./docs/**/*.md --rc-path .remarkrc + +package.json: + npm install `cat npm-requirements.txt` diff --git a/mkdocs.yml b/mkdocs.yml index cde9b43bf3..91bb9a5d45 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,23 +34,23 @@ theme: # Pages nav: - Welcome: "index.md" - - Introduction: "01_introduction.md" - - Project structure: "20_project_structure.md" - - Schema: "30_schema.md" + - Introduction: "introduction.md" + - Project structure: "project-structure.md" + - Schema: "schema.md" - User Guide: - - Create a research protocol: "41_create_new_protocol.md" - - Adopt assessments from the library: "42_adopt_assessments.md" - - Create new assessments for a protocol: "43_create_new_assess.md" - - Add a feedback section: "44_setup_feedback.md" - - Finalize the protocol: "45_finalize_protocol.md" - - Toolkit: "46_tools.md" + - Create a research protocol: "user-guide/create-new-protocol.md" + - Adopt assessments from the library: "user-guide/adopt-assessments.md" + - Create new assessments for a protocol: "user-guide/create-new-assess.md" + - Add a feedback section: "user-guide/setup-feedback.md" + - Finalize the protocol: "user-guide/finalize-protocol.md" + - Toolkit: "user-guide/tools.md" - Tutorial: - - Intro: "50_using_reproschema.md" - - Create a research protocol: "51_create_new_protocol.md" - - Creating a new activity: "52_create_new_activity.md" - - Tips to make your life easier: "53_tips_to_make_your_life_easier.md" - - Translate a questionnaire: "54_translating_an_activity.md" - - Demographic information : "55_collecting_demographics_information.md" + - Intro: "tutorials/using-reproschema.md" + - Create a research protocol: "tutorials/create-new-protocol.md" + - Creating a new activity: "tutorials/create-new-activity.md" + - Tips to make your life easier: "tutorials/tips-to-make-your-life-easier.md" + - Translate a questionnaire: "tutorials/translating-an-activity.md" + - Demographic information : "tutorials/collecting-demographics-information.md" # - Creating a new activity and protocol: "create_new_activity_protocol.md" # - Testing your schema and collecting data: "testing_using_schema.md" # - Contribute to the project: @@ -58,9 +58,9 @@ nav: # - Assesement library: "82_contribute_to_library.md" # - Python package: "83_contribute_to_python.md" # - User-interface: "84_contribute_to_ui.md" - - FAQ: "98_FAQ.md" - - Glossary: "99_glossary.md" - - About this doc: "100_about_this_doc.md" + - FAQ: "FAQ.md" + - Glossary: "glossary.md" + - Contributing: "CONTRIBUTING.md" # list of extension markdown_extensions: diff --git a/npm-requirements.txt b/npm-requirements.txt new file mode 100644 index 0000000000..7ef67d23b8 --- /dev/null +++ b/npm-requirements.txt @@ -0,0 +1,5 @@ +remark-cli@9.0.0 +remark-gfm@1 +remark-preset-lint-recommended@5.0.0 +remark-preset-lint-markdown-style-guide@4.0.0 +remark-lint-no-trailing-spaces@2 diff --git a/scripts/editProperties.py b/scripts/editProperties.py index 5ee4735abe..e045df6069 100644 --- a/scripts/editProperties.py +++ b/scripts/editProperties.py @@ -24,7 +24,7 @@ def edit_properties(version): "SoftwareAgent", ] - with open("docs/30_schema.md") as fp: + with open("docs/schema.md") as fp: doc = fp.readlines() for idx, line in enumerate(doc): if line.startswith(AUTO_LINE):