diff --git a/docs/41_create_new_protocol.md b/docs/41_create_new_protocol.md index c8d9ae01c..c5aff6c06 100644 --- 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. \ No newline at end of file +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 index d888b2c54..5366aaece 100644 --- 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,12 +120,12 @@ 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" + ] } ``` @@ -126,12 +133,14 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass - `"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 index ddf586871..46dc7226f 100644 --- 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: "" 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 index 3c2c69c69..634a6c5b1 100644 --- a/docs/45_finalize_protocol.md +++ b/docs/45_finalize_protocol.md @@ -7,8 +7,9 @@ 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", @@ -16,18 +17,19 @@ After setting up individual activities, we return to the main [protocol 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 index 5f2770d8a..78e813b39 100644 --- a/docs/46_tools.md +++ b/docs/46_tools.md @@ -4,7 +4,7 @@ In the world of research data management, flexibility and compatibility are key. ## Install reproschema-py -``` +```bash pip install reproschema ``` @@ -12,7 +12,7 @@ pip install reproschema `reproschema-py` can be used as a Commend-Line Interface. -``` +```bash $ reproschema Usage: reproschema [OPTIONS] COMMAND [ARGS]... @@ -41,29 +41,35 @@ Commands: To convert ReproSchema protocol to REDCap CSV format, use the following command -``` +```bash 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: + ```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 ``. - ``: 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. @@ -71,13 +77,15 @@ In the `templates/redcap2rs.yaml` file, provide the following information: - **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 ``` diff --git a/docs/98_FAQ.md b/docs/98_FAQ.md index b17c36055..dccb54141 100644 --- a/docs/98_FAQ.md +++ b/docs/98_FAQ.md @@ -65,12 +65,8 @@ OK before we go for JSON-LD, let's start with JSON. JSON stands for JavaScript O 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 {"status":"success","data":[{"id":"1","employee_name":"Tiger Nixon","employee_salary":"320800","employee_age":"61","profile_image":""},{"id":"2","employee_name":"Garrett Winters","employee_salary":"170750","employee_age":"63","profile_image":""},{"id":"3","employee_name":"Ashton Cox","employee_salary":"86000","employee_age":"66","profile_image":""},{"id":"4","employee_name":"Cedric Kelly","employee_salary":"433060","employee_age":"22","profile_image":""},{"id":"5","employee_name":"Airi Satou","employee_salary":"162700","employee_age":"33","profile_image":""},{"id":"6","employee_name":"Brielle Williamson","employee_salary":"372000","employee_age":"61","profile_image":""},{"id":"7","employee_name":"Herrod Chandler","employee_salary":"137500","employee_age":"59","profile_image":""},{"id":"8","employee_name":"Rhona Davidson","employee_salary":"327900","employee_age":"55","profile_image":""},{"id":"9","employee_name":"Colleen Hurst","employee_salary":"205500","employee_age":"39","profile_image":""},{"id":"10","employee_name":"Sonya Frost","employee_salary":"103600","employee_age":"23","profile_image":""},{"id":"11","employee_name":"Jena Gaines","employee_salary":"90560","employee_age":"30","profile_image":""},{"id":"12","employee_name":"Quinn Flynn","employee_salary":"342000","employee_age":"22","profile_image":""},{"id":"13","employee_name":"Charde Marshall","employee_salary":"470600","employee_age":"36","profile_image":""},{"id":"14","employee_name":"Haley Kennedy","employee_salary":"313500","employee_age":"43","profile_image":""},{"id":"15","employee_name":"Tatyana Fitzpatrick","employee_salary":"385750","employee_age":"19","profile_image":""},{"id":"16","employee_name":"Michael Silva","employee_salary":"198500","employee_age":"66","profile_image":""},{"id":"17","employee_name":"Paul Byrd","employee_salary":"725000","employee_age":"64","profile_image":""},{"id":"18","employee_name":"Gloria Little","employee_salary":"237500","employee_age":"59","profile_image":""},{"id":"19","employee_name":"Bradley Greer","employee_salary":"132000","employee_age":"41","profile_image":""},{"id":"20","employee_name":"Dai Rios","employee_salary":"217500","employee_age":"35","profile_image":""},{"id":"21","employee_name":"Jenette Caldwell","employee_salary":"345000","employee_age":"30","profile_image":""},{"id":"22","employee_name":"Yuri Berry","employee_salary":"675000","employee_age":"40","profile_image":""},{"id":"23","employee_name":"Caesar Vance","employee_salary":"106450","employee_age":"21","profile_image":""},{"id":"24","employee_name":"Doris Wilder","employee_salary":"85600","employee_age":"23","profile_image":""}]} @@ -79,12 +75,8 @@ 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. - - **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. ```json @@ -133,7 +125,6 @@ directly into the [JSON-LD playground](https://json-ld.org/playground/) to see w - ## Why is linked data important for the ReproSchema ? ## Which assessments tools will/are supporting this standard? @@ -190,4 +181,4 @@ But to get access to the raw content of that file you must click on the `Raw` bu [https://raw.githubusercontent.com/ReproNim/demo-protocol/master/VoicePilot/VoicePilot_schema](https://raw.githubusercontent.com/ReproNim/demo-protocol/master/VoicePilot/VoicePilot_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). +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).