content/howtos/pool-tool/document-instruments/create-edit-instrument.webp

@@ -0,0 +1 @@
+/annex/objects/MD5E-s100198--579267f99885d10884f7adc46284a7dc.webp

content/howtos/pool-tool/document-instruments/edit-instrument-pid.webp

@@ -0,0 +1 @@
+/annex/objects/MD5E-s75168--1d4832e23cae006be20cbc094a9319ce.webp

content/howtos/pool-tool/document-instruments/example-original-questionnaire.webp

@@ -0,0 +1 @@
+/annex/objects/MD5E-s48008--cd17146e9f63f7307b6d95f772920e5f.webp

content/howtos/pool-tool/document-instruments/example-questionnaire-item.webp

@@ -0,0 +1 @@
+/annex/objects/MD5E-s38766--00f4f92f8323763bbff3f600f6045ce9.webp

content/howtos/pool-tool/document-instruments/example-questionnaire-subscale.webp

@@ -0,0 +1 @@
+/annex/objects/MD5E-s30952--3b2fa5d12a6b8fc3158078442dd42187.webp

content/howtos/pool-tool/document-instruments/example-questionnaire-variant.webp

@@ -0,0 +1 @@
+/annex/objects/MD5E-s36764--6dd6338abd12d52c29db4d1d62956482.webp

content/howtos/pool-tool/document-instruments/index.md

