psytools 0.3.2 → 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 +29 -15
- package/SOURCES.md +2 -0
- 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 +4 -2
- package/dist/cjs/index.js +2 -2
- package/dist/cjs/inventories/aq10.js +35 -5
- package/dist/cjs/inventories/asrs6.js +28 -6
- package/dist/cjs/inventories/audit.js +107 -16
- package/dist/cjs/inventories/common.js +10 -0
- package/dist/cjs/inventories/dass21.js +75 -19
- package/dist/cjs/inventories/gad7.js +23 -5
- package/dist/cjs/inventories/mini-ipip.js +107 -9
- package/dist/cjs/inventories/phq9.js +30 -6
- package/dist/cjs/inventories/who5.js +31 -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 +4 -2
- package/dist/esm/index.js +1 -1
- package/dist/esm/inventories/aq10.js +35 -5
- package/dist/esm/inventories/asrs6.js +28 -6
- package/dist/esm/inventories/audit.js +107 -16
- package/dist/esm/inventories/common.js +10 -0
- package/dist/esm/inventories/dass21.js +75 -19
- package/dist/esm/inventories/gad7.js +23 -5
- package/dist/esm/inventories/mini-ipip.js +107 -9
- package/dist/esm/inventories/phq9.js +30 -6
- package/dist/esm/inventories/who5.js +31 -5
- package/dist/esm/types.d.ts +30 -1
- package/package.json +1 -1
- 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 +6 -1
- package/src/inventories/aq10.ts +35 -5
- package/src/inventories/asrs6.ts +28 -6
- package/src/inventories/audit.ts +107 -16
- package/src/inventories/common.ts +10 -0
- package/src/inventories/dass21.ts +75 -19
- package/src/inventories/gad7.ts +23 -5
- package/src/inventories/mini-ipip.ts +107 -9
- package/src/inventories/phq9.ts +30 -6
- package/src/inventories/who5.ts +31 -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,14 +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 |
|
|
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 |
|
|
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 |
|
|
92
92
|
|
|
93
93
|
```ts
|
|
94
94
|
import { loadInventory, inventories, dass21 } from "psytools";
|
|
@@ -147,6 +147,20 @@ Questions may also carry their own `options` to override the default scale, and
|
|
|
147
147
|
|
|
148
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/`).
|
|
149
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
|
+
|
|
150
164
|
## Custom evaluation
|
|
151
165
|
|
|
152
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:
|
|
@@ -163,7 +177,7 @@ const attachmentStyle: Evaluator = (definition, answers) => {
|
|
|
163
177
|
};
|
|
164
178
|
};
|
|
165
179
|
|
|
166
|
-
assessment.evaluate(response, attachmentStyle);
|
|
180
|
+
assessment.evaluate(response, { evaluator: attachmentStyle });
|
|
167
181
|
```
|
|
168
182
|
|
|
169
183
|
Result shapes: `scale` (single score + band + flags), `multiscale` (named subscales), `categorical`, and `custom` (escape hatch).
|
|
@@ -184,11 +198,11 @@ const history = rows
|
|
|
184
198
|
| --- | --- |
|
|
185
199
|
| `Assessment` | Wraps a definition: validation, `localize()`, `createResponse()`, `evaluate()`, `stringify()`/`parse()` |
|
|
186
200
|
| `AssessmentResponse` | `answer()`, `answerAll()`, `clearAnswer()`, `status`, `progress()`, `validate()`, `submit()`, `stringify()`/`parse()` |
|
|
187
|
-
| `evaluate(definition, answers, evaluator?)` | Standalone scoring (also available as `Assessment#evaluate`) |
|
|
201
|
+
| `evaluate(definition, answers, { evaluator? })` | Standalone scoring (also available as `Assessment#evaluate`) |
|
|
188
202
|
| `validateDefinition(input)` | Non-throwing structural validation of definitions |
|
|
189
|
-
| `loadInventory(id)` / `inventories`
|
|
190
|
-
| `
|
|
191
|
-
| `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`) |
|
|
192
206
|
|
|
193
207
|
## Development
|
|
194
208
|
|
package/SOURCES.md
CHANGED
|
@@ -21,6 +21,8 @@ The same provenance applies to every bundled inventory. If an inventory ever dev
|
|
|
21
21
|
| en | Reproduced from the original published instrument | Yes |
|
|
22
22
|
| tr | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
23
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 |
|
|
24
26
|
|
|
25
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.
|
|
26
28
|
|
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";
|
|
8
|
+
export type { EvaluateOptions } from "./evaluation.ts";
|
|
7
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.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.
|
|
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; } });
|
|
@@ -18,34 +18,40 @@ exports.aq10 = {
|
|
|
18
18
|
en: "Autism Spectrum Quotient (AQ-10) — Adult",
|
|
19
19
|
tr: "Otizm Spektrum Anketi (AQ-10) — Yetişkin",
|
|
20
20
|
de: "Autismus-Spektrum-Quotient (AQ-10) — Erwachsene",
|
|
21
|
+
zh: "自闭症谱系商数问卷(AQ-10)— 成人版",
|
|
22
|
+
es: "Cociente del Espectro Autista (AQ-10) — Adultos",
|
|
21
23
|
},
|
|
22
24
|
description: {
|
|
23
25
|
en: "A 10-item screening questionnaire for autistic traits in adults, condensed from the 50-item Autism Spectrum Quotient.",
|
|
24
26
|
tr: "50 maddelik Otizm Spektrum Anketi'nden kısaltılmış, yetişkinlerde otistik özellikleri taramak için 10 maddelik bir ölçek.",
|
|
25
27
|
de: "Ein 10-Item-Screeningfragebogen für autistische Merkmale bei Erwachsenen, verkürzt aus dem 50-Item-Autismus-Spektrum-Quotienten.",
|
|
28
|
+
zh: "一份用于筛查成人自闭症特质的10条目问卷,由50条目的自闭症谱系商数量表精简而成。",
|
|
29
|
+
es: "Un cuestionario de cribado de 10 ítems para rasgos autistas en adultos, condensado a partir del Cociente del Espectro Autista de 50 ítems.",
|
|
26
30
|
},
|
|
27
31
|
instructions: {
|
|
28
32
|
en: "For each statement, select the answer that best describes you.",
|
|
29
33
|
tr: "Her ifade için sizi en iyi tanımlayan yanıtı işaretleyin.",
|
|
30
34
|
de: "Wählen Sie zu jeder Aussage die Antwort, die Sie am besten beschreibt.",
|
|
35
|
+
zh: "请针对每条陈述,选择最符合您情况的答案。",
|
|
36
|
+
es: "Para cada afirmación, seleccione la respuesta que mejor lo describa.",
|
|
31
37
|
},
|
|
32
38
|
defaultLocale: "en",
|
|
33
39
|
options: [
|
|
34
40
|
{
|
|
35
41
|
value: 0,
|
|
36
|
-
label: { en: "Definitely disagree", tr: "Kesinlikle katılmıyorum", de: "Stimme überhaupt nicht zu" },
|
|
42
|
+
label: { en: "Definitely disagree", tr: "Kesinlikle katılmıyorum", de: "Stimme überhaupt nicht zu", zh: "完全不同意", es: "Totalmente en desacuerdo" },
|
|
37
43
|
},
|
|
38
44
|
{
|
|
39
45
|
value: 1,
|
|
40
|
-
label: { en: "Slightly disagree", tr: "Biraz katılmıyorum", de: "Stimme eher nicht zu" },
|
|
46
|
+
label: { en: "Slightly disagree", tr: "Biraz katılmıyorum", de: "Stimme eher nicht zu", zh: "有点不同意", es: "Ligeramente en desacuerdo" },
|
|
41
47
|
},
|
|
42
48
|
{
|
|
43
49
|
value: 2,
|
|
44
|
-
label: { en: "Slightly agree", tr: "Biraz katılıyorum", de: "Stimme eher zu" },
|
|
50
|
+
label: { en: "Slightly agree", tr: "Biraz katılıyorum", de: "Stimme eher zu", zh: "有点同意", es: "Ligeramente de acuerdo" },
|
|
45
51
|
},
|
|
46
52
|
{
|
|
47
53
|
value: 3,
|
|
48
|
-
label: { en: "Definitely agree", tr: "Kesinlikle katılıyorum", de: "Stimme voll und ganz zu" },
|
|
54
|
+
label: { en: "Definitely agree", tr: "Kesinlikle katılıyorum", de: "Stimme voll und ganz zu", zh: "完全同意", es: "Totalmente de acuerdo" },
|
|
49
55
|
},
|
|
50
56
|
],
|
|
51
57
|
questions: [
|
|
@@ -55,6 +61,8 @@ exports.aq10 = {
|
|
|
55
61
|
en: "I often notice small sounds when others do not",
|
|
56
62
|
tr: "Başkalarının fark etmediği küçük sesleri sıklıkla fark ederim",
|
|
57
63
|
de: "Ich nehme oft leise Geräusche wahr, die andere nicht bemerken",
|
|
64
|
+
zh: "我经常注意到别人注意不到的微小声音",
|
|
65
|
+
es: "A menudo noto pequeños sonidos que otras personas no perciben",
|
|
58
66
|
},
|
|
59
67
|
},
|
|
60
68
|
{
|
|
@@ -63,6 +71,8 @@ exports.aq10 = {
|
|
|
63
71
|
en: "I usually concentrate more on the whole picture, rather than the small details",
|
|
64
72
|
tr: "Genellikle küçük ayrıntılardan çok resmin bütününe odaklanırım",
|
|
65
73
|
de: "Ich konzentriere mich meist mehr auf das Gesamtbild als auf die kleinen Details",
|
|
74
|
+
zh: "我通常更关注事情的整体,而不是小细节",
|
|
75
|
+
es: "Normalmente me concentro más en la imagen global que en los pequeños detalles",
|
|
66
76
|
},
|
|
67
77
|
reverseScored: true,
|
|
68
78
|
},
|
|
@@ -72,6 +82,8 @@ exports.aq10 = {
|
|
|
72
82
|
en: "I find it easy to do more than one thing at once",
|
|
73
83
|
tr: "Aynı anda birden fazla iş yapmak benim için kolaydır",
|
|
74
84
|
de: "Es fällt mir leicht, mehrere Dinge gleichzeitig zu tun",
|
|
85
|
+
zh: "我觉得同时做几件事情很容易",
|
|
86
|
+
es: "Me resulta fácil hacer más de una cosa a la vez",
|
|
75
87
|
},
|
|
76
88
|
reverseScored: true,
|
|
77
89
|
},
|
|
@@ -81,6 +93,8 @@ exports.aq10 = {
|
|
|
81
93
|
en: "If there is an interruption, I can switch back to what I was doing very quickly",
|
|
82
94
|
tr: "Bir kesinti olursa, yapmakta olduğum işe çok hızlı bir şekilde geri dönebilirim",
|
|
83
95
|
de: "Wenn ich unterbrochen werde, kann ich sehr schnell zu meiner Tätigkeit zurückkehren",
|
|
96
|
+
zh: "如果被打断,我能很快回到原来正在做的事情上",
|
|
97
|
+
es: "Si hay una interrupción, puedo volver muy rápidamente a lo que estaba haciendo",
|
|
84
98
|
},
|
|
85
99
|
reverseScored: true,
|
|
86
100
|
},
|
|
@@ -90,6 +104,8 @@ exports.aq10 = {
|
|
|
90
104
|
en: "I find it easy to 'read between the lines' when someone is talking to me",
|
|
91
105
|
tr: "Biri benimle konuşurken 'satır aralarını okumak' benim için kolaydır",
|
|
92
106
|
de: "Es fällt mir leicht, 'zwischen den Zeilen zu lesen', wenn jemand mit mir spricht",
|
|
107
|
+
zh: "当别人和我说话时,我觉得'听出言外之意'很容易",
|
|
108
|
+
es: "Me resulta fácil 'leer entre líneas' cuando alguien me está hablando",
|
|
93
109
|
},
|
|
94
110
|
reverseScored: true,
|
|
95
111
|
},
|
|
@@ -99,6 +115,8 @@ exports.aq10 = {
|
|
|
99
115
|
en: "I know how to tell if someone listening to me is getting bored",
|
|
100
116
|
tr: "Beni dinleyen birinin sıkılmaya başladığını nasıl anlayacağımı bilirim",
|
|
101
117
|
de: "Ich erkenne, ob jemand, der mir zuhört, sich zu langweilen beginnt",
|
|
118
|
+
zh: "我知道如何判断听我说话的人是否开始感到厌烦",
|
|
119
|
+
es: "Sé darme cuenta de si la persona que me escucha se está aburriendo",
|
|
102
120
|
},
|
|
103
121
|
reverseScored: true,
|
|
104
122
|
},
|
|
@@ -108,6 +126,8 @@ exports.aq10 = {
|
|
|
108
126
|
en: "When I'm reading a story I find it difficult to work out the characters' intentions",
|
|
109
127
|
tr: "Bir öykü okurken karakterlerin niyetlerini anlamakta zorlanırım",
|
|
110
128
|
de: "Wenn ich eine Geschichte lese, fällt es mir schwer, die Absichten der Figuren zu erkennen",
|
|
129
|
+
zh: "读故事时,我很难弄清人物的意图",
|
|
130
|
+
es: "Cuando leo una historia, me resulta difícil deducir las intenciones de los personajes",
|
|
111
131
|
},
|
|
112
132
|
},
|
|
113
133
|
{
|
|
@@ -116,6 +136,8 @@ exports.aq10 = {
|
|
|
116
136
|
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
137
|
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
138
|
de: "Ich sammle gern Informationen über Kategorien von Dingen (z. B. Auto-, Vogel-, Zug- oder Pflanzenarten)",
|
|
139
|
+
zh: "我喜欢收集各类事物的信息(例如汽车的类型、鸟的种类、火车的类型、植物的种类等)",
|
|
140
|
+
es: "Me gusta recopilar información sobre categorías de cosas (p. ej., tipos de coches, de aves, de trenes, de plantas, etc.)",
|
|
119
141
|
},
|
|
120
142
|
},
|
|
121
143
|
{
|
|
@@ -124,6 +146,8 @@ exports.aq10 = {
|
|
|
124
146
|
en: "I find it easy to work out what someone is thinking or feeling just by looking at their face",
|
|
125
147
|
tr: "Sadece yüzüne bakarak birinin ne düşündüğünü ya da hissettiğini anlamak benim için kolaydır",
|
|
126
148
|
de: "Es fällt mir leicht, allein am Gesicht abzulesen, was jemand denkt oder fühlt",
|
|
149
|
+
zh: "我觉得只看别人的脸就能轻松看出对方在想什么或有什么感受",
|
|
150
|
+
es: "Me resulta fácil deducir lo que alguien piensa o siente con solo mirarle la cara",
|
|
127
151
|
},
|
|
128
152
|
reverseScored: true,
|
|
129
153
|
},
|
|
@@ -133,6 +157,8 @@ exports.aq10 = {
|
|
|
133
157
|
en: "I find it difficult to work out people's intentions",
|
|
134
158
|
tr: "İnsanların niyetlerini anlamakta zorlanırım",
|
|
135
159
|
de: "Es fällt mir schwer, die Absichten anderer Menschen zu erkennen",
|
|
160
|
+
zh: "我很难弄清别人的意图",
|
|
161
|
+
es: "Me resulta difícil deducir las intenciones de las personas",
|
|
136
162
|
},
|
|
137
163
|
},
|
|
138
164
|
],
|
|
@@ -159,6 +185,8 @@ exports.aq10 = {
|
|
|
159
185
|
en: "Below screening threshold",
|
|
160
186
|
tr: "Tarama eşiğinin altında",
|
|
161
187
|
de: "Unterhalb der Screening-Schwelle",
|
|
188
|
+
zh: "低于筛查阈值",
|
|
189
|
+
es: "Por debajo del umbral de cribado",
|
|
162
190
|
},
|
|
163
191
|
},
|
|
164
192
|
{
|
|
@@ -169,6 +197,8 @@ exports.aq10 = {
|
|
|
169
197
|
en: "At or above threshold — consider referral for a specialist autism assessment",
|
|
170
198
|
tr: "Eşikte ya da üzerinde — uzman otizm değerlendirmesine yönlendirme düşünülmelidir",
|
|
171
199
|
de: "An oder über der Schwelle — Überweisung zu einer spezialisierten Autismus-Diagnostik erwägen",
|
|
200
|
+
zh: "达到或超过阈值——建议考虑转介进行自闭症专科评估",
|
|
201
|
+
es: "En el umbral o por encima — considere la derivación para una evaluación especializada de autismo",
|
|
172
202
|
},
|
|
173
203
|
},
|
|
174
204
|
],
|
|
@@ -177,7 +207,7 @@ exports.aq10 = {
|
|
|
177
207
|
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
208
|
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
209
|
licenseFlag: "free-with-conditions",
|
|
180
|
-
translationProvenance: "en: reproduced from the original. tr
|
|
210
|
+
translationProvenance: "en: reproduced from the original. Other locales (tr, de, zh, es): 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
211
|
note: "Each item scores 1 point in the trait direction; disagree-scored items are modeled as reverseScored.",
|
|
182
212
|
},
|
|
183
213
|
};
|