Merge pull request #454 from yibeichan/master

minor fix
ReproNim · Jan 10, 2024 · 355df31 · 355df31
2 parents a9e64d7 + e43a8c1
commit 355df31
Show file tree

Hide file tree

Showing 6 changed files with 78 additions and 62 deletions.
diff --git a/docs/41_create_new_protocol.md b/docs/41_create_new_protocol.md
@@ -3,11 +3,14 @@
 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
-```
+
+    ```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
@@ -19,4 +22,4 @@ Once you run the Cookiecutter command, you will be prompted to make choices for
 
 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.
+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/42_adopt_assessments.md b/docs/42_adopt_assessments.md
@@ -6,7 +6,8 @@ Each activity or assessment within this `activities` folder is typically structu
 
 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 throught this [exemplar file](https://github.com/ReproNim/reproschema-protocol-cookiecutter/blob/main/%7B%7Bcookiecutter.protocol_name%7D%7D/activities/Activity1/activity1_schema) 
+## Step 1: Understand the structure of a *_schema file throught 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.
@@ -24,22 +25,26 @@ To illustrate this process, we will use two specific types of assessments from [
 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**:
-   
+
     In addition to the standard ReproSchema context, we've added a specific link in the "@context" section for demographics:
+
     ```javascript
     "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**: 
 
     In the "addProperties" section, we define each variable that corresponds to a demographic question. For example:
+
     ```javascript
     {
     "variableName": "year_of_birth",
     "isAbout": "demo:year_of_birth"
     }
     ```
+
     The `"variableName": "year_of_birth"` is where you specify the variable as the participant's year of birth.
     The `"isAbout": "demo:year_of_birth"` part establishes a link to the detailed structure of this item in the ReproSchema-library. The "demo:" prefix references the additional context you've added, guiding the schema to the correct location for the structure and details of the "year_of_birth" item.
 
@@ -52,6 +57,7 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass
 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:
+
     ```javascript
     "@context": [
     "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic",
@@ -61,6 +67,7 @@ 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.)**:
 
@@ -103,7 +110,7 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass
                 "variableName": "clinical_history_psychiatry_current_only_some_other",
                 "isAbout": "demo:clinical_history_psychiatry_current_only_some_other"
             }
-        ],
+            ],
         "order": [
             "activities:PHQ-9/PHQ9_schema",
             "activities:GAD7/GAD7_schema",
@@ -113,25 +120,27 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass
             "demo:clinical_history_psychiatry_current",
             "demo:clinical_history_psychiatry_current_only_some",
             "demo:clinical_history_psychiatry_current_only_some_other"
-        ],
+            ],
         "shuffle": false,
         "allow": [
-			"reproschema:AutoAdvance",
-			"reproschema:AllowExport"
-		]
+            "reproschema:AutoAdvance",
+            "reproschema:AllowExport"
+            ]
     }
     ```
 
     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.
+
         ```javascript
         {
             "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.
 

diff --git a/docs/43_create_new_assess.md b/docs/43_create_new_assess.md
@@ -13,6 +13,7 @@ The structure of an item within the `items` folder of a ReproSchema activity is
 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",
@@ -29,33 +30,34 @@ Take 'alcohol_consumption' as an example. The UI configuration and response opti
 
 ```javascript
 "question": {
-    	"en": "Have you drunk alcohol today?",
-    	"es": "¿Has bebido alcohol hoy?"
-	},
+    "en": "Have you drunk alcohol today?",
+    "es": "¿Has bebido alcohol hoy?"
+    },
 "ui": {
-    	"inputType": "radio"
-	},
+    "inputType": "radio"
+    },
 "responseOptions": {
-    	"valueType": "xsd:string",
-      	"multipleChoice": false,
-    	"choices": [
-        	{
-            	"name": {
-                	"en": "Yes",
-                	"es": "Sí"
-            	},
-            	"value": 1
-        	},
-        	{
-            	"name": {
-                	"en": "No",
-                	"es": "No"
-            	},
-            	"value": 2
-        	}
-    	]
-	}
+    "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").
@@ -73,9 +75,9 @@ Take 'alcohol_consumption' as an example. The UI configuration and response opti
     }
     ```
 
-- 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. 
+- 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
@@ -97,6 +99,7 @@ We can integrate additional components tailored to the unique requirements of sp
         }
     ]
     ```
-    The @context section includes a specific context link under "voice", pointing to the repository with items relevant to voice and audio tasks: "https://raw.githubusercontent.com/ReproNim/reproschema-library/.../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"`. 
+    The @context section includes a specific context link under "voice", pointing to the repository with items relevant to voice and audio tasks: "<https://raw.githubusercontent.com/ReproNim/reproschema-library/.../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/45_finalize_protocol.md b/docs/45_finalize_protocol.md
@@ -7,27 +7,29 @@ After setting up individual activities, we return to the main [protocol schema](
     The `@context`, `@type`, `@id`, and descriptive fields (`prefLabel`, `description`, etc.) provide the foundational information about the protocol.
 
 2. 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 
+
+    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
     {
         "isAbout": "../activities/0_audio/audio_check_schema",
         "variableName": "audio_check_schema",
         "prefLabel": {"en": "Audio Check"}
     }
     ```
+
     This structure is repeated for each activity, including audio check, demographics, psychological questions, clinical questions, speech task, and feedback.
 
-2. [Order of presentation](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L50)
-    
+3. [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`.
 
-3. [Additional UI settings](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L23)
+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.
 
-4. Update [README.md](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/README.md)
+5. 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.
-	
+
 Upon finalizing our protocol with the integrated activities, the end result is a fully interactive research tool hosted on our GitHub repository. For data collection, this tool can be linked to a backend server, or participants can be given the option to export their data directly.
diff --git a/docs/46_tools.md b/docs/46_tools.md
@@ -4,15 +4,15 @@ In the world of research data management, flexibility and compatibility are key.
 
 ## Install reproschema-py
 
-```
+```bash
 pip install reproschema
 ```
 
 ## CLI usage
 
 `reproschema-py` can be used as a Commend-Line Interface.
 
-```
+```bash
 $ reproschema
 Usage: reproschema [OPTIONS] COMMAND [ARGS]...
 
@@ -41,43 +41,51 @@ Commands:
 
 To convert ReproSchema protocol to REDCap CSV format, use the following command
 
-```
+```bash
 reproschema reproschema2redcap <input_dir_path> <output_csv_filename>
 ```
 
 - `<input_dir_path>`: 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
   cd reproschema-demo-protocol
   pwd
   ```
+
   In this case,  the output from `pwd` (which shows your current directory path)should be your `<input_dir_path>`.
 - `<output_csv_filename>`: The name of the output CSV file where the converted data will be saved.
 
 ## `redcap2reproschema` Usage
+
 The `redcap2reproschema` function is designed to process a given REDCap CSV file and YAML configuration to generate the output in the reproschema format.
 
 ### Prerequisites
+
 Before the conversion, ensure you have the following:
 
 **YAML Configuration File**:
-   - Download [templates/redcap2rs.yaml](templates/redcap2rs.yaml) and fill it out with your protocol details.
+
+- Download [templates/redcap2rs.yaml](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.
 
 Example:
+
 ```yaml
 protocol_name: "My_Protocol"
 protocol_display_name: "Assessment Protocol"
 protocol_description: "This protocol is for assessing cognitive skills."
 ```
 
-The `redcap2reproschema`` function has been integrated into a CLI tool, use the following command:
+The `redcap2reproschema` function has been integrated into a CLI tool, use the following command:
+
 ```bash
 reproschema redcap2reproschema path/to/your_redcap_data_dic.csv path/to/your_redcap2rs.yaml
 ```