@@ -0,0 +1,207 @@
+---
+title: Document instruments and questionnaires
+weight: 30
+---
+
+TRR379 uses  the [knowledge pool]({{% ref "references/services/knowledge-pooling/" %}}) to document research instruments and questionnaires, and to provide standardized identifiers that can be used when harmonizing data across sites.
+
+You can document an instrument at different levels.
+In particular, questionnaires can be documented as:
+- the **original instrument or questionnaire**,
+- a **TRR379-specific version or variant**,
+- individual **questionnaire items**, and
+- where useful, **site-specific versions** of an instrument or item.
+
+These records can be linked to one another to expose the relationships between the original instrument, TRR379 versions, and individual questionnaire items.
+
+**You do not need to complete every level or every metadata field at once.**
+Instrument documentation is an iterative process.
+A basic record with a clear identifier and name is already useful and can be expanded later.
+
+## Document an instrument
+
+If you have an instrument that is used in TRR379, start by creating an Instrument record in the [knowledge pool]({{% ref "references/services/knowledge-pooling/" %}}).
+At a minimum, give the instrument a meaningful name and a persistent identifier.
+
+If you know the description, instrument type, source publication, or relationships to other records, add those as well.
+You can always add additional information later.
+
+1. Navigate to the [knowledge pooling tool]({{% ref "/references/services/knowledge-pooling/" %}}).
+2. {{% expand title="Log in using your associated TRR379 hub account." %}}
+
+- Click the "Login" (human silhouette) button.
+- Select the "Login with TRR379 hub" option.
+- Read the disclaimer, and if you agree, select  "Authorize Application".
+- A checkmark will appear on to the "Login" (human silhouette) button if you were successfully logged in.
+
+{{% /expand %}}
+
+3. Select the "Instrument" Data Type on the left side of the page.
+4. Create a new record by clicking the `+` (plus) button, or edit an existing record by clicking the pencil icon.
+
+![Screenshot showing the add- and edit-buttons for an instrument record](create-edit-instrument.webp)
+
+5. Click the "Edit PID manually" button (pencil icon to the right of "Persistent identifier") and edit the random identifer according to the following naming convention:
+
+```
+trr379:instruments/<original_instrument>-<trr379_variant_and_version>-<item_or_subscale_name>
+```
+
+Click the "Persistent identifer" pencil icon again to lock the PID editor.
+
+{{% notice style="accent" title="Important information about PIDs" icon="bolt" %}}
+**PIDs should be human-readable** and should be sufficient for a knowledgeable human to understand what content is likely contained in that record.
+These PIDs will end up as column header values in pertinent data tables.
+The prefix, `trr379:` expands to https://trr379.de/ns/, and can be left out in any TRR379 internal usage.
+Within the scope of a data table, the instrument identifier can be further shorted by stripping `trr379:instruments/`, leaving, for example, `lha-trr379-q01-item1` as an item identifier (e.g., as a column header value).
+{{% /notice %}}
+
+6. Within the "Name" box, enter a human-readable name for the content in your Instrument record.
+As is relevant, this might take the format: <original_instrument_name>, <subscale_name> (<trr379_variant>), or for a specific questionnaire item it would simply be the text for that question.
+7. Add whatever metadata you have available (see also [Relationships](#relationships) and [Additional metadata](#additional-metadata)).
+
+![Screenshot showing the "Edit PID manually" button, "Name" box, and additional metadata (i.e., "Description")](edit-instrument-pid.webp)
+
+8. Once all relevant information has been entered, click "SAVE" in the top-right corner to save the Instrument record.
+9. Click the "Submit" button (cloud icon, top-right), which should show a green notification dot to indicate changes are ready to be submitted.
+
+![Screenshot showing an annotated Instrument record and highlighting the submission button](submit-instrument.webp)
+
+{{% notice style="accent" title="Important note about saving versus submitting" icon="bolt" %}}
+The pool has two separate actions: saving and submitting.
+**Saving stores your work in the browser only!**
+It does **not** *submit* the record to the server for use by the consortium workflows.
+To submit, click the Submit button (cloud icon, top-right corner) when there is a green notification dot indicating records are ready for submission.
+**Do not close your browser tab before submitting**, or your data will be lost.
+{{% /notice %}}
+
+10. The interface will list all records you are about to submit. You should see your Instrument record here.
+11. Click "Submit". A confirmation message will appear when submission is successful. If an error occurs, note the message and retry. If it persists, you may wish to review common error messages or reach out for help via the resources in the [Support]({{% ref "/support/" %}}) page.
+
+{{% notice style="primary" title="Tip" icon="lightbulb" %}}
+**At a minimum:**
+- Use a meaningful, human-readable PID.
+- Give the record a meaningful name.
+- Save and submit the record.
+
+Everything after that is a (welcomed) bonus.
+{{% /notice %}}
+
+## Document a questionnaire
+
+Questionnaires can be represented at several levels.
+
+```
+Original instrument
+    │
+    └─ TRR379 variant
+          │
+          ├─ Item 1
+          ├─ Item 2
+          ├─ Item 3
+          └─ ...
+```
+
+### Original questionnaire
+
+If the original instrument/questionnaire is known, [create a record](#document-an-instrument) for it, give it a PID in the format, `trr379:instruments/<original_instrument>` (e.g., `trr379:instruments/lha`) and, where possible, link it to its source publication or other canonical documentation.
+
+![Example of an annotated original instrument, highlighting the PID and links to source documentation](example-original-questionnaire.webp)
+
+### TRR379 questionnaire variant
+
+TRR379-specific versions take on the PID format, `trr379:instruments/<original_instrument>-<trr379_variant_and_version>` (e.g., `trr379:instruments/lha-trr379-q01`).
+This is where you should document meaninful differences from the original questionnaire, including:
+- translation
+- modified wording
+- different item selection
+- coding differences
+- particular TRR379 projects using the variant
+
+![Example of an annotated variant, highlighting the PID and links to the original instrument](example-questionnaire-variant.webp)
+
+### Questionnaire items
+
+If the individual questionnaire subscales and/or items (i.e., questions) are known, [create a separate Instrument record](#document-an-instrument) for each item.
+For LHA, for example:
+```
+trr379:instruments/lha-trr379-q01-subscale-aggression
+trr379:instruments/lha-trr379-q01-subscale-consequences
+trr379:instruments/lha-trr379-q01-subscale-selfdirected
+trr379:instruments/lha-trr379-q01-item1
+trr379:instruments/lha-trr379-q01-item2
+...
+```
+
+Item-level identifiers allow sites to refer to the same questionnaire items consistently when preparing standardized datasets.
+
+For each item, be sure to include:
+- **Name**: the actual question/item text
+- **`part of`**: the questionnaire/variant it belongs to
+
+![Example of an annotated subscale, highlighting the PID and links to the relevant questionnaire](example-questionnaire-subscale.webp)
+
+When available, this also where value encodings for answer options may be recorded.
+
+![Example of an annotated questionnaire item, highlighting the value encodings](example-questionnaire-item.webp)
+
+## Relationships
+
+Relationships are useful when you know how the record relates to another instrument or questionnaire.
+
+| Relationship | Use when... | Example |
+|--------------|-------------|---------|
+| `part of`    | An item/subscale belongs to a questionnaire | There are 11 individual items that are `part of` the LHA |
+| `alternate of` | Two records represent alternative versions of the same instrument | A TRR379 variant may be an `alternate of` the original instrument |
+| `derived from` | A version was created from an earlier/original instrument | A TRR379 questionanire might be `derived from` the original instrument through the "Activity", "Translation" |
+| `revision of` | A new version revises an earlier version | A second version of a TRR379 questionnaire is a `revision of` the first version of that TRR379 questionnaire |
+
+## Additional metadata
+
+For instruments to live up to their fullest metadata potential, proceed to add relevant information as you are able.
+For example:
+
+{{% expand title="Description" %}}
+
+- Within the "Description" box, enter any information that is pertinant to understand what content is contained in your Instrument record.
+For example, this may be a description/abstract taken directly from an original instrument's documentation or related publication, or this could include details on how a TRR379 variant was changed (or not) from the original form (e.g., translations, item coding, which TRR379 projects use the variant, etc.)
+
+{{% /expand %}}
+
+{{% expand title="Instrument type" %}}
+
+- Within the "Instrument type" box, select the appropriate type from the dropdown menu.
+- For questionnaires and their items, relevant types might include (but are not limited to): Psychological Assessment, Clinical or Research Assessment Subscale, Clinical or Research Assessment Question
+
+{{% /expand %}}
+
+{{% expand title="Topic(s)" %}}
+
+- Within the "About" box, select the "FILTER DATA" button and make sure only "Topic" is checked to browse and select from the dropdown menu topics relevant to your Instrument record.
+- To add additional topics, select the `+` (plus) button to the right of the "About" box.
+
+{{% /expand %}}
+
+{{% expand title="Relationship(s)" %}}
+
+- Within the relevant "Part of", "Alternate of", and/or "Specialization of" boxes, select the linked Instrument record from the dropdown menu. For example, a TRR379 questionnaire variant may be an `alternate of` the original instrument, a subscale may be `part of` a TRR379 variant, and a questionnaire item may be `part of` a TRR379 variant, as well as a subscale.
+- To add additional links, select the `+` (plus) button to the right of the "Part of", "Alternate of", and/or "Specialization of" boxes.
+
+{{% /expand %}}
+
+{{% expand title="Provenance" %}}
+
+Where known, record where an instrument or questionnaire variant came from, and how it relates to previous versions.
+
+- **Add source documentation and contributors:** Within the "Attributed to" box, select "Person" from the dropdown menu. Search for or add the author that contributed to the Instrument you are documenting. You can additiomal link the source documentation by adding to the "Characterized box" a new item with the Predicate, "is described by", and the Object linking to the relevant Publication.
+- **Add derivations for variants:** Within the "Derived from" box, select the linked Instrument record from the drop down menu. Click the pencil icon to the right of the box to add the "Generated by" relationship. For example, a TRR379 questionnaire might be `derived from` the original instrument through the "Activity", "Translation". Click "SAVE" in the top-right corner to save the derivation information.
+- **Add revisions for different versions:** Within the "Revision of" box, select "ADD NEW ITEM". Within the "Entity" box, select the instrument your record is a revision of. For example, a second version of a TRR379 questionnaire is a `revision of` the first version of that TRR379 questionnaire. Click "SAVE" in the top-right corner to save the revision information.
+
+{{% /expand %}}
+
+{{% expand title="Value encodings" %}}
+
+- For counts, select the "Count" Concept within the "About" box's dropdown menu and "range (value type): nonNegativeInteger" from the "Characterized by" box's dropdown menu.
+- For categorical values, select "ADD NEW ITEM" within the "Attributes" box. At a minimum enter the "Value" and its "Description". Select "assumes values specified by" within the "Predicate" box. Optionally, you can add semantics for "Defined by" and "Value type (range)" when appropriate.
+
+{{% /expand %}}

content/howtos/pool-tool/document-instruments/submit-instrument.webp

@@ -0,0 +1 @@
+/annex/objects/MD5E-s80582--eb416bc69998b8b3b4c7d75ed75800fe.webp