From 44f9041a589b6fe67145e633be98d0f87d4837e4 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Fri, 10 May 2024 12:37:12 -0400 Subject: [PATCH 01/10] add syntax highlighting where missing --- README.md | 2 +- docs/100_about_this_doc.md | 4 ++-- docs/42_adopt_assessments.md | 20 ++++++++++---------- docs/53_tips_to_make_your_life_easier.md | 7 +++---- 4 files changed, 16 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 535b1db922..c71c8692c5 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ following libraries via pip To make a new release: -``` +```bash python scripts/makeRelease.py python scripts/editProperties.py ``` diff --git a/docs/100_about_this_doc.md b/docs/100_about_this_doc.md index 3358742d93..f405c51b9c 100644 --- a/docs/100_about_this_doc.md +++ b/docs/100_about_this_doc.md @@ -9,7 +9,7 @@ and extra plugins to generate the website. To test locally, you will need to install the Python dependencies. To do that, type the following commands: -``` +```bash git clone https://github.com/ReproNim/reproschema.git cd reproschema pip install -r requirements.txt @@ -20,7 +20,7 @@ by `git clone git@github.com//reproschema.git` where `` is y Once done, you need to run MkDocs. Simply type: -``` +```bash mkdocs serve ``` diff --git a/docs/42_adopt_assessments.md b/docs/42_adopt_assessments.md index e32068faa9..f026e8e95e 100644 --- a/docs/42_adopt_assessments.md +++ b/docs/42_adopt_assessments.md @@ -28,7 +28,7 @@ This step involves precise modifications, particularly in the `@context` and `ad In addition to the standard ReproSchema context, we've added a specific link in the "@context" section for demographics: - ``` + ```json "demo": "https://raw.githubusercontent.com/ReproNim/reproschema-library/[commitID]/demographics_and_background_information_v1/items/" ``` @@ -38,7 +38,7 @@ This step involves precise modifications, particularly in the `@context` and `ad In the "addProperties" section, we define each variable that corresponds to a demographic question. For example: - ``` + ```json { "variableName": "year_of_birth", "isAbout": "demo:year_of_birth" @@ -58,7 +58,7 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass The @context section is expanded to include not only the generic ReproSchema context but also specific links to the ReproSchema-library. This enables the schema to access a broader range of predefined items and assessments. For the psychological questionnaire, two context links are established: - ``` + ```json "@context": [ "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", { @@ -76,7 +76,7 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass 3. **UI configuration and integration of multiple assessments (ui)**: - ``` + ```json "ui": { "addProperties": [ { @@ -135,12 +135,12 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass - Similarly, other assessments like `GAD-7` and `PC-PTSD-5` are included using their respective variable names and links to their schemas in the activities context. - Additional variables related to clinical history in psychiatry are linked using the demo context, pointing to specific items within the demographics and background information section of the reproschema-library. - ``` - { - "variableName": "clinical_history_psychiatry", - "isAbout": "demo:clinical_history_psychiatry" - } - ``` + ```json + { + "variableName": "clinical_history_psychiatry", + "isAbout": "demo:clinical_history_psychiatry" + } + ``` - The `order` array specifies the sequence in which these assessments will appear in the questionnaire, ensuring a logical flow for participants. - The `shuffle` setting is `false`, maintaining the defined order, and allow includes functionalities like auto-advance between assessments and data export. diff --git a/docs/53_tips_to_make_your_life_easier.md b/docs/53_tips_to_make_your_life_easier.md index e6585b7ad9..6ca65c8094 100644 --- a/docs/53_tips_to_make_your_life_easier.md +++ b/docs/53_tips_to_make_your_life_easier.md @@ -11,8 +11,7 @@ First, make sure your syntax is in correct jsonld format. Test all files with ```bash npm install -g jsonlint -grep -r "@context" . \ - | cut -d: -f1 | xargs -I fname jsonlint -q fname +grep -r "@context" . | cut -d: -f1 | xargs -I fname jsonlint -q fname ``` Or test individual files on the [json linter website](`https://jsonlint.com/`). @@ -45,7 +44,7 @@ every time there some new content is added on a repository. To set those up you simply need to create a `.github/workflows` folder inside the repository where you are working. This will contain all the workflows (a set of "actions") that Github has to run on this repository. Each workflow is -decribed by a `yml` file. +described by a `yml` file. ```json @@ -73,9 +76,11 @@ If you want to see an example of how this works, here is [dummy example](http:// ``` -By the way, if you ever come across such monstrosity and you want to turn into something you as a human being can understand (or least read), you can copy-paste it in a validator-formatter like [jsonformatter](https://jsonformatter.curiousconcept.com/) or [jsonlint](https://jsonlint.com/). This will quickly tell you a) whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and b) it will highlight and help you navigate the nested and hierarchical nature of the JSON file. +By the way, if you ever come across such monstrosity and you want to turn into something you as a human being can understand (or least read), you can copy-paste it in a validator-formatter like [jsonformatter](https://jsonformatter.curiousconcept.com/) or [jsonlint](https://jsonlint.com/). This will quickly tell you +1. whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and +1. it will highlight and help you navigate the nested and hierarchical nature of the JSON file. -**Insert image ???** + OK but let's start with a much simpler example of a JSON file, like the one below which could be the content of JSON file returned by a website when asked about a certain person. @@ -110,7 +115,7 @@ You now have a valid JSON-LD. If you want to make sure it is valid, you can copy If you want to visualize a more complex graph, we can try that with one of the JSON-LD file that describe one of the `protocols` of the reproschema like the one [here](https://github.com/ReproNim/reproschema/blob/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld). Actually if you want to test get the raw content of the file you should click on `Raw`. You can then either use the raw content of the file or the URL of this raw file which should be something like: -``` +```text https://raw.githubusercontent.com/ReproNim/reproschema/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld ``` @@ -118,8 +123,8 @@ directly into the [JSON-LD playground](https://json-ld.org/playground/) to see w ### More info -- It would be a stretch to say that the [JSON-LD specifications](https://www.w3.org/TR/json-ld11/) make for a fascinating read that will keep you up at night (although they might but mostly out of frustration) but it is good to know that it is out there in case you eventually need to look something up -- Two short videos by Manu Sporny about JSON-LD and core mark up features JSON-LD: +- It would be a stretch to say that the [JSON-LD specifications](https://www.w3.org/TR/json-ld11/) make for a fascinating read that will keep you up at night (although they might but mostly out of frustration) but it is good to know that it is out there in case you eventually need to look something up +- Two short videos by Manu Sporny about JSON-LD and core mark up features JSON-LD: diff --git a/docs/index.md b/docs/index.md index 5b23ed60d1..73acec22e7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,17 +7,17 @@ style="width: 350px; height: auto; display: block; margin-left: auto; margin-ri ## How to use this documentation -- If you want to know more about the ReproSchema project, its goals and the problems +- If you want to know more about the ReproSchema project, its goals and the problems it tries to solve: check out our [introduction](./introduction.md). -- The ReproSchema is related to the `Semantic Web` and relies on `linked data` +- The ReproSchema is related to the `Semantic Web` and relies on `linked data` and the `JSON-LD` format. If you are unfamiliar with such things, head over to our [FAQ](./FAQ.md). You do not need an in depth understanding of what those things are to use the ReproSchema but some "big picture" conceptual understanding could save you from a lot of confusion. 😉 -- Not sure how the project is organized? Check out the [project structure](./project_structure.md) page. -- Want more details on how the `Reproschema` itself is structured: check out our [schema page](./schema.md) +- Not sure how the project is organized? Check out the [project structure](./project_structure.md) page. +- Want more details on how the `Reproschema` itself is structured: check out our [schema page](./schema.md) ## Preparing the JSON for the activity Now let's create the `activities` folder, an activity file for the new -assessment tool we want to create. For this tutorial we will be using the short -form of the Edinburgh handedness inventory. +assessment tool we want to create. +For this tutorial we will be using the short form of the Edinburgh handedness inventory. ```bash # Type this in a terminal window @@ -77,8 +78,7 @@ mkdir activities touch activities/EHI/edinburgh_handedness_inventory_short.jsonld ``` -Now let's start by adding the following content in the activity file we have -just created. +Now let's start by adding the following content in the activity file we have just created. ```json { @@ -92,14 +92,14 @@ just created. } ``` -The content is for now very similar to the jsonld that defines our protocol. The -main difference is for the `@type` field that mentions that we are now -describing an activity as defined in the Reproschema. +The content is for now very similar to the jsonld that defines our protocol. +The main difference is for the `@type` field that mentions +that we are now describing an activity as defined in the Reproschema. Two other things we can add right away are: -- the references for this questionnaire, -- the "preamble" that is common to all items in this questionnaire. +- the references for this questionnaire, +- the "preamble" that is common to all items in this questionnaire. ```json { @@ -117,8 +117,7 @@ Two other things we can add right away are: ## Creating items -Now that we have a basic structure for this new activity, let us start adding -some items. +Now that we have a basic structure for this new activity, let us start adding some items. Let's first start with the item for `writing` @@ -145,10 +144,9 @@ The content for items starts like the ones we have seen so far but We can now add: -- the question for this item -- the response options -- and the `inputType` for for the user interface that will decide how this item - will displayed to the user. +- the question for this item +- the response options +- and the `inputType` for for the user interface that will decide how this item will displayed to the user. ```json { @@ -238,8 +236,7 @@ We can now add: ## In your own time: create a second item -For next step you can create on your own the `throwing` item of the -questionnaire. +For next step you can create on your own the `throwing` item of the questionnaire. ## Add the items to the activity @@ -310,11 +307,11 @@ git push Use the UI to visualize just the activity. -``` +```text https://www.repronim.org/reproschema-ui/#/activities/0?url=url-to-activity-schema ``` -``` +```text https://www.repronim.org/reproschema-ui/#/activities/0?url=https://raw.githubusercontent.com/your_user_name/depression_nimg_schema/activities/edinburgh_handedness_inventory_short.jsonld ``` diff --git a/docs/tutorials/create_new_protocol.md b/docs/tutorials/create-new-protocol.md similarity index 91% rename from docs/tutorials/create_new_protocol.md rename to docs/tutorials/create-new-protocol.md index 694fbebc1a..8f9205af2b 100644 --- a/docs/tutorials/create_new_protocol.md +++ b/docs/tutorials/create-new-protocol.md @@ -46,9 +46,9 @@ Open the `depression_nimg_schema.jsonld` with a text editor and add the followin To explain a bit what all of this means: -- `@context` gives the URL where we can find the "definitions" of terms used in the reproschema. It is itself a json file that you [can view directly](https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic). -- `@type` just says what type of entity this jsonld file describes. In this case it is a `protocol` entity as defined by the reproschema. -- `@id` is the identity of this entity, its unique identifier. +- `@context` gives the URL where we can find the "definitions" of terms used in the reproschema. It is itself a json file that you [can view directly](https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic). +- `@type` just says what type of entity this jsonld file describes. In this case it is a `protocol` entity as defined by the reproschema. +- `@id` is the identity of this entity, its unique identifier. You can then use the preferred label field and the description to give more human readable ways to describe this entity. @@ -110,13 +110,13 @@ To get access to the raw content of that activity you must click on the `Raw` bu You can then pass the the URL of raw content to the UI using the following template: -``` +```text https://www.repronim.org/reproschema-ui/#/activities/0?url=url-to-activity-schema ``` So in the case of the PHQ-9, it would give this URL that we copy-paste in a browser to view the activity on its own. -``` +```text https://www.repronim.org/reproschema-ui/#/activities/0?url=https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema ``` @@ -180,12 +180,12 @@ The field `order` is there to indicate which activity should be presented first, Json files can get a bit long and you might sometimes forget a coma of a closing square brackets, so to make sure that your json file is correctly formatted you can use a linter. For example, you can test individual files on the [json linter website](https://jsonlint.com/). ??? "JSON-LD expansion" - You might notice that `rl:PHQ-9/PHQ9_schema` does not look like a typical URL and clearly does not match the one we fed the UI earlier (https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema). Well this is because we have defined, in the `@context` part of our jsonld, that the `rl` from `rl:PHQ-9/PHQ9_schema` will actually stand for `https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/`. This shorthand makes it faster for us to write URL but the UI will know how to `expand` this into an actual URL. + You might notice that `rl:PHQ-9/PHQ9_schema` does not look like a typical URL and clearly does not match the one we fed the UI earlier (`https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema`). + Well this is because we have defined, in the `@context` part of our jsonld, that the `rl` from `rl:PHQ-9/PHQ9_schema` will actually stand for `https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/`. + This shorthand makes it faster for us to write URL but the UI will know how to `expand` this into an actual URL. Similarly the `reproschema:Protocol` in `"@type": "reproschema:Protocol"` expands in `http://schema.repronim.org/Protocol` because `reproschema` has been indirectly defined in the context of `depression_nimg_schema.jsonld`. To be more precise `reproschema` is defined in the [base file](https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/base) which is part of the context of the [generic file](https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic) that our protocol points to. - - #### Starting to put things online to see how they look So now we want to put things online and see how things look. @@ -212,7 +212,7 @@ Now to move things to a github repository, you need to go and create an empty re The repository should have an URL that resembles this one where `your_user_name` is your actual Github username: -``` +```text https://github.com/your_user_name/depression_nimg_schema.git ``` @@ -230,13 +230,13 @@ git push -u origin master If everything worked normally, you should be able to use the reproschema-ui to visualize your protocol using the following template: -``` +```text https://www.repronim.org/reproschema-ui/#/?url=url-to-protocol-schema ``` So once again grab the URL of the **raw** content of your protocol and point the UI to it: -``` +```text https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com/your_user_name/depression_nimg_schema/master/protocol/depression_nimg_schema.jsonld ``` diff --git a/docs/tutorials/tips_to_make_your_life_easier.md b/docs/tutorials/tips-to-make-your-life-easier.md similarity index 99% rename from docs/tutorials/tips_to_make_your_life_easier.md rename to docs/tutorials/tips-to-make-your-life-easier.md index f1c8cabe89..4be79df074 100644 --- a/docs/tutorials/tips_to_make_your_life_easier.md +++ b/docs/tutorials/tips-to-make-your-life-easier.md @@ -52,7 +52,7 @@ described by a `yml` file. For example you could create a `validate.yml` file in this repository. -``` +```text ├── .git # hidden git folder ├── .github # hidden github folder │ └── workflows @@ -151,7 +151,7 @@ For example, you could create response set file to constrains the possible answers on the questions of the Edinburgh Handedness Inventory we have been working on by organizing things this way. -``` +```text activities ├── edinburgh_handedness_inventory_short.jsonld ├── leftRightValueConstraints.jsonld diff --git a/docs/tutorials/translating_an_activity.md b/docs/tutorials/translating-an-activity.md similarity index 99% rename from docs/tutorials/translating_an_activity.md rename to docs/tutorials/translating-an-activity.md index 4ff14e9228..2821261879 100644 --- a/docs/tutorials/translating_an_activity.md +++ b/docs/tutorials/translating-an-activity.md @@ -6,7 +6,7 @@ Well there is an easy way to reuse the work we have already done to have the too First here is the list of the questions of the EHI in French. -``` +```text Quelle main utilisez vous de préférence pour: 1) Écrire (*) diff --git a/docs/tutorials/using_reproschema.md b/docs/tutorials/using-reproschema.md similarity index 85% rename from docs/tutorials/using_reproschema.md rename to docs/tutorials/using-reproschema.md index e391bbdf1e..dc3a1a8bb2 100644 --- a/docs/tutorials/using_reproschema.md +++ b/docs/tutorials/using-reproschema.md @@ -11,9 +11,9 @@ Here we will show a step by step approach to create a new protocol that includes For this tutorial you will be using some other tools to put your work online. Here is what you will need to install or set up. -- [Git](https://git-scm.com/downloads) -- a [Github account](https://github.com/) -- a "decent" text editor like [atom](https://atom.io/) or [visual studio code](https://code.visualstudio.com/) and we do recommend that you look for extensions or packages that help you deal with json files. +- [Git](https://git-scm.com/downloads) +- a [Github account](https://github.com/) +- a "decent" text editor like [atom](https://atom.io/) or [visual studio code](https://code.visualstudio.com/) and we do recommend that you look for extensions or packages that help you deal with json files. We don't assume that you have in-depth knowledge of Git and Github for this tutorial so we will try to provide with the commands you need to type when it is required. Similarly, we will provide some of the commands to create directories and files though you could do many of those actions "by hand" with a couple of mouse clicks. @@ -26,10 +26,9 @@ To make this a bit less abstract, we will imagine we want to create a new protoc So we would want to have a set of questionnaires: -- to assess the severity of the depression of our participants, -- check which participants can go in an MRI scanner, -- estimate the handedness of the participants (because of the language lateralization organization of the brain). - +- to assess the severity of the depression of our participants, +- check which participants can go in an MRI scanner, +- estimate the handedness of the participants (because of the language lateralization organization of the brain). ## A note about this tutorial diff --git a/docs/user_guide/adopt_assessments.md b/docs/user_guide/adopt-assessments.md similarity index 60% rename from docs/user_guide/adopt_assessments.md rename to docs/user_guide/adopt-assessments.md index fa26cf3dda..1d09080126 100644 --- a/docs/user_guide/adopt_assessments.md +++ b/docs/user_guide/adopt-assessments.md @@ -2,29 +2,38 @@ This part focuses on how to select and integrate assessments from the reproschema-library into your research protocol, an essential step in crafting a comprehensive study. The chosen assessments are to be placed in the `activities` folder within your repository. This folder serves as the central hub for various assessments or activities that collectively form your research protocol. -Each activity or assessment within this `activities` folder is typically structured around a file named with a suffix `_schema`. This file defines the overall framework of the assessment. Accompanying this, if an assessment comprises specific questions, these are organized in a subfolder titled `items` within the respective activity's directory. It's important to note that if an assessment is directly taken from the ReproSchema-library without any customization, the creation of an `items` subfolder is not necessary, as the itemized questions are predefined in the library. +Each activity or assessment within this `activities` folder is typically structured around a file named with a suffix `_schema`. +This file defines the overall framework of the assessment. +Accompanying this, if an assessment comprises specific questions, these are organized in a subfolder titled `items` within the respective activity's directory. +It's important to note that if an assessment is directly taken from the ReproSchema-library without any customization, the creation of an `items` subfolder is not necessary, as the itemized questions are predefined in the library. To illustrate this process, we will use two specific types of assessments from [reproschema-library](https://github.com/ReproNim/reproschema-library): `demographics` and `psychological questions`. The latter represents a composite assessment created from multiple pre-existing assessments within the library. This example demonstrates how to combine different elements from the library to construct a bespoke assessment tailored to the unique demands of your research protocol. ## Step 1: Understand the structure of a *_schema file through this [exemplar file](https://github.com/ReproNim/reproschema-protocol-cookiecutter/blob/main/%7B%7Bcookiecutter.protocol_name%7D%7D/activities/Activity1/activity1_schema) -1. **Context (@context)**: This field provides references to the context definitions. In this schema, it links to the generic context of ReproSchema and the specific context for the items in the repository, defined by the URL with the "rl" key. This context helps to interpret the terms used within the schema. -1. **Type (@type)**: Defined as "reproschema:Activity," this indicates the nature of the document, specifying that it is an activity within the ReproSchema framework. -1. **Identifier (@id)**: The unique identifier for this specific schema is "activity1_schema." This ID uniquely distinguishes this activity from others in the repository. -1. **PrefLabel**: This is the human-readable name of the activity, here given as "Screening." It serves as a clear and concise title for the activity. -1. **Description**: Provides a brief overview of the activity, in this case, "example of an activity." -1. **SchemaVersion and Version**: These fields indicate the versions of the ReproSchema being used ("1.0.0-rc2" means “1.0.0 Release Candidate 2”) and the version of this particular activity schema ("0.0.1"), respectively. -1. **UI Configuration**: This section specifies how the activity will be presented to users. It includes: - - **addProperties**: Lists the variables and corresponding items collected in the activity. For example, the variable `document_upload_item` is about the item `items/document_upload_item` and is always visible (`isVis: true`). It allows for the item to be skipped (`reproschema:Skipped`). - - **order**: Dictates the sequence in which items will appear in the UI. Here, it specifies that "items/document_upload_item" will be the first (and only) item. - - **shuffle**: Indicates whether the order of items should be randomized. In this example, it is set to `false`, meaning the order is fixed. - - **allow**: Defines additional UI functionalities. Here, it includes `reproschema:AutoAdvance` for automatic progression and `reproschema:AllowExport` to enable data export. +1. **Context (@context)**: This field provides references to the context definitions. In this schema, it links to the generic context of ReproSchema and the specific context for the items in the repository, defined by the URL with the "rl" key. This context helps to interpret the terms used within the schema. + +1. **Type (@type)**: Defined as "reproschema:Activity," this indicates the nature of the document, specifying that it is an activity within the ReproSchema framework. + +1. **Identifier (@id)**: The unique identifier for this specific schema is "activity1_schema." This ID uniquely distinguishes this activity from others in the repository. + +1. **PrefLabel**: This is the human-readable name of the activity, here given as "Screening." It serves as a clear and concise title for the activity. + +1. **Description**: Provides a brief overview of the activity, in this case, "example of an activity." + +1. **SchemaVersion and Version**: These fields indicate the versions of the ReproSchema being used ("1.0.0-rc2" means “1.0.0 Release Candidate 2”) and the version of this particular activity schema ("0.0.1"), respectively. + +1. **UI Configuration**: This section specifies how the activity will be presented to users. It includes: + - **addProperties**: Lists the variables and corresponding items collected in the activity. For example, the variable `document_upload_item` is about the item `items/document_upload_item` and is always visible (`isVis: true`). It allows for the item to be skipped (`reproschema:Skipped`). + - **order**: Dictates the sequence in which items will appear in the UI. Here, it specifies that "items/document_upload_item" will be the first (and only) item. + - **shuffle**: Indicates whether the order of items should be randomized. In this example, it is set to `false`, meaning the order is fixed. + - **allow**: Defines additional UI functionalities. Here, it includes `reproschema:AutoAdvance` for automatic progression and `reproschema:AllowExport` to enable data export. ## Step 2: Customizing the schema file for demographics using existing assessments from reproschema-library This step involves precise modifications, particularly in the `@context` and `addProperties` sections, to ensure the schema accurately reflects the demographic data you aim to collect. -1. **Adjusting the `@context` for Demographics**: +1. **Adjusting the `@context` for Demographics**: In addition to the standard ReproSchema context, we've added a specific link in the "@context" section for demographics: @@ -34,7 +43,7 @@ This step involves precise modifications, particularly in the `@context` and `ad 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. -1. **Customizing "addProperties" for Demographic Variables**: +1. **Customizing "addProperties" for Demographic Variables**: In the "addProperties" section, we define each variable that corresponds to a demographic question. For example: @@ -52,9 +61,13 @@ This step involves precise modifications, particularly in the `@context` and `ad ## Step 3: Integrating multiple assessments -Different from `demograpgics`, `psychological_questionnaire_schema` combines assessments, such as [PHQ-9](https://github.com/ReproNim/reproschema-library/tree/master/activities/PHQ-9), [GAD7](https://github.com/ReproNim/reproschema-library/tree/master/activities/GAD7), [PC-PTSD-5](https://github.com/ReproNim/reproschema-library/tree/master/activities/PC-PTSD-5), and [demographics](https://github.com/ReproNim/reproschema-library/tree/master/activities/demographics_and_background_information_v1/items) from [reproschema-library](https://github.com/ReproNim/reproschema-library). +Different from `demograpgics`, `psychological_questionnaire_schema` combines assessments, +such as [PHQ-9](https://github.com/ReproNim/reproschema-library/tree/master/activities/PHQ-9), +[GAD7](https://github.com/ReproNim/reproschema-library/tree/master/activities/GAD7), +[PC-PTSD-5](https://github.com/ReproNim/reproschema-library/tree/master/activities/PC-PTSD-5), +and [demographics](https://github.com/ReproNim/reproschema-library/tree/master/activities/demographics_and_background_information_v1/items) from [reproschema-library](https://github.com/ReproNim/reproschema-library). -1. **Contextual setup (@context)**: +1. **Contextual setup (@context)**: The @context section is expanded to include not only the generic ReproSchema context but also specific links to the ReproSchema-library. This enables the schema to access a broader range of predefined items and assessments. For the psychological questionnaire, two context links are established: @@ -70,11 +83,11 @@ 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. -1. **Defining the activity (@type, @id, prefLabel, etc.)**: +1. **Defining the activity (@type, @id, prefLabel, etc.)**: The standard fields like @type, @id, prefLabel, description, preamble, schemaVersion, and version define the nature and purpose of the psychological questionnaire. -3. **UI configuration and integration of multiple assessments (ui)**: +1. **UI configuration and integration of multiple assessments (ui)**: ```json "ui": { @@ -130,10 +143,11 @@ Different from `demograpgics`, `psychological_questionnaire_schema` combines ass } ``` - In the addProperties section, we define each variable that corresponds to a specific assessment. For instance: - - `"variableName": "phq-9"` is linked to `"isAbout": "activities:PHQ-9/PHQ9_schema"`. This implies that the PHQ-9 schema (an assessment for depressive symptoms) from the reproschema-library is used in the current psychological questionnaire schema. - - Similarly, other assessments like `GAD-7` and `PC-PTSD-5` are included using their respective variable names and links to their schemas in the activities context. - - Additional variables related to clinical history in psychiatry are linked using the demo context, pointing to specific items within the demographics and background information section of the reproschema-library. + In the addProperties section, we define each variable that corresponds to a specific assessment. + For instance: + - `"variableName": "phq-9"` is linked to `"isAbout": "activities:PHQ-9/PHQ9_schema"`. This implies that the PHQ-9 schema (an assessment for depressive symptoms) from the reproschema-library is used in the current psychological questionnaire schema. + - Similarly, other assessments like `GAD-7` and `PC-PTSD-5` are included using their respective variable names and links to their schemas in the activities context. + - Additional variables related to clinical history in psychiatry are linked using the demo context, pointing to specific items within the demographics and background information section of the reproschema-library. ```json { @@ -142,7 +156,7 @@ 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 `order` array specifies the sequence in which these assessments will appear in the questionnaire, ensuring a logical flow for participants. + - The `shuffle` setting is `false`, maintaining the defined order, and allow includes functionalities like auto-advance between assessments and data export. See the outcome [here](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/2_psychological/psychological_questionnaire_schema) diff --git a/docs/user_guide/create_new_assess.md b/docs/user_guide/create-new-assess.md similarity index 91% rename from docs/user_guide/create_new_assess.md rename to docs/user_guide/create-new-assess.md index 3382f79ee4..8ca1f2c0d9 100644 --- a/docs/user_guide/create_new_assess.md +++ b/docs/user_guide/create-new-assess.md @@ -2,11 +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, -1. a speech task designed to collect audio data, and -1. an audio check to facilitate the speech task. +1. clinical questions to gather clinical background information, +1. a speech task designed to collect audio data, and +1. an audio check to facilitate the speech task. -For each of these new assessments, the folder structure within the repository will differ slightly from those directly adopted from the reproschema-library. Specifically, each activity has its own dedicated folder within the `activities` directory. For instance, the speech task resides in [`activities/4_speech`](https://github.com/ReproNim/reproschema-demo-protocol/tree/main/activities/4_speech). Within this folder, besides the primary schema file (e.g., `speech_schema`), there is an additional subfolder named `items`. This `items` folder contains individual questions or tasks pertaining to that specific activity. +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. @@ -120,12 +123,12 @@ The UI configuration and response options for this question are tailored to capt 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 +1. Setting up an audio check for the speech task To ensure the effectiveness of our speech task, we create an activity for audio verification within the `activities` folder, naming it [`0_audio`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/0_audio/). This folder contains the [`audio_check_schema`](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/0_audio/audio_check_schema), a schema specifically designed to test and confirm that the audio recording system is operational and effective for participants. -1. Contextual and properties configuration for audio check +1. Contextual and properties configuration for audio check ```json "@context": [ diff --git a/docs/user_guide/create_new_protocol.md b/docs/user_guide/create-new-protocol.md similarity index 97% rename from docs/user_guide/create_new_protocol.md rename to docs/user_guide/create-new-protocol.md index 6ae18c6967..972550655e 100644 --- a/docs/user_guide/create_new_protocol.md +++ b/docs/user_guide/create-new-protocol.md @@ -22,13 +22,13 @@ Ready for your first ReproSchema project?! We are going to use the [Reproschema 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:** +1. **Use as templates:** The activities created based on your choices serve as templates. You can use these to understand the structure and elements within the activities folder. This is particularly useful if you're new to ReproSchema. By exploring these templates, you'll get a clearer picture of how activities are structured and what kind of information they contain. -1. **Delete and start fresh:** +1. **Delete and start fresh:** Alternatively, if you already have a clear idea of what your protocol needs, you can delete these generated activities. This allows you to start from scratch, creating activities that are tailored specifically to your research needs. diff --git a/docs/user_guide/finalize_protocol.md b/docs/user_guide/finalize-protocol.md similarity index 62% rename from docs/user_guide/finalize_protocol.md rename to docs/user_guide/finalize-protocol.md index 4dfcfa7667..af9c0b06e8 100644 --- a/docs/user_guide/finalize_protocol.md +++ b/docs/user_guide/finalize-protocol.md @@ -1,12 +1,14 @@ # Finalizing the Protocol -After setting up individual activities, we return to the main [protocol schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/reproschema_demo_protocol_schema) to organize everything cohesively. This step involves structuring the 'DemoProtocol_schema' to include all the activities we have developed, defining their sequence and presentation within the overall research protocol. In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate each activity schema using the following approach: +After setting up individual activities, we return to the main [protocol schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/reproschema_demo_protocol_schema) to organize everything cohesively. +This step involves structuring the 'DemoProtocol_schema' to include all the activities we have developed, defining their sequence and presentation within the overall research protocol. +In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate each activity schema using the following approach: -1. Context and protocol definition +1. Context and protocol definition The `@context`, `@type`, `@id`, and descriptive fields (`prefLabel`, `description`, etc.) provide the foundational information about the protocol. -1. Inclusion of activities +1. Inclusion of activities The ui section's addProperties array is crucial. Here, each activity schema we've created is referenced under `isAbout`, with its respective `variableName` and `prefLabel`. For example, the `audio` activity is linked as @@ -20,16 +22,16 @@ After setting up individual activities, we return to the main [protocol schema]( This structure is repeated for each activity, including audio check, demographics, psychological questions, clinical questions, speech task, and feedback. -1. [Order of presentation](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L50) +1. [Order of presentation](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L50) The order array within ui specifies the sequence in which these activities will appear in the protocol. It's arranged to flow logically from consent, through various assessments, to the final feedback, ensuring a structured participant experience. For instance, the order starts with `../activities/0_audio/audio_check_schema` and progresses through to `../activities/5_feedback/feedback_schema`. -1. [Additional UI settings](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L23) - - `"shuffle"` is set to false to maintain the specified order. - - `"allow"` includes functionalities such as `"reproschema:AllowExport"` for data exporting options. +1. [Additional UI settings](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L23) + - `"shuffle"` is set to false to maintain the specified order. + - `"allow"` includes functionalities such as `"reproschema:AllowExport"` for data exporting options. -1. Update [README.md](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/README.md) +1. Update [README.md](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/README.md) Give clear and concise instructions on what this protocol is about and how participants should use it. diff --git a/docs/user_guide/setup_feedback.md b/docs/user_guide/setup-feedback.md similarity index 100% rename from docs/user_guide/setup_feedback.md rename to docs/user_guide/setup-feedback.md diff --git a/docs/user_guide/tools.md b/docs/user_guide/tools.md index aa88a408ce..0f6079b68e 100644 --- a/docs/user_guide/tools.md +++ b/docs/user_guide/tools.md @@ -45,7 +45,7 @@ To convert ReproSchema protocol to REDCap CSV format, use the following command reproschema reproschema2redcap ``` -- ``: The path to the root folder of a protocol. For example, to convert the reproschema-demo-protocol provided by ReproNim, you can use the following commands: +- ``: The path to the root folder of a protocol. For example, to convert the reproschema-demo-protocol provided by ReproNim, you can use the following commands: ```bash git clone https://github.com/ReproNim/reproschema-demo-protocol.git @@ -53,8 +53,9 @@ reproschema reproschema2redcap pwd ``` - In this case, the output from `pwd` (which shows your current directory path)should be your ``. -- ``: The name of the output CSV file where the converted data will be saved. + In this case, the output from `pwd` (which shows your current directory path)should be your ``. + +- ``: The name of the output CSV file where the converted data will be saved. ## `redcap2reproschema` Usage @@ -66,15 +67,15 @@ Before the conversion, ensure you have the following: **YAML Configuration File**: -- Download [templates/redcap2rs.yaml](https://github.com/ReproNim/reproschema-py/blob/ab7c051dbd4ebfce92917ce154a8053343a011e7/templates/redcap2rs.yaml) and fill it out with your protocol details. +- Download [templates/redcap2rs.yaml](https://github.com/ReproNim/reproschema-py/blob/ab7c051dbd4ebfce92917ce154a8053343a011e7/templates/redcap2rs.yaml) and fill it out with your protocol details. ### YAML File Configuration In the `templates/redcap2rs.yaml` file, provide the following information: -- **protocol_name**: This is a unique identifier for your protocol. Use underscores for spaces and avoid special characters. -- **protocol_display_name**: The name that will appear in the application. -- **protocol_description**: A brief description of your protocol. +- **protocol_name**: This is a unique identifier for your protocol. Use underscores for spaces and avoid special characters. +- **protocol_display_name**: The name that will appear in the application. +- **protocol_description**: A brief description of your protocol. Example: diff --git a/makefile b/makefile index c9436b7b47..12f1865921 100644 --- a/makefile +++ b/makefile @@ -1,5 +1,5 @@ remark: package.json - npx remark ./docs/*.md ./docs/**/*/md --rc-path .remarkrc + npx remark ./docs/*.md ./docs/**/*.md --rc-path .remarkrc package.json: npm install `cat npm-requirements.txt` diff --git a/mkdocs.yml b/mkdocs.yml index e57a8e8ef8..2b774bc2ae 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,22 +17,22 @@ theme: nav: - Welcome: "index.md" - Introduction: "introduction.md" - - Project structure: "project_structure.md" + - Project structure: "project-structure.md" - Schema: "schema.md" - User Guide: - - Create a research protocol: "user_guide/create_new_protocol.md" - - Adopt assessments from the library: "user_guide/adopt_assessments.md" - - Create new assessments for a protocol: "user_guide/create_new_assess.md" - - Add a feedback section: "user_guide/setup_feedback.md" - - Finalize the protocol: "user_guide/finalize_protocol.md" + - Create a research protocol: "user_guide/create-new-protocol.md" + - Adopt assessments from the library: "user_guide/adopt-assessments.md" + - Create new assessments for a protocol: "user_guide/create-new-assess.md" + - Add a feedback section: "user_guide/setup-feedback.md" + - Finalize the protocol: "user_guide/finalize-protocol.md" - Toolkit: "user_guide/tools.md" - Tutorial: - Intro: "tutorials/using_reproschema.md" - - Create a research protocol: "tutorials/create_new_protocol.md" - - Creating a new activity: "tutorials/create_new_activity.md" - - Tips to make your life easier: "tutorials/tips_to_make_your_life_easier.md" - - Translate a questionnaire: "tutorials/translating_an_activity.md" - - Demographic information : "tutorials/collecting_demographics_information.md" + - Create a research protocol: "tutorials/create-new_protocol.md" + - Creating a new activity: "tutorials/create-new-activity.md" + - Tips to make your life easier: "tutorials/tips-to-make-your-life-easier.md" + - Translate a questionnaire: "tutorials/translating-an-activity.md" + - Demographic information : "tutorials/collecting-demographics-information.md" # - Creating a new activity and protocol: "create_new_activity_protocol.md" # - Testing your schema and collecting data: "testing_using_schema.md" # - Contribute to the project: From a96db385761cda1166cfe294cba3f1603627091a Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Fri, 10 May 2024 15:54:37 -0400 Subject: [PATCH 07/10] fix links --- docs/index.md | 2 +- docs/project-structure.md | 2 +- docs/user_guide/create-new-assess.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index 73acec22e7..f33964d600 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ our [FAQ](./FAQ.md). You do not need an in depth understanding of what those things are to use the ReproSchema but some "big picture" conceptual understanding could save you from a lot of confusion. 😉 -- Not sure how the project is organized? Check out the [project structure](./project_structure.md) page. +- Not sure how the project is organized? Check out the [project structure](./project-structure.md) page. - Want more details on how the `Reproschema` itself is structured: check out our [schema page](./schema.md) - -```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":""}]} - -``` - -By the way, if you ever come across such monstrosity and you want to turn into something you as a human being can understand (or least read), you can copy-paste it in a validator-formatter like [jsonformatter](https://jsonformatter.curiousconcept.com/) or [jsonlint](https://jsonlint.com/). This will quickly tell you -1. whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and -1. it will highlight and help you navigate the nested and hierarchical nature of the JSON file. - - - -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 -{ - "name": "Barack Obama", - "givenName": "Barack", - "familyName": "Obama", - "jobTitle": "44th President of the United States" -} -``` - -Looks familiar? It is very close to the one we had at the end of the previous FAQ section. - -### From JSON to JSON-LD - -Now say you would like to use this JSON file to represent a piece of linked-data. The only thing you would need to do in this specific case is to provide the `@context` line we saw before that will give a precise and unambiguous meaning to the following lines. - -```json -{ - "@context": "http://schema.org", - "name": "Barack Obama", - "givenName": "Barack", - "familyName": "Obama", - "jobTitle": "44th President of the United States" -} -``` - -🎉 **Congratulations!** 🎉 - -You now have a valid JSON-LD. If you want to make sure it is valid, you can copy-paste that into the [JSON-LD playground](https://json-ld.org/playground/). If you to to visualize the "linked" aspect of that data, you can click on the `Visualized` tab and this will give you a graph where that connects the different nodes (piece of information to one another). - -If you want to visualize a more complex graph, we can try that with one of the JSON-LD file that describe one of the `protocols` of the reproschema like the one [here](https://github.com/ReproNim/reproschema/blob/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld). Actually if you want to test get the raw content of the file you should click on `Raw`. You can then either use the raw content of the file or the URL of this raw file which should be something like: - -```text -https://raw.githubusercontent.com/ReproNim/reproschema/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld -``` - -directly into the [JSON-LD playground](https://json-ld.org/playground/) to see whether it is a valid JSON-LD and how the different elements are connected. - -### More info - -- It would be a stretch to say that the [JSON-LD specifications](https://www.w3.org/TR/json-ld11/) make for a fascinating read that will keep you up at night (although they might but mostly out of frustration) but it is good to know that it is out there in case you eventually need to look something up -- Two short videos by Manu Sporny about JSON-LD and core mark up features JSON-LD: - - - - - -## 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). - -If you want to see those different tools in action using our user interface, you can explore them on [schema.repronim.org/](https://schema.repronim.org/rl/). - -The ReproSchema is also used to develop a checklist to [improve methods and results reporting in neuroimaging](https://github.com/ohbm/cobidas). - -**🛠 Work in progress 🛠** - + ## How can I visualize the schema for a `protocol` or an `activity`? diff --git a/docs/faq/semantic-web.md b/docs/faq/semantic-web.md new file mode 100644 index 0000000000..918d308c65 --- /dev/null +++ b/docs/faq/semantic-web.md @@ -0,0 +1,139 @@ +## What is the semantic web? + +When you request access to a certain document by clicking on a hyperlink, the computer will give a visual rendering of the html code of this document. But computer used to do that in pretty "silly" fashion: it would give you a human-readable version of the content, but the computer would not make the distinction if a certain element in the webpage (for example a paragraph) was referring to a person or a place or a song. + +What the semantic wed allows is to "inject" additional information into a webpage so that a machine can know what certain elements are about (e.g "*this image is about a cat.*") or how they are linked to other elements (on the same page or somewhere else on the web). The tagged content of a webpage thus acquires "meaning" from the point of view of the computer, making the semantic content of the code machine-readable. + +### More info + +- [wikipedia article on the semantic web](https://en.wikipedia.org/wiki/Semantic_Web) +- A short video intro to the semantic web by Manu Sporny: + + + +## What is linked data? + +### The theory + +The same way that an element in webpage could be given "meaning" by tagging with extra information about the nature of this element, the same can be done with data. Hence a given row on a spreadsheet stored somewhere on the web can be tagged and linked to another piece of data on another website. + +"*Linked data is a way to create a network of standards-based machine interpretable data across different documents and Web sites. It allows an application to start at one piece of Linked Data, and follow embedded links to other pieces of Linked Data that are hosted on different sites across the Web.*" [[source](https://w3c.github.io/json-ld-bp/#terminology)] + +Linked data has some basic principles behind it ([adapted from wikipedia](https://en.wikipedia.org/wiki/Linked_data)): + +- Use Unique Resources identifiers (URI) to name (identify) things. +- Use HTTP URIs so that these things can be looked up. +- Provide useful information about what a name identifies when it's looked up. +- Refer to other things using their HTTP URI-based names when publishing data on the Web. + +### A more concrete example + +As things might be be quite abstract, here is a simple example of linked data to help make things more concrete: + +```json +{ + "@context": "http://schema.org", + "name": "Barack Obama", + "givenName": "Barack", + "familyName": "Obama", + "jobTitle": "44th President of the United States" +} +``` + +You can see that the file is organised in pairs of `"key": "value"`. The `@context` gives you the base URL of the website where you can find more information about the different properties of this piece of data. + +What follows (`name`, `givenNAme`, `familyName`, ...) are the actual properties about this data and in front of it the values that this data takes for each property (in this case: "Barack Obama", "Barack", "Obama"). + +Now go and look up what is hiding behind one of those property by going to the URL made of the **base URL + the property name**, for example [https://schema.org/familyName](https://schema.org/familyName). This is the HTTP URI of `familyName` and this gives you a description of the `familyName` property. + +Well "*So what?*" you might say. Well it also tells you which type of data this property it can be applied to: in this case, the `Person` type (see its description [here](https://schema.org/Person)). So even though, we never wrote anywhere explicitly that this data describes a person, a computer able to parse that piece of linked data above would "know" this. + +### More info + +- Here is [a TED talk](https://www.ted.com/talks/tim_berners_lee_the_next_web) by Tim Berners-Lee on linked data. +- A short video intro to linked data by Manu Sporny: + + + +## What is JSON-LD? + +### What is JSON? + +OK before we go for JSON-LD, let's start with JSON. JSON stands for JavaScript Object Notation and is just a specific format for a text file. +This type of text file is very often used by website when they need to transmit information to one another. + +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. + + + +```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":""}]} + +``` + +By the way, if you ever come across such monstrosity and you want to turn into something you as a human being can understand (or least read), you can copy-paste it in a validator-formatter like [jsonformatter](https://jsonformatter.curiousconcept.com/) or [jsonlint](https://jsonlint.com/). This will quickly tell you +1. whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and +1. it will highlight and help you navigate the nested and hierarchical nature of the JSON file. + + + +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 +{ + "name": "Barack Obama", + "givenName": "Barack", + "familyName": "Obama", + "jobTitle": "44th President of the United States" +} +``` + +Looks familiar? It is very close to the one we had at the end of the previous FAQ section. + +### From JSON to JSON-LD + +Now say you would like to use this JSON file to represent a piece of linked-data. The only thing you would need to do in this specific case is to provide the `@context` line we saw before that will give a precise and unambiguous meaning to the following lines. + +```json +{ + "@context": "http://schema.org", + "name": "Barack Obama", + "givenName": "Barack", + "familyName": "Obama", + "jobTitle": "44th President of the United States" +} +``` + +🎉 **Congratulations!** 🎉 + +You now have a valid JSON-LD. If you want to make sure it is valid, you can copy-paste that into the [JSON-LD playground](https://json-ld.org/playground/). If you to to visualize the "linked" aspect of that data, you can click on the `Visualized` tab and this will give you a graph where that connects the different nodes (piece of information to one another). + +If you want to visualize a more complex graph, we can try that with one of the JSON-LD file that describe one of the `protocols` of the reproschema like the one [here](https://github.com/ReproNim/reproschema/blob/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld). Actually if you want to test get the raw content of the file you should click on `Raw`. You can then either use the raw content of the file or the URL of this raw file which should be something like: + +```text +https://raw.githubusercontent.com/ReproNim/reproschema/741e295d998037629c213ef41cffaaf177f4d014/examples/protocols/protocol1.jsonld +``` + +directly into the [JSON-LD playground](https://json-ld.org/playground/) to see whether it is a valid JSON-LD and how the different elements are connected. + +### More info + +- It would be a stretch to say that the [JSON-LD specifications](https://www.w3.org/TR/json-ld11/) make for a fascinating read that will keep you up at night (although they might but mostly out of frustration) but it is good to know that it is out there in case you eventually need to look something up +- Two short videos by Manu Sporny about JSON-LD and core mark up features JSON-LD: + + + + + +## 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). + +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). diff --git a/docs/project-structure.md b/docs/project-structure.md index 37a98298be..5f3708f0e0 100644 --- a/docs/project-structure.md +++ b/docs/project-structure.md @@ -37,7 +37,7 @@ The ReproSchema is like a blueprint for research projects, ensuring everyone col There is also an [`example`](https://github.com/ReproNim/reproschema/tree/master/examples) 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](schema.md). +for a study might look like. For more details see the [schema section](./schema.md). ## [reproschema-library](https://github.com/ReproNim/reproschema-library) @@ -77,7 +77,7 @@ You can see it in action [here](https://www.repronim.org/reproschema-ui/) ## [reproschema-protocol-cookiecutter](https://github.com/ReproNim/reproschema-protocol-cookiecutter) The reproschema-protocol-cookiecutter is a straightforward tool that helps you quickly set up a research study. It offers a ready-to-use template for organizing your study's structure and surveys, ensuring everything meets standard guidelines. Think of it as a quick-start guide to get your research project up and running smoothly. -A step-by-step guide see [here](user_guide/create-new-protocol.md). +A step-by-step guide see [here](./user-guide/create-new-protocol.md). ## Other repositories diff --git a/docs/user_guide/adopt-assessments.md b/docs/user-guide/adopt-assessments.md similarity index 100% rename from docs/user_guide/adopt-assessments.md rename to docs/user-guide/adopt-assessments.md diff --git a/docs/user_guide/create-new-assess.md b/docs/user-guide/create-new-assess.md similarity index 100% rename from docs/user_guide/create-new-assess.md rename to docs/user-guide/create-new-assess.md diff --git a/docs/user_guide/create-new-protocol.md b/docs/user-guide/create-new-protocol.md similarity index 100% rename from docs/user_guide/create-new-protocol.md rename to docs/user-guide/create-new-protocol.md diff --git a/docs/user_guide/finalize-protocol.md b/docs/user-guide/finalize-protocol.md similarity index 100% rename from docs/user_guide/finalize-protocol.md rename to docs/user-guide/finalize-protocol.md diff --git a/docs/user_guide/setup-feedback.md b/docs/user-guide/setup-feedback.md similarity index 100% rename from docs/user_guide/setup-feedback.md rename to docs/user-guide/setup-feedback.md diff --git a/docs/user_guide/tools.md b/docs/user-guide/tools.md similarity index 100% rename from docs/user_guide/tools.md rename to docs/user-guide/tools.md diff --git a/mkdocs.yml b/mkdocs.yml index 2b774bc2ae..dd9a6dda74 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,12 +20,12 @@ nav: - Project structure: "project-structure.md" - Schema: "schema.md" - User Guide: - - Create a research protocol: "user_guide/create-new-protocol.md" - - Adopt assessments from the library: "user_guide/adopt-assessments.md" - - Create new assessments for a protocol: "user_guide/create-new-assess.md" - - Add a feedback section: "user_guide/setup-feedback.md" - - Finalize the protocol: "user_guide/finalize-protocol.md" - - Toolkit: "user_guide/tools.md" + - Create a research protocol: "user-guide/create-new-protocol.md" + - Adopt assessments from the library: "user-guide/adopt-assessments.md" + - Create new assessments for a protocol: "user-guide/create-new-assess.md" + - Add a feedback section: "user-guide/setup-feedback.md" + - Finalize the protocol: "user-guide/finalize-protocol.md" + - Toolkit: "user-guide/tools.md" - Tutorial: - Intro: "tutorials/using_reproschema.md" - Create a research protocol: "tutorials/create-new_protocol.md" From e858d726b50df27664acf94a7d96f987e12214f6 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Sun, 12 May 2024 18:21:17 +0200 Subject: [PATCH 10/10] fix filenames in mkdocs.yml --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index dd9a6dda74..dcb9a5ba4f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,8 +27,8 @@ nav: - Finalize the protocol: "user-guide/finalize-protocol.md" - Toolkit: "user-guide/tools.md" - Tutorial: - - Intro: "tutorials/using_reproschema.md" - - Create a research protocol: "tutorials/create-new_protocol.md" + - Intro: "tutorials/using-reproschema.md" + - Create a research protocol: "tutorials/create-new-protocol.md" - Creating a new activity: "tutorials/create-new-activity.md" - Tips to make your life easier: "tutorials/tips-to-make-your-life-easier.md" - Translate a questionnaire: "tutorials/translating-an-activity.md"