Each item (i.e question), activity (i.e questionnaire), and protocol
+(i.e set of questionnaires) provides unique and persistent identifiers.
+
Versions of a given questionnaire can be tracked (e.g., PHQ-9, PHQ-8).
+
Allows, supports, and tracks internationalization (e.g. ABCD requires Spanish
+and English forms).
+
Implementation agnostic – the schema can be used by several different software packages
+
Uses a linked data graph that can be validated using SHACL.
+
+
+
The problem
+
Cognitive and clinical questionnaires and assessments are used throughout
+neuroscience. There is little consistency in assessment data acquisition or response
+representation across studies or laboratories. Each project tends to use its own
+format and data collection tool (e.g., paper, survey tools, RedCap, LORIS). In the
+long run, this can be a source of a lot inefficiencies not only in terms data
+curation but also by diminishing the value of the data less interoperable and
+reusable. Imagine for example a researcher wanting to run a meta or mega-analysis
+across several studies. To do this each one would not only need to know which
+specific assessments were collected, but also how to relate different column names in
+data spreadsheets to these assessments and across projects.
+
Several efforts have focused on linking the assessments themselves
+through consistent terminologies and relationships that map to human cognition
+(e.g., Cognitive Atlas,
+Cognitive Paradigm Ontology). Other efforts such as the
+National Institute for Mental Health (NIMH) Data Archive (NDA) and the National
+Library of Medicine (NLM) Common Data Elements
+have curated data elements corresponding to the items and calculated scores from
+these questionnaires. However, these resources are often used to make data
+consistent and reusable after, rather than during data collection. However,
+harmonizing data after acquisition is resource intensive and this approach can
+create a mismatch between collected and submitted data due to human error during
+the harmonization process. To faciliate tedious harmonization efforts, several
+projects, over the last two decades, have developed technologies to automatically
+or interactively align and harmonize data elements (e.g., BIRN mediator, OpenRefine).
+
Given the dynamic and evolving nature of scientific investigation, many
+questionnaires are altered when used to suit the requirements of a particular
+study (e.g., different language, selective and new questions). This information
+linking the specific information used when asking a question is often decoupled
+from the data element representing the response to the question. When questions
+are changed, researchers often shoehorn the response into an existing data
+element, thus creating additional noise. Another drawback to these data elements
+is that there is often no way to find out which version of a questionnaire was
+used or how exactly it was scored.
+
Our solution
+
Our simpler solution is to enforce consistency directly at the data acquisition
+stage by relying on a common schema that encodes how the different elements of
+the data and / or the metadata relate to one another. This way, all this relational
+information between these elements is captured from the very start as it is already
+embedded in the formal description of the assessment. This solution was inspired
+by the work of CEDAR Metadata Model.
+
In this project we provide a comprehensive set of tools to create and use the
+schemas, while tracking the source of the schema, and changes to it over time.
+The ReproSchema project covers:
+
+
a schema that can be found in the present repository
+that describes the content and relations of the different elements of a
+questionnaire or set of assessment tools,
In brief, ReproSchema offers a way to standardize the underlying representation
+of assessment tools. It comes with an open and accessible library of questionnaires
+with appropriate conversion (e.g., from/to RedCap)
+and data collection tools (e.g., MindLogger,
+RedCap, LORIS - future work)
+to enable a more consistent acquisition across projects, with data being
+harmonized by design.
+
General description
+
With this schema we can represent:
+
+
at the item level, the elements of an individual assessment, like the questions
+in a questionnaire
+
at the activity level, an individual assessment that contains a set of items,
+like for example a whole questionnaire with a several questions.
+
at the protocols level, a collection of activities performed by a participant,
+ e.g a set of questionnaires used in a study.
+
+
All those elements are specified text files in a JSON-LD format (JavaScript
+Object Notation for Linked Data) and each item, activity, and protocol provides
+unique and persistent identifiers.
+
Below we show an example of one of the possible ways a questionnaire with 3 questions
+for a study could be organized with a protocol for that study, one activity
+and 3 items.
The ReproSchema can also easily and flexibly specify details how the schema
+for an assessment should be used. Independently of what solution is chosen in the
+end by a researcher, a lab, or an institute to display the assessment to their
+participants or patients (for example whether using an Web-app written in javascript
+or a mobile app written in React-native), the schema can already specify:
+
+
the input type to choose among several user-interface rendering options e.g.,
+ a Likert scale, a dropdown menu, a multiple choice...
+
the visibility to decide whether a given item or activity should be
+displayed to the user and under which conditions,
+
the compute logic of how the total score to the responses on a questionnaire
+should be computed
+
+
The ReproSchema also allows for internationalization and multiple languages support
+by making it very easy to keep everything the same
+except the language displayed by the user interface.
+
Finally ReproSchema allows tracking of variations and version of different assessments
+tools (e.g., PHQ-9, PHQ-8).
This documentation is a work in progress and we wellcome any input: if something is missing or unclear, let us know by [opening an issue on our repository] (???).
+
Serving the doc locally
+
This project uses MkDocs tool with Material theme
+and extra plugins to generate the website.
+
To test locally, you will need to install the Python dependencies. To do that, type the following commands:
If you are working on your fork, simply replace https://github.com/ReproNim/reproschema.git
+by git clone git@github.com/<username>/reproschema.git where <username> is your GitHub username
+
Once done, you need to run MkDocs. Simply type:
+
mkdocs serve
+
+
Finally, open up http://127.0.0.1:8000/ in your browser, and you
+should see the default home page of the being displayed.
A brief description of how they all interact could be along the following lines:
+
+
If you're gearing up to launch a research project that requires standardized questionnaires, starting with reproschema-protocol-cookiecutter is your best first step. This tool sets you up with a custom protocol for your study, integrating handy features for a smooth setup right from the get-go. You'll have two main paths for adding questionnaires, or activities, to your study:
+
Option 1: Dive into reproschema-library where we've got a stash of ready-made questionnaires. Pick what fits your study, and you're good to go.
+
Option 2: Feeling creative? Craft your own activities with reproschema-py. This tool not only lets you design new activities but also checks that they meet all the ReproSchema standards.
+
Once your protocol is packed with all the activities you need, reproschema-ui automatically steps in. This part of the toolkit lets you see your study in action before you even start, making sure everything's set up just right for gathering data.
The ReproSchema is like a blueprint for research projects, ensuring everyone collects data in a consistent way, which makes it easier to compare results from different studies. Here’s a simpler breakdown of what’s inside:
+
+
Key Terms: These are the building blocks, like common types of answers and data formats, that help everyone understand and use data the same way.
+
How Data is Organized: ReproSchema sorts information into three main layers to keep things neat:
+
+
+
Item Level: This is where individual questions or parts of a survey are detailed, allowing for close examination of each element.
+
+
+
+
+
Activity Level: At this stage, an entire survey or tool, made up of many items, is grouped together as an "Activity." It gives a complete overview of what the survey involves.
+
+
+
+
+
Protocols Level: The highest level, a "Protocol," bundles together all the activities a participant will do in a study, providing a comprehensive plan.
+
+
+
Validation: The schema uses special standards (like SHACL files) to make sure the data and forms are up to standard and consistent.
+
Context Files: These files (contextsand terms) specify user-interface details and enhance schema flexibility. They define elements like input types, visibility conditions, and response options, supporting a tailored user experience. Additionally, they enable internationalization and multiple language support for broad applicability.
+
+
There is also an example
+schema that can help give you a quick overview of what the protocol and activity
+for a study might look like. For more details see the schema section.
This repository hosts all the
+community curated assessments and questionnaires that support the ReproSchema
+standard.
+
Imagine this as curated library of reusable assessments and questionnaires, from
+where you can easily pull a copy from rather than having to photocopy a new
+questionnaire for your next participant or patient. Also you can mix and match
+items from this library, knowing that the information is tracked in your protocol.
+
All assessments are listed in the activity folder
+and are served here if you want to visualize
+them.
+
+
Standard Alignment: Each element in the library aligns with the ReproSchema framework, ensuring uniformity in terms and structure and upholding validation protocols for consistency across the ecosystem.
+
Research Protocol Integration: Researchers can utilize these assessments in various combinations to align with specific protocol needs, customizing their application per study objectives. This process can be integrated using the reproschema-protocol-cookiecutter for constructing user interfaces.
+
Collaborative Expansion: The library supports expansion through researcher contributions, allowing adding new, relevant assessments. These contributions are automatically validated using reproschema-py, maintaining the library’s standardization and relevance to evolving research demands.
This is the ReproSchema python library. This is a python Command Line Interface (CLI)
+that allows you to help create and validate the schemas of new assessments.
+
+
Schema Development and Validation: This tool streamlines the creation and validation of new assessment schemas, verifying their alignment with ReproSchema's standards. It rigorously tests protocols, activities, and items to meet predefined specifications.
+
Consistency Assurance: Integrated with the ReproSchema-library and ReproSchema-Protocol-Cookiecutter, reproschema-py validates library assessments for quality and uniformity. It also automatically ensures the consistency of research protocols generated through the ReproSchema-Protocol-Cookiecutter.
+
Interoperability with REDCap: Its capability to convert between REDCap and ReproSchema formats exemplifies its role in harmonizing diverse data collection methods in complex, multi-faceted research environments.
The reproschema-protocol-cookiecutter is a straightforward tool that helps you quickly set up a research study. It offers a ready-to-use template for organizing your study's structure and surveys, ensuring everything meets standard guidelines. Think of it as a quick-start guide to get your research project up and running smoothly. A step-by-step guide see here.
The core model of ReproSchema was initially derived from the CEDAR Metadata Model.
+To accommodate the needs of neuroimaging and other clinical and behavioral
+protocols and assessments the schema has evolved significantly. These changes
+include:
+
+
Alignment with schema.org and NIDM.
+We have used schema.org classes and properties where it maps on to the needs of
+the model and extended the model with NIDM elements to harmonize across ReproNim
+projects.
+
+
Allowing for structued nested elements in a schema
+Protocol > Activity > [Activity | Field > ResponseOption]. This nested
+structure provides a flexible schema to represent nested activities, which are
+common in biomedical and other domains.
Interaction with git/Github or another Web service to deliver a new Protocol,
+Activity or Field with a persistent URI, while tracking changes associated with
+any of these elements. By making every Field represented through a persistent URI,
+a data collection instrument can link the responses to the exact Field that was
+used.
+
+
Addition of computable elements that are derived from the values entered by a
+participant.
+
Allowing for user interface (UI) elements that allow interaction between the schema
+and any implementation that allows collecting data using the schema. By providing
+some additional UI elements the provider can guide an implementor to allow for
+more complex data collection behavior.
+
+
The ReproSchema-UI is a prototype implementation of an UI that leverages these
+different elements of the schema.
+
Properties of ReproSchema objects
+
This section lists the core ReproSchema objects and their allowed properties.
+
+
+
+
Protocol
+
A representation of a study which comprises one or more assessments.
An array of objects indicating computations in an activity or protocol and maps it to the corresponding Field item. scoring logic is a subset of all computations that could be performed and not all computations will be scoring. For example, one may want to do conversion from one unit to another.
Indicates (by URL or string) a particular version of a schema used in some CreativeWork. For example, a document could declare a schemaVersion using an URL such as http://schema.org/version/2.0/ if precise indication of schema version was required by some application.
An array of objects indicating computations in an activity or protocol and maps it to the corresponding Field item. scoring logic is a subset of all computations that could be performed and not all computations will be scoring. For example, one may want to do conversion from one unit to another.
Indicates (by URL or string) a particular version of a schema used in some CreativeWork. For example, a document could declare a schemaVersion using an URL such as http://schema.org/version/2.0/ if precise indication of schema version was required by some application.
A set of objects to define notes in a field. For example, most Redcap and NDA data dictionaries have notes for each item which needs to be captured in reproschema.
Whether or not a property is mutable. Default is false. Specifying this for a property that also has a value makes it act similar to a "hidden" input in an HTML form.
Indicates (by URL or string) a particular version of a schema used in some CreativeWork. For example, a document could declare a schemaVersion using an URL such as http://schema.org/version/2.0/ if precise indication of schema version was required by some application.
The unit of measurement given using the UN/CEFACT Common Code (3 characters) or a URL. Other codes than the UN/CEFACT Common Code may be used with a prefix followed by a colon.
A set of objects to define notes in a field. For example, most Redcap and NDA data dictionaries have notes for each item which needs to be captured in reproschema
The language of the content or performance or used in an action. Please use one of the language codes from the IETF BCP 47 standard. See also [[availableLanguage]].
Prerequisite: Ensure you have Git and Cookiecutter installed on your system. If not, please refer to the installation guides for Git and Cookiecutter.
+
Generate Your Repository: Use the Reproschema Protocol Cookiecutter to create a new repository for your research protocol. Run the following command in your terminal:
Follow the prompts to customize your new protocol, more details see here
+
+
Customizing Your Protocol
+
Once you run the Cookiecutter command, you will be prompted to make choices for your protocol, ranging from 1-5. These choices generate corresponding activities in your repository. Here's what you can do with these activities:
+
+
Use as Templates: The activities created based on your choices serve as templates. You can use these to understand the structure and elements within the activities folder. This is particularly useful if you're new to ReproSchema. By exploring these templates, you'll get a clearer picture of how activities are structured and what kind of information they contain.
+
Delete and Start Fresh: Alternatively, if you already have a clear idea of what your protocol needs, you can delete these generated activities. This allows you to start from scratch, creating activities that are tailored specifically to your research needs.
+
+
The inclusion of activity choices aims to provide users with a practical understanding of how activities are structured within ReproSchema protocols. Whether you use these as a starting point or prefer to create your own from the ground up, these templates are there to guide you in structuring your research protocol effectively.
+
We provide more detailed instructions for customizing your protocol in the following pages using reproschema-demo-protocol as an example.
This part focuses on how to select and integrate assessments from the reproschema-library into your research protocol, an essential step in crafting a comprehensive study. The chosen assessments are to be placed in the activities folder within your repository. This folder serves as the central hub for various assessments or activities that collectively form your research protocol.
+
Each activity or assessment within this activities folder is typically structured around a file named with a suffix _schema. This file defines the overall framework of the assessment. Accompanying this, if an assessment comprises specific questions, these are organized in a subfolder titled items within the respective activity's directory. It's important to note that if an assessment is directly taken from the ReproSchema-library without any customization, the creation of an items subfolder is not necessary, as the itemized questions are predefined in the library.
+
To illustrate this process, we will use two specific types of assessments from reproschema-library: demographics and psychological questions. The latter represents a composite assessment created from multiple pre-existing assessments within the library. This example demonstrates how to combine different elements from the library to construct a bespoke assessment tailored to the unique demands of your research protocol.
+
Step 1: Understand the structure of a *_schema file throught this exemplar file
+
+
Context (@context): This field provides references to the context definitions. In this schema, it links to the generic context of ReproSchema and the specific context for the items in the repository, defined by the URL with the "rl" key. This context helps to interpret the terms used within the schema.
+
Type (@type): Defined as "reproschema:Activity," this indicates the nature of the document, specifying that it is an activity within the ReproSchema framework.
+
Identifier (@id): The unique identifier for this specific schema is "activity1_schema." This ID uniquely distinguishes this activity from others in the repository.
+
PrefLabel: This is the human-readable name of the activity, here given as "Screening." It serves as a clear and concise title for the activity.
+
Description: Provides a brief overview of the activity, in this case, "example of an activity."
+
SchemaVersion and Version: These fields indicate the versions of the ReproSchema being used ("1.0.0-rc2" means “1.0.0 Release Candidate 2”) and the version of this particular activity schema ("0.0.1"), respectively.
+
UI Configuration: This section specifies how the activity will be presented to users. It includes:
+
addProperties: Lists the variables and corresponding items collected in the activity. For example, the variable document_upload_item is about the item items/document_upload_item and is always visible (isVis: true). It allows for the item to be skipped (reproschema:Skipped).
+
order: Dictates the sequence in which items will appear in the UI. Here, it specifies that "items/document_upload_item" will be the first (and only) item.
+
shuffle: Indicates whether the order of items should be randomized. In this example, it is set to false, meaning the order is fixed.
+
allow: Defines additional UI functionalities. Here, it includes reproschema:AutoAdvance for automatic progression and reproschema:AllowExport to enable data export.
+
+
+
+
Step 2: Customizing the schema file for demographics using existing assessments from reproschema-library
+
This step involves precise modifications, particularly in the @context and addProperties sections, to ensure the schema accurately reflects the demographic data you aim to collect.
+
+
+
Adjusting the @context for Demographics:
+
In addition to the standard ReproSchema context, we've added a specific link in the "@context" section for demographics:
Labeling this link as "demo" directs the schema to the location in the ReproSchema-library where items for demographics and background information are defined. We use the link with a specific commit ID to ensure the consistency of the assessment version. This contextual link allows the schema to access the detailed structures and definitions needed for each demographic item.
+
+
+
Customizing "addProperties" for Demographic Variables:
+
In the "addProperties" section, we define each variable that corresponds to a demographic question. For example:
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.
The @context section is expanded to include not only the generic ReproSchema context but also specific links to the ReproSchema-library. This enables the schema to access a broader range of predefined items and assessments. For the psychological questionnaire, two context links are established:
A link to the activities in the reproschema-library (activities: ) and a link for demographics items (demo: ), both are commit-specific. This indicates that we will combine different assessments from those two parts.
+
+
+
Defining the activity (@type, @id, prefLabel, etc.):
+
The standard fields like @type, @id, prefLabel, description, preamble, schemaVersion, and version define the nature and purpose of the psychological questionnaire.
+
+
+
UI configuration and integration of multiple assessments (ui):
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.
Creating New Assessments for Unique Research Needs
+
This section provides the customized new assessments tailored to specific research needs. Our focus is on creating three distinct types of activities that are not readily available in the reproschema-library. These include: (1) clinical questions to gather clinical background information, (2) a speech task designed to collect audio data, and (3) an audio check to facilitate the speech task.
+
For each of these new assessments, the folder structure within the repository will differ slightly from those directly adopted from the reproschema-library. Specifically, each activity has its own dedicated folder within the activities directory. For instance, the speech task resides in activities/4_speech. Within this folder, besides the primary schema file (e.g., speech_schema), there is an additional subfolder named items. This items folder contains individual questions or tasks pertaining to that specific activity.
+
In the case of the speech task, the items folder might include a single task designed to prompt the participant to provide a speech sample. Similarly, for the clinical questions, their respective folders will contain items subfolders with corresponding questions tailored to elicit the required information.
+
The structure of an item within the items folder of a ReproSchema activity is similar to the schema template, but with key differences that cater to the specifics of individual data collection elements. Here's an explanation of the provided template for a country item:
+
+
Context and type (@context, @type): The @context remains the same, pointing to the generic context of ReproSchema. The @type is now "reproschema:Field" instead of "reproschema:Activity". This change signifies that this template defines a single data collection field or question within an activity, as opposed to the overall structure of an activity.
+
Identifier and descriptive fields (@id, prefLabel, description, etc.): @id serves as a unique identifier for the item, here named "country_item". prefLabel and description provide a human-readable name and a brief description of the item, similar to their use in the schema template.
+
Question field (question): This field contains the actual question or prompt that will be presented to the participant. In this template, it reads: "This is an item where the user can select a country."
+
UI configuration (ui): The ui section in the item template differs from the schema template. It specifies how the question will be presented to the user. The inputType is set to "selectCountry", indicating that the user interface will provide a country selection method.
+
Response options (responseOptions): This section defines the nature and structure of the responses allowed for the item. In this example, it specifies the valueType as "xsd:string" and a maxLength of 50 characters. It also provides a URL to a list of choices, in this case, a JSON file containing country names. This link allows the questionnaire to dynamically fetch and display a list of countries as response options.
Step 1: Specifying inputType and responseOption to gather precise data
+
We have crafted ten items in the 'items' folder for the clinical questions assessment. Each item, such as alcohol_consumption, height, weight, etc., has its ui inputType and responseOptions specifically defined to suit the nature of the question.
+
Take 'alcohol_consumption' as an example. The UI configuration and response options for this question are tailored to capture a straightforward piece of information:
The ui section sets the inputType to "radio". This choice indicates that the question will be presented to the participant as a radio button selection, providing a simple and clear interface for response selection.
+
In the responseOptions, the valueType is defined as "xsd:string", signifying that the expected type of response is a string. The multipleChoice field is set to false, indicating that participants can only select one of the provided options.
+
+
The choices array lists the possible responses. In this case, there are two: "Yes" and "No", each with a corresponding value (1 for Yes, 2 for No) and translations provided for English ("en") and Spanish ("es").
+
+
+
For the speech task in our demo project, the configuration of ui inputType and responseOptions is distinctively tailored to facilitate audio data collection:
In the ui section, the inputType is set to "audioPassageRecord". This specific input type is designed to enable participants to record an audio passage directly within the questionnaire interface.
+
The responseOptions are configured to accommodate the nature of audio data.
+
The valueType is specified as "schema:AudioObject", indicating that the response will be an audio file.
+
The fields minValue and maxValue define the allowable duration of the audio recording in milliseconds. In this case, the maximum duration is set to 60,000 milliseconds (or 1 minute).
+
+
Step 2: Integrating additional components for activity-specific needs
+
We can integrate additional components tailored to the unique requirements of specific activities. For instance, considering the unique needs of our speech task, we add an 'audio check' component to confirm the functionality of the audio recording feature.
+
+
+
Setting up an audio check for the speech task
+
To ensure the effectiveness of our speech task, we create an activity for audio verification within the activities folder, naming it 0_audio.
+This folder contains the audio_check_schema, a schema specifically designed to test and confirm that the audio recording system is operational and effective for participants.
+
+
+
Contextual and properties configuration for audio check
The @context section includes a specific context link under "voice", pointing to the repository with items relevant to voice and audio tasks: "<https://raw.githubusercontent.com/ReproNim/reproschema-library/.../VoiceTask/items/>" This targeted link ensures that the audio check activity aligns with the specific requirements of voice-related tasks.
+
+The ui's `addProperties` array is tailored for the audio check. We define a property `"variableName": "audio_check"` linked to `"isAbout": "voice:audio_check"`.
+
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.
+
{
+ "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic",
+ "@type": "reproschema:Field",
+ "@id": "feedback",
+ "prefLabel": "Feedback",
+ "description": "schema to record text response of overall feedback of the protocol",
+ "schemaVersion": "1.0.0-rc4",
+ "version": "0.0.1",
+ "question": {
+ "en": "Please leave any comments or suggestions on the study so we can improve it (or skip):",
+ "es": "Deje cualquier comentario o sugerencia sobre el estudio para que podamos mejorarlo (u omitir):"
+ },
+ "ui": {
+ "inputType": "textarea"
+ },
+ "responseOptions": {
+ "valueType": "xsd:string"
+ }
+}
+
+
The feedback item in this activity (5_feedback) is specifically designed to gather open-ended responses, allowing participants to share their thoughts and suggestions:
+
+
Item Structure: The item feedback is set up with an identification and purpose, indicated by its '@id' and descriptive fields.
+
Question Prompt: The question is presented in both English and Spanish, encouraging participants to provide comments on their study experience. It’s formatted to be inclusive, giving participants the option to skip if they choose.
+
UI Configuration for Open Responses: The choice of textarea as the inputType in the ui configuration facilitates extended text input, enabling participants to express detailed feedback comfortably. Accordingly, valueType in the responseOptions has been set as "xsd:string".
After setting up individual activities, we return to the main protocol schema to organize everything cohesively. This step involves structuring the 'DemoProtocol_schema' to include all the activities we have developed, defining their sequence and presentation within the overall research protocol. In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate each activity schema using the following approach:
+
+
+
Context and protocol definition
+
The @context, @type, @id, and descriptive fields (prefLabel, description, etc.) provide the foundational information about the protocol.
+
+
+
Inclusion of activities
+
The ui section's addProperties array is crucial. Here, each activity schema we've created is referenced under isAbout, with its respective variableName and prefLabel. For example, the audio activity is linked as
This structure is repeated for each activity, including audio check, demographics, psychological questions, clinical questions, speech task, and feedback.
+
The order array within ui specifies the sequence in which these activities will appear in the protocol. It's arranged to flow logically from consent, through various assessments, to the final feedback, ensuring a structured participant experience. For instance, the order starts with ../activities/0_audio/audio_check_schema and progresses through to ../activities/5_feedback/feedback_schema.
Give clear and concise instructions on what this protocol is about and how participants should use it.
+
+
+
Upon finalizing our protocol with the integrated activities, the end result is a fully interactive research tool hosted on our GitHub repository. For data collection, this tool can be linked to a backend server, or participants can be given the option to export their data directly.
In the world of research data management, flexibility and compatibility are key. Understanding this, we provide specialized tools designed to create, validata schemas, and convert data between ReproSchema format and REDCap CSV format. Whether you're transitioning from REDCap to ReproSchema or vice versa, these tools ensure a smooth and efficient conversion process, preserving the integrity and structure of your data.
+
Install reproschema-py
+
pip install reproschema
+
+
CLI usage
+
reproschema-py can be used as a Commend-Line Interface.
+
$ reproschema
+Usage: reproschema [OPTIONS] COMMAND [ARGS]...
+
+ A client to support interactions with ReproSchema
+
+ To see help for a specific command, run
+
+ reproschema COMMAND --help e.g. reproschema validate --help
+
+Options:
+ --version
+ -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
+ Log level name [default: INFO]
+ --help Show this message and exit.
+
+Commands:
+ convert
+ create
+ redcap2reproschema Convert REDCap CSV files to Reproschema format.
+ reproschema2redcap Convert reproschema protocol to REDCap CSV format.
+ serve
+ validate
+
+
reproschema2redcap Usage
+
To convert ReproSchema protocol to REDCap CSV format, use the following command
<input_dir_path>: The path to the root folder of a protocol. For example, to convert the reproschema-demo-protocol provided by ReproNim, you can use the following commands:
+
+
bash
+ git clone https://github.com/ReproNim/reproschema-demo-protocol.git
+ cd reproschema-demo-protocol
+ pwd
+
In this case, the output from pwd (which shows your current directory path)should be your <input_dir_path>.
+- <output_csv_filename>: The name of the output CSV file where the converted data will be saved.
+
redcap2reproschema Usage
+
The redcap2reproschema function is designed to process a given REDCap CSV file and YAML configuration to generate the output in the reproschema format.
+
Prerequisites
+
Before the conversion, ensure you have the following:
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.
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]
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:
+
{
+ "@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. 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). 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 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 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.
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 or jsonlint. This will quickly tell you a) whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and b) it will highlight and help you navigate the nested and hierarchical nature of the JSON file.
+
Insert image ???
+
OK but let's start with a much simpler example of a JSON file, like the one below which could be the content of JSON file returned by a website when asked about a certain person.
+
{
+ "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.
+
{
+ "@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. 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. 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:
directly into the JSON-LD 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 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?
How can I know if a certain property is supported by ReproSchema?
+
🛠 Work in progress 🛠
+
How can I add a property to my schema?
+
🛠 Work in progress 🛠
+
How are these assessments licensed?
+
🛠 Work in progress 🛠
+
How can I contribute to the project?
+
🛠 Work in progress 🛠
+
An assessment tool I regularly use is not supported by ReproSchema: how can I add it?
+
🛠 Work in progress 🛠
+
How can I visualize the schema for a protocol or an activity?
+
If you want to see what the assessment that are already supported by the ReproSchema would look like using our ReproSchema user-interface, you can visualize them directly on schema.repronim.org.
+
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 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 want to know more about the ReproSchema project, its goals and the problems
+it tries to solve: check out our introduction.
+
+
+
The ReproSchema is related to the Semantic Web and relies on linked data
+and the JSON-LD format. If you are unfamiliar with such things, head over to
+our FAQ. You do not need an in depth understanding of what those
+things are to use the ReproSchema but some "big picture" conceptual understanding
+could save you from a lot of confusion. 😉
+
+
+
Not sure how the project is organized? Check out the project structure
+page.
+
+
+
How to cite
+
If you need to cite ReproSchema, you can use this DOI:
If you want to get started right away and contribute directly to this
+documentation,you can find references and how-to in the about section.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/search/search_index.json b/search/search_index.json
new file mode 100644
index 0000000000..af3c5f2868
--- /dev/null
+++ b/search/search_index.json
@@ -0,0 +1 @@
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to the ReproSchema documentation","text":""},{"location":"#how-to-use-this-documentation","title":"How to use this documentation","text":"
If you want to know more about the ReproSchema project, its goals and the problems it tries to solve: check out our introduction.
The ReproSchema is related to the Semantic Web and relies on linked data and the JSON-LD format. If you are unfamiliar with such things, head over to our FAQ. You do not need an in depth understanding of what those things are to use the ReproSchema but some \"big picture\" conceptual understanding could save you from a lot of confusion. \ud83d\ude09
Not sure how the project is organized? Check out the project structure page.
"},{"location":"#how-to-cite","title":"How to cite","text":"
If you need to cite ReproSchema, you can use this DOI:
Cognitive and clinical questionnaires and assessments are used throughout neuroscience. There is little consistency in assessment data acquisition or response representation across studies or laboratories. Each project tends to use its own format and data collection tool (e.g., paper, survey tools, RedCap, LORIS). In the long run, this can be a source of a lot inefficiencies not only in terms data curation but also by diminishing the value of the data less interoperable and reusable. Imagine for example a researcher wanting to run a meta or mega-analysis across several studies. To do this each one would not only need to know which specific assessments were collected, but also how to relate different column names in data spreadsheets to these assessments and across projects.
Several efforts have focused on linking the assessments themselves through consistent terminologies and relationships that map to human cognition (e.g., Cognitive Atlas, Cognitive Paradigm Ontology). Other efforts such as the National Institute for Mental Health (NIMH) Data Archive (NDA) and the National Library of Medicine (NLM) Common Data Elements have curated data elements corresponding to the items and calculated scores from these questionnaires. However, these resources are often used to make data consistent and reusable after, rather than during data collection. However, harmonizing data after acquisition is resource intensive and this approach can create a mismatch between collected and submitted data due to human error during the harmonization process. To faciliate tedious harmonization efforts, several projects, over the last two decades, have developed technologies to automatically or interactively align and harmonize data elements (e.g., BIRN mediator, OpenRefine).
Given the dynamic and evolving nature of scientific investigation, many questionnaires are altered when used to suit the requirements of a particular study (e.g., different language, selective and new questions). This information linking the specific information used when asking a question is often decoupled from the data element representing the response to the question. When questions are changed, researchers often shoehorn the response into an existing data element, thus creating additional noise. Another drawback to these data elements is that there is often no way to find out which version of a questionnaire was used or how exactly it was scored.
Our simpler solution is to enforce consistency directly at the data acquisition stage by relying on a common schema that encodes how the different elements of the data and / or the metadata relate to one another. This way, all this relational information between these elements is captured from the very start as it is already embedded in the formal description of the assessment. This solution was inspired by the work of CEDAR Metadata Model.
In this project we provide a comprehensive set of tools to create and use the schemas, while tracking the source of the schema, and changes to it over time. The ReproSchema project covers:
a schema that can be found in the present repository that describes the content and relations of the different elements of a questionnaire or set of assessment tools,
an associated curated library of reusable common assessments and questionnaires,
a python package to help create and validate the schemas of new assessments,
a user interface to visualize questionnaire and collect data locally,
a backend server to capture the data remotely.
In brief, ReproSchema offers a way to standardize the underlying representation of assessment tools. It comes with an open and accessible library of questionnaires with appropriate conversion (e.g., from/to RedCap) and data collection tools (e.g., MindLogger, RedCap, LORIS - future work) to enable a more consistent acquisition across projects, with data being harmonized by design.
at the item level, the elements of an individual assessment, like the questions in a questionnaire
at the activity level, an individual assessment that contains a set of items, like for example a whole questionnaire with a several questions.
at the protocols level, a collection of activities performed by a participant, e.g a set of questionnaires used in a study.
All those elements are specified text files in a JSON-LD format (JavaScript Object Notation for Linked Data) and each item, activity, and protocol provides unique and persistent identifiers.
Below we show an example of one of the possible ways a questionnaire with 3 questions for a study could be organized with a protocol for that study, one activity and 3 items.
The ReproSchema can also easily and flexibly specify details how the schema for an assessment should be used. Independently of what solution is chosen in the end by a researcher, a lab, or an institute to display the assessment to their participants or patients (for example whether using an Web-app written in javascript or a mobile app written in React-native), the schema can already specify:
the input type to choose among several user-interface rendering options e.g., a Likert scale, a dropdown menu, a multiple choice...
the visibility to decide whether a given item or activity should be displayed to the user and under which conditions,
the compute logic of how the total score to the responses on a questionnaire should be computed
The ReproSchema also allows for internationalization and multiple languages support by making it very easy to keep everything the same except the language displayed by the user interface.
Finally ReproSchema allows tracking of variations and version of different assessments tools (e.g., PHQ-9, PHQ-8).
"},{"location":"100_about_this_doc/","title":"About this documentation","text":"
This documentation is a work in progress and we wellcome any input: if something is missing or unclear, let us know by [opening an issue on our repository] (???).
"},{"location":"100_about_this_doc/#serving-the-doc-locally","title":"Serving the doc locally","text":"
This project uses MkDocs tool with Material theme and extra plugins to generate the website.
To test locally, you will need to install the Python dependencies. To do that, type the following commands:
If you are working on your fork, simply replace https://github.com/ReproNim/reproschema.git by git clone git@github.com/<username>/reproschema.git where <username> is your GitHub username
Once done, you need to run MkDocs. Simply type:
mkdocs serve\n
Finally, open up http://127.0.0.1:8000/ in your browser, and you should see the default home page of the being displayed.
The ReproSchema project is organized around several github repositories. The main ones are the following.
reproschema
reproschema-library
reproschema-py
reproschema-ui
reproschema-protocol-cookiecutter
A brief description of how they all interact could be along the following lines:
If you're gearing up to launch a research project that requires standardized questionnaires, starting with reproschema-protocol-cookiecutter is your best first step. This tool sets you up with a custom protocol for your study, integrating handy features for a smooth setup right from the get-go. You'll have two main paths for adding questionnaires, or activities, to your study:
Option 1: Dive into reproschema-library where we've got a stash of ready-made questionnaires. Pick what fits your study, and you're good to go.
Option 2: Feeling creative? Craft your own activities with reproschema-py. This tool not only lets you design new activities but also checks that they meet all the ReproSchema standards.
Once your protocol is packed with all the activities you need, reproschema-ui automatically steps in. This part of the toolkit lets you see your study in action before you even start, making sure everything's set up just right for gathering data.
The ReproSchema is like a blueprint for research projects, ensuring everyone collects data in a consistent way, which makes it easier to compare results from different studies. Here\u2019s a simpler breakdown of what\u2019s inside:
Key Terms: These are the building blocks, like common types of answers and data formats, that help everyone understand and use data the same way.
How Data is Organized: ReproSchema sorts information into three main layers to keep things neat:
Item Level: This is where individual questions or parts of a survey are detailed, allowing for close examination of each element.
Activity Level: At this stage, an entire survey or tool, made up of many items, is grouped together as an \"Activity.\" It gives a complete overview of what the survey involves.
Protocols Level: The highest level, a \"Protocol,\" bundles together all the activities a participant will do in a study, providing a comprehensive plan.
Validation: The schema uses special standards (like SHACL files) to make sure the data and forms are up to standard and consistent.
Context Files: These files (contextsand terms) specify user-interface details and enhance schema flexibility. They define elements like input types, visibility conditions, and response options, supporting a tailored user experience. Additionally, they enable internationalization and multiple language support for broad applicability.
There is also an example schema that can help give you a quick overview of what the protocol and activity for a study might look like. For more details see the schema section.
This repository hosts all the community curated assessments and questionnaires that support the ReproSchema standard.
Imagine this as curated library of reusable assessments and questionnaires, from where you can easily pull a copy from rather than having to photocopy a new questionnaire for your next participant or patient. Also you can mix and match items from this library, knowing that the information is tracked in your protocol.
All assessments are listed in the activity folder and are served here if you want to visualize them.
Standard Alignment: Each element in the library aligns with the ReproSchema framework, ensuring uniformity in terms and structure and upholding validation protocols for consistency across the ecosystem.
Research Protocol Integration: Researchers can utilize these assessments in various combinations to align with specific protocol needs, customizing their application per study objectives. This process can be integrated using the reproschema-protocol-cookiecutter for constructing user interfaces.
Collaborative Expansion: The library supports expansion through researcher contributions, allowing adding new, relevant assessments. These contributions are automatically validated using reproschema-py, maintaining the library\u2019s standardization and relevance to evolving research demands.
This is the ReproSchema python library. This is a python Command Line Interface (CLI) that allows you to help create and validate the schemas of new assessments.
Schema Development and Validation: This tool streamlines the creation and validation of new assessment schemas, verifying their alignment with ReproSchema's standards. It rigorously tests protocols, activities, and items to meet predefined specifications.
Consistency Assurance: Integrated with the ReproSchema-library and ReproSchema-Protocol-Cookiecutter, reproschema-py validates library assessments for quality and uniformity. It also automatically ensures the consistency of research protocols generated through the ReproSchema-Protocol-Cookiecutter.
Interoperability with REDCap: Its capability to convert between REDCap and ReproSchema formats exemplifies its role in harmonizing diverse data collection methods in complex, multi-faceted research environments.
The reproschema-protocol-cookiecutter is a straightforward tool that helps you quickly set up a research study. It offers a ready-to-use template for organizing your study's structure and surveys, ensuring everything meets standard guidelines. Think of it as a quick-start guide to get your research project up and running smoothly. A step-by-step guide see here.
The core model of ReproSchema was initially derived from the CEDAR Metadata Model. To accommodate the needs of neuroimaging and other clinical and behavioral protocols and assessments the schema has evolved significantly. These changes include:
Alignment with schema.org and NIDM. We have used schema.org classes and properties where it maps on to the needs of the model and extended the model with NIDM elements to harmonize across ReproNim projects.
Allowing for structued nested elements in a schema Protocol > Activity > [Activity | Field > ResponseOption]. This nested structure provides a flexible schema to represent nested activities, which are common in biomedical and other domains.
Interaction with git/Github or another Web service to deliver a new Protocol, Activity or Field with a persistent URI, while tracking changes associated with any of these elements. By making every Field represented through a persistent URI, a data collection instrument can link the responses to the exact Field that was used.
Addition of computable elements that are derived from the values entered by a participant.
Allowing for user interface (UI) elements that allow interaction between the schema and any implementation that allows collecting data using the schema. By providing some additional UI elements the provider can guide an implementor to allow for more complex data collection behavior.
The ReproSchema-UI is a prototype implementation of an UI that leverages these different elements of the schema.
"},{"location":"30_schema/#properties-of-reproschema-objects","title":"Properties of ReproSchema objects","text":"
This section lists the core ReproSchema objects and their allowed properties.
A representation of a study which comprises one or more assessments.
URI: http://schema.repronim.org/Protocol
Name Description URI addProperties An array of objects to describe the various properties added to assessments and fields. http://schema.repronim.org/addProperties allow An array of items indicating properties allowed on an activity or protocol http://schema.repronim.org/allow compute An array of objects indicating computations in an activity or protocol and maps it to the corresponding Field item. scoring logic is a subset of all computations that could be performed and not all computations will be scoring. For example, one may want to do conversion from one unit to another. http://schema.repronim.org/compute landingPage An element (by URL) to point to the protocol readme or landing page. http://schema.repronim.org/landingPage messages An array of objects to define conditional messages in an activity or protocol. http://schema.repronim.org/messages order An ordered list to describe the order in which the items of an assessment or protocol appear in the user interface. http://schema.repronim.org/order overrideProperties An array of objects to override the various properties added to assessments and fields. http://schema.repronim.org/overrideProperties preamble The preamble for an assessment http://schema.repronim.org/preamble shuffle An element (bool) to determine if the list of items is shuffled or in order. http://schema.repronim.org/shuffle about The subject matter of the Field. http://schema.org/about audio An embedded audio object. http://schema.org/audio description A description of the item. http://schema.org/description image An image of the item. This can be a URL or a fully described ImageObject. http://schema.org/image schemaVersion Indicates (by URL or string) a particular version of a schema used in some CreativeWork. For example, a document could declare a schemaVersion using an URL such as http://schema.org/version/2.0/ if precise indication of schema version was required by some application. http://schema.org/schemaVersion version The version of the CreativeWork embodied by a specified resource. http://schema.org/version video An embedded video object. http://schema.org/video altLabel The alternate label. http://www.w3.org/2004/02/skos/core#altLabel prefLabel The preferred label. http://www.w3.org/2004/02/skos/core#prefLabel"},{"location":"30_schema/#activity","title":"Activity","text":"
An assessment in a protocol.
URI: http://schema.repronim.org/Activity
Name Description URI addProperties An array of objects to describe the various properties added to assessments and fields. http://schema.repronim.org/addProperties allow An array of items indicating properties allowed on an activity or protocol http://schema.repronim.org/allow compute An array of objects indicating computations in an activity or protocol and maps it to the corresponding Field item. scoring logic is a subset of all computations that could be performed and not all computations will be scoring. For example, one may want to do conversion from one unit to another. http://schema.repronim.org/compute cronTable None http://schema.repronim.org/cronTable messages An array of objects to define conditional messages in an activity or protocol. http://schema.repronim.org/messages order An ordered list to describe the order in which the items of an assessment or protocol appear in the user interface. http://schema.repronim.org/order overrideProperties An array of objects to override the various properties added to assessments and fields. http://schema.repronim.org/overrideProperties preamble The preamble for an assessment http://schema.repronim.org/preamble shuffle An element (bool) to determine if the list of items is shuffled or in order. http://schema.repronim.org/shuffle about The subject matter of the Field. http://schema.org/about audio An embedded audio object. http://schema.org/audio citation A citation or reference to another creative work, such as another publication, web page, scholarly article, etc. http://schema.org/citation description A description of the item. http://schema.org/description image An image of the item. This can be a URL or a fully described ImageObject. http://schema.org/image schemaVersion Indicates (by URL or string) a particular version of a schema used in some CreativeWork. For example, a document could declare a schemaVersion using an URL such as http://schema.org/version/2.0/ if precise indication of schema version was required by some application. http://schema.org/schemaVersion version The version of the CreativeWork embodied by a specified resource. http://schema.org/version video An embedded video object. http://schema.org/video altLabel The alternate label. http://www.w3.org/2004/02/skos/core#altLabel prefLabel The preferred label. http://www.w3.org/2004/02/skos/core#prefLabel"},{"location":"30_schema/#field","title":"Field","text":"
An item in an assessment.
URI: http://schema.repronim.org/Field
Name Description URI additionalNotesObj A set of objects to define notes in a field. For example, most Redcap and NDA data dictionaries have notes for each item which needs to be captured in reproschema. http://schema.repronim.org/additionalNotesObj inputType An element to describe the input type of a Field item. http://schema.repronim.org/inputType preamble The preamble for an assessment http://schema.repronim.org/preamble responseOptions An element (object or by URL)to describe the properties of response of the Field item. http://schema.repronim.org/responseOptions about The subject matter of the Field. http://schema.org/about audio An embedded audio object. http://schema.org/audio description A description of the item. http://schema.org/description image An image of the item. This can be a URL or a fully described ImageObject. http://schema.org/image isPartOf Indicates an item or CreativeWork that this item, or CreativeWork (in some sense), is part of. http://schema.org/isPartOf question A sub property of object. A question. http://schema.org/question readonlyValue Whether or not a property is mutable. Default is false. Specifying this for a property that also has a value makes it act similar to a \"hidden\" input in an HTML form. http://schema.org/readonlyValue schemaVersion Indicates (by URL or string) a particular version of a schema used in some CreativeWork. For example, a document could declare a schemaVersion using an URL such as http://schema.org/version/2.0/ if precise indication of schema version was required by some application. http://schema.org/schemaVersion version The version of the CreativeWork embodied by a specified resource. http://schema.org/version video An embedded video object. http://schema.org/video altLabel The alternate label. http://www.w3.org/2004/02/skos/core#altLabel prefLabel The preferred label. http://www.w3.org/2004/02/skos/core#prefLabel"},{"location":"30_schema/#additionalproperty","title":"AdditionalProperty","text":"
An object to describe the various properties added to assessments and fields.
Name Description URI allow An array of items indicating properties allowed on an activity or protocol http://schema.repronim.org/allow isAbout A pointer to the node describing the item. http://schema.repronim.org/isAbout isVis An element to describe (by boolean or conditional statement) visibility conditions of items in an assessment. http://schema.repronim.org/isVis limit An element to limit the duration (uses ISO 8601) this activity is allowed to be completed by once activity is available. http://schema.repronim.org/limit maxRetakes Defines number of times the item is allowed to be redone. http://schema.repronim.org/maxRetakes randomMaxDelay Present activity/item within some random offset of activity available time up to the maximum specified by this ISO 8601 duration http://schema.repronim.org/randomMaxDelay schedule An element to set make activity available/repeat info using ISO 8601 repeating interval format. http://schema.repronim.org/schedule variableName The name used to represent an item. http://schema.repronim.org/variableName valueRequired Whether the property must be filled in to complete the action. Default is false. http://schema.org/valueRequired prefLabel The preferred label. http://www.w3.org/2004/02/skos/core#prefLabel"},{"location":"30_schema/#overrideproperty","title":"OverrideProperty","text":"
An object to override the various properties added to assessments and fields.
URI: http://schema.repronim.org/OverrideProperty
Name Description URI isAbout A pointer to the node describing the item. http://schema.repronim.org/isAbout isVis An element to describe (by boolean or conditional statement) visibility conditions of items in an assessment. http://schema.repronim.org/isVis limit An element to limit the duration (uses ISO 8601) this activity is allowed to be completed by once activity is available. http://schema.repronim.org/limit maxRetakes Defines number of times the item is allowed to be redone. http://schema.repronim.org/maxRetakes randomMaxDelay Present activity/item within some random offset of activity available time up to the maximum specified by this ISO 8601 duration http://schema.repronim.org/randomMaxDelay schedule An element to set make activity available/repeat info using ISO 8601 repeating interval format. http://schema.repronim.org/schedule variableName The name used to represent an item. http://schema.repronim.org/variableName valueRequired Whether the property must be filled in to complete the action. Default is false. http://schema.org/valueRequired prefLabel The preferred label. http://www.w3.org/2004/02/skos/core#prefLabel"},{"location":"30_schema/#unitoption","title":"UnitOption","text":"
An object to represent a human displayable name alongside the more formal value for units.
URI: http://schema.repronim.org/UnitOption
Name Description URI value The value for each option in choices or in additionalNotesObj http://schema.repronim.org/value prefLabel The preferred label. http://www.w3.org/2004/02/skos/core#prefLabel"},{"location":"30_schema/#responseoption","title":"ResponseOption","text":"
An element (object or by URL)to describe the properties of response of the Field item.
URI: http://schema.repronim.org/ResponseOption
Name Description URI choices An array to list the available options for response of the Field item. http://schema.repronim.org/choices datumType Indicates what type of datum the response is (e.g. range,count,scalar etc.) for the Field item. http://schema.repronim.org/datumType multipleChoice Indicates (by bool) if response for the Field item has one or more answer. http://schema.repronim.org/multipleChoice unitOptions A list of objects to represent a human displayable name alongside the more formal value for units. http://schema.repronim.org/unitOptions valueType The type of the response of an item. For example, string, integer, etc. http://schema.repronim.org/valueType maxValue The upper value of some characteristic or property. http://schema.org/maxValue minValue The lower value of some characteristic or property. http://schema.org/minValue unitCode The unit of measurement given using the UN/CEFACT Common Code (3 characters) or a URL. Other codes than the UN/CEFACT Common Code may be used with a prefix followed by a colon. http://schema.org/unitCode"},{"location":"30_schema/#choice","title":"Choice","text":"
An object to describe a response option.
URI: http://schema.repronim.org/Choice
Name Description URI value The value for each option in choices or in additionalNotesObj http://schema.repronim.org/value image An image of the item. This can be a URL or a fully described ImageObject. http://schema.org/image name The name of the item. http://schema.org/name"},{"location":"30_schema/#computespecification","title":"ComputeSpecification","text":"
An object to define computations in an activity or protocol.
Name Description URI jsExpression A JavaScript expression to compute a score from other variables. http://schema.repronim.org/jsExpression variableName The name used to represent an item. http://schema.repronim.org/variableName"},{"location":"30_schema/#messagespecification","title":"MessageSpecification","text":"
An object to define messages in an activity or protocol.
Name Description URI jsExpression A JavaScript expression to compute a score from other variables. http://schema.repronim.org/jsExpression message The message to be conditionally displayed for an item. http://schema.repronim.org/message"},{"location":"30_schema/#additionalnoteobj","title":"AdditionalNoteObj","text":"
A set of objects to define notes in a field. For example, most Redcap and NDA data dictionaries have notes for each item which needs to be captured in reproschema
URI: http://schema.repronim.org/AdditionalNoteObj
Name Description URI column An element to define the column name where the note was taken from. http://schema.repronim.org/column source An element to define the source (eg. RedCap, NDA) where the note was taken from. http://schema.repronim.org/source value The value for each option in choices or in additionalNotesObj http://schema.repronim.org/value"},{"location":"30_schema/#responseactivity","title":"ResponseActivity","text":"
Captures information about some action that took place. It also links to information (entities) that were used during the activity
URI: http://schema.repronim.org/ResponseActivity
Name Description URI endedAtTime None http://www.w3.org/ns/prov#endedAtTime generated None http://www.w3.org/ns/prov#generated startedAtTime None http://www.w3.org/ns/prov#startedAtTime used None http://www.w3.org/ns/prov#used wasAssociatedWith None http://www.w3.org/ns/prov#wasAssociatedWith inLanguage The language of the content or performance or used in an action. Please use one of the language codes from the IETF BCP 47 standard. See also [[availableLanguage]]. http://schema.org/inLanguage"},{"location":"30_schema/#response","title":"Response","text":"
Describes the response of an item.
URI: http://schema.repronim.org/Response
Name Description URI wasAttributedTo None http://www.w3.org/ns/prov#wasAttributedTo isAbout A pointer to the node describing the item. http://schema.repronim.org/isAbout value The value for each option in choices or in additionalNotesObj http://schema.repronim.org/value"},{"location":"30_schema/#participant","title":"Participant","text":"
An Agent describing characteristics associated with a participant.
URI: http://schema.repronim.org/Participant
Name Description URI subject_id The identifier of a participant http://purl.org/nidash/nidm#subject_id"},{"location":"30_schema/#softwareagent","title":"SoftwareAgent","text":"
Captures information about some action that took place. It also links to information (entities) that were used during the activity
URI: http://schema.repronim.org/SoftwareAgent
Name Description URI url URL of the item. http://schema.org/url version The version of the CreativeWork embodied by a specified resource. http://schema.org/version"},{"location":"41_create_new_protocol/","title":"Creating a Research Protocol Using Cookiecutter","text":"
Ready for your first ReproSchema project?! We are going to use the Reproschema Protocol Cookiecutter to create a demo protocol.
Prerequisite: Ensure you have Git and Cookiecutter installed on your system. If not, please refer to the installation guides for Git and Cookiecutter.
Generate Your Repository: Use the Reproschema Protocol Cookiecutter to create a new repository for your research protocol. Run the following command in your terminal:
Follow the prompts to customize your new protocol, more details see here
"},{"location":"41_create_new_protocol/#customizing-your-protocol","title":"Customizing Your Protocol","text":"
Once you run the Cookiecutter command, you will be prompted to make choices for your protocol, ranging from 1-5. These choices generate corresponding activities in your repository. Here's what you can do with these activities:
Use as Templates: The activities created based on your choices serve as templates. You can use these to understand the structure and elements within the activities folder. This is particularly useful if you're new to ReproSchema. By exploring these templates, you'll get a clearer picture of how activities are structured and what kind of information they contain.
Delete and Start Fresh: Alternatively, if you already have a clear idea of what your protocol needs, you can delete these generated activities. This allows you to start from scratch, creating activities that are tailored specifically to your research needs.
The inclusion of activity choices aims to provide users with a practical understanding of how activities are structured within ReproSchema protocols. Whether you use these as a starting point or prefer to create your own from the ground up, these templates are there to guide you in structuring your research protocol effectively.
We provide more detailed instructions for customizing your protocol in the following pages using reproschema-demo-protocol as an example.
"},{"location":"42_adopt_assessments/","title":"Adopting Assessments from the reproschema-library","text":"
This part focuses on how to select and integrate assessments from the reproschema-library into your research protocol, an essential step in crafting a comprehensive study. The chosen assessments are to be placed in the activities folder within your repository. This folder serves as the central hub for various assessments or activities that collectively form your research protocol.
Each activity or assessment within this activities folder is typically structured around a file named with a suffix _schema. This file defines the overall framework of the assessment. Accompanying this, if an assessment comprises specific questions, these are organized in a subfolder titled items within the respective activity's directory. It's important to note that if an assessment is directly taken from the ReproSchema-library without any customization, the creation of an items subfolder is not necessary, as the itemized questions are predefined in the library.
To illustrate this process, we will use two specific types of assessments from reproschema-library: demographics and psychological questions. The latter represents a composite assessment created from multiple pre-existing assessments within the library. This example demonstrates how to combine different elements from the library to construct a bespoke assessment tailored to the unique demands of your research protocol.
"},{"location":"42_adopt_assessments/#step-1-understand-the-structure-of-a-_schema-file-throught-this-exemplar-file","title":"Step 1: Understand the structure of a *_schema file throught this exemplar file","text":"
Context (@context): This field provides references to the context definitions. In this schema, it links to the generic context of ReproSchema and the specific context for the items in the repository, defined by the URL with the \"rl\" key. This context helps to interpret the terms used within the schema.
Type (@type): Defined as \"reproschema:Activity,\" this indicates the nature of the document, specifying that it is an activity within the ReproSchema framework.
Identifier (@id): The unique identifier for this specific schema is \"activity1_schema.\" This ID uniquely distinguishes this activity from others in the repository.
PrefLabel: This is the human-readable name of the activity, here given as \"Screening.\" It serves as a clear and concise title for the activity.
Description: Provides a brief overview of the activity, in this case, \"example of an activity.\"
SchemaVersion and Version: These fields indicate the versions of the ReproSchema being used (\"1.0.0-rc2\" means \u201c1.0.0 Release Candidate 2\u201d) and the version of this particular activity schema (\"0.0.1\"), respectively.
UI Configuration: This section specifies how the activity will be presented to users. It includes:
addProperties: Lists the variables and corresponding items collected in the activity. For example, the variable document_upload_item is about the item items/document_upload_item and is always visible (isVis: true). It allows for the item to be skipped (reproschema:Skipped).
order: Dictates the sequence in which items will appear in the UI. Here, it specifies that \"items/document_upload_item\" will be the first (and only) item.
shuffle: Indicates whether the order of items should be randomized. In this example, it is set to false, meaning the order is fixed.
allow: Defines additional UI functionalities. Here, it includes reproschema:AutoAdvance for automatic progression and reproschema:AllowExport to enable data export.
"},{"location":"42_adopt_assessments/#step-2-customizing-the-schema-file-for-demographics-using-existing-assessments-from-reproschema-library","title":"Step 2: Customizing the schema file for demographics using existing assessments from reproschema-library","text":"
This step involves precise modifications, particularly in the @context and addProperties sections, to ensure the schema accurately reflects the demographic data you aim to collect.
Adjusting the @context for Demographics:
In addition to the standard ReproSchema context, we've added a specific link in the \"@context\" section for demographics:
Labeling this link as \"demo\" directs the schema to the location in the ReproSchema-library where items for demographics and background information are defined. We use the link with a specific commit ID to ensure the consistency of the assessment version. This contextual link allows the schema to access the detailed structures and definitions needed for each demographic item.
Customizing \"addProperties\" for Demographic Variables:
In the \"addProperties\" section, we define each variable that corresponds to a demographic question. For example:
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.
Different from demograpgics, psychological_questionnaire_schema combines assessments, such as PHQ-9, GAD7, PC-PTSD-5, and demographics from reproschema-library.
Contextual setup (@context):
The @context section is expanded to include not only the generic ReproSchema context but also specific links to the ReproSchema-library. This enables the schema to access a broader range of predefined items and assessments. For the psychological questionnaire, two context links are established:
A link to the activities in the reproschema-library (activities: ) and a link for demographics items (demo: ), both are commit-specific. This indicates that we will combine different assessments from those two parts.
Defining the activity (@type, @id, prefLabel, etc.):
The standard fields like @type, @id, prefLabel, description, preamble, schemaVersion, and version define the nature and purpose of the psychological questionnaire.
UI configuration and integration of multiple assessments (ui):
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.
The order array specifies the sequence in which these assessments will appear in the questionnaire, ensuring a logical flow for participants.
The shuffle setting is false, maintaining the defined order, and allow includes functionalities like auto-advance between assessments and data export.
See the outcome here
"},{"location":"43_create_new_assess/","title":"Creating New Assessments for Unique Research Needs","text":"
This section provides the customized new assessments tailored to specific research needs. Our focus is on creating three distinct types of activities that are not readily available in the reproschema-library. These include: (1) clinical questions to gather clinical background information, (2) a speech task designed to collect audio data, and (3) an audio check to facilitate the speech task.
For each of these new assessments, the folder structure within the repository will differ slightly from those directly adopted from the reproschema-library. Specifically, each activity has its own dedicated folder within the activities directory. For instance, the speech task resides in activities/4_speech. Within this folder, besides the primary schema file (e.g., speech_schema), there is an additional subfolder named items. This items folder contains individual questions or tasks pertaining to that specific activity.
In the case of the speech task, the items folder might include a single task designed to prompt the participant to provide a speech sample. Similarly, for the clinical questions, their respective folders will contain items subfolders with corresponding questions tailored to elicit the required information.
The structure of an item within the items folder of a ReproSchema activity is similar to the schema template, but with key differences that cater to the specifics of individual data collection elements. Here's an explanation of the provided template for a country item:
Context and type (@context, @type): The @context remains the same, pointing to the generic context of ReproSchema. The @type is now \"reproschema:Field\" instead of \"reproschema:Activity\". This change signifies that this template defines a single data collection field or question within an activity, as opposed to the overall structure of an activity.
Identifier and descriptive fields (@id, prefLabel, description, etc.): @id serves as a unique identifier for the item, here named \"country_item\". prefLabel and description provide a human-readable name and a brief description of the item, similar to their use in the schema template.
Question field (question): This field contains the actual question or prompt that will be presented to the participant. In this template, it reads: \"This is an item where the user can select a country.\"
UI configuration (ui): The ui section in the item template differs from the schema template. It specifies how the question will be presented to the user. The inputType is set to \"selectCountry\", indicating that the user interface will provide a country selection method.
Response options (responseOptions): This section defines the nature and structure of the responses allowed for the item. In this example, it specifies the valueType as \"xsd:string\" and a maxLength of 50 characters. It also provides a URL to a list of choices, in this case, a JSON file containing country names. This link allows the questionnaire to dynamically fetch and display a list of countries as response options.
"},{"location":"43_create_new_assess/#step-1-specifying-inputtype-and-responseoption-to-gather-precise-data","title":"Step 1: Specifying inputType and responseOption to gather precise data","text":"
We have crafted ten items in the 'items' folder for the clinical questions assessment. Each item, such as alcohol_consumption, height, weight, etc., has its ui inputType and responseOptions specifically defined to suit the nature of the question.
Take 'alcohol_consumption' as an example. The UI configuration and response options for this question are tailored to capture a straightforward piece of information:
The ui section sets the inputType to \"radio\". This choice indicates that the question will be presented to the participant as a radio button selection, providing a simple and clear interface for response selection.
In the responseOptions, the valueType is defined as \"xsd:string\", signifying that the expected type of response is a string. The multipleChoice field is set to false, indicating that participants can only select one of the provided options.
The choices array lists the possible responses. In this case, there are two: \"Yes\" and \"No\", each with a corresponding value (1 for Yes, 2 for No) and translations provided for English (\"en\") and Spanish (\"es\").
For the speech task in our demo project, the configuration of ui inputType and responseOptions is distinctively tailored to facilitate audio data collection:
In the ui section, the inputType is set to \"audioPassageRecord\". This specific input type is designed to enable participants to record an audio passage directly within the questionnaire interface.
The responseOptions are configured to accommodate the nature of audio data.
The valueType is specified as \"schema:AudioObject\", indicating that the response will be an audio file.
The fields minValue and maxValue define the allowable duration of the audio recording in milliseconds. In this case, the maximum duration is set to 60,000 milliseconds (or 1 minute).
"},{"location":"43_create_new_assess/#step-2-integrating-additional-components-for-activity-specific-needs","title":"Step 2: Integrating additional components for activity-specific needs","text":"
We can integrate additional components tailored to the unique requirements of specific activities. For instance, considering the unique needs of our speech task, we add an 'audio check' component to confirm the functionality of the audio recording feature.
Setting up an audio check for the speech task
To ensure the effectiveness of our speech task, we create an activity for audio verification within the activities folder, naming it 0_audio. This folder contains the audio_check_schema, a schema specifically designed to test and confirm that the audio recording system is operational and effective for participants.
Contextual and properties configuration for audio check
The @context section includes a specific context link under \"voice\", pointing to the repository with items relevant to voice and audio tasks: \"<https://raw.githubusercontent.com/ReproNim/reproschema-library/.../VoiceTask/items/>\" This targeted link ensures that the audio check activity aligns with the specific requirements of voice-related tasks.\n\nThe ui's `addProperties` array is tailored for the audio check. We define a property `\"variableName\": \"audio_check\"` linked to `\"isAbout\": \"voice:audio_check\"`.\n
"},{"location":"44_setup_feedback/","title":"Adding a customized feedback section","text":"
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.
{\n \"@context\": \"https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc4/contexts/generic\",\n \"@type\": \"reproschema:Field\",\n \"@id\": \"feedback\",\n \"prefLabel\": \"Feedback\",\n \"description\": \"schema to record text response of overall feedback of the protocol\",\n \"schemaVersion\": \"1.0.0-rc4\",\n \"version\": \"0.0.1\",\n \"question\": {\n \"en\": \"Please leave any comments or suggestions on the study so we can improve it (or skip):\",\n \"es\": \"Deje cualquier comentario o sugerencia sobre el estudio para que podamos mejorarlo (u omitir):\"\n },\n \"ui\": {\n \"inputType\": \"textarea\"\n },\n \"responseOptions\": {\n \"valueType\": \"xsd:string\"\n }\n}\n
The feedback item in this activity (5_feedback) is specifically designed to gather open-ended responses, allowing participants to share their thoughts and suggestions:
Item Structure: The item feedback is set up with an identification and purpose, indicated by its '@id' and descriptive fields.
Question Prompt: The question is presented in both English and Spanish, encouraging participants to provide comments on their study experience. It\u2019s 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\".
"},{"location":"45_finalize_protocol/","title":"Finalizing the Protocol","text":"
After setting up individual activities, we return to the main protocol schema to organize everything cohesively. This step involves structuring the 'DemoProtocol_schema' to include all the activities we have developed, defining their sequence and presentation within the overall research protocol. In the 'DemoProtocol_schema', located in the 'DemoProtocol' folder, we integrate each activity schema using the following approach:
Context and protocol definition
The @context, @type, @id, and descriptive fields (prefLabel, description, etc.) provide the foundational information about the protocol.
Inclusion of activities
The ui section's addProperties array is crucial. Here, each activity schema we've created is referenced under isAbout, with its respective variableName and prefLabel. For example, the audio activity is linked as
This structure is repeated for each activity, including audio check, demographics, psychological questions, clinical questions, speech task, and feedback.\n
Order of presentation
The order array within ui specifies the sequence in which these activities will appear in the protocol. It's arranged to flow logically from consent, through various assessments, to the final feedback, ensuring a structured participant experience. For instance, the order starts with ../activities/0_audio/audio_check_schema and progresses through to ../activities/5_feedback/feedback_schema.
Additional UI settings
'shuffle' is set to false to maintain the specified order.
'allow' includes functionalities such as 'reproschema:AllowExport' for data exporting options.
Update README.md
Give clear and concise instructions on what this protocol is about and how participants should use it.
Upon finalizing our protocol with the integrated activities, the end result is a fully interactive research tool hosted on our GitHub repository. For data collection, this tool can be linked to a backend server, or participants can be given the option to export their data directly.
In the world of research data management, flexibility and compatibility are key. Understanding this, we provide specialized tools designed to create, validata schemas, and convert data between ReproSchema format and REDCap CSV format. Whether you're transitioning from REDCap to ReproSchema or vice versa, these tools ensure a smooth and efficient conversion process, preserving the integrity and structure of your data.
reproschema-py can be used as a Commend-Line Interface.
$ reproschema\nUsage: reproschema [OPTIONS] COMMAND [ARGS]...\n\n A client to support interactions with ReproSchema\n\n To see help for a specific command, run\n\n reproschema COMMAND --help e.g. reproschema validate --help\n\nOptions:\n --version\n -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]\n Log level name [default: INFO]\n --help Show this message and exit.\n\nCommands:\n convert\n create\n redcap2reproschema Convert REDCap CSV files to Reproschema format.\n reproschema2redcap Convert reproschema protocol to REDCap CSV format.\n serve\n validate\n
<input_dir_path>: The path to the root folder of a protocol. For example, to convert the reproschema-demo-protocol provided by ReproNim, you can use the following commands:
bash git clone https://github.com/ReproNim/reproschema-demo-protocol.git cd reproschema-demo-protocol pwd
In this case, the output from pwd (which shows your current directory path)should be your <input_dir_path>. - <output_csv_filename>: The name of the output CSV file where the converted data will be saved.
The redcap2reproschema function is designed to process a given REDCap CSV file and YAML configuration to generate the output in the reproschema format.
Those tools can also be used as Python functions. For detailed instructions, please visit reproschema-py.
"},{"location":"98_FAQ/","title":"FAQ","text":""},{"location":"98_FAQ/#what-is-the-semantic-web","title":"What is the semantic web?","text":"
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.
A short video intro to the semantic web by Manu Sporny:
"},{"location":"98_FAQ/#what-is-linked-data","title":"What is linked data?","text":""},{"location":"98_FAQ/#the-theory","title":"The theory","text":"
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]
Linked data has some basic principles behind it (adapted from wikipedia):
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.
"},{"location":"98_FAQ/#a-more-concrete-example","title":"A more concrete example","text":"
As things might be be quite abstract, here is a simple example of linked data to help make things more concrete:
{\n \"@context\": \"http://schema.org\",\n \"name\": \"Barack Obama\",\n \"givenName\": \"Barack\",\n \"familyName\": \"Obama\",\n \"jobTitle\": \"44th President of the United States\"\n}\n
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. 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). 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.
Here is a TED talk by Tim Berners-Lee on linked data.
A short video intro to linked data by Manu Sporny:
"},{"location":"98_FAQ/#what-is-json-ld","title":"What is JSON-LD?","text":""},{"location":"98_FAQ/#what-is-json","title":"What is JSON?","text":"
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 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.
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 or jsonlint. This will quickly tell you a) whether this is a valid JSON format (eaning if it respects the rules of how a JSON file should be formatted) and b) it will highlight and help you navigate the nested and hierarchical nature of the JSON file.
Insert image ???
OK but let's start with a much simpler example of a JSON file, like the one below which could be the content of JSON file returned by a website when asked about a certain person.
{\n \"name\": \"Barack Obama\",\n \"givenName\": \"Barack\",\n \"familyName\": \"Obama\",\n \"jobTitle\": \"44th President of the United States\"\n}\n
Looks familiar? It is very close to the one we had at the end of the previous FAQ section.
"},{"location":"98_FAQ/#from-json-to-json-ld","title":"From JSON to JSON-LD","text":"
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.
{\n \"@context\": \"http://schema.org\",\n \"name\": \"Barack Obama\",\n \"givenName\": \"Barack\",\n \"familyName\": \"Obama\",\n \"jobTitle\": \"44th President of the United States\"\n}\n
\ud83c\udf89 Congratulations! \ud83c\udf89
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. 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. 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:
It would be a stretch to say that the JSON-LD specifications 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:
"},{"location":"98_FAQ/#why-is-linked-data-important-for-the-reproschema","title":"Why is linked data important for the ReproSchema ?","text":""},{"location":"98_FAQ/#which-assessments-tools-willare-supporting-this-standard","title":"Which assessments tools will/are supporting this standard?","text":"
At the moment, all the assessments that support this standard are listed in this folder or the reproschema-library repository.
If you want to see those different tools in action using our user interface, you can explore them on schema.repronim.org/.
The ReproSchema is also used to develop a checklist to improve methods and results reporting in neuroimaging.
\ud83d\udee0 Work in progress \ud83d\udee0
"},{"location":"98_FAQ/#why-should-i-use-reproschema","title":"Why should I use ReproSchema?","text":"
\ud83d\udee0 Work in progress \ud83d\udee0
"},{"location":"98_FAQ/#who-is-reproschema-for","title":"Who is ReproSchema for?","text":"
\ud83d\udee0 Work in progress \ud83d\udee0
"},{"location":"98_FAQ/#how-can-i-know-if-a-certain-property-is-supported-by-reproschema","title":"How can I know if a certain property is supported by ReproSchema?","text":"
\ud83d\udee0 Work in progress \ud83d\udee0
"},{"location":"98_FAQ/#how-can-i-add-a-property-to-my-schema","title":"How can I add a property to my schema?","text":"
\ud83d\udee0 Work in progress \ud83d\udee0
"},{"location":"98_FAQ/#how-are-these-assessments-licensed","title":"How are these assessments licensed?","text":"
\ud83d\udee0 Work in progress \ud83d\udee0
"},{"location":"98_FAQ/#how-can-i-contribute-to-the-project","title":"How can I contribute to the project?","text":"
\ud83d\udee0 Work in progress \ud83d\udee0
"},{"location":"98_FAQ/#an-assessment-tool-i-regularly-use-is-not-supported-by-reproschema-how-can-i-add-it","title":"An assessment tool I regularly use is not supported by ReproSchema: how can I add it?","text":"
\ud83d\udee0 Work in progress \ud83d\udee0
"},{"location":"98_FAQ/#how-can-i-visualize-the-schema-for-a-protocol-or-an-activity","title":"How can I visualize the schema for a protocol or an activity?","text":"
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.
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 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:
