From 99c321c44be62cc206a9780ddd81ddfec61be8bb Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Fri, 14 Jun 2024 22:53:15 +0200 Subject: [PATCH] [REF] refactor documentation (#487) * add syntax highlighting where missing * move files in subfolders * rename files * update contributing info * format markdown * apply remark * fix links * fix file name * refactor jsonld snippets out of doc * more extracting of snippets * rm prettier hook * fix validation * misc * apply review suggestions * Update .github/workflows/pythonpackage.yml * fix validation * fix and refactor * fix * move FAQ * refactor * mv question * fix indents --- .github/workflows/pythonpackage.yml | 8 +- .../{validation.yml => validate_cff.yml} | 2 +- .remarkrc | 54 ++- docs/FAQ.md | 209 +++++++++- docs/faq/semantic-web.md | 139 ------- docs/glossary.md | 11 - docs/introduction.md | 2 +- docs/tutorials/create-new-activity.md | 388 +----------------- docs/tutorials/create-new-items.md | 147 +++++++ docs/tutorials/create-new-protocol.md | 51 +-- docs/tutorials/finalizing-the-protocol.md | 26 ++ .../tips-to-make-your-life-easier.md | 179 +------- docs/tutorials/translating-an-activity.md | 186 +-------- docs/tutorials/using-reproschema.md | 25 +- docs/user-guide/adopt-assessments.md | 34 +- docs/user-guide/create-new-assess.md | 51 +-- docs/user-guide/finalize-protocol.md | 18 +- docs/user-guide/setup-feedback.md | 46 +-- ...dinburgh_handedness_inventory_short.jsonld | 44 ++ ...ndedness_inventory_short_multi_lang.jsonld | 50 +++ .../activities/EHI/items/EHI_results.jsonld | 18 + examples/activities/EHI/items/throwing.jsonld | 41 ++ examples/activities/EHI/items/writing.jsonld | 41 ++ .../EHI/leftRightValueConstraints.jsonld | 31 ++ .../leftRightValueConstraintsMultiLang.jsonld | 46 +++ examples/activities/activity1_embed.jsonld | 2 +- .../user_guide/items/feedback.jsonld | 19 + examples/protocols/README.md | 3 + .../protocols/depression_nimg_schema.jsonld | 36 ++ examples/protocols/protocol1.jsonld | 2 +- examples/protocols/protocol1_embed.jsonld | 2 +- examples/responses/response1.jsonld | 2 +- examples/responses/responseActivity1.jsonld | 2 +- includes/abbreviations.md | 3 + mkdocs.yml | 36 +- mlc_config.json | 24 +- 36 files changed, 952 insertions(+), 1026 deletions(-) rename .github/workflows/{validation.yml => validate_cff.yml} (93%) delete mode 100644 docs/faq/semantic-web.md delete mode 100644 docs/glossary.md create mode 100644 docs/tutorials/create-new-items.md create mode 100644 docs/tutorials/finalizing-the-protocol.md create mode 100644 examples/activities/EHI/edinburgh_handedness_inventory_short.jsonld create mode 100644 examples/activities/EHI/edinburgh_handedness_inventory_short_multi_lang.jsonld create mode 100644 examples/activities/EHI/items/EHI_results.jsonld create mode 100644 examples/activities/EHI/items/throwing.jsonld create mode 100644 examples/activities/EHI/items/writing.jsonld create mode 100644 examples/activities/EHI/leftRightValueConstraints.jsonld create mode 100644 examples/activities/EHI/leftRightValueConstraintsMultiLang.jsonld create mode 100644 examples/activities/user_guide/items/feedback.jsonld create mode 100644 examples/protocols/README.md create mode 100644 examples/protocols/depression_nimg_schema.jsonld create mode 100644 includes/abbreviations.md diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml index 7cb352c35d..a769b9c240 100644 --- a/.github/workflows/pythonpackage.yml +++ b/.github/workflows/pythonpackage.yml @@ -16,14 +16,16 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Set up Python 3.10 + - name: Set up Python uses: actions/setup-python@v5 with: - python-version: "3.10" + python-version: 3.12 - name: Install dependencies + # TODO update to install from the latest version on reproschema + # once https://github.com/ReproNim/reproschema-py/pull/40 has been merged and a new release has been made. run: | python -m pip install --upgrade pip setuptools - pip install reproschema + pip install git+https://github.com/Remi-Gau/reproschema-py.git@skip - name: Test with pyshacl run: | python scripts/jsonParser.py diff --git a/.github/workflows/validation.yml b/.github/workflows/validate_cff.yml similarity index 93% rename from .github/workflows/validation.yml rename to .github/workflows/validate_cff.yml index e41d9aabf8..b16edd8637 100644 --- a/.github/workflows/validation.yml +++ b/.github/workflows/validate_cff.yml @@ -1,5 +1,5 @@ --- -name: validation +name: validation CITATION.cff on: pull_request: diff --git a/.remarkrc b/.remarkrc index b0a518d8c2..41ce9d2d65 100644 --- a/.remarkrc +++ b/.remarkrc @@ -3,16 +3,48 @@ "preset-lint-markdown-style-guide", "preset-lint-recommended", "remark-gfm", - ["lint-no-duplicate-headings", false], - ["lint-list-item-indent", "tab-size"], - ["lint-emphasis-marker", "consistent"], - ["lint-maximum-line-length", 500], - ["lint-maximum-heading-length", false], - ["lint-no-shortcut-reference-link", false], - ["remark-lint-unordered-list-marker-style", "-"], - ["lint-no-trailing-spaces"], - ["remark-lint-code-block-style", false], - ["lint-no-undefined-references", false], - ["remark-lint-heading-style", false] + [ + "lint-no-duplicate-headings", + false + ], + [ + "lint-list-item-indent", + "tab-size" + ], + [ + "lint-emphasis-marker", + "consistent" + ], + [ + "lint-maximum-line-length", + 500 + ], + [ + "lint-maximum-heading-length", + false + ], + [ + "lint-no-shortcut-reference-link", + false + ], + [ + "remark-lint-unordered-list-marker-style", + "-" + ], + [ + "lint-no-trailing-spaces" + ], + [ + "remark-lint-code-block-style", + false + ], + [ + "lint-no-undefined-references", + false + ], + [ + "remark-lint-heading-style", + false + ] ] } diff --git a/docs/FAQ.md b/docs/FAQ.md index 84545b3820..52398cfb83 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,49 +1,234 @@ # FAQ +## Reproschema -## How can I visualize the schema for a `protocol` or an `activity`? +### How can I visualize the schema for a `protocol` or an `activity`? If you want to see what the assessment that are already supported by the ReproSchema would look like using our ReproSchema user-interface, you can visualize them directly on [schema.repronim.org](https://schema.repronim.org/rl). -If you just want to view a protocol or activity you are developing using the `reproschema-ui`, you can pass the URL of the schema to the `url` query parameter like this: +If you just want to view a protocol or activity you are developing using the `reproschema-ui`, +you can pass the URL of the schema to the `url` query parameter like this: ```https://schema.repronim.org/ui/#/?url=url-to-your-schema``` -If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema. For example, our demo protocol can be accessed at this URL: +If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema. +For example, our demo protocol can be accessed at this URL: [https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema) -But to get access to the raw content of that file you must click on the `Raw` button once you have opened that page on github that will open this URL: +But to get access to the raw content of that file you must click on the `Raw` button +once you have opened that page on github that will open this URL: [https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/7ed1ae49279f75acdd57380fff1f8aaff2c7b511/reproschema_demo_protocol/reproschema_demo_protocol_schema). -If you want to visualize the graph represented by the JSON-LD file, we explain how to do this in [From JSON to JSON-LD](#from-json-to-json-ld). +If you want to visualize the graph represented by the JSON-LD file, +we explain how to do this in [From JSON to JSON-LD](#from-json-to-json-ld). + + +### 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). + + +## Linked data and semantic web + +## 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: + + + + diff --git a/docs/faq/semantic-web.md b/docs/faq/semantic-web.md deleted file mode 100644 index 918d308c65..0000000000 --- a/docs/faq/semantic-web.md +++ /dev/null @@ -1,139 +0,0 @@ -## 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/glossary.md b/docs/glossary.md deleted file mode 100644 index 898197690a..0000000000 --- a/docs/glossary.md +++ /dev/null @@ -1,11 +0,0 @@ -# Glossary - -- activity -- compute specification -- input type -- item -- JSON -- JSON-LD -- protocol -- SHACL -- visibility diff --git a/docs/introduction.md b/docs/introduction.md index f85ffee037..dca4e48c0a 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,6 +1,6 @@ # Introduction -??? example "Tl;DR - Advantages of the current schema representation" +!!! example "Tl;DR - Advantages of the current schema representation" - Rich contexts for a questionnaire with JSON-LD rather than a "flat" csv file. - A single source of curated assessments from [ReproSchema Library](https://github.com/ReproNim/reproschema-library) diff --git a/docs/tutorials/create-new-activity.md b/docs/tutorials/create-new-activity.md index 54c07729d3..533c0203d9 100644 --- a/docs/tutorials/create-new-activity.md +++ b/docs/tutorials/create-new-activity.md @@ -36,8 +36,7 @@ i) Which foot do you prefer to kick with ? ii) Which eye do you use when using only one? ``` -The asterisks denote the subset of items that belong to the short form of the -questionnaire. +The asterisks denote the subset of items that belong to the short form of the questionnaire. The scoring for each item follows the following scheme: @@ -55,7 +54,6 @@ classification according to the Laterality Quotient score goes as follow: - Right handers: 61 to 100 +Source: http://www.brainmapping.org/shared/Edinburgh.php +--> ## 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. +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. ```bash @@ -80,7 +78,7 @@ 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. -```json +```json linenums="1" { "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", "@type": "reproschema:Activity", @@ -92,16 +90,16 @@ Now let's start by adding the following content in the activity file we have jus } ``` -The content is for now very similar to the jsonld that defines our protocol. +The content is for now very similar to the JSON-LD 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 `"preamble"` that is common to all items in this questionnaire. -```json +```json linenums="1" hl_lines="9-10" { "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", "@type": "reproschema:Activity", @@ -114,373 +112,3 @@ Two other things we can add right away are: "preamble": "Please indicate your preferences in the use of hands in the following activities or objects:" } ``` - -## Creating 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` - -```bash -# Type this in a terminal window -mkdir activities/EHI/items -touch activities/EHI/items/writing.jsonld -``` - -The content for items starts like the ones we have seen so far but -`"reproschema:Field"` for the `@type` field. - -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@type": "reproschema:Field", - "@id": "writing.jsonld", - "prefLabel": "writing", - "description": "writing item of the EHI", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1" -} -``` - -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. - -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@type": "reproschema:Field", - "@id": "writing", - "prefLabel": "writing", - "description": "writing item of the EHI", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "question": "Writing", - "ui": { "inputType": "radio" }, - "responseOptions": { - "valueType": "xsd:integer", - "minValue": -100, - "maxValue": 100, - "multipleChoice": false, - "choices": [ - { - "name": "Always right", - "value": 100 - }, - { - "name": "Usually right", - "value": 50 - }, - { - "name": "Both equally", - "value": 0 - }, - { - "name": "Usually left", - "value": -50 - }, - { - "name": "Always left", - "value": -100 - } - ] - } -} -``` - -### What did we add ? - -```json -"question": "Writing", -``` - -```json -"ui": {"inputType": "radio"}, -``` - -```json -"responseOptions": { - "valueType": "xsd:integer", - "minValue": -100, - "maxValue": 100, - "multipleChoice": false, - "choices": [ - { - "name": "Always right", - "value": 100 - }, - { - "name": "Usually right", - "value": 50 - }, - { - "name": "Both equally", - "value": 0 - }, - { - "name": "Usually left", - "value": -50 - }, - { - "name": "Always left", - "value": -100 - } - ] -} -``` - - - -## In your own time: create a second item - -For next step you can create on your own the `throwing` item of the questionnaire. - -## Add the items to the activity - -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@type": "reproschema:Activity", - "@id": "edinburgh_handedness_inventory_short.jsonld", - "prefLabel": "Edinburgh handedness inventory - short form", - "description": "Short version of the Edinburgh handedness inventory", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "citation": "10.1080/1357650X.2013.783045", - "preamble": "Please indicate your preferences in the use of hands in the following activities or objects:", - "ui": { - "order": ["items/writing.jsonld", "items/throwing.jsonld"], - "shuffle": false, - "addProperties": [ - { - "variableName": "writing", - "isAbout": "items/writing.jsonld", - "isVis": true - }, - { - "variableName": "throwing", - "isAbout": "items/throwing.jsonld", - "isVis": true - } - ] - } -} -``` - -### What did we add ? - -```json -"ui": { - "order": [ - "items/writing.jsonld", - "items/throwing.jsonld" - ], - "shuffle": false, - "addProperties": [ - { - "variableName": "writing", - "isAbout": "items/writing.jsonld", - "isVis": true - }, - { - "variableName": "throwing", - "isAbout": "items/throwing.jsonld", - "isVis": true - } - ] -} -``` - -## Viewing the activity - -Push the content you have created on your repository on github - -```bash -# Type this in a terminal window -git add --all -git commit -m 'adding the EHI activity' -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 -``` - - - - - -## Viewing the results - -### Creating an item for the results - -```bash -# Type this in a terminal window -mkdir activities/items -touch activities/items/EHI_results.jsonld -``` - -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@type": "reproschema:Field", - "@id": "EHI_results.jsonld", - "prefLabel": "EHI results", - "description": "Edinburgh handedness inventory", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "ui": { - "inputType": "number", - "readonlyValue": true - }, - "responseOptions": { - "valueType": "xsd:integer", - "minValue": -100, - "maxValue": 100 - } -} -``` - -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@type": "reproschema:Activity", - "@id": "edinburgh_handedness_inventory_short.jsonld", - "prefLabel": "Edinburgh handedness inventory - short form", - "description": "Short version of the Edinburgh handedness inventory", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "citation": "10.1080/1357650X.2013.783045", - "preamble": "Please indicate your preferences in the use of hands in the following activities or objects:", - "ui": { - "order": [ - "items/writing.jsonld", - "items/throwing.jsonld", - "items/EHI_results.jsonld" - ], - "shuffle": false, - "addProperties": [ - { - "variableName": "writing", - "isAbout": "items/writing.jsonld", - "valueRequired": true, - "isVis": true - }, - { - "variableName": "throwing", - "isAbout": "items/throwing.jsonld", - "valueRequired": true, - "isVis": true - }, - { - "isAbout": "items/EHI_results.jsonld", - "variableName": "EHI_results", - "isVis": true - } - ] - }, - "compute": [ - { - "variableName": "EHI_results", - "jsExpression": "( writing + throwing ) / 2" - } - ] -} -``` - -### What did we add ? - -```json - "ui": { - "order": [ - ... - "items/EHI_results.jsonld" - ], - "addProperties": [ - ... - { - "isAbout": "items/EHI_results.jsonld", - "variableName": "EHI_results", - "isVis": true - } - ] - } -``` - -```json -"compute": [ - { - "variableName": "EHI_results", - "jsExpression": "( writing + throwing ) / 2" - } -] -``` - -## Adding the activity to the protocol - -```json -{ - "@context": [ - "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - { - "rl": "https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/" - } - ], - "@type": "reproschema:Protocol", - "@id": "depression_nimg_schema.jsonld", - "prefLabel": "depression neuroimaging study", - "description": "a study on linguistic processing in depression", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "landingPage": { - "@id": "README.md", - "@language": "en" - }, - "ui": { - "addProperties": [ - { - "isAbout": "rl:PHQ-9/PHQ9_schema", - "variableName": "PHQ9_schema", - "prefLabel": { "en": "Depression" } - }, - { - "isAbout": "../activities/EHI/edinburgh_handedness_inventory_short.jsonld", - "variableName": "EHI_short_schema", - "prefLabel": { "en": "EHI" } - } - ], - "order": [ - "rl:PHQ-9/PHQ9_schema", - "EHI_short_schema" - ] - } -} -``` - -### What did we add ? - -```json -"ui": { -"addProperties": [ - ... - { - "isAbout": "../activities/edinburgh_handedness_inventory_short.jsonld", - "variableName": "EHI_short_schema", - "prefLabel": { "en": "EHI" } - } -], -"order": [ - ... - "EHI_short_schema" - ] -} -``` diff --git a/docs/tutorials/create-new-items.md b/docs/tutorials/create-new-items.md new file mode 100644 index 0000000000..b9aca85cd5 --- /dev/null +++ b/docs/tutorials/create-new-items.md @@ -0,0 +1,147 @@ +## Creating 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` + +```bash +# Type this in a terminal window +mkdir activities/EHI/items +touch activities/EHI/items/writing.jsonld +``` + +The content for items starts like the ones we have seen so far but +`"reproschema:Field"` for the `@type` field. + +```json linenums="1" +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Field", + "@id": "writing.jsonld", + "prefLabel": "writing", + "description": "writing item of the EHI", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1" +} +``` + +We can now add: + +- the question for this item +- the `inputType` for for the user interface that will decide how this item will displayed to the user. +- the response options + +```json linenums="1" hl_lines="9 10 11-38" +--8<-- "examples/activities/EHI/items/writing.jsonld" +``` + + + +## In your own time: create a second item + +For next step you can create on your own the `throwing` item of the questionnaire. + +## Add the items to the activity + +```json linenums="1" hl_lines="11-26" +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Activity", + "@id": "edinburgh_handedness_inventory_short.jsonld", + "prefLabel": "Edinburgh handedness inventory - short form", + "description": "Short version of the Edinburgh handedness inventory", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "citation": "10.1080/1357650X.2013.783045", + "preamble": "Please indicate your preferences in the use of hands in the following activities or objects:", + "ui": { + "order": ["items/writing.jsonld", "items/throwing.jsonld"], + "shuffle": false, + "addProperties": [ + { + "variableName": "writing",jsonld + "isAbout": "items/writing.jsonld", + "isVis": true + }, + { + "variableName": "throwing", + "isAbout": "items/throwing.jsonld", + "isVis": true + } + ] + } +} +``` + +## Viewing the results + +### Creating an item for the results + +```bash +# Type this in a terminal window +touch activities/EHI/items/EHI_results.jsonld +``` + +Add the following content to it. + +```json linenums="1" +--8<-- "examples/activities/EHI/items/EHI_results.jsonld" +``` + +Add it to the activity. + +```json linenums="1" hl_lines="15 31-35 38-42" +--8<-- "examples/activities/EHI/edinburgh_handedness_inventory_short.jsonld" +``` + +## Using presets response options + +If you have to create several items that always have the same set of response options, +then it might be easier to create a separate file with those response options and point each item to that file instead. +This way, if you need to change the characteristics of one response, +you only have to change things in one file rather than in many. + +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 +└── items + ├── writing.jsonld + ├ ... + ... +``` + +The content of the `leftRightValueConstraints.jsonld` file would look like this: + +```json linenums="1" +--8<-- "examples/activities/EHI/leftRightValueConstraints.jsonld" +``` + +And you can point each item to it by referring to the local file in the `responseOptions` field. + +```json linenums="1" hl_lines="11" +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Field", + "@id": "writing", + "prefLabel": "writing", + "description": "writing item of the EHI", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "question": "Writing", + "ui": { "inputType": "radio" }, + "responseOptions": "../leftRightValueConstraints.jsonld" +} +``` + + diff --git a/docs/tutorials/create-new-protocol.md b/docs/tutorials/create-new-protocol.md index 8f9205af2b..89486edcd9 100644 --- a/docs/tutorials/create-new-protocol.md +++ b/docs/tutorials/create-new-protocol.md @@ -32,9 +32,9 @@ Ok so now we are ready to start putting some content into those files. Open the `depression_nimg_schema.jsonld` with a text editor and add the following content into it. -```json +```json linenums="1" { - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@context": ["https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic"], "@type": "reproschema:Protocol", "@id": "depression_nimg_schema.jsonld", "prefLabel": "depression neuroimaging study", @@ -46,8 +46,8 @@ 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. +- `@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 JSON-LD 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. @@ -75,9 +75,9 @@ Hello world Now we want to add this file to our protocol and make it the landing page for the english version of this study. So the content of your protocol file should now read like this. -```json +```json linenums="1" hl_lines="9-12" { - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@context": ["https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic"], "@type": "reproschema:Protocol", "@id": "depression_nimg_schema.jsonld", "prefLabel": "depression neuroimaging study", @@ -86,13 +86,14 @@ Now we want to add this file to our protocol and make it the landing page for th "version": "0.0.1", "landingPage": { "@id": "README.md", - "@language": "en" + "inLanguage": "en" } } ``` -??? "A note about relative paths" - Reproschema allows for the use of relative paths which means that in the example above the landing page `@id` being "README.md" means that the `README.md` and `depression_nimg_schema` are in the same folder. If the `README.md` had been in the parent directory, the `@id` of the `landingPage` section would have read `"@id": "../README.md"`. +!!! note "A note about relative paths" + Reproschema allows for the use of relative paths which means that in the example above the landing page `@id` being "README.md" means that the `README.md` and `depression_nimg_schema` are in the same folder. + If the `README.md` had been in the parent directory, the `@id` of the `landingPage` section would have read `"@id": "../README.md"`. ### Add a first assessment @@ -104,9 +105,11 @@ It seems that we can use the [PHQ-9](https://www.ncbi.nlm.nih.gov/pmc/articles/P The schema that describe the PHQ-9 activity can be found [here](https://github.com/ReproNim/reproschema-library/blob/master/activities/PHQ-9/PHQ9_schema). -If you want to visualize this activity on its own, you can use the [reproschema-ui](https://www.repronim.org/reproschema-ui/#/). To do that you can point the UI to the **raw** content of this activity. +If you want to visualize this activity on its own, you can use the [reproschema-ui](https://www.repronim.org/reproschema-ui/#/). +To do that you can point the UI to the **raw** content of this activity. -To get access to the raw content of that activity you must click on the `Raw` button on github once you have opened its [page](https://github.com/ReproNim/reproschema-library/blob/master/activities/PHQ-9/PHQ9_schema). This will open this URL: [https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema](https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema). +To get access to the raw content of that activity you must click on the `Raw` button on github once you have opened its [page](https://github.com/ReproNim/reproschema-library/blob/master/activities/PHQ-9/PHQ9_schema). +This will open this URL: [https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema](https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/PHQ-9/PHQ9_schema). You can then pass the the URL of raw content to the UI using the following template: @@ -123,7 +126,7 @@ https://www.repronim.org/reproschema-ui/#/activities/0?url=https://raw.githubuse You should now be able to see something like this and browse directly through the content of the activity. phq-9_ui.png @@ -131,7 +134,7 @@ OK now that we know what we need to add to our protocol, let's add it our schema To do this, the content of your `depression_nimg_schema.jsonld` should now look like this. -```json +```json linenums="1" hl_lines="4-6 18-27" { "@context": [ "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", @@ -147,7 +150,7 @@ To do this, the content of your `depression_nimg_schema.jsonld` should now look "version": "0.0.1", "landingPage": { "@id": "README.md", - "@language": "en" + "inLanguage": "en" }, "ui": { "addProperties": [ @@ -176,15 +179,17 @@ The field `isAbout` is the URL to point to the schema of that activity. The field `order` is there to indicate which activity should be presented first, second... -??? "Making sure you have a valid json file" - 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/). +!!! note "Making sure you have a valid JSON file" + 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" +!!! note "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/`. + Well this is because we have defined, in the `@context` part of our JSON-LD, 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. + 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 @@ -210,10 +215,10 @@ git commit -m 'add protocol and README' # make a first snapshot of your protocol Now to move things to a github repository, you need to go and create an empty repository to host the folder and files you have created. -The repository should have an URL that resembles this one where `your_user_name` is your actual Github username: +The repository should have an URL that resembles this one where `` is your actual Github username: ```text -https://github.com/your_user_name/depression_nimg_schema.git +https://github.com//depression_nimg_schema.git ``` You "push" the content of the `depression_nimg_schema` onto the empty "remote" repository you have just created. @@ -222,7 +227,7 @@ You "push" the content of the `depression_nimg_schema` onto the empty "remote" r # Type this in a terminal window # tell git about the existence of this new online repository you have just created -git remote add origin https://github.com/your_user_name/depression_nimg_schema.git +git remote add origin https://github.com//depression_nimg_schema.git # Transfer the content there git push -u origin master @@ -237,7 +242,7 @@ 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 +https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com//depression_nimg_schema/master/protocol/depression_nimg_schema.jsonld ``` ### In you own time: add the `thank-you` activity diff --git a/docs/tutorials/finalizing-the-protocol.md b/docs/tutorials/finalizing-the-protocol.md new file mode 100644 index 0000000000..db531c9f5c --- /dev/null +++ b/docs/tutorials/finalizing-the-protocol.md @@ -0,0 +1,26 @@ +## Viewing the activity + +Push the content you have created on your repository on github + +```bash +# Type this in a terminal window +git add --all +git commit -m 'adding the EHI activity' +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//depression_nimg_schema/activities/edinburgh_handedness_inventory_short.jsonld +``` + +## Adding the activity to the protocol + +```json linenums="1" hl_lines="25-29 33" +--8<-- "examples/protocols/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 index 4be79df074..e5a6684215 100644 --- a/docs/tutorials/tips-to-make-your-life-easier.md +++ b/docs/tutorials/tips-to-make-your-life-easier.md @@ -1,13 +1,9 @@ # Tips to make your life easier -## Validating your json files +## Validating your JSON files - - -First, make sure your syntax is in correct jsonld format. Test all files with -`@context` from command line: +First, make sure your syntax is in correct JSON-LD format. +Test all files with `@context` from command line: ```bash npm install -g jsonlint @@ -18,11 +14,6 @@ Or test individual files on the [json linter website](https://jsonlint.com/). ## Validating your schema - - ```bash pip install reproschema requests_cache reproschema -l DEBUG validate activities @@ -41,14 +32,9 @@ into your workflow. They rely on using some of the features of Github or Git. The first one is using Github actions to let Github perform those checks for you 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 -described by a `yml` file. - - +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 described by a `yml` file. For example you could create a `validate.yml` file in this repository. @@ -56,7 +42,7 @@ For example you could create a `validate.yml` file in this repository. ├── .git # hidden git folder ├── .github # hidden github folder │ └── workflows -│ └── validate.xml # file the actions used to validate your schema +│ └── validate.yml # file the actions used to validate your schema ├── protocols │ ├── README-en.md │ └── protocol-1.jsonld @@ -70,154 +56,5 @@ For example you could create a `validate.yml` file in this repository. The content of `validate.yml` file would look like this. ```yaml -name: validate protocol and activities - -# describes when this workfllow is triggered -on: - push: # when pushing to a branch - branches: [master] # on which branch - pull_request: # when opening a new pull request - branches: "*" # * refers to all branches - -jobs: - build: - # describes the operating system that will #be used - runs-on: ubuntu-latest - - # Steps represent a sequence of tasks executed as part of the job - steps: - - name: Setup Node # installing Node.js for all the javascript part - uses: actions/setup-node@v1 - with: - node-version: "12.x" - - # Checks-out your repository under $GITHUB_WORKSPACE, - # so your job can access it - - uses: actions/checkout@v2 - - # Checks that our JSON are valid - # Installing `jsonlint` to validate the JSON files - # Looking recursively through the directories `protocol` - # and `activities` for any file with "@context" in them - # (that makes them jsonld files) and validate their content - # with jsonlint - - name: Check for syntax errors - run: | - npm install -g jsonlint - grep -r "@context" activities | cut -d: -f1 | xargs -I fname jsonlint -q fname - grep -r "@context" protocols | cut -d: -f1 | xargs -I fname jsonlint -q fname - - # Checks that the schemas are valid - # Using python and the installing the reproschema tools - # from the reproschema-py repository to then validate - # the content of the `activities` and `protocols` folders. - - name: Set up Python 3.8 - uses: actions/setup-python@v2 - with: - python-version: 3.8 - - - name: Install dependencies - run: | - python -m pip install --upgrade pip setuptools - pip install reproschema requests_cache - - - name: Test with pyshacl - run: | - reproschema -l DEBUG validate activities - reproschema -l DEBUG validate protocols +--8<-- ".github/workflows/validate.yml" ``` - -### Using git hooks and pre-commit - -## Using a template for a new protocol - -If you are starting a new study from scratch and already familiar with some of -the basics of reproschema, we recommend you use our template repository that -already has some basic set-up to to validate your files... - - - -## Using presets response options - -If you have to create several items that always have the same set of response -options, then it might be easier to create a separate file with those response -options and point each item to that file instead. This way, if you need to -change the characteristics of one response, you only have to change things in -one file rather than in many. - -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 -└── items - ├── writing.jsonld - ├ ... - ... -``` - -The content of the `leftRightValueConstraints.jsonld` file would look like this: - -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@id": "leftRightValueConstraints.jsonld", - "@type": "reproschema:ResponseOption", - "valueType": "xsd:integer", - "minValue": -100, - "maxValue": 100, - "multipleChoice": false, - "choices": [ - { - "name": "Always right", - "value": 100 - }, - { - "name": "Usually right", - "value": 50 - }, - { - "name": "Both equally", - "value": 0 - }, - { - "name": "Usually left", - "value": -50 - }, - { - "name": "Always left", - "value": -100 - } - ] -} -``` - -And you can point each item to it by referring to the local file in the -`responseOptions` field. - -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@type": "reproschema:Field", - "@id": "writing", - "prefLabel": "writing", - "description": "writing item of the EHI", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "question": "Writing", - "ui": { "inputType": "radio" }, - "responseOptions": "../leftRightValueConstraints.jsonld" -} -``` - - diff --git a/docs/tutorials/translating-an-activity.md b/docs/tutorials/translating-an-activity.md index 2821261879..8b3ae0ebeb 100644 --- a/docs/tutorials/translating-an-activity.md +++ b/docs/tutorials/translating-an-activity.md @@ -1,6 +1,8 @@ # Translating a questionnaire -Imagine that a colleague of yours has heard that you have created this online tool based on the Edinburgh handedness inventory and she wants to use it for her own work. But she would need a French version of the questionnaire. +Imagine that a colleague of yours has heard that you have created this online tool +based on the Edinburgh handedness inventory and she wants to use it for her own work. +But she would need a French version of the questionnaire. Well there is an easy way to reuse the work we have already done to have the tool support several languages. @@ -24,187 +26,39 @@ i) Quel est le pied avec lequel vous préférez shooter? ii) Quel oeil utiliser-vous pour viser? ``` - - ## Updating the items -```json +```json linenums="1" hl_lines="5-8 12-15" { - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@type": "reproschema:Field", - "@id": "writing", - "prefLabel": { - "en": "writing", - "fr": "écrire" - }, - "description": "writing item of the EHI", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "question": { - "en": "Writing", - "fr": "Écrire", - }, - "ui": {"inputType": "radio"}, - "responseOptions": "../leftRightValueConstraints.jsonld" -} -``` - -### What did we change ? - -```json -"prefLabel": { + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Field", + "@id": "writing", + "prefLabel": { "en": "writing", "fr": "écrire" -} -``` - -```json -"question": { + }, + "description": "writing item of the EHI", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "question": { "en": "Writing", "fr": "Écrire" + }, + "ui": { "inputType": "radio" }, + "responseOptions": "../leftRightValueConstraintsMultiLang.jsonld" } ``` ## Updating the response options -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@id": "leftRightValueConstraints.jsonld", - "@type": "reproschema:ResponseOption", - "valueType": "xsd:integer", - "minValue": -100, - "maxValue": 100, - "multipleChoice": false, - "choices": [ - { - "name": { - "en": "Always right", - "fr": "Toujours la main droite" - }, - "value": 100 - }, - { - "name": { - "en": "Usually right", - "fr": "En général la main droite" - }, - "value": 50 - }, - { - "name": { - "en": "Both equally", - "fr": "Les deux" - }, - "value": 0 - }, - { - "name": { - "en": "Usually left", - "fr": "En général la main gauche" - }, - "value": -50 - }, - { - "name": { - "en": "Always left", - "fr": "Toujours la main gauche" - }, - "value": -100 - } - ] -} -``` - -### What did we change ? - -```json - +```json linenums="1" hl_lines="10-14 17-21 24-28 31-35 38-42" +--8<-- "examples/activities/EHI/leftRightValueConstraintsMultiLang.jsonld" ``` ## Updating the activity We need to update the `edinburgh_handedness_inventory_short.jsonld` so that the preamble question has both languages: -```json -{ - "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", - "@type": "reproschema:Activity", - "@id": "edinburgh_handedness_inventory_short.jsonld", - "prefLabel": { - "en": "Edinburgh handedness inventory - short form", - "fr": "Version abrégée du test Edinburgh", - }, - "description": "Short version of the Edinburgh handedness inventory", - "schemaVersion": "1.0.0-rc1", - "version": "0.0.1", - "citation": "10.1080/1357650X.2013.783045", - "preamble": { - "en": "Please indicate your preferences in the use of hands in the following activities or objects:", - "fr": "Quelle main utilisez-vous de préférence pour :" - }, - "ui": { - "order": [ - "items/writing.jsonld", - "items/throwing.jsonld", - "items/EHI_results.jsonld" - ], - "shuffle": false, - "addProperties": [ - { - "variableName": "writing", - "isAbout": "items/writing.jsonld", - "valueRequired": true, - "isVis": true - }, - { - "variableName": "throwing", - "isAbout": "items/throwing.jsonld", - "valueRequired": true, - "isVis": true - }, - { - "isAbout": "items/EHI_results.jsonld", - "variableName": "EHI_results", - "isVis": true - } - ] - }, - "compute": [ - { - "variableName": "EHI_results", - "jsExpression": "( writing + throwing ) / 2" - } - ] -} -``` - -### What did we change ? - -```json -"prefLabel": { - "en": "Edinburgh handedness inventory - short form", - "fr": "Version abrégée du test Edinburgh", -} -``` - -```json -"preamble": { - "en": "Please indicate your preferences in the use of hands in the following activities or objects:", - "fr": "Quelle main utilisez vous de préférence pour :" -} +```json linenums="1" hl_lines="5-8 13-16" +--8<-- "examples/activities/EHI/edinburgh_handedness_inventory_short_multi_lang.jsonld" ``` diff --git a/docs/tutorials/using-reproschema.md b/docs/tutorials/using-reproschema.md index dc3a1a8bb2..c1dde517b4 100644 --- a/docs/tutorials/using-reproschema.md +++ b/docs/tutorials/using-reproschema.md @@ -1,7 +1,8 @@ # How can I use reproschema to create my own questionnaire? -Broadly speaking, there are two ways to create new assessments (`actitivies`) or combinations -of assessments (`protocols`). IF you only have very few items to put in new activity or you simply want to create a protocol that reuses activities that already exist, you can do that manually by editing the files directly. But if you have to create complex activities or protocols, we suggest that for your own sanity and to avoid wasting time in the long run, you look into scripting the creation of your new tools. +Broadly speaking, there are two ways to create new assessments (`actitivies`) or combinations of assessments (`protocols`). +If you only have very few items to put in new activity or you simply want to create a protocol that reuses activities that already exist, you can do that manually by editing the files directly. +But if you have to create complex activities or protocols, we suggest that for your own sanity and to avoid wasting time in the long run, you look into scripting the creation of your new tools. ## Manual schema generation @@ -13,11 +14,12 @@ For this tutorial you will be using some other tools to put your work online. He - [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. +- a "decent" text editor like [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. +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. -??? "For Windows users" +!!! note "For Windows users" Most of the commands we will provide should work in the command line interface that will come on your computer when you install Git. But you could also look into using one the linux sub-system that provide you with Unix command line and that can be easily installed from the app-store on your computer. ## Context @@ -32,11 +34,14 @@ So we would want to have a set of questionnaires: ## A note about this tutorial -We will be creating several jsonld files in this tutorial. Those can quickly grow big and it can be hard to see what was added to a certain file from one step to the next. This gets even more confusing when you know that the order of the lines does not really matter. So to makes things easier to follow (and unless we explicitly say so) any new content we add to a file we have already worked on will be put at the end of this file. +We will be creating several JSON-LD files in this tutorial. +Those can quickly grow big and it can be hard to see what was added to a certain file from one step to the next. +This gets even more confusing when you know that the order of the lines does not really matter. +So to makes things easier to follow (and unless we explicitly say so) any new content we add to a file we have already worked on will be put at the end of this file. So if step 1 looked like this: -```json +```json linenums="1" { "@context": "some_URL", "@type": "reproschema:Protocol", @@ -48,7 +53,7 @@ So if step 1 looked like this: We will make sure that step 2 where we add a `landingPage` field looks like this: -```json +```json linenums="1" hl_lines="7" { "@context": "some_URL", "@type": "reproschema:Protocol", @@ -61,7 +66,7 @@ We will make sure that step 2 where we add a `landingPage` field looks like this Although some other possibility would be equivalent: -```json +```json linenums="1" hl_lines="2" { "landingPage": {"@id": "README.md"}, "@context": "some_URL", @@ -72,7 +77,7 @@ Although some other possibility would be equivalent: } ``` -```json +```json linenums="1" hl_lines="5" { "@context": "some_URL", "@type": "reproschema:Protocol", diff --git a/docs/user-guide/adopt-assessments.md b/docs/user-guide/adopt-assessments.md index 1d09080126..3cbfa64749 100644 --- a/docs/user-guide/adopt-assessments.md +++ b/docs/user-guide/adopt-assessments.md @@ -57,7 +57,7 @@ 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) +See the outcome file [here](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/activities/1_demographics/demographics_schema) ## Step 3: Integrating multiple assessments @@ -144,19 +144,29 @@ and [demographics](https://github.com/ReproNim/reproschema-library/tree/master/a ``` 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 - { - "variableName": "clinical_history_psychiatry", - "isAbout": "demo:clinical_history_psychiatry" - } - ``` + - `"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 + { + "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 `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. 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 index 4fa931cdf2..d39e0bae93 100644 --- a/docs/user-guide/create-new-assess.md +++ b/docs/user-guide/create-new-assess.md @@ -2,6 +2,7 @@ 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. @@ -39,13 +40,13 @@ The structure of an item within the `items` folder of a ReproSchema activity is It also provides a URL to a list of choices, in this case, a JSON file containing country names. This link allows the questionnaire to dynamically fetch and display a list of countries as response options. -```json -"responseOptions": { - "valueType": "xsd:string", - "maxLength": 50, - "choices": "https://raw.githubusercontent.com/samayo/country-json/master/src/country-by-name.json" -} -``` + ```json + "responseOptions": { + "valueType": "xsd:string", + "maxLength": 50, + "choices": "https://raw.githubusercontent.com/samayo/country-json/master/src/country-by-name.json" + } + ``` ## Step 1: Specifying `inputType` and `responseOption` to gather precise data @@ -98,16 +99,16 @@ The UI configuration and response options for this question are tailored to capt - For the speech task in our demo project, the configuration of ui `inputType` and `responseOptions` is distinctively tailored to facilitate audio data collection: -```json -"ui": { - "inputType": "audioPassageRecord" -}, -"responseOptions": { - "valueType": "schema:AudioObject", - "minValue": 0, - "maxValue": 60000 -} -``` + ```json + "ui": { + "inputType": "audioPassageRecord" + }, + "responseOptions": { + "valueType": "schema:AudioObject", + "minValue": 0, + "maxValue": 60000 + } + ``` - In the ui section, the `inputType` is set to `"audioPassageRecord"`. This specific input type is designed to enable participants to record an audio passage directly within the questionnaire interface. @@ -130,14 +131,14 @@ We can integrate additional components tailored to the unique requirements of sp 1. Contextual and properties configuration for audio check -```json -"@context": [ - "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", - { - "voice": "https://github.com/ReproNim/reproschema-library/tree/master/activities/VoiceTask/items" - } -] -``` + ```json + "@context": [ + "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", + { + "voice": "https://github.com/ReproNim/reproschema-library/tree/master/activities/VoiceTask/items" + } + ] + ``` The `@context` section includes a specific context link under "voice", pointing to the repository with items relevant to voice and audio tasks: diff --git a/docs/user-guide/finalize-protocol.md b/docs/user-guide/finalize-protocol.md index af9c0b06e8..06ee93297c 100644 --- a/docs/user-guide/finalize-protocol.md +++ b/docs/user-guide/finalize-protocol.md @@ -12,15 +12,15 @@ In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate 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 -```json -{ - "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. + ```json + { + "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. 1. [Order of presentation](https://github.com/ReproNim/reproschema-demo-protocol/blob/454ea9b65ef563c70cd496de7c8f22fbbc18ba5a/reproschema_demo_protocol/reproschema_demo_protocol_schema#L50) diff --git a/docs/user-guide/setup-feedback.md b/docs/user-guide/setup-feedback.md index 906aa1fe15..8de270559d 100644 --- a/docs/user-guide/setup-feedback.md +++ b/docs/user-guide/setup-feedback.md @@ -1,35 +1,27 @@ # 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. +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. -```json -{ - "@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" - } -} +```json linenums="1" +--8<-- "examples/activities/user_guide/items/feedback.jsonld" ``` -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: +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. +- 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. +- 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"`. +- 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/examples/activities/EHI/edinburgh_handedness_inventory_short.jsonld b/examples/activities/EHI/edinburgh_handedness_inventory_short.jsonld new file mode 100644 index 0000000000..e05cf25d45 --- /dev/null +++ b/examples/activities/EHI/edinburgh_handedness_inventory_short.jsonld @@ -0,0 +1,44 @@ +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Activity", + "@id": "edinburgh_handedness_inventory_short.jsonld", + "prefLabel": "Edinburgh handedness inventory - short form", + "description": "Short version of the Edinburgh handedness inventory", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "citation": "10.1080/1357650X.2013.783045", + "preamble": "Please indicate your preferences in the use of hands in the following activities or objects:", + "ui": { + "order": [ + "items/writing.jsonld", + "items/throwing.jsonld", + "items/EHI_results.jsonld" + ], + "shuffle": false, + "addProperties": [ + { + "variableName": "writing", + "isAbout": "items/writing.jsonld", + "valueRequired": true, + "isVis": true + }, + { + "variableName": "throwing", + "isAbout": "items/throwing.jsonld", + "valueRequired": true, + "isVis": true + }, + { + "isAbout": "items/EHI_results.jsonld", + "variableName": "EHI_results", + "isVis": true + } + ] + }, + "compute": [ + { + "variableName": "EHI_results", + "jsExpression": "( writing + throwing ) / 2" + } + ] +} diff --git a/examples/activities/EHI/edinburgh_handedness_inventory_short_multi_lang.jsonld b/examples/activities/EHI/edinburgh_handedness_inventory_short_multi_lang.jsonld new file mode 100644 index 0000000000..127c4c915d --- /dev/null +++ b/examples/activities/EHI/edinburgh_handedness_inventory_short_multi_lang.jsonld @@ -0,0 +1,50 @@ +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Activity", + "@id": "edinburgh_handedness_inventory_short_multi_lang.jsonld", + "prefLabel": { + "en": "Edinburgh handedness inventory - short form", + "fr": "Version abrégée du test Edinburgh" + }, + "description": "Short version of the Edinburgh handedness inventory", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "citation": "10.1080/1357650X.2013.783045", + "preamble": { + "en": "Please indicate your preferences in the use of hands in the following activities or objects:", + "fr": "Quelle main utilisez-vous de préférence pour :" + }, + "ui": { + "order": [ + "items/writing.jsonld", + "items/throwing.jsonld", + "items/EHI_results.jsonld" + ], + "shuffle": false, + "addProperties": [ + { + "variableName": "writing", + "isAbout": "items/writing.jsonld", + "valueRequired": true, + "isVis": true + }, + { + "variableName": "throwing", + "isAbout": "items/throwing.jsonld", + "valueRequired": true, + "isVis": true + }, + { + "isAbout": "items/EHI_results.jsonld", + "variableName": "EHI_results", + "isVis": true + } + ] + }, + "compute": [ + { + "variableName": "EHI_results", + "jsExpression": "( writing + throwing ) / 2" + } + ] +} diff --git a/examples/activities/EHI/items/EHI_results.jsonld b/examples/activities/EHI/items/EHI_results.jsonld new file mode 100644 index 0000000000..11fe4ac0d8 --- /dev/null +++ b/examples/activities/EHI/items/EHI_results.jsonld @@ -0,0 +1,18 @@ +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Field", + "@id": "EHI_results.jsonld", + "prefLabel": "EHI results", + "description": "Edinburgh handedness inventory", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "ui": { + "inputType": "number", + "readonlyValue": true + }, + "responseOptions": { + "valueType": "xsd:integer", + "minValue": -100, + "maxValue": 100 + } +} diff --git a/examples/activities/EHI/items/throwing.jsonld b/examples/activities/EHI/items/throwing.jsonld new file mode 100644 index 0000000000..03c3b5feea --- /dev/null +++ b/examples/activities/EHI/items/throwing.jsonld @@ -0,0 +1,41 @@ +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Field", + "@id": "throwing.jsonld", + "prefLabel": "throwing", + "description": "throwing item of the EHI", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "question": "Throwing", + "ui": { + "inputType": "radio" + }, + "responseOptions": { + "valueType": "xsd:integer", + "minValue": -100, + "maxValue": 100, + "multipleChoice": false, + "choices": [ + { + "name": "Always right", + "value": 100 + }, + { + "name": "Usually right", + "value": 50 + }, + { + "name": "Both equally", + "value": 0 + }, + { + "name": "Usually left", + "value": -50 + }, + { + "name": "Always left", + "value": -100 + } + ] + } +} diff --git a/examples/activities/EHI/items/writing.jsonld b/examples/activities/EHI/items/writing.jsonld new file mode 100644 index 0000000000..36e81e818c --- /dev/null +++ b/examples/activities/EHI/items/writing.jsonld @@ -0,0 +1,41 @@ +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@type": "reproschema:Field", + "@id": "writing.jsonld", + "prefLabel": "writing", + "description": "writing item of the EHI", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "question": "Writing", + "ui": { + "inputType": "radio" + }, + "responseOptions": { + "valueType": "xsd:integer", + "minValue": -100, + "maxValue": 100, + "multipleChoice": false, + "choices": [ + { + "name": "Always right", + "value": 100 + }, + { + "name": "Usually right", + "value": 50 + }, + { + "name": "Both equally", + "value": 0 + }, + { + "name": "Usually left", + "value": -50 + }, + { + "name": "Always left", + "value": -100 + } + ] + } +} diff --git a/examples/activities/EHI/leftRightValueConstraints.jsonld b/examples/activities/EHI/leftRightValueConstraints.jsonld new file mode 100644 index 0000000000..c889bb07de --- /dev/null +++ b/examples/activities/EHI/leftRightValueConstraints.jsonld @@ -0,0 +1,31 @@ +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@id": "leftRightValueConstraints.jsonld", + "@type": "reproschema:ResponseOption", + "valueType": "xsd:integer", + "minValue": -100, + "maxValue": 100, + "multipleChoice": false, + "choices": [ + { + "name": "Always right", + "value": 100 + }, + { + "name": "Usually right", + "value": 50 + }, + { + "name": "Both equally", + "value": 0 + }, + { + "name": "Usually left", + "value": -50 + }, + { + "name": "Always left", + "value": -100 + } + ] +} diff --git a/examples/activities/EHI/leftRightValueConstraintsMultiLang.jsonld b/examples/activities/EHI/leftRightValueConstraintsMultiLang.jsonld new file mode 100644 index 0000000000..8f540cda6b --- /dev/null +++ b/examples/activities/EHI/leftRightValueConstraintsMultiLang.jsonld @@ -0,0 +1,46 @@ +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + "@id": "leftRightValueConstraintsMultiLang.jsonld", + "@type": "reproschema:ResponseOption", + "valueType": "xsd:integer", + "minValue": -100, + "maxValue": 100, + "multipleChoice": false, + "choices": [ + { + "name": { + "en": "Always right", + "fr": "Toujours la main droite" + }, + "value": 100 + }, + { + "name": { + "en": "Usually right", + "fr": "En général la main droite" + }, + "value": 50 + }, + { + "name": { + "en": "Both equally", + "fr": "Les deux" + }, + "value": 0 + }, + { + "name": { + "en": "Usually left", + "fr": "En général la main gauche" + }, + "value": -50 + }, + { + "name": { + "en": "Always left", + "fr": "Toujours la main gauche" + }, + "value": -100 + } + ] +} diff --git a/examples/activities/activity1_embed.jsonld b/examples/activities/activity1_embed.jsonld index fc27f7cd35..f582c492fb 100644 --- a/examples/activities/activity1_embed.jsonld +++ b/examples/activities/activity1_embed.jsonld @@ -1,7 +1,7 @@ { "@context": "../../contexts/reproschema", "@type": "reproschema:Activity", - "@id": "activity1.jsonld", + "@id": "activity1_embed.jsonld", "prefLabel": "Example 1", "description": "Activity example 1", "schemaVersion": "1.0.0-rc4", diff --git a/examples/activities/user_guide/items/feedback.jsonld b/examples/activities/user_guide/items/feedback.jsonld new file mode 100644 index 0000000000..14dcbb2e13 --- /dev/null +++ b/examples/activities/user_guide/items/feedback.jsonld @@ -0,0 +1,19 @@ +{ + "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic", + "@type": "reproschema:Field", + "@id": "feedback.jsonld", + "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" + } +} diff --git a/examples/protocols/README.md b/examples/protocols/README.md new file mode 100644 index 0000000000..350513daa0 --- /dev/null +++ b/examples/protocols/README.md @@ -0,0 +1,3 @@ +# README + +Hello world diff --git a/examples/protocols/depression_nimg_schema.jsonld b/examples/protocols/depression_nimg_schema.jsonld new file mode 100644 index 0000000000..267b548b54 --- /dev/null +++ b/examples/protocols/depression_nimg_schema.jsonld @@ -0,0 +1,36 @@ +{ + "@context": [ + "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic", + { + "rl": "https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/" + } + ], + "@type": "reproschema:Protocol", + "@id": "depression_nimg_schema.jsonld", + "prefLabel": "depression neuroimaging study", + "description": "a study on linguistic processing in depression", + "schemaVersion": "1.0.0-rc1", + "version": "0.0.1", + "landingPage": { + "@id": "README.md", + "inLanguage": "en" + }, + "ui": { + "addProperties": [ + { + "isAbout": "rl:PHQ-9/PHQ9_schema", + "variableName": "PHQ9_schema", + "prefLabel": { "en": "Depression" } + }, + { + "isAbout": "../activities/EHI/edinburgh_handedness_inventory_short.jsonld", + "variableName": "EHI_short_schema", + "prefLabel": { "en": "EHI" } + } + ], + "order": [ + "rl:PHQ-9/PHQ9_schema", + "EHI_short_schema" + ] + } +} diff --git a/examples/protocols/protocol1.jsonld b/examples/protocols/protocol1.jsonld index 7af2813101..b765235286 100644 --- a/examples/protocols/protocol1.jsonld +++ b/examples/protocols/protocol1.jsonld @@ -10,7 +10,7 @@ "schemaVersion": "1.0.0-rc4", "version": "0.0.1", "landingPage": {"@id": "http://example.com/sample-readme.md", - "inLanguage": "en"}, + "inLanguage": "en"}, "messages": [ { "message": "Test message: Triggered when item1 value is greater than 0", diff --git a/examples/protocols/protocol1_embed.jsonld b/examples/protocols/protocol1_embed.jsonld index 3cf1b29e62..343f72eeda 100644 --- a/examples/protocols/protocol1_embed.jsonld +++ b/examples/protocols/protocol1_embed.jsonld @@ -1,7 +1,7 @@ { "@context": "../../contexts/reproschema", "@type": "reproschema:Protocol", - "@id": "protocol1.jsonld", + "@id": "protocol1_embed.jsonld", "prefLabel": { "en": "Protocol1", "es": "Protocol1_es" diff --git a/examples/responses/response1.jsonld b/examples/responses/response1.jsonld index 3dc93014e3..92dc4b712c 100644 --- a/examples/responses/response1.jsonld +++ b/examples/responses/response1.jsonld @@ -1,7 +1,7 @@ { "@context": "../../contexts/reproschema", "@type": "reproschema:Response", - "@id": "uuid:fc963765-1f1b-4ad9-bc4b-0d21b9de5acb", + "@id": "response1.jsonld", "wasAttributedTo": { "@id": "uuid:2b0aab3d-495f-4eee-98a5-4284b3268a56", "subject_id": "6aabb03d-9e5f-ae5e-c4a5-21b9b326868a" diff --git a/examples/responses/responseActivity1.jsonld b/examples/responses/responseActivity1.jsonld index e7b9bbf4d4..c3afc68912 100644 --- a/examples/responses/responseActivity1.jsonld +++ b/examples/responses/responseActivity1.jsonld @@ -1,7 +1,7 @@ { "@context": "../../contexts/reproschema", "@type": "reproschema:ResponseActivity", - "@id": "uuid:96496a96-50d6-4b87-a65e-468420e7c80d", + "@id": "responseActivity1.jsonld", "used": [ "../activities/items/item1.jsonld", "../activities/activity1.jsonld", diff --git a/includes/abbreviations.md b/includes/abbreviations.md new file mode 100644 index 0000000000..1daeea9c3a --- /dev/null +++ b/includes/abbreviations.md @@ -0,0 +1,3 @@ +*[JSON]: JavaScript Object Notation +*[JSON-LD]: JavaScript Object Notation - Linked Data +*[SHACL]: Shapes Constraint Language diff --git a/mkdocs.yml b/mkdocs.yml index 91bb9a5d45..5721e4d33d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,9 @@ theme: language: "en" favicon: img/favicon.png logo: img/favicon_on_white.png + features: + - content.code.copy + - content.code.annotate icon: repo: fontawesome/brands/github edit: material/pencil @@ -46,31 +49,38 @@ nav: - 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" + - Create a protocol: "tutorials/create-new-protocol.md" + - Create a new activity: "tutorials/create-new-activity.md" + - Create new items: "tutorials/create-new-items.md" + - Finalize the protocol: "tutorials/finalizing-the-protocol.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: - # - 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" + - Tips to make your life easier: "tutorials/tips-to-make-your-life-easier.md" - FAQ: "FAQ.md" - - Glossary: "glossary.md" - Contributing: "CONTRIBUTING.md" # list of extension markdown_extensions: + - abbr + - attr_list - admonition - - pymdownx.details - pymdownx.critic + - pymdownx.details - pymdownx.highlight: anchor_linenums: true line_spans: __span pygments_lang_class: true - pymdownx.inlinehilite - - pymdownx.snippets - pymdownx.superfences + - pymdownx.snippets: + auto_append: + - includes/abbreviations.md + - toc: + anchorlink: true + +watch: + - includes + +plugins: + - search + - tags diff --git a/mlc_config.json b/mlc_config.json index ebc6ca1adb..c3325eda53 100644 --- a/mlc_config.json +++ b/mlc_config.json @@ -1,9 +1,19 @@ { - "ignorePatterns": [ - {"pattern": "http://127.0.0.1:8000/"}, - {"pattern": "^https://jsonformatter.curiousconcept.com/"}, - {"pattern": "^http.*://schema.repronim.org/.*"}, - {"pattern": "^http://schema.org/version/2.0/"}, - {"pattern": "^https://doi.org/10.1080/1357650X.2013.783045"} - ] + "ignorePatterns": [ + { + "pattern": "http://127.0.0.1:8000/" + }, + { + "pattern": "^https://jsonformatter.curiousconcept.com/" + }, + { + "pattern": "^http.*://schema.repronim.org/.*" + }, + { + "pattern": "^http://schema.org/version/2.0/" + }, + { + "pattern": "^https://doi.org/10.1080/1357650X.2013.783045" + } + ] }