psytools 0.3.1 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -14
- package/SOURCES.md +63 -33
- package/dist/cjs/assessment.d.ts +6 -4
- package/dist/cjs/assessment.js +10 -6
- package/dist/cjs/errors.d.ts +4 -2
- package/dist/cjs/evaluation.d.ts +10 -5
- package/dist/cjs/evaluation.js +68 -31
- package/dist/cjs/i18n.d.ts +1 -1
- package/dist/cjs/i18n.js +2 -2
- package/dist/cjs/index.d.ts +5 -3
- package/dist/cjs/index.js +4 -2
- package/dist/cjs/inventories/aq10.js +37 -5
- package/dist/cjs/inventories/asrs6.js +30 -6
- package/dist/cjs/inventories/audit.d.ts +10 -0
- package/dist/cjs/inventories/audit.js +322 -0
- package/dist/cjs/inventories/common.js +10 -0
- package/dist/cjs/inventories/dass21.js +77 -19
- package/dist/cjs/inventories/gad7.js +25 -5
- package/dist/cjs/inventories/index.d.ts +4 -2
- package/dist/cjs/inventories/index.js +7 -1
- package/dist/cjs/inventories/mini-ipip.d.ts +11 -0
- package/dist/cjs/inventories/mini-ipip.js +370 -0
- package/dist/cjs/inventories/phq9.js +32 -6
- package/dist/cjs/inventories/who5.js +33 -5
- package/dist/cjs/types.d.ts +30 -1
- package/dist/esm/assessment.d.ts +6 -4
- package/dist/esm/assessment.js +11 -7
- package/dist/esm/errors.d.ts +4 -2
- package/dist/esm/evaluation.d.ts +10 -5
- package/dist/esm/evaluation.js +68 -31
- package/dist/esm/i18n.d.ts +1 -1
- package/dist/esm/i18n.js +1 -1
- package/dist/esm/index.d.ts +5 -3
- package/dist/esm/index.js +2 -2
- package/dist/esm/inventories/aq10.js +37 -5
- package/dist/esm/inventories/asrs6.js +30 -6
- package/dist/esm/inventories/audit.d.ts +10 -0
- package/dist/esm/inventories/audit.js +319 -0
- package/dist/esm/inventories/common.js +10 -0
- package/dist/esm/inventories/dass21.js +77 -19
- package/dist/esm/inventories/gad7.js +25 -5
- package/dist/esm/inventories/index.d.ts +4 -2
- package/dist/esm/inventories/index.js +5 -1
- package/dist/esm/inventories/mini-ipip.d.ts +11 -0
- package/dist/esm/inventories/mini-ipip.js +367 -0
- package/dist/esm/inventories/phq9.js +32 -6
- package/dist/esm/inventories/who5.js +33 -5
- package/dist/esm/types.d.ts +30 -1
- package/package.json +6 -2
- package/schema/assessment-definition.schema.json +15 -3
- package/src/assessment.ts +15 -9
- package/src/errors.ts +25 -2
- package/src/evaluation.ts +103 -30
- package/src/i18n.ts +1 -1
- package/src/index.ts +8 -1
- package/src/inventories/aq10.ts +39 -5
- package/src/inventories/asrs6.ts +32 -6
- package/src/inventories/audit.ts +325 -0
- package/src/inventories/common.ts +10 -0
- package/src/inventories/dass21.ts +78 -19
- package/src/inventories/gad7.ts +26 -5
- package/src/inventories/index.ts +14 -2
- package/src/inventories/mini-ipip.ts +372 -0
- package/src/inventories/phq9.ts +33 -6
- package/src/inventories/who5.ts +34 -5
- package/src/types.ts +38 -6
package/README.md
CHANGED
|
@@ -19,7 +19,7 @@ That's a complete depression screening: standardized items, answer validation, p
|
|
|
19
19
|
|
|
20
20
|
## Why psytools
|
|
21
21
|
|
|
22
|
-
- **Batteries included** — PHQ-9, GAD-7,
|
|
22
|
+
- **Batteries included** — eight instruments (PHQ-9, GAD-7, DASS-21, WHO-5, ASRS, AQ-10, AUDIT, Mini-IPIP) ship ready to use in English, Turkish, German, Chinese, and Spanish, with published scoring rules and citations.
|
|
23
23
|
- **Your tests too** — therapists and researchers can define their own instruments as one plain JSON object; psytools validates, localizes, and scores them the same way.
|
|
24
24
|
- **Everything is plain JSON** — assessments and responses `stringify()`/`parse()` losslessly, so definitions live in your database and travel between backend and frontend. Scoring rules are data, not code, and survive the round trip.
|
|
25
25
|
- **Safe by default** — every answer is validated against the option scale, incomplete responses can't be scored accidentally, and submitted responses are immutable.
|
|
@@ -61,7 +61,7 @@ const result = phq9.evaluate(response);
|
|
|
61
61
|
|
|
62
62
|
// evaluate() refuses responses that are not complete/submitted;
|
|
63
63
|
// score partial data explicitly:
|
|
64
|
-
phq9.evaluate(inProgressResponse,
|
|
64
|
+
phq9.evaluate(inProgressResponse, { allowIncomplete: true });
|
|
65
65
|
|
|
66
66
|
// 4. Persist — both sides are plain JSON.
|
|
67
67
|
db.save(response.stringify()); // response -> DB
|
|
@@ -81,12 +81,14 @@ const response = AssessmentResponse.parse(assessment, rowFromDb); // answers re-
|
|
|
81
81
|
|
|
82
82
|
| Id | Instrument | Items | Scoring | Locales |
|
|
83
83
|
| --- | --- | --- | --- | --- |
|
|
84
|
-
| `phq9` | Patient Health Questionnaire-9 (depression) | 9 | Sum 0–27, 5 severity bands, item-9 suicidality flag | en, tr, de |
|
|
85
|
-
| `gad7` | Generalized Anxiety Disorder-7 | 7 | Sum 0–21, 4 severity bands | en, tr, de |
|
|
86
|
-
| `dass21` | Depression Anxiety Stress Scales (short form) | 21 | 3 subscales × 7 items, sums doubled, banded per subscale | en, tr, de |
|
|
87
|
-
| `who5` | WHO-5 Well-Being Index | 5 | Sum × 4 → 0–100 (higher is better), 3 well-being bands | en, tr, de |
|
|
88
|
-
| `asrs6` | Adult ADHD Self-Report Scale (ASRS-v1.1) screener | 6 | Count of screen-positive items (per-item thresholds), ≥4 positive | en, tr, de |
|
|
89
|
-
| `aq10` | Autism Spectrum Quotient (AQ-10, adult) | 10 | 1 point per item in trait direction (agree/disagree), ≥6 refer | en, tr, de |
|
|
84
|
+
| `phq9` | Patient Health Questionnaire-9 (depression) | 9 | Sum 0–27, 5 severity bands, item-9 suicidality flag | en, tr, de, zh, es |
|
|
85
|
+
| `gad7` | Generalized Anxiety Disorder-7 | 7 | Sum 0–21, 4 severity bands | en, tr, de, zh, es |
|
|
86
|
+
| `dass21` | Depression Anxiety Stress Scales (short form) | 21 | 3 subscales × 7 items, sums doubled, banded per subscale | en, tr, de, zh, es |
|
|
87
|
+
| `who5` | WHO-5 Well-Being Index | 5 | Sum × 4 → 0–100 (higher is better), 3 well-being bands | en, tr, de, zh, es |
|
|
88
|
+
| `asrs6` | Adult ADHD Self-Report Scale (ASRS-v1.1) screener | 6 | Count of screen-positive items (per-item thresholds), ≥4 positive | en, tr, de, zh, es |
|
|
89
|
+
| `aq10` | Autism Spectrum Quotient (AQ-10, adult) | 10 | 1 point per item in trait direction (agree/disagree), ≥6 refer | en, tr, de, zh, es |
|
|
90
|
+
| `audit` | Alcohol Use Disorders Identification Test (WHO) | 10 | Sum 0–40 with per-question point systems, 4 WHO risk zones | en, tr, de, zh, es |
|
|
91
|
+
| `mini-ipip` | Mini-IPIP Big Five personality scale | 20 | 5 trait subscales (4–20 each), reverse-keyed items, no cutoffs | en, tr, de, zh, es |
|
|
90
92
|
|
|
91
93
|
```ts
|
|
92
94
|
import { loadInventory, inventories, dass21 } from "psytools";
|
|
@@ -145,6 +147,20 @@ Questions may also carry their own `options` to override the default scale, and
|
|
|
145
147
|
|
|
146
148
|
Non-JavaScript backends can validate stored definitions against the published [JSON Schema](schema/assessment-definition.schema.json) (shipped in the npm package under `schema/`).
|
|
147
149
|
|
|
150
|
+
### Missing answers
|
|
151
|
+
|
|
152
|
+
Declarative scoring takes an optional missing-data policy governing how incomplete answer sets are scored (they reach the scorer via raw answer maps or `allowIncomplete`):
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
scoring: {
|
|
156
|
+
kind: "sum",
|
|
157
|
+
missing: { strategy: "prorate", minAnswered: 7 }, // or "ignore" (default) / "require-complete"
|
|
158
|
+
...
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`ignore` sums what is answered (partial totals understate severity — use deliberately); `prorate` scales the raw score up to the full item count (rounded) and refuses to score below `minAnswered`; `require-complete` throws unless every contributing non-optional item is answered. For subscale scoring the policy applies to each subscale independently.
|
|
163
|
+
|
|
148
164
|
## Custom evaluation
|
|
149
165
|
|
|
150
166
|
Declarative scoring is optional. Pass an evaluator for anything beyond sums and subscales — it can return a single scale, multiple scales, a category, or arbitrary data:
|
|
@@ -161,7 +177,7 @@ const attachmentStyle: Evaluator = (definition, answers) => {
|
|
|
161
177
|
};
|
|
162
178
|
};
|
|
163
179
|
|
|
164
|
-
assessment.evaluate(response, attachmentStyle);
|
|
180
|
+
assessment.evaluate(response, { evaluator: attachmentStyle });
|
|
165
181
|
```
|
|
166
182
|
|
|
167
183
|
Result shapes: `scale` (single score + band + flags), `multiscale` (named subscales), `categorical`, and `custom` (escape hatch).
|
|
@@ -182,11 +198,11 @@ const history = rows
|
|
|
182
198
|
| --- | --- |
|
|
183
199
|
| `Assessment` | Wraps a definition: validation, `localize()`, `createResponse()`, `evaluate()`, `stringify()`/`parse()` |
|
|
184
200
|
| `AssessmentResponse` | `answer()`, `answerAll()`, `clearAnswer()`, `status`, `progress()`, `validate()`, `submit()`, `stringify()`/`parse()` |
|
|
185
|
-
| `evaluate(definition, answers, evaluator?)` | Standalone scoring (also available as `Assessment#evaluate`) |
|
|
201
|
+
| `evaluate(definition, answers, { evaluator? })` | Standalone scoring (also available as `Assessment#evaluate`) |
|
|
186
202
|
| `validateDefinition(input)` | Non-throwing structural validation of definitions |
|
|
187
|
-
| `loadInventory(id)` / `inventories`
|
|
188
|
-
| `
|
|
189
|
-
| `PsytoolsError` | All errors carry a
|
|
203
|
+
| `loadInventory(id)` / `inventories` | Predefined instruments (definitions also exported by name) |
|
|
204
|
+
| `localizeText(text, locale, fallback?)` / `collectLocales(texts)` | Locale helpers |
|
|
205
|
+
| `PsytoolsError` | All errors carry a `code` typed as `PsytoolsErrorCode` (e.g. `invalid_value`, `already_submitted`) |
|
|
190
206
|
|
|
191
207
|
## Development
|
|
192
208
|
|
|
@@ -200,7 +216,8 @@ npm run build # ESM + CJS + type declarations into dist/
|
|
|
200
216
|
|
|
201
217
|
- **Not a diagnostic tool.** Scores, severity bands, and flags implement the published scoring rules of screening instruments; they are not diagnoses and do not replace clinical judgment.
|
|
202
218
|
- **Crisis-relevant answers.** PHQ-9 item 9 raises a `suicidality` flag — applications should surface this to a responsible clinician and provide crisis resources to respondents.
|
|
203
|
-
- **Instrument licensing
|
|
219
|
+
- **Instrument licensing.** [SOURCES.md](SOURCES.md) flags every bundled instrument as **Free** (PHQ-9, GAD-7, DASS-21, WHO-5 — usable without permission, including commercially) or **Free with conditions** (ASRS v1.1, AQ-10 — free for clinical/research use; verify with the rights holder before embedding in commercial products). Each inventory's `meta.licenseFlag` carries the same flag programmatically.
|
|
220
|
+
- **Translation provenance.** English texts are reproduced from the original instruments. Turkish and German texts are AI translations (Anthropic Claude, model `claude-fable-5`) of the original English — official translations were **not** consulted and the texts are unverified; see [SOURCES.md](SOURCES.md). Obtain and compare the official version for your language before clinical use. Corrections: <samed@luckys.dev>.
|
|
204
221
|
|
|
205
222
|
## License
|
|
206
223
|
|
package/SOURCES.md
CHANGED
|
@@ -1,53 +1,83 @@
|
|
|
1
|
-
# Sources &
|
|
1
|
+
# Sources, licenses & translations
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
psytools is integrated into real products, so this file states precisely — per instrument — where every text comes from, who holds the rights, and what you are allowed to do with it. Each inventory also carries a machine-readable summary in its `meta` field.
|
|
4
4
|
|
|
5
|
-
**Corrections and requests:** if you find a wording that deviates from an official version, hold rights to an instrument, or want an instrument added or removed,
|
|
5
|
+
**Corrections and requests:** if you find a wording that deviates from an official version, hold rights to an instrument, or want an instrument added, corrected, or removed, email <samed@luckys.dev> or open an issue at <https://github.com/urtuba/psytools/issues>.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## License flags
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
| Flag | Meaning |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| **Free** | Public domain or explicitly free for any use, including commercial products, without permission. |
|
|
12
|
+
| **Free with conditions** | Free for clinical and research use as distributed; embedding in commercial products is not explicitly licensed — verify with the rights holder before shipping. |
|
|
13
|
+
| **Research only** | Usable in research contexts only. *(No bundled instrument currently carries this flag, and none will be added without it being stated here.)* |
|
|
14
|
+
|
|
15
|
+
## Translation provenance — read this before clinical use
|
|
16
|
+
|
|
17
|
+
The same provenance applies to every bundled inventory. If an inventory ever deviates (e.g. an official translation is adopted and verified), it will be stated in its section below.
|
|
18
|
+
|
|
19
|
+
| Language | Text source | Verified against an official version |
|
|
20
|
+
| --- | --- | --- |
|
|
21
|
+
| en | Reproduced from the original published instrument | Yes |
|
|
22
|
+
| tr | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
23
|
+
| de | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
24
|
+
| zh | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
25
|
+
| es | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
26
|
+
|
|
27
|
+
Official validated translations exist for most of these instruments, but they were **not consulted** in preparing the bundled texts, so they are deliberately not cited as sources. The packaged Turkish and German wording has not been checked against them and has not been psychometrically validated. Validated instruments are only validated for their exact wording — before clinical or research use, obtain the official version for your language and compare or replace the text. Verification contributions from native speakers are very welcome.
|
|
12
28
|
|
|
13
29
|
## PHQ-9 — Patient Health Questionnaire-9 (`phq9`)
|
|
14
30
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- **
|
|
18
|
-
- **Scoring:** Sum
|
|
31
|
+
**License: Free.** Developed with an educational grant from Pfizer Inc. The copyright holders state that no permission is required to reproduce, translate, display, or distribute the PHQ screeners. Official repository: <https://www.phqscreeners.com>.
|
|
32
|
+
|
|
33
|
+
- **Citation:** Kroenke, K., Spitzer, R. L., & Williams, J. B. W. (2001). The PHQ-9: Validity of a brief depression severity measure. *Journal of General Internal Medicine, 16*(9), 606–613.
|
|
34
|
+
- **Scoring:** Sum 0–27; severity bands per Kroenke et al. (2001). The item-9 `suicidality` flag is an implementation aid, not part of the published instrument.
|
|
19
35
|
|
|
20
36
|
## GAD-7 — Generalized Anxiety Disorder Scale (`gad7`)
|
|
21
37
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
- **
|
|
25
|
-
- **Scoring:** Sum
|
|
38
|
+
**License: Free.** Same rights statement and repository as the PHQ-9 (Pfizer educational grant; no permission required).
|
|
39
|
+
|
|
40
|
+
- **Citation:** Spitzer, R. L., Kroenke, K., Williams, J. B. W., & Löwe, B. (2006). A brief measure for assessing generalized anxiety disorder: The GAD-7. *Archives of Internal Medicine, 166*(10), 1092–1097.
|
|
41
|
+
- **Scoring:** Sum 0–21; severity bands per Spitzer et al. (2006).
|
|
42
|
+
|
|
43
|
+
## DASS-21 — Depression Anxiety Stress Scales, short form (`dass21`)
|
|
44
|
+
|
|
45
|
+
**License: Free.** The official DASS site states the questionnaires and their translations are in the public domain and may be used without permission. Official site: <http://www2.psy.unsw.edu.au/dass/>.
|
|
46
|
+
|
|
47
|
+
- **Citation:** Lovibond, S. H., & Lovibond, P. F. (1995). *Manual for the Depression Anxiety Stress Scales* (2nd ed.). Sydney: Psychology Foundation of Australia.
|
|
48
|
+
- **Scoring:** Three 7-item subscales; sums doubled to match DASS-42 severity cutoffs, per the DASS manual.
|
|
26
49
|
|
|
27
50
|
## WHO-5 — World Health Organization Well-Being Index (`who5`)
|
|
28
51
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
- **
|
|
32
|
-
- **Scoring:** Raw sum (0–25)
|
|
52
|
+
**License: Free.** The WHO-5 may be used without permission; official versions and translations are distributed by the Psychiatric Research Unit, Mental Health Centre North Zealand (on behalf of the WHO Regional Office for Europe).
|
|
53
|
+
|
|
54
|
+
- **Citation:** Topp, C. W., Østergaard, S. D., Søndergaard, S., & Bech, P. (2015). The WHO-5 Well-Being Index: A systematic review of the literature. *Psychotherapy and Psychosomatics, 84*(3), 167–176.
|
|
55
|
+
- **Scoring:** Raw sum (0–25) × 4, reported 0–100 (higher is better); cutoffs (≤50 reduced well-being, ≤28 likely depression) per Topp et al. (2015).
|
|
56
|
+
|
|
57
|
+
## AUDIT — Alcohol Use Disorders Identification Test (`audit`)
|
|
58
|
+
|
|
59
|
+
**License: Free.** Developed by the World Health Organization; the WHO's AUDIT manual permits reproduction and use of the questionnaire without permission.
|
|
60
|
+
|
|
61
|
+
- **Citation:** Babor, T. F., Higgins-Biddle, J. C., Saunders, J. B., & Monteiro, M. G. (2001). *AUDIT: The Alcohol Use Disorders Identification Test — Guidelines for Use in Primary Care* (2nd ed.). Geneva: World Health Organization.
|
|
62
|
+
- **Scoring:** Sum 0–40 with item-specific point systems (items 1–8 score 0–4, items 9–10 score 0/2/4); interpreted in the four risk zones of the WHO manual.
|
|
63
|
+
|
|
64
|
+
## Mini-IPIP — Big Five personality scale (`mini-ipip`)
|
|
65
|
+
|
|
66
|
+
**License: Free.** The International Personality Item Pool (Lewis Goldberg; <https://ipip.ori.org>) was created explicitly as a public-domain alternative to copyrighted commercial personality tests — items are free for any use, including commercial, without permission.
|
|
67
|
+
|
|
68
|
+
- **Citation:** Donnellan, M. B., Oswald, F. L., Baird, B. M., & Lucas, R. E. (2006). The Mini-IPIP scales: Tiny-yet-effective measures of the Big Five factors of personality. *Psychological Assessment, 18*(2), 192–203.
|
|
69
|
+
- **Scoring:** Five trait subscales (extraversion, agreeableness, conscientiousness, neuroticism, openness) of 4 items each on a 1–5 accuracy scale, half reverse-keyed; scores 4–20 per trait are descriptive — no clinical cutoffs exist, so no bands are defined.
|
|
33
70
|
|
|
34
71
|
## ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (`asrs6`)
|
|
35
72
|
|
|
36
|
-
|
|
37
|
-
- **Rights:** Free to reproduce, distribute, and score.
|
|
38
|
-
- **Translations:** Turkish text follows the validated Turkish adaptation (Doğan et al., 2009); German text follows the WHO's German ASRS-v1.1 distribution.
|
|
39
|
-
- **Scoring:** Count of screen-positive items — items 1–3 from "Sometimes", items 4–6 from "Often"; 4 or more positives indicate symptoms highly consistent with adult ADHD, per the ASRS-v1.1 screener key.
|
|
73
|
+
**License: Free with conditions.** Copyright is held by the World Health Organization and the Workgroup on Adult ADHD (Harvard Medical School / NYU). The screener is distributed free of charge for clinical and research use. Embedding in commercial products is not explicitly covered by the public distribution terms — verify with the rights holders (Harvard NCS/ASRS distribution) before shipping commercially.
|
|
40
74
|
|
|
41
|
-
|
|
75
|
+
- **Citation:** Kessler, R. C., Adler, L., Ames, M., Demler, O., Faraone, S., Hiripi, E., et al. (2005). The World Health Organization Adult ADHD Self-Report Scale (ASRS): A short screening scale for use in the general population. *Psychological Medicine, 35*(2), 245–256.
|
|
76
|
+
- **Scoring:** Count of screen-positive items (items 1–3 from "Sometimes", items 4–6 from "Often"); ≥4 positives = positive screen, per the ASRS-v1.1 screener key.
|
|
42
77
|
|
|
43
|
-
|
|
44
|
-
- **Rights:** Free to use for clinical and research purposes.
|
|
45
|
-
- **Translations:** Turkish text follows the Turkish adaptation of the Autism Spectrum Quotient (Köse et al.); German text follows the published German AQ translations. Both were condensed to the AQ-10 item set — treat them as provisional and verify before clinical use.
|
|
46
|
-
- **Scoring:** 1 point per item answered in the trait direction (agree on items 1, 7, 8, 10; disagree on items 2–6 and 9); a total of 6 or more suggests referral for specialist assessment, per Allison et al. (2012).
|
|
78
|
+
## AQ-10 — Autism Spectrum Quotient, 10-item adult version (`aq10`)
|
|
47
79
|
|
|
48
|
-
|
|
80
|
+
**License: Free with conditions.** Copyright is held by the Autism Research Centre (ARC), University of Cambridge. ARC distributes its measures free of charge and the AQ-10 is recommended by NICE (CG142) for adult screening in clinical practice. Commercial redistribution is not explicitly licensed — verify with ARC before shipping commercially.
|
|
49
81
|
|
|
50
|
-
- **
|
|
51
|
-
- **
|
|
52
|
-
- **Translations:** Turkish text follows the validated short-form adaptation (Sarıçam, 2018); German text follows the published German DASS (Nilges & Essau, 2015).
|
|
53
|
-
- **Scoring:** Three 7-item subscales (depression, anxiety, stress); sums doubled to match DASS-42 severity cutoffs, per the DASS manual.
|
|
82
|
+
- **Citation:** Allison, C., Auyeung, B., & Baron-Cohen, S. (2012). Toward brief "Red Flags" for autism screening: The Short Autism Spectrum Quotient and the Short Quantitative Checklist in 1,000 cases and 3,000 controls. *Journal of the American Academy of Child & Adolescent Psychiatry, 51*(2), 202–212.
|
|
83
|
+
- **Scoring:** 1 point per item in the trait direction (agree on items 1, 7, 8, 10; disagree on the rest); ≥6 suggests specialist referral, per Allison et al. (2012).
|
package/dist/cjs/assessment.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import type { AssessmentDefinition, AssessmentOption, AssessmentQuestion, EvaluationResult,
|
|
1
|
+
import type { AssessmentDefinition, AssessmentOption, AssessmentQuestion, EvaluationResult, LocalizedAssessmentView, ValidationResult } from "./types.ts";
|
|
2
2
|
import { AssessmentResponse } from "./response.ts";
|
|
3
|
+
import { type EvaluateOptions } from "./evaluation.ts";
|
|
3
4
|
/**
|
|
4
5
|
* Structurally validates an assessment definition (useful before persisting
|
|
5
6
|
* user-created assessments). Returns issues instead of throwing.
|
|
@@ -34,16 +35,17 @@ export declare class Assessment {
|
|
|
34
35
|
}): AssessmentResponse;
|
|
35
36
|
/**
|
|
36
37
|
* Evaluates a response (or raw answers) with the definition's declarative
|
|
37
|
-
* scoring, or with `evaluator` when provided.
|
|
38
|
+
* scoring, or with `options.evaluator` when provided.
|
|
38
39
|
*
|
|
39
40
|
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
40
41
|
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
41
42
|
* Raw answer maps skip the completeness check, but their values are
|
|
42
|
-
* still validated against the option scales
|
|
43
|
+
* still validated against the option scales, and the scoring definition's
|
|
44
|
+
* missing-data policy still applies.
|
|
43
45
|
*
|
|
44
46
|
* @throws PsytoolsError `incomplete_response` | `unknown_question` | `invalid_value` | `no_scoring`
|
|
45
47
|
*/
|
|
46
|
-
evaluate(response: AssessmentResponse | Record<string, number>,
|
|
48
|
+
evaluate(response: AssessmentResponse | Record<string, number>, options?: EvaluateOptions & {
|
|
47
49
|
allowIncomplete?: boolean;
|
|
48
50
|
}): EvaluationResult;
|
|
49
51
|
/** The plain serializable definition (used by `JSON.stringify`). */
|
package/dist/cjs/assessment.js
CHANGED
|
@@ -191,16 +191,20 @@ class Assessment {
|
|
|
191
191
|
}
|
|
192
192
|
/**
|
|
193
193
|
* Evaluates a response (or raw answers) with the definition's declarative
|
|
194
|
-
* scoring, or with `evaluator` when provided.
|
|
194
|
+
* scoring, or with `options.evaluator` when provided.
|
|
195
195
|
*
|
|
196
196
|
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
197
197
|
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
198
198
|
* Raw answer maps skip the completeness check, but their values are
|
|
199
|
-
* still validated against the option scales
|
|
199
|
+
* still validated against the option scales, and the scoring definition's
|
|
200
|
+
* missing-data policy still applies.
|
|
200
201
|
*
|
|
201
202
|
* @throws PsytoolsError `incomplete_response` | `unknown_question` | `invalid_value` | `no_scoring`
|
|
202
203
|
*/
|
|
203
|
-
evaluate(response,
|
|
204
|
+
evaluate(response, options) {
|
|
205
|
+
if (typeof options === "function") {
|
|
206
|
+
throw new errors_ts_1.PsytoolsError("invalid_argument", "Pass the evaluator as an option: assessment.evaluate(response, { evaluator })");
|
|
207
|
+
}
|
|
204
208
|
if (response instanceof response_ts_1.AssessmentResponse) {
|
|
205
209
|
const scorable = response.status === "complete" || response.status === "submitted";
|
|
206
210
|
if (!scorable && !options?.allowIncomplete) {
|
|
@@ -208,9 +212,9 @@ class Assessment {
|
|
|
208
212
|
throw new errors_ts_1.PsytoolsError("incomplete_response", `Cannot evaluate a response with status "${response.status}" (unanswered: ${missing}); ` +
|
|
209
213
|
"pass { allowIncomplete: true } to score it anyway");
|
|
210
214
|
}
|
|
211
|
-
return (0, evaluation_ts_1.evaluate)(this.definition, response.answers, evaluator);
|
|
215
|
+
return (0, evaluation_ts_1.evaluate)(this.definition, response.answers, { evaluator: options?.evaluator });
|
|
212
216
|
}
|
|
213
|
-
return (0, evaluation_ts_1.evaluate)(this.definition, response, evaluator);
|
|
217
|
+
return (0, evaluation_ts_1.evaluate)(this.definition, response, { evaluator: options?.evaluator });
|
|
214
218
|
}
|
|
215
219
|
/** The plain serializable definition (used by `JSON.stringify`). */
|
|
216
220
|
toJSON() {
|
|
@@ -237,7 +241,7 @@ class Assessment {
|
|
|
237
241
|
return new Assessment(raw);
|
|
238
242
|
}
|
|
239
243
|
text(text, locale) {
|
|
240
|
-
return (0, i18n_ts_1.
|
|
244
|
+
return (0, i18n_ts_1.localizeText)(text, locale ?? this.definition.defaultLocale, this.definition.defaultLocale);
|
|
241
245
|
}
|
|
242
246
|
}
|
|
243
247
|
exports.Assessment = Assessment;
|
package/dist/cjs/errors.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
|
+
/** Every error code psytools can throw, for exhaustive handling. */
|
|
2
|
+
export type PsytoolsErrorCode = "malformed" | "duplicate_question" | "invalid_definition" | "unknown_question" | "invalid_value" | "missing_answer" | "already_submitted" | "invalid_response" | "incomplete_response" | "assessment_mismatch" | "no_scoring" | "invalid_json" | "unknown_inventory" | "invalid_argument";
|
|
1
3
|
/** Error thrown by psytools, carrying a stable machine-readable code. */
|
|
2
4
|
export declare class PsytoolsError extends Error {
|
|
3
|
-
readonly code:
|
|
4
|
-
constructor(code:
|
|
5
|
+
readonly code: PsytoolsErrorCode;
|
|
6
|
+
constructor(code: PsytoolsErrorCode, message: string);
|
|
5
7
|
}
|
package/dist/cjs/evaluation.d.ts
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
1
|
import type { AnswerMap, AssessmentDefinition, EvaluationResult, Evaluator } from "./types.ts";
|
|
2
|
+
export interface EvaluateOptions {
|
|
3
|
+
/** Custom evaluator used instead of the definition's declarative scoring. */
|
|
4
|
+
evaluator?: Evaluator;
|
|
5
|
+
}
|
|
2
6
|
/**
|
|
3
7
|
* Evaluates answers against an assessment definition.
|
|
4
8
|
*
|
|
5
9
|
* Every answer is first validated against the assessment: the question must
|
|
6
|
-
* exist and the value must belong to its option scale. Then
|
|
7
|
-
* used when given; otherwise the definition's
|
|
8
|
-
* (`sum` or `
|
|
10
|
+
* exist and the value must belong to its option scale. Then
|
|
11
|
+
* `options.evaluator` is used when given; otherwise the definition's
|
|
12
|
+
* declarative `scoring` (`sum`, `subscales`, or `count`) applies, honoring
|
|
13
|
+
* its missing-data policy.
|
|
9
14
|
*
|
|
10
|
-
* @throws PsytoolsError `unknown_question` | `invalid_value` | `no_scoring`
|
|
15
|
+
* @throws PsytoolsError `unknown_question` | `invalid_value` | `incomplete_response` | `no_scoring`
|
|
11
16
|
*/
|
|
12
|
-
export declare function evaluate(definition: AssessmentDefinition, answers: AnswerMap,
|
|
17
|
+
export declare function evaluate(definition: AssessmentDefinition, answers: AnswerMap, options?: EvaluateOptions): EvaluationResult;
|
package/dist/cjs/evaluation.js
CHANGED
|
@@ -6,16 +6,20 @@ const errors_ts_1 = require("./errors.js");
|
|
|
6
6
|
* Evaluates answers against an assessment definition.
|
|
7
7
|
*
|
|
8
8
|
* Every answer is first validated against the assessment: the question must
|
|
9
|
-
* exist and the value must belong to its option scale. Then
|
|
10
|
-
* used when given; otherwise the definition's
|
|
11
|
-
* (`sum` or `
|
|
9
|
+
* exist and the value must belong to its option scale. Then
|
|
10
|
+
* `options.evaluator` is used when given; otherwise the definition's
|
|
11
|
+
* declarative `scoring` (`sum`, `subscales`, or `count`) applies, honoring
|
|
12
|
+
* its missing-data policy.
|
|
12
13
|
*
|
|
13
|
-
* @throws PsytoolsError `unknown_question` | `invalid_value` | `no_scoring`
|
|
14
|
+
* @throws PsytoolsError `unknown_question` | `invalid_value` | `incomplete_response` | `no_scoring`
|
|
14
15
|
*/
|
|
15
|
-
function evaluate(definition, answers,
|
|
16
|
+
function evaluate(definition, answers, options) {
|
|
17
|
+
if (typeof options === "function") {
|
|
18
|
+
throw new errors_ts_1.PsytoolsError("invalid_argument", "Pass the evaluator as an option: evaluate(definition, answers, { evaluator })");
|
|
19
|
+
}
|
|
16
20
|
assertValidAnswers(definition, answers);
|
|
17
|
-
if (evaluator)
|
|
18
|
-
return evaluator(definition, answers);
|
|
21
|
+
if (options?.evaluator)
|
|
22
|
+
return options.evaluator(definition, answers);
|
|
19
23
|
const scoring = definition.scoring;
|
|
20
24
|
if (!scoring) {
|
|
21
25
|
throw new errors_ts_1.PsytoolsError("no_scoring", `Assessment "${definition.id}" has no scoring definition; pass a custom evaluator`);
|
|
@@ -24,19 +28,22 @@ function evaluate(definition, answers, evaluator) {
|
|
|
24
28
|
case "sum":
|
|
25
29
|
return evaluateSum(definition, answers, scoring);
|
|
26
30
|
case "count": {
|
|
27
|
-
|
|
31
|
+
const questions = scoring.items.map((item) => requireQuestion(definition, item.questionId));
|
|
32
|
+
const answered = enforceMissing(questions, answers, scoring.missing);
|
|
33
|
+
let positives = 0;
|
|
28
34
|
for (const item of scoring.items) {
|
|
29
35
|
const question = requireQuestion(definition, item.questionId);
|
|
30
|
-
const
|
|
31
|
-
if (
|
|
36
|
+
const value = answers[question.id];
|
|
37
|
+
if (value === undefined)
|
|
32
38
|
continue;
|
|
33
39
|
const values = (question.options ?? definition.options).map((o) => o.value);
|
|
34
40
|
const effective = question.reverseScored
|
|
35
|
-
? Math.max(...values) + Math.min(...values) -
|
|
36
|
-
:
|
|
41
|
+
? Math.max(...values) + Math.min(...values) - value
|
|
42
|
+
: value;
|
|
37
43
|
if (effective >= item.minValue)
|
|
38
|
-
|
|
44
|
+
positives += 1;
|
|
39
45
|
}
|
|
46
|
+
const score = prorate(positives, answered, questions.length, scoring.missing);
|
|
40
47
|
return {
|
|
41
48
|
kind: "scale",
|
|
42
49
|
score,
|
|
@@ -49,15 +56,12 @@ function evaluate(definition, answers, evaluator) {
|
|
|
49
56
|
case "subscales": {
|
|
50
57
|
const scales = scoring.subscales.map((subscale) => {
|
|
51
58
|
const questions = subscale.questionIds.map((id) => requireQuestion(definition, id));
|
|
52
|
-
const
|
|
53
|
-
const { score, min, max } = sumQuestions(definition, questions, answers, multiplier);
|
|
59
|
+
const scored = scoreQuestionSet(definition, questions, answers, subscale.multiplier ?? 1, scoring.missing, subscale.id);
|
|
54
60
|
return {
|
|
55
61
|
id: subscale.id,
|
|
56
62
|
label: subscale.label,
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
max,
|
|
60
|
-
...bandOf(score, subscale.bands),
|
|
63
|
+
...scored,
|
|
64
|
+
...bandOf(scored.score, subscale.bands),
|
|
61
65
|
};
|
|
62
66
|
});
|
|
63
67
|
return {
|
|
@@ -85,19 +89,21 @@ function assertValidAnswers(definition, answers) {
|
|
|
85
89
|
}
|
|
86
90
|
}
|
|
87
91
|
function evaluateSum(definition, answers, scoring) {
|
|
88
|
-
const
|
|
89
|
-
const { score, min, max } = sumQuestions(definition, definition.questions, answers, multiplier);
|
|
92
|
+
const result = scoreQuestionSet(definition, definition.questions, answers, scoring.multiplier ?? 1, scoring.missing);
|
|
90
93
|
return {
|
|
91
94
|
kind: "scale",
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
max,
|
|
95
|
-
...bandOf(score, scoring.bands),
|
|
95
|
+
...result,
|
|
96
|
+
...bandOf(result.score, scoring.bands),
|
|
96
97
|
flags: triggeredFlags(answers, scoring.flags),
|
|
97
98
|
};
|
|
98
99
|
}
|
|
99
|
-
|
|
100
|
-
|
|
100
|
+
/**
|
|
101
|
+
* Sums one set of questions (the whole assessment or one subscale),
|
|
102
|
+
* applying reverse scoring, the missing-data policy, and the multiplier.
|
|
103
|
+
*/
|
|
104
|
+
function scoreQuestionSet(definition, questions, answers, multiplier, missing, scaleId) {
|
|
105
|
+
const answered = enforceMissing(questions, answers, missing, scaleId);
|
|
106
|
+
let raw = 0;
|
|
101
107
|
let min = 0;
|
|
102
108
|
let max = 0;
|
|
103
109
|
for (const question of questions) {
|
|
@@ -106,12 +112,43 @@ function sumQuestions(definition, questions, answers, multiplier) {
|
|
|
106
112
|
const highest = Math.max(...values);
|
|
107
113
|
min += lowest;
|
|
108
114
|
max += highest;
|
|
109
|
-
const
|
|
110
|
-
if (
|
|
115
|
+
const value = answers[question.id];
|
|
116
|
+
if (value === undefined)
|
|
111
117
|
continue;
|
|
112
|
-
|
|
118
|
+
raw += question.reverseScored ? highest + lowest - value : value;
|
|
113
119
|
}
|
|
114
|
-
|
|
120
|
+
raw = prorate(raw, answered, questions.length, missing);
|
|
121
|
+
return { score: raw * multiplier, min: min * multiplier, max: max * multiplier };
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Enforces the missing-data policy over one set of contributing questions
|
|
125
|
+
* and returns how many of them are answered.
|
|
126
|
+
*
|
|
127
|
+
* `require-complete` only demands questions that are not marked `optional`.
|
|
128
|
+
*/
|
|
129
|
+
function enforceMissing(questions, answers, missing, scaleId) {
|
|
130
|
+
const strategy = missing?.strategy ?? "ignore";
|
|
131
|
+
const minAnswered = missing?.minAnswered ?? (strategy === "prorate" ? 1 : 0);
|
|
132
|
+
const scope = scaleId ? ` in subscale "${scaleId}"` : "";
|
|
133
|
+
const answered = questions.filter((q) => answers[q.id] !== undefined).length;
|
|
134
|
+
if (strategy === "require-complete") {
|
|
135
|
+
const unanswered = questions
|
|
136
|
+
.filter((q) => !(q.optional ?? false) && answers[q.id] === undefined)
|
|
137
|
+
.map((q) => q.id);
|
|
138
|
+
if (unanswered.length > 0) {
|
|
139
|
+
throw new errors_ts_1.PsytoolsError("incomplete_response", `Scoring requires complete answers${scope}; unanswered: ${unanswered.join(", ")}`);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
if (answered < minAnswered) {
|
|
143
|
+
throw new errors_ts_1.PsytoolsError("incomplete_response", `Scoring requires at least ${minAnswered} answered item(s)${scope}, got ${answered}`);
|
|
144
|
+
}
|
|
145
|
+
return answered;
|
|
146
|
+
}
|
|
147
|
+
/** Scales a partial raw score up to the full item count (rounded). */
|
|
148
|
+
function prorate(raw, answered, total, missing) {
|
|
149
|
+
if (missing?.strategy !== "prorate" || answered === 0 || answered === total)
|
|
150
|
+
return raw;
|
|
151
|
+
return Math.round((raw * total) / answered);
|
|
115
152
|
}
|
|
116
153
|
function bandOf(score, bands) {
|
|
117
154
|
const match = bands?.find((band) => score >= band.min && score <= band.max);
|
package/dist/cjs/i18n.d.ts
CHANGED
|
@@ -5,6 +5,6 @@ import type { LocalizedText } from "./types.ts";
|
|
|
5
5
|
* Resolution order: exact locale -> base language of the locale
|
|
6
6
|
* (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
|
|
7
7
|
*/
|
|
8
|
-
export declare function
|
|
8
|
+
export declare function localizeText(text: LocalizedText, locale: string, fallbackLocale?: string): string;
|
|
9
9
|
/** Collects the union of locales present in a set of localized texts. */
|
|
10
10
|
export declare function collectLocales(texts: Array<LocalizedText | undefined>): string[];
|
package/dist/cjs/i18n.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.
|
|
3
|
+
exports.localizeText = localizeText;
|
|
4
4
|
exports.collectLocales = collectLocales;
|
|
5
5
|
/**
|
|
6
6
|
* Resolves a `LocalizedText` to a string for the given locale.
|
|
@@ -8,7 +8,7 @@ exports.collectLocales = collectLocales;
|
|
|
8
8
|
* Resolution order: exact locale -> base language of the locale
|
|
9
9
|
* (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
|
|
10
10
|
*/
|
|
11
|
-
function
|
|
11
|
+
function localizeText(text, locale, fallbackLocale) {
|
|
12
12
|
const exact = text[locale];
|
|
13
13
|
if (exact !== undefined)
|
|
14
14
|
return exact;
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, CountScoringItem, CountScoring, ScoringDefinition, AnswerMap, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
|
|
1
|
+
export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, CountScoringItem, CountScoring, MissingDataPolicy, MissingDataStrategy, ScoringDefinition, ValidationIssueCode, AnswerMap, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
|
|
2
2
|
export { PsytoolsError } from "./errors.ts";
|
|
3
|
-
export {
|
|
3
|
+
export type { PsytoolsErrorCode } from "./errors.ts";
|
|
4
|
+
export { localizeText, collectLocales } from "./i18n.ts";
|
|
4
5
|
export { Assessment, validateDefinition } from "./assessment.ts";
|
|
5
6
|
export { AssessmentResponse } from "./response.ts";
|
|
6
7
|
export { evaluate } from "./evaluation.ts";
|
|
7
|
-
export {
|
|
8
|
+
export type { EvaluateOptions } from "./evaluation.ts";
|
|
9
|
+
export { phq9, gad7, dass21, who5, asrs6, aq10, audit, miniIpip, inventories, loadInventory, twoWeekFrequencyOptions, twoWeekInstructions, } from "./inventories/index.ts";
|
|
8
10
|
export type { InventoryId } from "./inventories/index.ts";
|
package/dist/cjs/index.js
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.twoWeekInstructions = exports.twoWeekFrequencyOptions = exports.loadInventory = exports.inventories = exports.aq10 = exports.asrs6 = exports.who5 = exports.dass21 = exports.gad7 = exports.phq9 = exports.evaluate = exports.AssessmentResponse = exports.validateDefinition = exports.Assessment = exports.collectLocales = exports.
|
|
3
|
+
exports.twoWeekInstructions = exports.twoWeekFrequencyOptions = exports.loadInventory = exports.inventories = exports.miniIpip = exports.audit = exports.aq10 = exports.asrs6 = exports.who5 = exports.dass21 = exports.gad7 = exports.phq9 = exports.evaluate = exports.AssessmentResponse = exports.validateDefinition = exports.Assessment = exports.collectLocales = exports.localizeText = exports.PsytoolsError = void 0;
|
|
4
4
|
var errors_ts_1 = require("./errors.js");
|
|
5
5
|
Object.defineProperty(exports, "PsytoolsError", { enumerable: true, get: function () { return errors_ts_1.PsytoolsError; } });
|
|
6
6
|
var i18n_ts_1 = require("./i18n.js");
|
|
7
|
-
Object.defineProperty(exports, "
|
|
7
|
+
Object.defineProperty(exports, "localizeText", { enumerable: true, get: function () { return i18n_ts_1.localizeText; } });
|
|
8
8
|
Object.defineProperty(exports, "collectLocales", { enumerable: true, get: function () { return i18n_ts_1.collectLocales; } });
|
|
9
9
|
var assessment_ts_1 = require("./assessment.js");
|
|
10
10
|
Object.defineProperty(exports, "Assessment", { enumerable: true, get: function () { return assessment_ts_1.Assessment; } });
|
|
@@ -20,6 +20,8 @@ Object.defineProperty(exports, "dass21", { enumerable: true, get: function () {
|
|
|
20
20
|
Object.defineProperty(exports, "who5", { enumerable: true, get: function () { return index_ts_1.who5; } });
|
|
21
21
|
Object.defineProperty(exports, "asrs6", { enumerable: true, get: function () { return index_ts_1.asrs6; } });
|
|
22
22
|
Object.defineProperty(exports, "aq10", { enumerable: true, get: function () { return index_ts_1.aq10; } });
|
|
23
|
+
Object.defineProperty(exports, "audit", { enumerable: true, get: function () { return index_ts_1.audit; } });
|
|
24
|
+
Object.defineProperty(exports, "miniIpip", { enumerable: true, get: function () { return index_ts_1.miniIpip; } });
|
|
23
25
|
Object.defineProperty(exports, "inventories", { enumerable: true, get: function () { return index_ts_1.inventories; } });
|
|
24
26
|
Object.defineProperty(exports, "loadInventory", { enumerable: true, get: function () { return index_ts_1.loadInventory; } });
|
|
25
27
|
Object.defineProperty(exports, "twoWeekFrequencyOptions", { enumerable: true, get: function () { return index_ts_1.twoWeekFrequencyOptions; } });
|