From 3d8e3937f33cc158cfce9835e3c43f555042bac5 Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Fri, 15 Dec 2023 20:40:53 +0000 Subject: [PATCH 01/12] change Reproschema to ReproSchema --- docs/01_introduction.md | 10 +++++----- docs/20_project_structure.md | 34 +++++++++++++++++----------------- docs/98_FAQ.md | 16 ++++++++-------- 3 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/01_introduction.md b/docs/01_introduction.md index 60b510452d..524ebf9732 100644 --- a/docs/01_introduction.md +++ b/docs/01_introduction.md @@ -60,7 +60,7 @@ by the work of [CEDAR Metadata Model](https://more.metadatacenter.org/tools-trai In this project we provide a comprehensive set of tools to create and use the schemas, while tracking the source of the schema, and changes to it over time. -The Reproschema project covers: +The ReproSchema project covers: 1. a schema that can be found [in the present repository](https://github.com/ReproNim/reproschema) that describes the content and relations of the different elements of a @@ -73,7 +73,7 @@ questionnaire and collect data locally, 5. a [backend server](https://github.com/sensein/voice-backend) to capture the data remotely. -In brief, Reproschema offers a way to standardize the underlying representation +In brief, ReproSchema offers a way to standardize the underlying representation of assessment tools. It comes with an open and accessible library of questionnaires with appropriate conversion (e.g., from/to [RedCap](https://www.project-redcap.org/)) and data collection tools (e.g., [MindLogger](https://mindlogger.org/), @@ -112,7 +112,7 @@ and 3 `items`. └── protocol1_schema.jsonld ``` -The Reproschema can also easily and flexibly specify details how the schema +The ReproSchema can also easily and flexibly specify details how the schema for an assessment should be used. Independently of what solution is chosen in the end by a researcher, a lab, or an institute to display the assessment to their participants or patients (for example whether using an Web-app written in javascript @@ -125,9 +125,9 @@ displayed to the user and under which conditions, - the `compute logic` of how the total score to the responses on a questionnaire should be computed -The Reproschema also allows for internationalization and multiple languages support +The ReproSchema also allows for internationalization and multiple languages support by making it very easy to keep everything the same except the language displayed by the user interface. -Finally Reproschema allows tracking of variations and version of different assessments +Finally ReproSchema allows tracking of variations and version of different assessments tools (e.g., PHQ-9, PHQ-8). diff --git a/docs/20_project_structure.md b/docs/20_project_structure.md index 5dddccd8a9..0472b494f1 100644 --- a/docs/20_project_structure.md +++ b/docs/20_project_structure.md @@ -1,20 +1,20 @@ # Project structure -The Reproschema project is organized around several github repositories. The +The ReproSchema project is organized around several github repositories. The main ones are the following. -- [Reproschema](https://github.com/ReproNim/reproschema) -- [Reproschema-library](https://github.com/ReproNim/reproschema-library) -- [Reproschema-ui](https://github.com/ReproNim/reproschema-ui) -- [Reproschema-py](https://github.com/ReproNim/reproschema-py) +- [reproschema](https://github.com/ReproNim/reproschema) +- [reproschema-library](https://github.com/ReproNim/reproschema-library) +- [reproschema-ui](https://github.com/ReproNim/reproschema-ui) +- [reproschema-py](https://github.com/ReproNim/reproschema-py) A brief description of how they all interact could be along the following lines: ->If you are about to start a new study that needs you to use some standardized assessments, you can create new **Reproschema** `protocol` either by reusing some of the ones that we have already created and are listed in the `activities` of the **Reproschema-library**, or by using the tools of **Reproschema-py** to create the `activities` describing new questionnaires you might want to use. You can also use the **Reproschema-py** to make sure that the these `activities` conform to the specifications described in the **Reproschema**. Once you have added all the `activities` to your study `protocol`, you can use the **Reproschema-ui** to visualize the `protocol` and collect data. +>If you are about to start a new study that needs you to use some standardized assessments, you can create new **ReproSchema** `protocol` either by reusing some of the ones that we have already created and are listed in the `activities` of the **reproschema-library**, or by using the tools of **reproschema-py** to create the `activities` describing new questionnaires you might want to use. You can also use the **reproschema-py** to make sure that the these `activities` conform to the specifications described in the **reproschema**. Once you have added all the `activities` to your study `protocol`, you can use the **reproschema-ui** to visualize the `protocol` and collect data. -## [Reproschema](https://github.com/ReproNim/reproschema) +## [reproschema](https://github.com/ReproNim/reproschema) -This repository contains the actual Reproschema with the [`contexts`](https://github.com/ReproNim/reproschema/tree/master/contexts) +This repository contains the actual ReproSchema with the [`contexts`](https://github.com/ReproNim/reproschema/tree/master/contexts) of the schema and the [`terms`](https://github.com/ReproNim/reproschema/tree/master/terms) that define its different elements and how they relate to each other and to other external entities. @@ -27,10 +27,10 @@ There is also an [`example`](https://github.com/ReproNim/reproschema/tree/master schema that can help give you a quick overview of what the protocol and activity for a study might look like. For more details see the [schema section](../30_schema). -## [Reproschema-library](https://github.com/ReproNim/reproschema-library) +## [reproschema-library](https://github.com/ReproNim/reproschema-library) This [repository](https://github.com/ReproNim/reproschema-library) hosts all the -community curated assessments and questionnaires that support the Reproschema +community curated assessments and questionnaires that support the ReproSchema standard. Imagine this as curated library of reusable assessments and questionnaires, from @@ -42,21 +42,21 @@ All assessments are listed in [the `activity` folder](https://github.com/ReproNi and are served [here](https://schema.repronim.org/rl/) if you want to visualize them. -## [Reproschema-ui](https://github.com/ReproNim/reproschema-ui) +## [reproschema-ui](https://github.com/ReproNim/reproschema-ui) This repository contains the code for the user-interface for the ReproSchema to visualize questionnaires and collect data. You can see it in action [here](https://www.repronim.org/reproschema-ui/) -## [Reproschema-py](https://github.com/ReproNim/reproschema-py) +## [reproschema-py](https://github.com/ReproNim/reproschema-py) -This is the Reproschema python library. This is a python Command Line Interface (CLI) +This is the ReproSchema python library. This is a python Command Line Interface (CLI) that allows you to help create and validate the schemas of new assessments. - test that a schema for a `protocol`, `activity` or `item` is valid and matches -the specification of the Reproschema -- convert a csv file of a questionnaire into its equivalent Reproschema +the specification of the ReproSchema +- convert a csv file of a questionnaire into its equivalent ReproSchema ## Other repositories @@ -69,8 +69,8 @@ This repository contain a full fledge protocol that can be used as demonstration This contains some additional information on how the activities are served on [https://schema.repronim.org/rl/](https://schema.repronim.org/rl/). -### [Reproschema-builder](https://github.com/ReproNim/reproschema-builder) +### [reproschema-builder](https://github.com/ReproNim/reproschema-builder) This repository contains a javascript conversion tool that have been used to create some of our activities, and can be used to convert RedCap data -dictionaries to Reproschema. +dictionaries to ReproSchema. diff --git a/docs/98_FAQ.md b/docs/98_FAQ.md index b474c7b15f..b17c36055b 100644 --- a/docs/98_FAQ.md +++ b/docs/98_FAQ.md @@ -134,27 +134,27 @@ directly into the [JSON-LD playground](https://json-ld.org/playground/) to see w -## Why is linked data important for the Reproschema ? +## Why is linked data important for the ReproSchema ? ## Which assessments tools will/are supporting this standard? -At the moment, all the assessments that support this standard are listed in [this folder](https://github.com/ReproNim/reproschema-library/tree/master/activities) or the [Reproschema-library repository](https://github.com/ReproNim/reproschema-library). +At the moment, all the assessments that support this standard are listed in [this folder](https://github.com/ReproNim/reproschema-library/tree/master/activities) or the [reproschema-library repository](https://github.com/ReproNim/reproschema-library). 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). +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? +## Why should I use ReproSchema? **πŸ›  Work in progress πŸ› ** -## Who is Reproschema for? +## Who is ReproSchema for? **πŸ›  Work in progress πŸ› ** -## How can I know if a certain property is supported by Reproschema? +## How can I know if a certain property is supported by ReproSchema? **πŸ›  Work in progress πŸ› ** @@ -170,13 +170,13 @@ The Reproschema is also used to develop a checklist to [improve methods and resu **πŸ›  Work in progress πŸ› ** -## An assessment tool I regularly use is not supported by Reproschema: how can I add it? +## 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 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: From bb3df34d11893fdbe9594fed9c0e987a104c47dc Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Fri, 15 Dec 2023 20:42:47 +0000 Subject: [PATCH 02/12] change Reproschema to ReproSchema --- docs/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index 147b87cd2e..875700410f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Welcome to the Reproschema documentation +# Welcome to the ReproSchema documentation Date: Fri, 15 Dec 2023 21:07:47 +0000 Subject: [PATCH 03/12] add create_new_protocol.md --- README.md | 2 +- docs/41_create_new_protocol.md | 95 ++++++++++++++++++++++++++++++++++ mkdocs.yml | 7 ++- 3 files changed, 101 insertions(+), 3 deletions(-) create mode 100644 docs/41_create_new_protocol.md diff --git a/README.md b/README.md index ad2a5bf51f..535b1db922 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ To see the documentation concerning the ReproNim schema specification [click her This repository contains: -- the [different terms of the Reproschema](./terms) +- the [different terms of the ReproSchema](./terms) - the [corresponding context files](./contexts) - a example of [a protocol based on the reproschema](./examples) - the [validation SHACL files](./validation) diff --git a/docs/41_create_new_protocol.md b/docs/41_create_new_protocol.md new file mode 100644 index 0000000000..eb428a4a6a --- /dev/null +++ b/docs/41_create_new_protocol.md @@ -0,0 +1,95 @@ +# Creating a Research Protocol + +[TODO] add some explanations + +## Step 1: Setting Up a Project Repository + +1. **Clone the demo-protocol repository**: + Start by cloning the demo-protocol provided by ReproNim using the following command in your terminal: + ```bash + git clone https://github.com/ReproNim/demo-protocol.git + ``` + This command creates a local copy of the demo-protocol on your computer. + +2. **Rename the project**: + Rename the cloned directory to match your project's name. In this example, we'll call it `reproschema-demo`: + ```bash + mv demo-protocol reproschema-demo cd reproschema-demo + ``` + +## Step 2: Create a New Repository on GitHub + +1. **Create a new repository**: + + Visit your GitHub account and create a new repository named `reproschema-demo`. Ensure you do not initialize this new repository with a README, .gitignore, or license file. + +2. **Set up the remote repository**: + - Remove the existing origin with the command: + ```bash + git remote remove origin + ``` + - Add a new origin, which is the repository you just created on GitHub: + ```bash + git remote add origin https://github.com/[yourusername]/reproschema-demo.git + ``` + - Set the default branch to 'main' and push your changes: + ```bash + git branch -M main git push -u origin main + ``` + +3. **Create the gh-pages branch**: + - Fetch the latest changes from your repository (if any): + ```bash + git fetch origin + ``` + - Create and switch to the new gh-pages branch: + ```bash + git checkout -b gh-pages + ``` + This branch allows you to deploy your ReproSchema UI publicly. + +## Step 3: Customizing the Cloned Demo-Protocol + +### Editing the DemoProtocol and README.md + +1. **Rename the DemoProtocol Folder**: + + Change the folder name 'DemoProtocol' to something more reflective of your project. + +2. **Modify the Schema File**: + + In the 'DemoProtocol' folder, rename `DemoProtocol_schema` to a name of your choice, e.g., `younameit_schema`. Update the "@id" on line 4 from `"@id": "DemoProtocol_schema"` to `"@id": "younameit_schema"`. + +3. **Update the description**: + + Edit the description field in the schema file (line 9) to align with your research. + +4. **Revise the README.md file**: + + Update the README.md file to reflect the nature and objectives of your research protocol. + +### Updating the config.js file in the ui-changes/src folder + +1. **Update the schema source Link**: + + Replace the 'githubSrc' link with the raw content link of your schema. + +2. **Adjust the assetsPublicPath**: + + Change `assetsPublicPath: '/demo-protocol/'` to match your repository's name, e.g., `assetsPublicPath: '/reproschema-demo/'`. Example `config.js` content: + ```javascript + module.exports = { + /* eslint-disable */ + githubSrc: 'https://raw.githubusercontent.com/[yourusername]/reproschema-demo/main/DemoProtocol/[younameit]_schema', + banner: 'This is a custom protocol for ReproSchema.', + startButton: 'Join', + assetsPublicPath: '/reproschema-demo/', + backendServer: null + } + ``` + +### Update the build_deploy.yml file in the .github/workflows folder + +- **Modify the validation command**: Change the line `reproschema -l DEBUG validate DemoProtocol/DemoProtocol_schema` to reflect your new folder and schema file names, e.g., `reproschema -l DEBUG validate [yourfoldername]/[younameit]_schema`. + +These steps are essential for tailoring the demo-protocol to your research project, ensuring that all links, paths, and descriptions accurately represent your study. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index e529604123..668f503158 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: Reproschema documentation +site_name: ReproSchema documentation repo_name: "ReproNim/reproschema" repo_url: "https://github.com/ReproNim/reproschema" copyright: "CC-BY 4.0" @@ -19,10 +19,13 @@ nav: - Introduction: "01_introduction.md" - Project structure: "20_project_structure.md" - Schema: "30_schema.md" + - How-To-Guide: + - Create a research Protocol: "41_create_new_protocol.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: - # - Reproschema: "81_contribute_to_schema.md" + # - ReproSchema: "81_contribute_to_schema.md" # - Assesement library: "82_contribute_to_library.md" # - Python package: "83_contribute_to_python.md" # - User-interface: "84_contribute_to_ui.md" From cd549fbb1bcc0ff42b085b209357777e71fb4eb0 Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Fri, 15 Dec 2023 21:36:12 +0000 Subject: [PATCH 04/12] add 42_adopt_assessments.md --- docs/42_adopt_assessments.md | 134 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 3 +- 2 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 docs/42_adopt_assessments.md diff --git a/docs/42_adopt_assessments.md b/docs/42_adopt_assessments.md new file mode 100644 index 0000000000..d8b4ddfa1c --- /dev/null +++ b/docs/42_adopt_assessments.md @@ -0,0 +1,134 @@ +# Integrating Assessments from the reproschema-library + +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. + +To illustrate this process, we will use two specific types of assessments from the 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 +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. + +## 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**: + + 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. + +## Step 3: Integrating multiple assessments + +Different from `demograpgics`, `psychological_questionnaire_schema` combines assessments, such as PHQ-9, GAD7, PC-PTSD-5, and demographics from the reproschema-library. + +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", + { + "activities": "https://raw.githubusercontent.com/ReproNim/reproschema-library/[commitID]/activities/", + "demo": "https://raw.githubusercontent.com/ReproNim/reproschema-library/[commitID]/activities/demographics_and_background_information_v1/items/" + } + ] + ``` + 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.)**: + + 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)**: + + ```javascript + "ui": { + "addProperties": [ + { + "variableName": "phq-9", + "isAbout": "activities:PHQ-9/PHQ9_schema" + }, + { + "variableName": "gad-7", + "isAbout": "activities:GAD7/GAD7_schema" + }, + { + "variableName": "pc-ptsd-5", + "isAbout": "activities:PC-PTSD-5/PC-PTSD-5_schema" + }, + { + "variableName": "clinical_history_psychiatry", + "isAbout": "demo:clinical_history_psychiatry" + }, + { + "variableName": "clinical_history_psychiatry_other", + "isAbout": "demo:clinical_history_psychiatry_other" + }, + { + "variableName": "clinical_history_psychiatry_current", + "isAbout": "demo:clinical_history_psychiatry_current" + }, + { + "variableName": "clinical_history_psychiatry_current_only_some", + "isAbout": "demo:clinical_history_psychiatry_current_only_some" + }, + { + "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", + "activities:PC-PTSD-5/PC-PTSD-5_schema", + "demo:clinical_history_psychiatry", + "demo:clinical_history_psychiatry_other", + "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" + ] + } + ``` + + 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/mkdocs.yml b/mkdocs.yml index 668f503158..dc63ce0c19 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,7 +20,8 @@ nav: - Project structure: "20_project_structure.md" - Schema: "30_schema.md" - How-To-Guide: - - Create a research Protocol: "41_create_new_protocol.md" + - Create a research protocol: "41_create_new_protocol.md" + - Adopt assessments from the library: "42_adopt_assessments.md" # - Creating a new activity and protocol: "create_new_activity_protocol.md" # - Testing your schema and collecting data: "testing_using_schema.md" From b5418807ba4b643d1d5e8c63495df224989a32fb Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Fri, 15 Dec 2023 21:59:17 +0000 Subject: [PATCH 05/12] docs/43_create_new_assess.md --- docs/42_adopt_assessments.md | 2 +- docs/43_create_new_assess.md | 97 ++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 docs/43_create_new_assess.md diff --git a/docs/42_adopt_assessments.md b/docs/42_adopt_assessments.md index d8b4ddfa1c..7e0b8bcb1b 100644 --- a/docs/42_adopt_assessments.md +++ b/docs/42_adopt_assessments.md @@ -1,4 +1,4 @@ -# Integrating Assessments from the reproschema-library +# Adopting Assessments from the reproschema-library 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. diff --git a/docs/43_create_new_assess.md b/docs/43_create_new_assess.md new file mode 100644 index 0000000000..8615452753 --- /dev/null +++ b/docs/43_create_new_assess.md @@ -0,0 +1,97 @@ +# 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`. 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`. + This folder contains the `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: "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/mkdocs.yml b/mkdocs.yml index dc63ce0c19..ef877ee054 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,6 +22,7 @@ nav: - How-To-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" # - Creating a new activity and protocol: "create_new_activity_protocol.md" # - Testing your schema and collecting data: "testing_using_schema.md" From 241ec96b3ae394cbdafbbf1f37480a7b9c2baca3 Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Fri, 15 Dec 2023 22:05:37 +0000 Subject: [PATCH 06/12] add 44_setup_feedback.md --- docs/44_setup_feedback.md | 31 +++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 32 insertions(+) create mode 100644 docs/44_setup_feedback.md diff --git a/docs/44_setup_feedback.md b/docs/44_setup_feedback.md new file mode 100644 index 0000000000..cec327a3d8 --- /dev/null +++ b/docs/44_setup_feedback.md @@ -0,0 +1,31 @@ +# Adding a customized feedback section + +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 +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", + "@type": "reproschema:Field", + "@id": "feedback", + "prefLabel": "Feedback", + "description": "schema to record text response of overall feedback of the protocol", + "schemaVersion": "1.0.0-rc4", + "version": "0.0.1", + "question": { + "en": "Please leave any comments or suggestions on the study so we can improve it (or skip):", + "es": "Deje cualquier comentario o sugerencia sobre el estudio para que podamos mejorarlo (u omitir):" + }, + "ui": { + "inputType": "textarea" + }, + "responseOptions": { + "valueType": "xsd:string" + } +} +``` + +The `feedback` item in this activity (`5_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"`. diff --git a/mkdocs.yml b/mkdocs.yml index ef877ee054..566a99d6b4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,6 +23,7 @@ nav: - 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" # - Creating a new activity and protocol: "create_new_activity_protocol.md" # - Testing your schema and collecting data: "testing_using_schema.md" From 8fe7009acf40477b39a92c331935adfc97f34ac4 Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Fri, 15 Dec 2023 22:09:14 +0000 Subject: [PATCH 07/12] add 45_finalize_protocol.md --- docs/45_finalize_protocol.md | 28 ++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 29 insertions(+) create mode 100644 docs/45_finalize_protocol.md diff --git a/docs/45_finalize_protocol.md b/docs/45_finalize_protocol.md new file mode 100644 index 0000000000..b941670ea6 --- /dev/null +++ b/docs/45_finalize_protocol.md @@ -0,0 +1,28 @@ +# Finalizing the Protocol + +After setting up individual activities, we return to the main 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 + + 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 consent activity is linked as + ```javascript + { + "isAbout": "../activities/0_consent/consent_schema", + "variableName": "consent_schema", + "prefLabel": {"en": "Sign Consent"} + } + ``` + This structure is repeated for each activity, including audio check, demographics, psychological questions, clinical questions, speech task, and feedback. + +2. Order of presentation + + 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: + - 'shuffle' is set to false to maintain the specified order. + - 'allow' includes functionalities such as 'reproschema:AllowExport' for data exporting options. + +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/mkdocs.yml b/mkdocs.yml index 566a99d6b4..81d31d7aa4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,6 +24,7 @@ nav: - 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" # - Creating a new activity and protocol: "create_new_activity_protocol.md" # - Testing your schema and collecting data: "testing_using_schema.md" From fbd482e0ad2bf9ae62910de88de27c7c6b24a037 Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Sun, 31 Dec 2023 15:54:44 +0000 Subject: [PATCH 08/12] update creating a new repo --- docs/41_create_new_protocol.md | 102 +++------------------------------ 1 file changed, 9 insertions(+), 93 deletions(-) diff --git a/docs/41_create_new_protocol.md b/docs/41_create_new_protocol.md index eb428a4a6a..88e9eb252d 100644 --- a/docs/41_create_new_protocol.md +++ b/docs/41_create_new_protocol.md @@ -1,95 +1,11 @@ -# Creating a Research Protocol +# Creating a Research Protocol Using Cookiecutter -[TODO] add some explanations +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. -## Step 1: Setting Up a Project Repository - -1. **Clone the demo-protocol repository**: - Start by cloning the demo-protocol provided by ReproNim using the following command in your terminal: - ```bash - git clone https://github.com/ReproNim/demo-protocol.git - ``` - This command creates a local copy of the demo-protocol on your computer. - -2. **Rename the project**: - Rename the cloned directory to match your project's name. In this example, we'll call it `reproschema-demo`: - ```bash - mv demo-protocol reproschema-demo cd reproschema-demo - ``` - -## Step 2: Create a New Repository on GitHub - -1. **Create a new repository**: - - Visit your GitHub account and create a new repository named `reproschema-demo`. Ensure you do not initialize this new repository with a README, .gitignore, or license file. - -2. **Set up the remote repository**: - - Remove the existing origin with the command: - ```bash - git remote remove origin - ``` - - Add a new origin, which is the repository you just created on GitHub: - ```bash - git remote add origin https://github.com/[yourusername]/reproschema-demo.git - ``` - - Set the default branch to 'main' and push your changes: - ```bash - git branch -M main git push -u origin main - ``` - -3. **Create the gh-pages branch**: - - Fetch the latest changes from your repository (if any): - ```bash - git fetch origin - ``` - - Create and switch to the new gh-pages branch: - ```bash - git checkout -b gh-pages - ``` - This branch allows you to deploy your ReproSchema UI publicly. - -## Step 3: Customizing the Cloned Demo-Protocol - -### Editing the DemoProtocol and README.md - -1. **Rename the DemoProtocol Folder**: - - Change the folder name 'DemoProtocol' to something more reflective of your project. - -2. **Modify the Schema File**: - - In the 'DemoProtocol' folder, rename `DemoProtocol_schema` to a name of your choice, e.g., `younameit_schema`. Update the "@id" on line 4 from `"@id": "DemoProtocol_schema"` to `"@id": "younameit_schema"`. - -3. **Update the description**: - - Edit the description field in the schema file (line 9) to align with your research. - -4. **Revise the README.md file**: - - Update the README.md file to reflect the nature and objectives of your research protocol. - -### Updating the config.js file in the ui-changes/src folder - -1. **Update the schema source Link**: - - Replace the 'githubSrc' link with the raw content link of your schema. - -2. **Adjust the assetsPublicPath**: - - Change `assetsPublicPath: '/demo-protocol/'` to match your repository's name, e.g., `assetsPublicPath: '/reproschema-demo/'`. Example `config.js` content: - ```javascript - module.exports = { - /* eslint-disable */ - githubSrc: 'https://raw.githubusercontent.com/[yourusername]/reproschema-demo/main/DemoProtocol/[younameit]_schema', - banner: 'This is a custom protocol for ReproSchema.', - startButton: 'Join', - assetsPublicPath: '/reproschema-demo/', - backendServer: null - } - ``` - -### Update the build_deploy.yml file in the .github/workflows folder - -- **Modify the validation command**: Change the line `reproschema -l DEBUG validate DemoProtocol/DemoProtocol_schema` to reflect your new folder and schema file names, e.g., `reproschema -l DEBUG validate [yourfoldername]/[younameit]_schema`. - -These steps are essential for tailoring the demo-protocol to your research project, ensuring that all links, paths, and descriptions accurately represent your study. \ No newline at end of file +## 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. \ No newline at end of file From fdacd189b57c07e17f3ae3dbdf11c3e6bb8f6705 Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Wed, 3 Jan 2024 21:12:33 +0000 Subject: [PATCH 09/12] update details --- docs/41_create_new_protocol.md | 13 ++++++++++++- docs/42_adopt_assessments.md | 8 +++++--- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/41_create_new_protocol.md b/docs/41_create_new_protocol.md index 88e9eb252d..a91dde112b 100644 --- a/docs/41_create_new_protocol.md +++ b/docs/41_create_new_protocol.md @@ -8,4 +8,15 @@ Ready for your first ReproSchema project?! We are going to use the [Reproschema ```bash cookiecutter gh:ReproNim/reproschema-protocol-cookiecutter ``` -3. Follow the prompts to customize your new protocol. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/42_adopt_assessments.md b/docs/42_adopt_assessments.md index 7e0b8bcb1b..18324c18f7 100644 --- a/docs/42_adopt_assessments.md +++ b/docs/42_adopt_assessments.md @@ -4,9 +4,9 @@ This part focuses on how to select and integrate assessments from the reproschem 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 the 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. +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 +## 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. @@ -43,9 +43,11 @@ This step involves precise modifications, particularly in the `@context` and `ad 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. +See the outcome file [here](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/1_demographics/demographics_schema) + ## Step 3: Integrating multiple assessments -Different from `demograpgics`, `psychological_questionnaire_schema` combines assessments, such as PHQ-9, GAD7, PC-PTSD-5, and demographics from the 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)**: From 07d08dff24bb37f97819d62173743a27d4f5ebcc Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Wed, 3 Jan 2024 21:14:23 +0000 Subject: [PATCH 10/12] update details --- docs/41_create_new_protocol.md | 2 +- docs/42_adopt_assessments.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/41_create_new_protocol.md b/docs/41_create_new_protocol.md index a91dde112b..c8d9ae01ce 100644 --- a/docs/41_create_new_protocol.md +++ b/docs/41_create_new_protocol.md @@ -19,4 +19,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. \ 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. \ No newline at end of file diff --git a/docs/42_adopt_assessments.md b/docs/42_adopt_assessments.md index 18324c18f7..bcff4aea4b 100644 --- a/docs/42_adopt_assessments.md +++ b/docs/42_adopt_assessments.md @@ -123,7 +123,7 @@ 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. + - `"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 @@ -133,4 +133,4 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass } ``` - 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 `shuffle` setting is `false`, maintaining the defined order, and allow includes functionalities like auto-advance between assessments and data export. From db9a475785891c731505d290a7b7385f3dae2537 Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Wed, 3 Jan 2024 21:40:35 +0000 Subject: [PATCH 11/12] add new section & rename --- docs/42_adopt_assessments.md | 4 +++- docs/43_create_new_assess.md | 19 ++++++++++++------- docs/44_setup_feedback.md | 2 +- docs/45_finalize_protocol.md | 21 +++++++++++++-------- docs/46_tools.md | 5 +++++ mkdocs.yml | 3 ++- 6 files changed, 36 insertions(+), 18 deletions(-) create mode 100644 docs/46_tools.md diff --git a/docs/42_adopt_assessments.md b/docs/42_adopt_assessments.md index bcff4aea4b..d888b2c544 100644 --- a/docs/42_adopt_assessments.md +++ b/docs/42_adopt_assessments.md @@ -124,7 +124,7 @@ 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. + - 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 { @@ -134,3 +134,5 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass ``` - 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) \ No newline at end of file diff --git a/docs/43_create_new_assess.md b/docs/43_create_new_assess.md index 8615452753..ddf586871d 100644 --- a/docs/43_create_new_assess.md +++ b/docs/43_create_new_assess.md @@ -2,12 +2,14 @@ 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`. 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. +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. + +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. @@ -21,9 +23,10 @@ The structure of an item within the `items` folder of a ReproSchema activity is ## 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. +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?", @@ -57,7 +60,8 @@ Take 'alcohol_consumption' as an example. The UI configuration and response opti - 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: +- 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" @@ -80,10 +84,11 @@ We can integrate additional components tailored to the unique requirements of sp 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`. - This folder contains the `audio_check_schema`, a schema specifically designed to test and confirm that the audio recording system is operational and effective for participants. + 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", diff --git a/docs/44_setup_feedback.md b/docs/44_setup_feedback.md index cec327a3d8..a5d7dc761c 100644 --- a/docs/44_setup_feedback.md +++ b/docs/44_setup_feedback.md @@ -24,7 +24,7 @@ To conclude our protocol, we integrate a customized feedback activity. This choi } ``` -The `feedback` item in this activity (`5_feedback`) is specifically designed to gather open-ended responses, allowing participants to share their thoughts and suggestions: +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. diff --git a/docs/45_finalize_protocol.md b/docs/45_finalize_protocol.md index b941670ea6..3c2c69c69f 100644 --- a/docs/45_finalize_protocol.md +++ b/docs/45_finalize_protocol.md @@ -1,28 +1,33 @@ # Finalizing the Protocol -After setting up individual activities, we return to the main 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 - The '@context', '@type', '@id', and descriptive fields ('prefLabel', 'description', etc.) provide the foundational information about the protocol. + 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 consent 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_consent/consent_schema", - "variableName": "consent_schema", - "prefLabel": {"en": "Sign Consent"} + "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 +2. [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: +3. [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) + + 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 new file mode 100644 index 0000000000..8c1f94227a --- /dev/null +++ b/docs/46_tools.md @@ -0,0 +1,5 @@ +# Converting between ReproSchema and REDCap + +In the world of research data management, flexibility and compatibility are key. Understanding this, we provide specialized tools designed to seamlessly convert data between ReproSchema format and REDCap CSV format. Whether you're transitioning from REDCap to ReproSchema or vice versa, these tools ensure a smooth and efficient conversion process, preserving the integrity and structure of your data. + +For detailed instructions on how to use these conversion tools, please visit [reproschema-py](https://github.com/ReproNim/reproschema-py). This link provides comprehensive guidance on usage, ensuring you can easily adapt your data to the format best suited for your research needs. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 81d31d7aa4..1562026a64 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,12 +19,13 @@ nav: - Introduction: "01_introduction.md" - Project structure: "20_project_structure.md" - Schema: "30_schema.md" - - How-To-Guide: + - 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" + - Additional tools: "46_tools.md" # - Creating a new activity and protocol: "create_new_activity_protocol.md" # - Testing your schema and collecting data: "testing_using_schema.md" From d21e376ebc4f42714e28e9b0fabfbb1e07b70284 Mon Sep 17 00:00:00 2001 From: Yibei Chen Date: Wed, 10 Jan 2024 20:55:20 +0000 Subject: [PATCH 12/12] update the tool page --- docs/46_tools.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++-- mkdocs.yml | 2 +- 2 files changed, 84 insertions(+), 4 deletions(-) diff --git a/docs/46_tools.md b/docs/46_tools.md index 8c1f94227a..5f2770d8ae 100644 --- a/docs/46_tools.md +++ b/docs/46_tools.md @@ -1,5 +1,85 @@ -# Converting between ReproSchema and REDCap +# Toolkit -In the world of research data management, flexibility and compatibility are key. Understanding this, we provide specialized tools designed to seamlessly convert data between ReproSchema format and REDCap CSV format. Whether you're transitioning from REDCap to ReproSchema or vice versa, these tools ensure a smooth and efficient conversion process, preserving the integrity and structure of your data. +In the world of research data management, flexibility and compatibility are key. Understanding this, we provide specialized tools designed to create, validata schemas, and convert data between ReproSchema format and REDCap CSV format. Whether you're transitioning from REDCap to ReproSchema or vice versa, these tools ensure a smooth and efficient conversion process, preserving the integrity and structure of your data. -For detailed instructions on how to use these conversion tools, please visit [reproschema-py](https://github.com/ReproNim/reproschema-py). This link provides comprehensive guidance on usage, ensuring you can easily adapt your data to the format best suited for your research needs. \ No newline at end of file +## Install reproschema-py + +``` +pip install reproschema +``` + +## CLI usage + +`reproschema-py` can be used as a Commend-Line Interface. + +``` +$ reproschema +Usage: reproschema [OPTIONS] COMMAND [ARGS]... + + A client to support interactions with ReproSchema + + To see help for a specific command, run + + reproschema COMMAND --help e.g. reproschema validate --help + +Options: + --version + -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL] + Log level name [default: INFO] + --help Show this message and exit. + +Commands: + convert + create + redcap2reproschema Convert REDCap CSV files to Reproschema format. + reproschema2redcap Convert reproschema protocol to REDCap CSV format. + serve + validate +``` + +## `reproschema2redcap` Usage + +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: + ```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. + +### 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: +```bash +reproschema redcap2reproschema path/to/your_redcap_data_dic.csv path/to/your_redcap2rs.yaml +``` + +Those tools can also be used as Python functions. For detailed instructions, please visit [reproschema-py](https://github.com/ReproNim/reproschema-py). diff --git a/mkdocs.yml b/mkdocs.yml index 1562026a64..d80d83b113 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,7 +25,7 @@ nav: - 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" - - Additional tools: "46_tools.md" + - Toolkit: "46_tools.md" # - Creating a new activity and protocol: "create_new_activity_protocol.md" # - Testing your schema and collecting data: "testing_using_schema.md"