psytools 0.3.0 → 0.3.2
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 +37 -16
- package/SOURCES.md +81 -0
- package/dist/cjs/assessment.d.ts +3 -2
- package/dist/cjs/assessment.js +13 -3
- package/dist/cjs/evaluation.d.ts +5 -3
- package/dist/cjs/evaluation.js +49 -8
- package/dist/cjs/index.d.ts +2 -2
- package/dist/cjs/index.js +6 -1
- package/dist/cjs/inventories/aq10.d.ts +12 -0
- package/dist/cjs/inventories/aq10.js +183 -0
- package/dist/cjs/inventories/asrs6.d.ts +11 -0
- package/dist/cjs/inventories/asrs6.js +130 -0
- package/dist/cjs/inventories/audit.d.ts +10 -0
- package/dist/cjs/inventories/audit.js +231 -0
- package/dist/cjs/inventories/dass21.js +3 -1
- package/dist/cjs/inventories/gad7.js +3 -1
- package/dist/cjs/inventories/index.d.ts +7 -2
- package/dist/cjs/inventories/index.js +16 -1
- package/dist/cjs/inventories/mini-ipip.d.ts +11 -0
- package/dist/cjs/inventories/mini-ipip.js +272 -0
- package/dist/cjs/inventories/phq9.js +3 -1
- package/dist/cjs/inventories/who5.d.ts +11 -0
- package/dist/cjs/inventories/who5.js +152 -0
- package/dist/cjs/types.d.ts +24 -2
- package/dist/esm/assessment.d.ts +3 -2
- package/dist/esm/assessment.js +13 -3
- package/dist/esm/evaluation.d.ts +5 -3
- package/dist/esm/evaluation.js +49 -8
- package/dist/esm/index.d.ts +2 -2
- package/dist/esm/index.js +1 -1
- package/dist/esm/inventories/aq10.d.ts +12 -0
- package/dist/esm/inventories/aq10.js +180 -0
- package/dist/esm/inventories/asrs6.d.ts +11 -0
- package/dist/esm/inventories/asrs6.js +127 -0
- package/dist/esm/inventories/audit.d.ts +10 -0
- package/dist/esm/inventories/audit.js +228 -0
- package/dist/esm/inventories/dass21.js +3 -1
- package/dist/esm/inventories/gad7.js +3 -1
- package/dist/esm/inventories/index.d.ts +7 -2
- package/dist/esm/inventories/index.js +11 -1
- package/dist/esm/inventories/mini-ipip.d.ts +11 -0
- package/dist/esm/inventories/mini-ipip.js +269 -0
- package/dist/esm/inventories/phq9.js +3 -1
- package/dist/esm/inventories/who5.d.ts +11 -0
- package/dist/esm/inventories/who5.js +149 -0
- package/dist/esm/types.d.ts +24 -2
- package/package.json +14 -3
- package/schema/assessment-definition.schema.json +27 -1
- package/src/assessment.ts +14 -3
- package/src/evaluation.ts +55 -9
- package/src/index.ts +7 -0
- package/src/inventories/aq10.ts +185 -0
- package/src/inventories/asrs6.ts +132 -0
- package/src/inventories/audit.ts +234 -0
- package/src/inventories/dass21.ts +4 -1
- package/src/inventories/gad7.ts +4 -1
- package/src/inventories/index.ts +20 -2
- package/src/inventories/mini-ipip.ts +274 -0
- package/src/inventories/phq9.ts +4 -1
- package/src/inventories/who5.ts +153 -0
- package/src/types.ts +26 -2
package/README.md
CHANGED
|
@@ -1,13 +1,29 @@
|
|
|
1
1
|
# psytools
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Give your app a validated psychological questionnaire — rendered, collected, and scored — in a few lines:
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
```ts
|
|
6
|
+
import { loadInventory } from "psytools";
|
|
7
|
+
|
|
8
|
+
const phq9 = loadInventory("phq9"); // Patient Health Questionnaire-9
|
|
9
|
+
phq9.localize("en"); // render-ready questions & options for your UI
|
|
6
10
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
+
const response = phq9.createResponse();
|
|
12
|
+
response.answerAll([2, 1, 3, 1, 0, 1, 2, 0, 0]).submit();
|
|
13
|
+
|
|
14
|
+
phq9.evaluate(response);
|
|
15
|
+
// { score: 10, band: { id: "moderate", label: { en: "Moderate depression", ... } }, ... }
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
That's a complete depression screening: standardized items, answer validation, published severity cutoffs, and clinical flags (e.g. PHQ-9's self-harm item) — with zero dependencies.
|
|
19
|
+
|
|
20
|
+
## Why psytools
|
|
21
|
+
|
|
22
|
+
- **Batteries included** — PHQ-9, GAD-7, and DASS-21 ship ready to use in English, Turkish, and German, with published scoring rules and citations.
|
|
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
|
+
- **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
|
+
- **Safe by default** — every answer is validated against the option scale, incomplete responses can't be scored accidentally, and submitted responses are immutable.
|
|
26
|
+
- **Runs anywhere** — zero runtime dependencies; Node (>= 18), browsers, and edge runtimes; ESM + CommonJS with full TypeScript declarations.
|
|
11
27
|
|
|
12
28
|
## Install
|
|
13
29
|
|
|
@@ -15,7 +31,7 @@ Built for therapy apps and research tools where therapists or researchers use st
|
|
|
15
31
|
npm install psytools
|
|
16
32
|
```
|
|
17
33
|
|
|
18
|
-
##
|
|
34
|
+
## Walkthrough
|
|
19
35
|
|
|
20
36
|
```ts
|
|
21
37
|
import { loadInventory } from "psytools";
|
|
@@ -28,12 +44,12 @@ const view = phq9.localize("tr");
|
|
|
28
44
|
|
|
29
45
|
// 2. Collect answers — one by one or all at once.
|
|
30
46
|
const response = phq9.createResponse({ respondentId: "client-42" });
|
|
31
|
-
response.
|
|
32
|
-
response.answer("phq9-1", 2); // one by one, validated immediately
|
|
33
|
-
response.status; // "in-progress"
|
|
47
|
+
response.answer("phq9-1", 2); // validated immediately
|
|
34
48
|
response.answerAll([2, 1, 3, 1, 0, 1, 2, 0, 0]); // or all at once (question order)
|
|
35
|
-
response.
|
|
36
|
-
|
|
49
|
+
response.submit(); // validates completeness, freezes, timestamps
|
|
50
|
+
|
|
51
|
+
// Responses track their lifecycle as `response.status`:
|
|
52
|
+
// "empty" -> "in-progress" -> "complete" -> "submitted"
|
|
37
53
|
|
|
38
54
|
// 3. Evaluate.
|
|
39
55
|
const result = phq9.evaluate(response);
|
|
@@ -43,9 +59,8 @@ const result = phq9.evaluate(response);
|
|
|
43
59
|
// flags: [] // phq9-9 > 0 would raise the "suicidality" flag here
|
|
44
60
|
// }
|
|
45
61
|
|
|
46
|
-
//
|
|
47
|
-
//
|
|
48
|
-
// responses that are not complete/submitted; score partial data explicitly:
|
|
62
|
+
// evaluate() refuses responses that are not complete/submitted;
|
|
63
|
+
// score partial data explicitly:
|
|
49
64
|
phq9.evaluate(inProgressResponse, undefined, { allowIncomplete: true });
|
|
50
65
|
|
|
51
66
|
// 4. Persist — both sides are plain JSON.
|
|
@@ -69,6 +84,11 @@ const response = AssessmentResponse.parse(assessment, rowFromDb); // answers re-
|
|
|
69
84
|
| `phq9` | Patient Health Questionnaire-9 (depression) | 9 | Sum 0–27, 5 severity bands, item-9 suicidality flag | en, tr, de |
|
|
70
85
|
| `gad7` | Generalized Anxiety Disorder-7 | 7 | Sum 0–21, 4 severity bands | en, tr, de |
|
|
71
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 |
|
|
90
|
+
| `audit` | Alcohol Use Disorders Identification Test (WHO) | 10 | Sum 0–40 with per-question point systems, 4 WHO risk zones | en, tr, de |
|
|
91
|
+
| `mini-ipip` | Mini-IPIP Big Five personality scale | 20 | 5 trait subscales (4–20 each), reverse-keyed items, no cutoffs | en, tr, de |
|
|
72
92
|
|
|
73
93
|
```ts
|
|
74
94
|
import { loadInventory, inventories, dass21 } from "psytools";
|
|
@@ -182,7 +202,8 @@ npm run build # ESM + CJS + type declarations into dist/
|
|
|
182
202
|
|
|
183
203
|
- **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.
|
|
184
204
|
- **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.
|
|
185
|
-
- **Instrument licensing.** PHQ-9, GAD-7
|
|
205
|
+
- **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.
|
|
206
|
+
- **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>.
|
|
186
207
|
|
|
187
208
|
## License
|
|
188
209
|
|
package/SOURCES.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Sources, licenses & translations
|
|
2
|
+
|
|
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
|
+
|
|
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
|
+
|
|
7
|
+
## License flags
|
|
8
|
+
|
|
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
|
+
|
|
25
|
+
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.
|
|
26
|
+
|
|
27
|
+
## PHQ-9 — Patient Health Questionnaire-9 (`phq9`)
|
|
28
|
+
|
|
29
|
+
**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>.
|
|
30
|
+
|
|
31
|
+
- **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.
|
|
32
|
+
- **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.
|
|
33
|
+
|
|
34
|
+
## GAD-7 — Generalized Anxiety Disorder Scale (`gad7`)
|
|
35
|
+
|
|
36
|
+
**License: Free.** Same rights statement and repository as the PHQ-9 (Pfizer educational grant; no permission required).
|
|
37
|
+
|
|
38
|
+
- **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.
|
|
39
|
+
- **Scoring:** Sum 0–21; severity bands per Spitzer et al. (2006).
|
|
40
|
+
|
|
41
|
+
## DASS-21 — Depression Anxiety Stress Scales, short form (`dass21`)
|
|
42
|
+
|
|
43
|
+
**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/>.
|
|
44
|
+
|
|
45
|
+
- **Citation:** Lovibond, S. H., & Lovibond, P. F. (1995). *Manual for the Depression Anxiety Stress Scales* (2nd ed.). Sydney: Psychology Foundation of Australia.
|
|
46
|
+
- **Scoring:** Three 7-item subscales; sums doubled to match DASS-42 severity cutoffs, per the DASS manual.
|
|
47
|
+
|
|
48
|
+
## WHO-5 — World Health Organization Well-Being Index (`who5`)
|
|
49
|
+
|
|
50
|
+
**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).
|
|
51
|
+
|
|
52
|
+
- **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.
|
|
53
|
+
- **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).
|
|
54
|
+
|
|
55
|
+
## AUDIT — Alcohol Use Disorders Identification Test (`audit`)
|
|
56
|
+
|
|
57
|
+
**License: Free.** Developed by the World Health Organization; the WHO's AUDIT manual permits reproduction and use of the questionnaire without permission.
|
|
58
|
+
|
|
59
|
+
- **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.
|
|
60
|
+
- **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.
|
|
61
|
+
|
|
62
|
+
## Mini-IPIP — Big Five personality scale (`mini-ipip`)
|
|
63
|
+
|
|
64
|
+
**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.
|
|
65
|
+
|
|
66
|
+
- **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.
|
|
67
|
+
- **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.
|
|
68
|
+
|
|
69
|
+
## ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (`asrs6`)
|
|
70
|
+
|
|
71
|
+
**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.
|
|
72
|
+
|
|
73
|
+
- **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.
|
|
74
|
+
- **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.
|
|
75
|
+
|
|
76
|
+
## AQ-10 — Autism Spectrum Quotient, 10-item adult version (`aq10`)
|
|
77
|
+
|
|
78
|
+
**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.
|
|
79
|
+
|
|
80
|
+
- **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.
|
|
81
|
+
- **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
|
@@ -38,9 +38,10 @@ export declare class Assessment {
|
|
|
38
38
|
*
|
|
39
39
|
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
40
40
|
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
41
|
-
* Raw answer maps
|
|
41
|
+
* Raw answer maps skip the completeness check, but their values are
|
|
42
|
+
* still validated against the option scales.
|
|
42
43
|
*
|
|
43
|
-
* @throws PsytoolsError `incomplete_response` | `no_scoring`
|
|
44
|
+
* @throws PsytoolsError `incomplete_response` | `unknown_question` | `invalid_value` | `no_scoring`
|
|
44
45
|
*/
|
|
45
46
|
evaluate(response: AssessmentResponse | Record<string, number>, evaluator?: Evaluator, options?: {
|
|
46
47
|
allowIncomplete?: boolean;
|
package/dist/cjs/assessment.js
CHANGED
|
@@ -77,7 +77,16 @@ function validateDefinition(input) {
|
|
|
77
77
|
}
|
|
78
78
|
}
|
|
79
79
|
}
|
|
80
|
-
|
|
80
|
+
if (scoring.kind === "count" && Array.isArray(scoring.items)) {
|
|
81
|
+
for (const item of scoring.items) {
|
|
82
|
+
if (!seen.has(item.questionId)) {
|
|
83
|
+
issues.push({ code: "unknown_question", message: `count scoring references unknown question "${item.questionId}"`, questionId: item.questionId });
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
const flags = scoring.kind === "sum" || scoring.kind === "subscales" || scoring.kind === "count"
|
|
88
|
+
? scoring.flags ?? []
|
|
89
|
+
: [];
|
|
81
90
|
for (const flag of flags) {
|
|
82
91
|
if (!seen.has(flag.questionId)) {
|
|
83
92
|
issues.push({ code: "unknown_question", message: `flag "${flag.id}" references unknown question "${flag.questionId}"`, questionId: flag.questionId });
|
|
@@ -186,9 +195,10 @@ class Assessment {
|
|
|
186
195
|
*
|
|
187
196
|
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
188
197
|
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
189
|
-
* Raw answer maps
|
|
198
|
+
* Raw answer maps skip the completeness check, but their values are
|
|
199
|
+
* still validated against the option scales.
|
|
190
200
|
*
|
|
191
|
-
* @throws PsytoolsError `incomplete_response` | `no_scoring`
|
|
201
|
+
* @throws PsytoolsError `incomplete_response` | `unknown_question` | `invalid_value` | `no_scoring`
|
|
192
202
|
*/
|
|
193
203
|
evaluate(response, evaluator, options) {
|
|
194
204
|
if (response instanceof response_ts_1.AssessmentResponse) {
|
package/dist/cjs/evaluation.d.ts
CHANGED
|
@@ -2,9 +2,11 @@ import type { AnswerMap, AssessmentDefinition, EvaluationResult, Evaluator } fro
|
|
|
2
2
|
/**
|
|
3
3
|
* Evaluates answers against an assessment definition.
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* Every answer is first validated against the assessment: the question must
|
|
6
|
+
* exist and the value must belong to its option scale. Then `evaluator` is
|
|
7
|
+
* used when given; otherwise the definition's declarative `scoring`
|
|
8
|
+
* (`sum` or `subscales`) applies.
|
|
7
9
|
*
|
|
8
|
-
* @throws PsytoolsError `
|
|
10
|
+
* @throws PsytoolsError `unknown_question` | `invalid_value` | `no_scoring`
|
|
9
11
|
*/
|
|
10
12
|
export declare function evaluate(definition: AssessmentDefinition, answers: AnswerMap, evaluator?: Evaluator): EvaluationResult;
|
package/dist/cjs/evaluation.js
CHANGED
|
@@ -5,12 +5,15 @@ const errors_ts_1 = require("./errors.js");
|
|
|
5
5
|
/**
|
|
6
6
|
* Evaluates answers against an assessment definition.
|
|
7
7
|
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
8
|
+
* Every answer is first validated against the assessment: the question must
|
|
9
|
+
* exist and the value must belong to its option scale. Then `evaluator` is
|
|
10
|
+
* used when given; otherwise the definition's declarative `scoring`
|
|
11
|
+
* (`sum` or `subscales`) applies.
|
|
10
12
|
*
|
|
11
|
-
* @throws PsytoolsError `
|
|
13
|
+
* @throws PsytoolsError `unknown_question` | `invalid_value` | `no_scoring`
|
|
12
14
|
*/
|
|
13
15
|
function evaluate(definition, answers, evaluator) {
|
|
16
|
+
assertValidAnswers(definition, answers);
|
|
14
17
|
if (evaluator)
|
|
15
18
|
return evaluator(definition, answers);
|
|
16
19
|
const scoring = definition.scoring;
|
|
@@ -19,7 +22,30 @@ function evaluate(definition, answers, evaluator) {
|
|
|
19
22
|
}
|
|
20
23
|
switch (scoring.kind) {
|
|
21
24
|
case "sum":
|
|
22
|
-
return evaluateSum(definition, answers, scoring
|
|
25
|
+
return evaluateSum(definition, answers, scoring);
|
|
26
|
+
case "count": {
|
|
27
|
+
let score = 0;
|
|
28
|
+
for (const item of scoring.items) {
|
|
29
|
+
const question = requireQuestion(definition, item.questionId);
|
|
30
|
+
const answered = answers[question.id];
|
|
31
|
+
if (answered === undefined)
|
|
32
|
+
continue;
|
|
33
|
+
const values = (question.options ?? definition.options).map((o) => o.value);
|
|
34
|
+
const effective = question.reverseScored
|
|
35
|
+
? Math.max(...values) + Math.min(...values) - answered
|
|
36
|
+
: answered;
|
|
37
|
+
if (effective >= item.minValue)
|
|
38
|
+
score += 1;
|
|
39
|
+
}
|
|
40
|
+
return {
|
|
41
|
+
kind: "scale",
|
|
42
|
+
score,
|
|
43
|
+
min: 0,
|
|
44
|
+
max: scoring.items.length,
|
|
45
|
+
...bandOf(score, scoring.bands),
|
|
46
|
+
flags: triggeredFlags(answers, scoring.flags),
|
|
47
|
+
};
|
|
48
|
+
}
|
|
23
49
|
case "subscales": {
|
|
24
50
|
const scales = scoring.subscales.map((subscale) => {
|
|
25
51
|
const questions = subscale.questionIds.map((id) => requireQuestion(definition, id));
|
|
@@ -44,15 +70,30 @@ function evaluate(definition, answers, evaluator) {
|
|
|
44
70
|
throw new errors_ts_1.PsytoolsError("no_scoring", `Unsupported scoring kind "${scoring.kind}"`);
|
|
45
71
|
}
|
|
46
72
|
}
|
|
47
|
-
function
|
|
48
|
-
const
|
|
73
|
+
function assertValidAnswers(definition, answers) {
|
|
74
|
+
const questions = new Map(definition.questions.map((q) => [q.id, q]));
|
|
75
|
+
for (const [questionId, value] of Object.entries(answers)) {
|
|
76
|
+
const question = questions.get(questionId);
|
|
77
|
+
if (!question) {
|
|
78
|
+
throw new errors_ts_1.PsytoolsError("unknown_question", `Answers reference unknown question "${questionId}" in assessment "${definition.id}"`);
|
|
79
|
+
}
|
|
80
|
+
const options = question.options ?? definition.options;
|
|
81
|
+
if (!options.some((option) => option.value === value)) {
|
|
82
|
+
const allowed = options.map((option) => option.value).join(", ");
|
|
83
|
+
throw new errors_ts_1.PsytoolsError("invalid_value", `Value ${value} is not a valid option for question "${questionId}" (allowed: ${allowed})`);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
function evaluateSum(definition, answers, scoring) {
|
|
88
|
+
const multiplier = scoring.multiplier ?? 1;
|
|
89
|
+
const { score, min, max } = sumQuestions(definition, definition.questions, answers, multiplier);
|
|
49
90
|
return {
|
|
50
91
|
kind: "scale",
|
|
51
92
|
score,
|
|
52
93
|
min,
|
|
53
94
|
max,
|
|
54
|
-
...bandOf(score, bands),
|
|
55
|
-
flags: triggeredFlags(answers, flags),
|
|
95
|
+
...bandOf(score, scoring.bands),
|
|
96
|
+
flags: triggeredFlags(answers, scoring.flags),
|
|
56
97
|
};
|
|
57
98
|
}
|
|
58
99
|
function sumQuestions(definition, questions, answers, multiplier) {
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, 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, ScoringDefinition, 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
3
|
export { localize, collectLocales } from "./i18n.ts";
|
|
4
4
|
export { Assessment, validateDefinition } from "./assessment.ts";
|
|
5
5
|
export { AssessmentResponse } from "./response.ts";
|
|
6
6
|
export { evaluate } from "./evaluation.ts";
|
|
7
|
-
export { phq9, gad7, dass21, inventories, loadInventory, twoWeekFrequencyOptions, twoWeekInstructions, } from "./inventories/index.ts";
|
|
7
|
+
export { phq9, gad7, dass21, who5, asrs6, aq10, audit, miniIpip, inventories, loadInventory, twoWeekFrequencyOptions, twoWeekInstructions, } from "./inventories/index.ts";
|
|
8
8
|
export type { InventoryId } from "./inventories/index.ts";
|
package/dist/cjs/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.twoWeekInstructions = exports.twoWeekFrequencyOptions = exports.loadInventory = exports.inventories = exports.dass21 = exports.gad7 = exports.phq9 = exports.evaluate = exports.AssessmentResponse = exports.validateDefinition = exports.Assessment = exports.collectLocales = exports.localize = exports.PsytoolsError = void 0;
|
|
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.localize = 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");
|
|
@@ -17,6 +17,11 @@ var index_ts_1 = require("./inventories/index.js");
|
|
|
17
17
|
Object.defineProperty(exports, "phq9", { enumerable: true, get: function () { return index_ts_1.phq9; } });
|
|
18
18
|
Object.defineProperty(exports, "gad7", { enumerable: true, get: function () { return index_ts_1.gad7; } });
|
|
19
19
|
Object.defineProperty(exports, "dass21", { enumerable: true, get: function () { return index_ts_1.dass21; } });
|
|
20
|
+
Object.defineProperty(exports, "who5", { enumerable: true, get: function () { return index_ts_1.who5; } });
|
|
21
|
+
Object.defineProperty(exports, "asrs6", { enumerable: true, get: function () { return index_ts_1.asrs6; } });
|
|
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; } });
|
|
20
25
|
Object.defineProperty(exports, "inventories", { enumerable: true, get: function () { return index_ts_1.inventories; } });
|
|
21
26
|
Object.defineProperty(exports, "loadInventory", { enumerable: true, get: function () { return index_ts_1.loadInventory; } });
|
|
22
27
|
Object.defineProperty(exports, "twoWeekFrequencyOptions", { enumerable: true, get: function () { return index_ts_1.twoWeekFrequencyOptions; } });
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { AssessmentDefinition } from "../types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* AQ-10 — Autism Spectrum Quotient, 10-item version (adults).
|
|
4
|
+
*
|
|
5
|
+
* Recommended by NICE (UK) for quick screening of autistic traits in
|
|
6
|
+
* adults. Each item is answered on a 4-point agree/disagree scale but
|
|
7
|
+
* scores binary: one point per item answered in the trait direction
|
|
8
|
+
* ("agree" on items 1, 7, 8, 10; "disagree" on the rest, modeled here as
|
|
9
|
+
* `reverseScored`). A total of 6 or more suggests referral for a
|
|
10
|
+
* specialist autism assessment (Allison et al., 2012). Free to use.
|
|
11
|
+
*/
|
|
12
|
+
export declare const aq10: AssessmentDefinition;
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.aq10 = void 0;
|
|
4
|
+
/**
|
|
5
|
+
* AQ-10 — Autism Spectrum Quotient, 10-item version (adults).
|
|
6
|
+
*
|
|
7
|
+
* Recommended by NICE (UK) for quick screening of autistic traits in
|
|
8
|
+
* adults. Each item is answered on a 4-point agree/disagree scale but
|
|
9
|
+
* scores binary: one point per item answered in the trait direction
|
|
10
|
+
* ("agree" on items 1, 7, 8, 10; "disagree" on the rest, modeled here as
|
|
11
|
+
* `reverseScored`). A total of 6 or more suggests referral for a
|
|
12
|
+
* specialist autism assessment (Allison et al., 2012). Free to use.
|
|
13
|
+
*/
|
|
14
|
+
exports.aq10 = {
|
|
15
|
+
id: "aq10",
|
|
16
|
+
version: "1.0.0",
|
|
17
|
+
title: {
|
|
18
|
+
en: "Autism Spectrum Quotient (AQ-10) — Adult",
|
|
19
|
+
tr: "Otizm Spektrum Anketi (AQ-10) — Yetişkin",
|
|
20
|
+
de: "Autismus-Spektrum-Quotient (AQ-10) — Erwachsene",
|
|
21
|
+
},
|
|
22
|
+
description: {
|
|
23
|
+
en: "A 10-item screening questionnaire for autistic traits in adults, condensed from the 50-item Autism Spectrum Quotient.",
|
|
24
|
+
tr: "50 maddelik Otizm Spektrum Anketi'nden kısaltılmış, yetişkinlerde otistik özellikleri taramak için 10 maddelik bir ölçek.",
|
|
25
|
+
de: "Ein 10-Item-Screeningfragebogen für autistische Merkmale bei Erwachsenen, verkürzt aus dem 50-Item-Autismus-Spektrum-Quotienten.",
|
|
26
|
+
},
|
|
27
|
+
instructions: {
|
|
28
|
+
en: "For each statement, select the answer that best describes you.",
|
|
29
|
+
tr: "Her ifade için sizi en iyi tanımlayan yanıtı işaretleyin.",
|
|
30
|
+
de: "Wählen Sie zu jeder Aussage die Antwort, die Sie am besten beschreibt.",
|
|
31
|
+
},
|
|
32
|
+
defaultLocale: "en",
|
|
33
|
+
options: [
|
|
34
|
+
{
|
|
35
|
+
value: 0,
|
|
36
|
+
label: { en: "Definitely disagree", tr: "Kesinlikle katılmıyorum", de: "Stimme überhaupt nicht zu" },
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
value: 1,
|
|
40
|
+
label: { en: "Slightly disagree", tr: "Biraz katılmıyorum", de: "Stimme eher nicht zu" },
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
value: 2,
|
|
44
|
+
label: { en: "Slightly agree", tr: "Biraz katılıyorum", de: "Stimme eher zu" },
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
value: 3,
|
|
48
|
+
label: { en: "Definitely agree", tr: "Kesinlikle katılıyorum", de: "Stimme voll und ganz zu" },
|
|
49
|
+
},
|
|
50
|
+
],
|
|
51
|
+
questions: [
|
|
52
|
+
{
|
|
53
|
+
id: "aq10-1",
|
|
54
|
+
text: {
|
|
55
|
+
en: "I often notice small sounds when others do not",
|
|
56
|
+
tr: "Başkalarının fark etmediği küçük sesleri sıklıkla fark ederim",
|
|
57
|
+
de: "Ich nehme oft leise Geräusche wahr, die andere nicht bemerken",
|
|
58
|
+
},
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
id: "aq10-2",
|
|
62
|
+
text: {
|
|
63
|
+
en: "I usually concentrate more on the whole picture, rather than the small details",
|
|
64
|
+
tr: "Genellikle küçük ayrıntılardan çok resmin bütününe odaklanırım",
|
|
65
|
+
de: "Ich konzentriere mich meist mehr auf das Gesamtbild als auf die kleinen Details",
|
|
66
|
+
},
|
|
67
|
+
reverseScored: true,
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
id: "aq10-3",
|
|
71
|
+
text: {
|
|
72
|
+
en: "I find it easy to do more than one thing at once",
|
|
73
|
+
tr: "Aynı anda birden fazla iş yapmak benim için kolaydır",
|
|
74
|
+
de: "Es fällt mir leicht, mehrere Dinge gleichzeitig zu tun",
|
|
75
|
+
},
|
|
76
|
+
reverseScored: true,
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
id: "aq10-4",
|
|
80
|
+
text: {
|
|
81
|
+
en: "If there is an interruption, I can switch back to what I was doing very quickly",
|
|
82
|
+
tr: "Bir kesinti olursa, yapmakta olduğum işe çok hızlı bir şekilde geri dönebilirim",
|
|
83
|
+
de: "Wenn ich unterbrochen werde, kann ich sehr schnell zu meiner Tätigkeit zurückkehren",
|
|
84
|
+
},
|
|
85
|
+
reverseScored: true,
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
id: "aq10-5",
|
|
89
|
+
text: {
|
|
90
|
+
en: "I find it easy to 'read between the lines' when someone is talking to me",
|
|
91
|
+
tr: "Biri benimle konuşurken 'satır aralarını okumak' benim için kolaydır",
|
|
92
|
+
de: "Es fällt mir leicht, 'zwischen den Zeilen zu lesen', wenn jemand mit mir spricht",
|
|
93
|
+
},
|
|
94
|
+
reverseScored: true,
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
id: "aq10-6",
|
|
98
|
+
text: {
|
|
99
|
+
en: "I know how to tell if someone listening to me is getting bored",
|
|
100
|
+
tr: "Beni dinleyen birinin sıkılmaya başladığını nasıl anlayacağımı bilirim",
|
|
101
|
+
de: "Ich erkenne, ob jemand, der mir zuhört, sich zu langweilen beginnt",
|
|
102
|
+
},
|
|
103
|
+
reverseScored: true,
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
id: "aq10-7",
|
|
107
|
+
text: {
|
|
108
|
+
en: "When I'm reading a story I find it difficult to work out the characters' intentions",
|
|
109
|
+
tr: "Bir öykü okurken karakterlerin niyetlerini anlamakta zorlanırım",
|
|
110
|
+
de: "Wenn ich eine Geschichte lese, fällt es mir schwer, die Absichten der Figuren zu erkennen",
|
|
111
|
+
},
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
id: "aq10-8",
|
|
115
|
+
text: {
|
|
116
|
+
en: "I like to collect information about categories of things (e.g. types of car, types of bird, types of train, types of plant etc)",
|
|
117
|
+
tr: "Belirli kategorilerdeki şeyler hakkında bilgi toplamayı severim (örneğin araba türleri, kuş türleri, tren türleri, bitki türleri vb.)",
|
|
118
|
+
de: "Ich sammle gern Informationen über Kategorien von Dingen (z. B. Auto-, Vogel-, Zug- oder Pflanzenarten)",
|
|
119
|
+
},
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
id: "aq10-9",
|
|
123
|
+
text: {
|
|
124
|
+
en: "I find it easy to work out what someone is thinking or feeling just by looking at their face",
|
|
125
|
+
tr: "Sadece yüzüne bakarak birinin ne düşündüğünü ya da hissettiğini anlamak benim için kolaydır",
|
|
126
|
+
de: "Es fällt mir leicht, allein am Gesicht abzulesen, was jemand denkt oder fühlt",
|
|
127
|
+
},
|
|
128
|
+
reverseScored: true,
|
|
129
|
+
},
|
|
130
|
+
{
|
|
131
|
+
id: "aq10-10",
|
|
132
|
+
text: {
|
|
133
|
+
en: "I find it difficult to work out people's intentions",
|
|
134
|
+
tr: "İnsanların niyetlerini anlamakta zorlanırım",
|
|
135
|
+
de: "Es fällt mir schwer, die Absichten anderer Menschen zu erkennen",
|
|
136
|
+
},
|
|
137
|
+
},
|
|
138
|
+
],
|
|
139
|
+
scoring: {
|
|
140
|
+
kind: "count",
|
|
141
|
+
items: [
|
|
142
|
+
{ questionId: "aq10-1", minValue: 2 },
|
|
143
|
+
{ questionId: "aq10-2", minValue: 2 },
|
|
144
|
+
{ questionId: "aq10-3", minValue: 2 },
|
|
145
|
+
{ questionId: "aq10-4", minValue: 2 },
|
|
146
|
+
{ questionId: "aq10-5", minValue: 2 },
|
|
147
|
+
{ questionId: "aq10-6", minValue: 2 },
|
|
148
|
+
{ questionId: "aq10-7", minValue: 2 },
|
|
149
|
+
{ questionId: "aq10-8", minValue: 2 },
|
|
150
|
+
{ questionId: "aq10-9", minValue: 2 },
|
|
151
|
+
{ questionId: "aq10-10", minValue: 2 },
|
|
152
|
+
],
|
|
153
|
+
bands: [
|
|
154
|
+
{
|
|
155
|
+
id: "below-threshold",
|
|
156
|
+
min: 0,
|
|
157
|
+
max: 5,
|
|
158
|
+
label: {
|
|
159
|
+
en: "Below screening threshold",
|
|
160
|
+
tr: "Tarama eşiğinin altında",
|
|
161
|
+
de: "Unterhalb der Screening-Schwelle",
|
|
162
|
+
},
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
id: "above-threshold",
|
|
166
|
+
min: 6,
|
|
167
|
+
max: 10,
|
|
168
|
+
label: {
|
|
169
|
+
en: "At or above threshold — consider referral for a specialist autism assessment",
|
|
170
|
+
tr: "Eşikte ya da üzerinde — uzman otizm değerlendirmesine yönlendirme düşünülmelidir",
|
|
171
|
+
de: "An oder über der Schwelle — Überweisung zu einer spezialisierten Autismus-Diagnostik erwägen",
|
|
172
|
+
},
|
|
173
|
+
},
|
|
174
|
+
],
|
|
175
|
+
},
|
|
176
|
+
meta: {
|
|
177
|
+
reference: "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.",
|
|
178
|
+
license: "Free with conditions — (c) Autism Research Centre, University of Cambridge; distributed free of charge, NICE-recommended for clinical screening. Verify licensing with ARC before embedding in commercial products.",
|
|
179
|
+
licenseFlag: "free-with-conditions",
|
|
180
|
+
translationProvenance: "en: reproduced from the original. tr/de: AI translation (Anthropic Claude, claude-fable-5) from the original English; official translations were not consulted and the texts are unverified. See SOURCES.md.",
|
|
181
|
+
note: "Each item scores 1 point in the trait direction; disagree-scored items are modeled as reverseScored.",
|
|
182
|
+
},
|
|
183
|
+
};
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { AssessmentDefinition } from "../types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (Part A).
|
|
4
|
+
*
|
|
5
|
+
* Developed by the WHO and the Workgroup on Adult ADHD (Harvard Medical
|
|
6
|
+
* School / NYU). Items 1–3 count as screen-positive from "Sometimes" and
|
|
7
|
+
* items 4–6 from "Often"; four or more positive items indicate symptoms
|
|
8
|
+
* highly consistent with adult ADHD and warrant further investigation
|
|
9
|
+
* (Kessler et al., 2005). Free to distribute and score.
|
|
10
|
+
*/
|
|
11
|
+
export declare const asrs6: AssessmentDefinition;
|