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/dist/esm/types.d.ts
CHANGED
|
@@ -57,6 +57,28 @@ export interface ScoreFlag {
|
|
|
57
57
|
minValue: number;
|
|
58
58
|
label: LocalizedText;
|
|
59
59
|
}
|
|
60
|
+
/** How a scorer treats unanswered items among the ones it uses. */
|
|
61
|
+
export type MissingDataStrategy = "ignore" | "prorate" | "require-complete";
|
|
62
|
+
/**
|
|
63
|
+
* Missing-data policy for declarative scoring. Applies when incomplete
|
|
64
|
+
* answers reach the scorer (raw answer maps, or `allowIncomplete`).
|
|
65
|
+
*
|
|
66
|
+
* - `ignore` (default): unanswered items contribute nothing — partial
|
|
67
|
+
* totals understate severity, so use deliberately.
|
|
68
|
+
* - `prorate`: the raw score is scaled up by totalItems / answeredItems
|
|
69
|
+
* and rounded before any multiplier, per scale/subscale.
|
|
70
|
+
* - `require-complete`: evaluation throws `incomplete_response` when any
|
|
71
|
+
* contributing item is unanswered.
|
|
72
|
+
*/
|
|
73
|
+
export interface MissingDataPolicy {
|
|
74
|
+
strategy: MissingDataStrategy;
|
|
75
|
+
/**
|
|
76
|
+
* Minimum answered contributing items (per scale/subscale) needed to
|
|
77
|
+
* produce a score; below it evaluation throws `incomplete_response`.
|
|
78
|
+
* Defaults to 1 for `prorate`, 0 otherwise.
|
|
79
|
+
*/
|
|
80
|
+
minAnswered?: number;
|
|
81
|
+
}
|
|
60
82
|
/** Sums all answers into a single total score (PHQ-9, GAD-7, ...). */
|
|
61
83
|
export interface SumScoring {
|
|
62
84
|
kind: "sum";
|
|
@@ -65,6 +87,7 @@ export interface SumScoring {
|
|
|
65
87
|
/** Severity bands the (multiplied) total is matched against. */
|
|
66
88
|
bands?: ScoreBand[];
|
|
67
89
|
flags?: ScoreFlag[];
|
|
90
|
+
missing?: MissingDataPolicy;
|
|
68
91
|
}
|
|
69
92
|
/** One subscale of a multi-scale scoring definition. */
|
|
70
93
|
export interface SubscaleDefinition {
|
|
@@ -82,6 +105,8 @@ export interface SubscaleScoring {
|
|
|
82
105
|
kind: "subscales";
|
|
83
106
|
subscales: SubscaleDefinition[];
|
|
84
107
|
flags?: ScoreFlag[];
|
|
108
|
+
/** Applied to each subscale independently. */
|
|
109
|
+
missing?: MissingDataPolicy;
|
|
85
110
|
}
|
|
86
111
|
/** One item of a `count` scoring: when it counts as screen-positive. */
|
|
87
112
|
export interface CountScoringItem {
|
|
@@ -102,6 +127,8 @@ export interface CountScoring {
|
|
|
102
127
|
/** Bands the positive-item count is matched against. */
|
|
103
128
|
bands?: ScoreBand[];
|
|
104
129
|
flags?: ScoreFlag[];
|
|
130
|
+
/** `prorate` scales the positive count by totalItems / answeredItems. */
|
|
131
|
+
missing?: MissingDataPolicy;
|
|
105
132
|
}
|
|
106
133
|
/** Declarative, serializable scoring rules built into psytools. */
|
|
107
134
|
export type ScoringDefinition = SumScoring | SubscaleScoring | CountScoring;
|
|
@@ -156,9 +183,11 @@ export interface ResponseData {
|
|
|
156
183
|
submittedAt?: string;
|
|
157
184
|
meta?: Record<string, unknown>;
|
|
158
185
|
}
|
|
186
|
+
/** Codes a validation issue can carry (a subset of `PsytoolsErrorCode`). */
|
|
187
|
+
export type ValidationIssueCode = "unknown_question" | "invalid_value" | "missing_answer" | "duplicate_question" | "malformed";
|
|
159
188
|
/** A single validation problem. */
|
|
160
189
|
export interface ValidationIssue {
|
|
161
|
-
code:
|
|
190
|
+
code: ValidationIssueCode;
|
|
162
191
|
message: string;
|
|
163
192
|
questionId?: string;
|
|
164
193
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "psytools",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Zero-dependency toolkit for psychological assessments: data models, response validation, scoring, and predefined inventories (PHQ-9, GAD-7, DASS-21, WHO-5, ASRS, AQ-10, AUDIT, Mini-IPIP) in multiple languages.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"psychology",
|
|
@@ -86,6 +86,15 @@
|
|
|
86
86
|
"label": { "$ref": "#/$defs/localizedText" }
|
|
87
87
|
}
|
|
88
88
|
},
|
|
89
|
+
"missingDataPolicy": {
|
|
90
|
+
"type": "object",
|
|
91
|
+
"required": ["strategy"],
|
|
92
|
+
"additionalProperties": false,
|
|
93
|
+
"properties": {
|
|
94
|
+
"strategy": { "enum": ["ignore", "prorate", "require-complete"] },
|
|
95
|
+
"minAnswered": { "type": "number" }
|
|
96
|
+
}
|
|
97
|
+
},
|
|
89
98
|
"sumScoring": {
|
|
90
99
|
"type": "object",
|
|
91
100
|
"required": ["kind"],
|
|
@@ -94,7 +103,8 @@
|
|
|
94
103
|
"kind": { "const": "sum" },
|
|
95
104
|
"multiplier": { "type": "number" },
|
|
96
105
|
"bands": { "type": "array", "items": { "$ref": "#/$defs/scoreBand" } },
|
|
97
|
-
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } }
|
|
106
|
+
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } },
|
|
107
|
+
"missing": { "$ref": "#/$defs/missingDataPolicy" }
|
|
98
108
|
}
|
|
99
109
|
},
|
|
100
110
|
"subscale": {
|
|
@@ -134,7 +144,8 @@
|
|
|
134
144
|
"items": { "$ref": "#/$defs/countScoringItem" }
|
|
135
145
|
},
|
|
136
146
|
"bands": { "type": "array", "items": { "$ref": "#/$defs/scoreBand" } },
|
|
137
|
-
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } }
|
|
147
|
+
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } },
|
|
148
|
+
"missing": { "$ref": "#/$defs/missingDataPolicy" }
|
|
138
149
|
}
|
|
139
150
|
},
|
|
140
151
|
"subscaleScoring": {
|
|
@@ -148,7 +159,8 @@
|
|
|
148
159
|
"minItems": 1,
|
|
149
160
|
"items": { "$ref": "#/$defs/subscale" }
|
|
150
161
|
},
|
|
151
|
-
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } }
|
|
162
|
+
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } },
|
|
163
|
+
"missing": { "$ref": "#/$defs/missingDataPolicy" }
|
|
152
164
|
}
|
|
153
165
|
}
|
|
154
166
|
}
|
package/src/assessment.ts
CHANGED
|
@@ -9,9 +9,9 @@ import type {
|
|
|
9
9
|
ValidationResult,
|
|
10
10
|
} from "./types.ts";
|
|
11
11
|
import { PsytoolsError } from "./errors.ts";
|
|
12
|
-
import { collectLocales,
|
|
12
|
+
import { collectLocales, localizeText } from "./i18n.ts";
|
|
13
13
|
import { AssessmentResponse } from "./response.ts";
|
|
14
|
-
import { evaluate } from "./evaluation.ts";
|
|
14
|
+
import { evaluate, type EvaluateOptions } from "./evaluation.ts";
|
|
15
15
|
|
|
16
16
|
/**
|
|
17
17
|
* Structurally validates an assessment definition (useful before persisting
|
|
@@ -216,20 +216,26 @@ export class Assessment {
|
|
|
216
216
|
|
|
217
217
|
/**
|
|
218
218
|
* Evaluates a response (or raw answers) with the definition's declarative
|
|
219
|
-
* scoring, or with `evaluator` when provided.
|
|
219
|
+
* scoring, or with `options.evaluator` when provided.
|
|
220
220
|
*
|
|
221
221
|
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
222
222
|
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
223
223
|
* Raw answer maps skip the completeness check, but their values are
|
|
224
|
-
* still validated against the option scales
|
|
224
|
+
* still validated against the option scales, and the scoring definition's
|
|
225
|
+
* missing-data policy still applies.
|
|
225
226
|
*
|
|
226
227
|
* @throws PsytoolsError `incomplete_response` | `unknown_question` | `invalid_value` | `no_scoring`
|
|
227
228
|
*/
|
|
228
229
|
evaluate(
|
|
229
230
|
response: AssessmentResponse | Record<string, number>,
|
|
230
|
-
|
|
231
|
-
options?: { allowIncomplete?: boolean },
|
|
231
|
+
options?: EvaluateOptions & { allowIncomplete?: boolean },
|
|
232
232
|
): EvaluationResult {
|
|
233
|
+
if (typeof options === "function") {
|
|
234
|
+
throw new PsytoolsError(
|
|
235
|
+
"invalid_argument",
|
|
236
|
+
"Pass the evaluator as an option: assessment.evaluate(response, { evaluator })",
|
|
237
|
+
);
|
|
238
|
+
}
|
|
233
239
|
if (response instanceof AssessmentResponse) {
|
|
234
240
|
const scorable = response.status === "complete" || response.status === "submitted";
|
|
235
241
|
if (!scorable && !options?.allowIncomplete) {
|
|
@@ -240,9 +246,9 @@ export class Assessment {
|
|
|
240
246
|
"pass { allowIncomplete: true } to score it anyway",
|
|
241
247
|
);
|
|
242
248
|
}
|
|
243
|
-
return evaluate(this.definition, response.answers, evaluator);
|
|
249
|
+
return evaluate(this.definition, response.answers, { evaluator: options?.evaluator });
|
|
244
250
|
}
|
|
245
|
-
return evaluate(this.definition, response, evaluator);
|
|
251
|
+
return evaluate(this.definition, response, { evaluator: options?.evaluator });
|
|
246
252
|
}
|
|
247
253
|
|
|
248
254
|
/** The plain serializable definition (used by `JSON.stringify`). */
|
|
@@ -272,6 +278,6 @@ export class Assessment {
|
|
|
272
278
|
}
|
|
273
279
|
|
|
274
280
|
private text(text: Record<string, string>, locale?: string): string {
|
|
275
|
-
return
|
|
281
|
+
return localizeText(text, locale ?? this.definition.defaultLocale, this.definition.defaultLocale);
|
|
276
282
|
}
|
|
277
283
|
}
|
package/src/errors.ts
CHANGED
|
@@ -1,8 +1,31 @@
|
|
|
1
|
+
/** Every error code psytools can throw, for exhaustive handling. */
|
|
2
|
+
export type PsytoolsErrorCode =
|
|
3
|
+
// definition problems
|
|
4
|
+
| "malformed"
|
|
5
|
+
| "duplicate_question"
|
|
6
|
+
| "invalid_definition"
|
|
7
|
+
// answer problems
|
|
8
|
+
| "unknown_question"
|
|
9
|
+
| "invalid_value"
|
|
10
|
+
| "missing_answer"
|
|
11
|
+
// response lifecycle
|
|
12
|
+
| "already_submitted"
|
|
13
|
+
| "invalid_response"
|
|
14
|
+
| "incomplete_response"
|
|
15
|
+
| "assessment_mismatch"
|
|
16
|
+
// evaluation
|
|
17
|
+
| "no_scoring"
|
|
18
|
+
// serialization & lookup
|
|
19
|
+
| "invalid_json"
|
|
20
|
+
| "unknown_inventory"
|
|
21
|
+
// API misuse
|
|
22
|
+
| "invalid_argument";
|
|
23
|
+
|
|
1
24
|
/** Error thrown by psytools, carrying a stable machine-readable code. */
|
|
2
25
|
export class PsytoolsError extends Error {
|
|
3
|
-
readonly code:
|
|
26
|
+
readonly code: PsytoolsErrorCode;
|
|
4
27
|
|
|
5
|
-
constructor(code:
|
|
28
|
+
constructor(code: PsytoolsErrorCode, message: string) {
|
|
6
29
|
super(message);
|
|
7
30
|
this.name = "PsytoolsError";
|
|
8
31
|
this.code = code;
|
package/src/evaluation.ts
CHANGED
|
@@ -5,6 +5,7 @@ import type {
|
|
|
5
5
|
BandResult,
|
|
6
6
|
EvaluationResult,
|
|
7
7
|
Evaluator,
|
|
8
|
+
MissingDataPolicy,
|
|
8
9
|
MultiScaleResult,
|
|
9
10
|
ScaleResult,
|
|
10
11
|
ScoreBand,
|
|
@@ -14,23 +15,35 @@ import type {
|
|
|
14
15
|
} from "./types.ts";
|
|
15
16
|
import { PsytoolsError } from "./errors.ts";
|
|
16
17
|
|
|
18
|
+
export interface EvaluateOptions {
|
|
19
|
+
/** Custom evaluator used instead of the definition's declarative scoring. */
|
|
20
|
+
evaluator?: Evaluator;
|
|
21
|
+
}
|
|
22
|
+
|
|
17
23
|
/**
|
|
18
24
|
* Evaluates answers against an assessment definition.
|
|
19
25
|
*
|
|
20
26
|
* Every answer is first validated against the assessment: the question must
|
|
21
|
-
* exist and the value must belong to its option scale. Then
|
|
22
|
-
* used when given; otherwise the definition's
|
|
23
|
-
* (`sum` or `
|
|
27
|
+
* exist and the value must belong to its option scale. Then
|
|
28
|
+
* `options.evaluator` is used when given; otherwise the definition's
|
|
29
|
+
* declarative `scoring` (`sum`, `subscales`, or `count`) applies, honoring
|
|
30
|
+
* its missing-data policy.
|
|
24
31
|
*
|
|
25
|
-
* @throws PsytoolsError `unknown_question` | `invalid_value` | `no_scoring`
|
|
32
|
+
* @throws PsytoolsError `unknown_question` | `invalid_value` | `incomplete_response` | `no_scoring`
|
|
26
33
|
*/
|
|
27
34
|
export function evaluate(
|
|
28
35
|
definition: AssessmentDefinition,
|
|
29
36
|
answers: AnswerMap,
|
|
30
|
-
|
|
37
|
+
options?: EvaluateOptions,
|
|
31
38
|
): EvaluationResult {
|
|
39
|
+
if (typeof options === "function") {
|
|
40
|
+
throw new PsytoolsError(
|
|
41
|
+
"invalid_argument",
|
|
42
|
+
"Pass the evaluator as an option: evaluate(definition, answers, { evaluator })",
|
|
43
|
+
);
|
|
44
|
+
}
|
|
32
45
|
assertValidAnswers(definition, answers);
|
|
33
|
-
if (evaluator) return evaluator(definition, answers);
|
|
46
|
+
if (options?.evaluator) return options.evaluator(definition, answers);
|
|
34
47
|
|
|
35
48
|
const scoring = definition.scoring;
|
|
36
49
|
if (!scoring) {
|
|
@@ -43,17 +56,20 @@ export function evaluate(
|
|
|
43
56
|
case "sum":
|
|
44
57
|
return evaluateSum(definition, answers, scoring);
|
|
45
58
|
case "count": {
|
|
46
|
-
|
|
59
|
+
const questions = scoring.items.map((item) => requireQuestion(definition, item.questionId));
|
|
60
|
+
const answered = enforceMissing(questions, answers, scoring.missing);
|
|
61
|
+
let positives = 0;
|
|
47
62
|
for (const item of scoring.items) {
|
|
48
63
|
const question = requireQuestion(definition, item.questionId);
|
|
49
|
-
const
|
|
50
|
-
if (
|
|
64
|
+
const value = answers[question.id];
|
|
65
|
+
if (value === undefined) continue;
|
|
51
66
|
const values = (question.options ?? definition.options).map((o) => o.value);
|
|
52
67
|
const effective = question.reverseScored
|
|
53
|
-
? Math.max(...values) + Math.min(...values) -
|
|
54
|
-
:
|
|
55
|
-
if (effective >= item.minValue)
|
|
68
|
+
? Math.max(...values) + Math.min(...values) - value
|
|
69
|
+
: value;
|
|
70
|
+
if (effective >= item.minValue) positives += 1;
|
|
56
71
|
}
|
|
72
|
+
const score = prorate(positives, answered, questions.length, scoring.missing);
|
|
57
73
|
return {
|
|
58
74
|
kind: "scale",
|
|
59
75
|
score,
|
|
@@ -66,15 +82,12 @@ export function evaluate(
|
|
|
66
82
|
case "subscales": {
|
|
67
83
|
const scales: MultiScaleResult["scales"] = scoring.subscales.map((subscale) => {
|
|
68
84
|
const questions = subscale.questionIds.map((id) => requireQuestion(definition, id));
|
|
69
|
-
const
|
|
70
|
-
const { score, min, max } = sumQuestions(definition, questions, answers, multiplier);
|
|
85
|
+
const scored = scoreQuestionSet(definition, questions, answers, subscale.multiplier ?? 1, scoring.missing, subscale.id);
|
|
71
86
|
return {
|
|
72
87
|
id: subscale.id,
|
|
73
88
|
label: subscale.label,
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
max,
|
|
77
|
-
...bandOf(score, subscale.bands),
|
|
89
|
+
...scored,
|
|
90
|
+
...bandOf(scored.score, subscale.bands),
|
|
78
91
|
};
|
|
79
92
|
});
|
|
80
93
|
return {
|
|
@@ -117,25 +130,36 @@ function evaluateSum(
|
|
|
117
130
|
answers: AnswerMap,
|
|
118
131
|
scoring: SumScoring,
|
|
119
132
|
): ScaleResult {
|
|
120
|
-
const
|
|
121
|
-
|
|
133
|
+
const result = scoreQuestionSet(
|
|
134
|
+
definition,
|
|
135
|
+
definition.questions,
|
|
136
|
+
answers,
|
|
137
|
+
scoring.multiplier ?? 1,
|
|
138
|
+
scoring.missing,
|
|
139
|
+
);
|
|
122
140
|
return {
|
|
123
141
|
kind: "scale",
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
max,
|
|
127
|
-
...bandOf(score, scoring.bands),
|
|
142
|
+
...result,
|
|
143
|
+
...bandOf(result.score, scoring.bands),
|
|
128
144
|
flags: triggeredFlags(answers, scoring.flags),
|
|
129
145
|
};
|
|
130
146
|
}
|
|
131
147
|
|
|
132
|
-
|
|
148
|
+
/**
|
|
149
|
+
* Sums one set of questions (the whole assessment or one subscale),
|
|
150
|
+
* applying reverse scoring, the missing-data policy, and the multiplier.
|
|
151
|
+
*/
|
|
152
|
+
function scoreQuestionSet(
|
|
133
153
|
definition: AssessmentDefinition,
|
|
134
154
|
questions: readonly AssessmentQuestion[],
|
|
135
155
|
answers: AnswerMap,
|
|
136
156
|
multiplier: number,
|
|
157
|
+
missing: MissingDataPolicy | undefined,
|
|
158
|
+
scaleId?: string,
|
|
137
159
|
): { score: number; min: number; max: number } {
|
|
138
|
-
|
|
160
|
+
const answered = enforceMissing(questions, answers, missing, scaleId);
|
|
161
|
+
|
|
162
|
+
let raw = 0;
|
|
139
163
|
let min = 0;
|
|
140
164
|
let max = 0;
|
|
141
165
|
for (const question of questions) {
|
|
@@ -145,11 +169,60 @@ function sumQuestions(
|
|
|
145
169
|
min += lowest;
|
|
146
170
|
max += highest;
|
|
147
171
|
|
|
148
|
-
const
|
|
149
|
-
if (
|
|
150
|
-
|
|
172
|
+
const value = answers[question.id];
|
|
173
|
+
if (value === undefined) continue;
|
|
174
|
+
raw += question.reverseScored ? highest + lowest - value : value;
|
|
151
175
|
}
|
|
152
|
-
|
|
176
|
+
raw = prorate(raw, answered, questions.length, missing);
|
|
177
|
+
return { score: raw * multiplier, min: min * multiplier, max: max * multiplier };
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* Enforces the missing-data policy over one set of contributing questions
|
|
182
|
+
* and returns how many of them are answered.
|
|
183
|
+
*
|
|
184
|
+
* `require-complete` only demands questions that are not marked `optional`.
|
|
185
|
+
*/
|
|
186
|
+
function enforceMissing(
|
|
187
|
+
questions: readonly AssessmentQuestion[],
|
|
188
|
+
answers: AnswerMap,
|
|
189
|
+
missing: MissingDataPolicy | undefined,
|
|
190
|
+
scaleId?: string,
|
|
191
|
+
): number {
|
|
192
|
+
const strategy = missing?.strategy ?? "ignore";
|
|
193
|
+
const minAnswered = missing?.minAnswered ?? (strategy === "prorate" ? 1 : 0);
|
|
194
|
+
const scope = scaleId ? ` in subscale "${scaleId}"` : "";
|
|
195
|
+
|
|
196
|
+
const answered = questions.filter((q) => answers[q.id] !== undefined).length;
|
|
197
|
+
if (strategy === "require-complete") {
|
|
198
|
+
const unanswered = questions
|
|
199
|
+
.filter((q) => !(q.optional ?? false) && answers[q.id] === undefined)
|
|
200
|
+
.map((q) => q.id);
|
|
201
|
+
if (unanswered.length > 0) {
|
|
202
|
+
throw new PsytoolsError(
|
|
203
|
+
"incomplete_response",
|
|
204
|
+
`Scoring requires complete answers${scope}; unanswered: ${unanswered.join(", ")}`,
|
|
205
|
+
);
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
if (answered < minAnswered) {
|
|
209
|
+
throw new PsytoolsError(
|
|
210
|
+
"incomplete_response",
|
|
211
|
+
`Scoring requires at least ${minAnswered} answered item(s)${scope}, got ${answered}`,
|
|
212
|
+
);
|
|
213
|
+
}
|
|
214
|
+
return answered;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** Scales a partial raw score up to the full item count (rounded). */
|
|
218
|
+
function prorate(
|
|
219
|
+
raw: number,
|
|
220
|
+
answered: number,
|
|
221
|
+
total: number,
|
|
222
|
+
missing: MissingDataPolicy | undefined,
|
|
223
|
+
): number {
|
|
224
|
+
if (missing?.strategy !== "prorate" || answered === 0 || answered === total) return raw;
|
|
225
|
+
return Math.round((raw * total) / answered);
|
|
153
226
|
}
|
|
154
227
|
|
|
155
228
|
function bandOf(score: number, bands?: ScoreBand[]): { band?: BandResult } {
|
package/src/i18n.ts
CHANGED
|
@@ -6,7 +6,7 @@ import type { LocalizedText } from "./types.ts";
|
|
|
6
6
|
* Resolution order: exact locale -> base language of the locale
|
|
7
7
|
* (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
|
|
8
8
|
*/
|
|
9
|
-
export function
|
|
9
|
+
export function localizeText(
|
|
10
10
|
text: LocalizedText,
|
|
11
11
|
locale: string,
|
|
12
12
|
fallbackLocale?: string,
|
package/src/index.ts
CHANGED
|
@@ -10,7 +10,10 @@ export type {
|
|
|
10
10
|
SubscaleScoring,
|
|
11
11
|
CountScoringItem,
|
|
12
12
|
CountScoring,
|
|
13
|
+
MissingDataPolicy,
|
|
14
|
+
MissingDataStrategy,
|
|
13
15
|
ScoringDefinition,
|
|
16
|
+
ValidationIssueCode,
|
|
14
17
|
AnswerMap,
|
|
15
18
|
ResponseStatus,
|
|
16
19
|
ResponseData,
|
|
@@ -29,10 +32,12 @@ export type {
|
|
|
29
32
|
} from "./types.ts";
|
|
30
33
|
|
|
31
34
|
export { PsytoolsError } from "./errors.ts";
|
|
32
|
-
export {
|
|
35
|
+
export type { PsytoolsErrorCode } from "./errors.ts";
|
|
36
|
+
export { localizeText, collectLocales } from "./i18n.ts";
|
|
33
37
|
export { Assessment, validateDefinition } from "./assessment.ts";
|
|
34
38
|
export { AssessmentResponse } from "./response.ts";
|
|
35
39
|
export { evaluate } from "./evaluation.ts";
|
|
40
|
+
export type { EvaluateOptions } from "./evaluation.ts";
|
|
36
41
|
export {
|
|
37
42
|
phq9,
|
|
38
43
|
gad7,
|
package/src/inventories/aq10.ts
CHANGED
|
@@ -17,34 +17,40 @@ export const aq10: AssessmentDefinition = {
|
|
|
17
17
|
en: "Autism Spectrum Quotient (AQ-10) — Adult",
|
|
18
18
|
tr: "Otizm Spektrum Anketi (AQ-10) — Yetişkin",
|
|
19
19
|
de: "Autismus-Spektrum-Quotient (AQ-10) — Erwachsene",
|
|
20
|
+
zh: "自闭症谱系商数问卷(AQ-10)— 成人版",
|
|
21
|
+
es: "Cociente del Espectro Autista (AQ-10) — Adultos",
|
|
20
22
|
},
|
|
21
23
|
description: {
|
|
22
24
|
en: "A 10-item screening questionnaire for autistic traits in adults, condensed from the 50-item Autism Spectrum Quotient.",
|
|
23
25
|
tr: "50 maddelik Otizm Spektrum Anketi'nden kısaltılmış, yetişkinlerde otistik özellikleri taramak için 10 maddelik bir ölçek.",
|
|
24
26
|
de: "Ein 10-Item-Screeningfragebogen für autistische Merkmale bei Erwachsenen, verkürzt aus dem 50-Item-Autismus-Spektrum-Quotienten.",
|
|
27
|
+
zh: "一份用于筛查成人自闭症特质的10条目问卷,由50条目的自闭症谱系商数量表精简而成。",
|
|
28
|
+
es: "Un cuestionario de cribado de 10 ítems para rasgos autistas en adultos, condensado a partir del Cociente del Espectro Autista de 50 ítems.",
|
|
25
29
|
},
|
|
26
30
|
instructions: {
|
|
27
31
|
en: "For each statement, select the answer that best describes you.",
|
|
28
32
|
tr: "Her ifade için sizi en iyi tanımlayan yanıtı işaretleyin.",
|
|
29
33
|
de: "Wählen Sie zu jeder Aussage die Antwort, die Sie am besten beschreibt.",
|
|
34
|
+
zh: "请针对每条陈述,选择最符合您情况的答案。",
|
|
35
|
+
es: "Para cada afirmación, seleccione la respuesta que mejor lo describa.",
|
|
30
36
|
},
|
|
31
37
|
defaultLocale: "en",
|
|
32
38
|
options: [
|
|
33
39
|
{
|
|
34
40
|
value: 0,
|
|
35
|
-
label: { en: "Definitely disagree", tr: "Kesinlikle katılmıyorum", de: "Stimme überhaupt nicht zu" },
|
|
41
|
+
label: { en: "Definitely disagree", tr: "Kesinlikle katılmıyorum", de: "Stimme überhaupt nicht zu", zh: "完全不同意", es: "Totalmente en desacuerdo" },
|
|
36
42
|
},
|
|
37
43
|
{
|
|
38
44
|
value: 1,
|
|
39
|
-
label: { en: "Slightly disagree", tr: "Biraz katılmıyorum", de: "Stimme eher nicht zu" },
|
|
45
|
+
label: { en: "Slightly disagree", tr: "Biraz katılmıyorum", de: "Stimme eher nicht zu", zh: "有点不同意", es: "Ligeramente en desacuerdo" },
|
|
40
46
|
},
|
|
41
47
|
{
|
|
42
48
|
value: 2,
|
|
43
|
-
label: { en: "Slightly agree", tr: "Biraz katılıyorum", de: "Stimme eher zu" },
|
|
49
|
+
label: { en: "Slightly agree", tr: "Biraz katılıyorum", de: "Stimme eher zu", zh: "有点同意", es: "Ligeramente de acuerdo" },
|
|
44
50
|
},
|
|
45
51
|
{
|
|
46
52
|
value: 3,
|
|
47
|
-
label: { en: "Definitely agree", tr: "Kesinlikle katılıyorum", de: "Stimme voll und ganz zu" },
|
|
53
|
+
label: { en: "Definitely agree", tr: "Kesinlikle katılıyorum", de: "Stimme voll und ganz zu", zh: "完全同意", es: "Totalmente de acuerdo" },
|
|
48
54
|
},
|
|
49
55
|
],
|
|
50
56
|
questions: [
|
|
@@ -54,6 +60,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
54
60
|
en: "I often notice small sounds when others do not",
|
|
55
61
|
tr: "Başkalarının fark etmediği küçük sesleri sıklıkla fark ederim",
|
|
56
62
|
de: "Ich nehme oft leise Geräusche wahr, die andere nicht bemerken",
|
|
63
|
+
zh: "我经常注意到别人注意不到的微小声音",
|
|
64
|
+
es: "A menudo noto pequeños sonidos que otras personas no perciben",
|
|
57
65
|
},
|
|
58
66
|
},
|
|
59
67
|
{
|
|
@@ -62,6 +70,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
62
70
|
en: "I usually concentrate more on the whole picture, rather than the small details",
|
|
63
71
|
tr: "Genellikle küçük ayrıntılardan çok resmin bütününe odaklanırım",
|
|
64
72
|
de: "Ich konzentriere mich meist mehr auf das Gesamtbild als auf die kleinen Details",
|
|
73
|
+
zh: "我通常更关注事情的整体,而不是小细节",
|
|
74
|
+
es: "Normalmente me concentro más en la imagen global que en los pequeños detalles",
|
|
65
75
|
},
|
|
66
76
|
reverseScored: true,
|
|
67
77
|
},
|
|
@@ -71,6 +81,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
71
81
|
en: "I find it easy to do more than one thing at once",
|
|
72
82
|
tr: "Aynı anda birden fazla iş yapmak benim için kolaydır",
|
|
73
83
|
de: "Es fällt mir leicht, mehrere Dinge gleichzeitig zu tun",
|
|
84
|
+
zh: "我觉得同时做几件事情很容易",
|
|
85
|
+
es: "Me resulta fácil hacer más de una cosa a la vez",
|
|
74
86
|
},
|
|
75
87
|
reverseScored: true,
|
|
76
88
|
},
|
|
@@ -80,6 +92,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
80
92
|
en: "If there is an interruption, I can switch back to what I was doing very quickly",
|
|
81
93
|
tr: "Bir kesinti olursa, yapmakta olduğum işe çok hızlı bir şekilde geri dönebilirim",
|
|
82
94
|
de: "Wenn ich unterbrochen werde, kann ich sehr schnell zu meiner Tätigkeit zurückkehren",
|
|
95
|
+
zh: "如果被打断,我能很快回到原来正在做的事情上",
|
|
96
|
+
es: "Si hay una interrupción, puedo volver muy rápidamente a lo que estaba haciendo",
|
|
83
97
|
},
|
|
84
98
|
reverseScored: true,
|
|
85
99
|
},
|
|
@@ -89,6 +103,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
89
103
|
en: "I find it easy to 'read between the lines' when someone is talking to me",
|
|
90
104
|
tr: "Biri benimle konuşurken 'satır aralarını okumak' benim için kolaydır",
|
|
91
105
|
de: "Es fällt mir leicht, 'zwischen den Zeilen zu lesen', wenn jemand mit mir spricht",
|
|
106
|
+
zh: "当别人和我说话时,我觉得'听出言外之意'很容易",
|
|
107
|
+
es: "Me resulta fácil 'leer entre líneas' cuando alguien me está hablando",
|
|
92
108
|
},
|
|
93
109
|
reverseScored: true,
|
|
94
110
|
},
|
|
@@ -98,6 +114,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
98
114
|
en: "I know how to tell if someone listening to me is getting bored",
|
|
99
115
|
tr: "Beni dinleyen birinin sıkılmaya başladığını nasıl anlayacağımı bilirim",
|
|
100
116
|
de: "Ich erkenne, ob jemand, der mir zuhört, sich zu langweilen beginnt",
|
|
117
|
+
zh: "我知道如何判断听我说话的人是否开始感到厌烦",
|
|
118
|
+
es: "Sé darme cuenta de si la persona que me escucha se está aburriendo",
|
|
101
119
|
},
|
|
102
120
|
reverseScored: true,
|
|
103
121
|
},
|
|
@@ -107,6 +125,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
107
125
|
en: "When I'm reading a story I find it difficult to work out the characters' intentions",
|
|
108
126
|
tr: "Bir öykü okurken karakterlerin niyetlerini anlamakta zorlanırım",
|
|
109
127
|
de: "Wenn ich eine Geschichte lese, fällt es mir schwer, die Absichten der Figuren zu erkennen",
|
|
128
|
+
zh: "读故事时,我很难弄清人物的意图",
|
|
129
|
+
es: "Cuando leo una historia, me resulta difícil deducir las intenciones de los personajes",
|
|
110
130
|
},
|
|
111
131
|
},
|
|
112
132
|
{
|
|
@@ -115,6 +135,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
115
135
|
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)",
|
|
116
136
|
tr: "Belirli kategorilerdeki şeyler hakkında bilgi toplamayı severim (örneğin araba türleri, kuş türleri, tren türleri, bitki türleri vb.)",
|
|
117
137
|
de: "Ich sammle gern Informationen über Kategorien von Dingen (z. B. Auto-, Vogel-, Zug- oder Pflanzenarten)",
|
|
138
|
+
zh: "我喜欢收集各类事物的信息(例如汽车的类型、鸟的种类、火车的类型、植物的种类等)",
|
|
139
|
+
es: "Me gusta recopilar información sobre categorías de cosas (p. ej., tipos de coches, de aves, de trenes, de plantas, etc.)",
|
|
118
140
|
},
|
|
119
141
|
},
|
|
120
142
|
{
|
|
@@ -123,6 +145,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
123
145
|
en: "I find it easy to work out what someone is thinking or feeling just by looking at their face",
|
|
124
146
|
tr: "Sadece yüzüne bakarak birinin ne düşündüğünü ya da hissettiğini anlamak benim için kolaydır",
|
|
125
147
|
de: "Es fällt mir leicht, allein am Gesicht abzulesen, was jemand denkt oder fühlt",
|
|
148
|
+
zh: "我觉得只看别人的脸就能轻松看出对方在想什么或有什么感受",
|
|
149
|
+
es: "Me resulta fácil deducir lo que alguien piensa o siente con solo mirarle la cara",
|
|
126
150
|
},
|
|
127
151
|
reverseScored: true,
|
|
128
152
|
},
|
|
@@ -132,6 +156,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
132
156
|
en: "I find it difficult to work out people's intentions",
|
|
133
157
|
tr: "İnsanların niyetlerini anlamakta zorlanırım",
|
|
134
158
|
de: "Es fällt mir schwer, die Absichten anderer Menschen zu erkennen",
|
|
159
|
+
zh: "我很难弄清别人的意图",
|
|
160
|
+
es: "Me resulta difícil deducir las intenciones de las personas",
|
|
135
161
|
},
|
|
136
162
|
},
|
|
137
163
|
],
|
|
@@ -158,6 +184,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
158
184
|
en: "Below screening threshold",
|
|
159
185
|
tr: "Tarama eşiğinin altında",
|
|
160
186
|
de: "Unterhalb der Screening-Schwelle",
|
|
187
|
+
zh: "低于筛查阈值",
|
|
188
|
+
es: "Por debajo del umbral de cribado",
|
|
161
189
|
},
|
|
162
190
|
},
|
|
163
191
|
{
|
|
@@ -168,6 +196,8 @@ export const aq10: AssessmentDefinition = {
|
|
|
168
196
|
en: "At or above threshold — consider referral for a specialist autism assessment",
|
|
169
197
|
tr: "Eşikte ya da üzerinde — uzman otizm değerlendirmesine yönlendirme düşünülmelidir",
|
|
170
198
|
de: "An oder über der Schwelle — Überweisung zu einer spezialisierten Autismus-Diagnostik erwägen",
|
|
199
|
+
zh: "达到或超过阈值——建议考虑转介进行自闭症专科评估",
|
|
200
|
+
es: "En el umbral o por encima — considere la derivación para una evaluación especializada de autismo",
|
|
171
201
|
},
|
|
172
202
|
},
|
|
173
203
|
],
|
|
@@ -179,7 +209,7 @@ export const aq10: AssessmentDefinition = {
|
|
|
179
209
|
"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.",
|
|
180
210
|
licenseFlag: "free-with-conditions",
|
|
181
211
|
translationProvenance:
|
|
182
|
-
"en: reproduced from the original. tr
|
|
212
|
+
"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.",
|
|
183
213
|
note: "Each item scores 1 point in the trait direction; disagree-scored items are modeled as reverseScored.",
|
|
184
214
|
},
|
|
185
215
|
};
|