psytools 0.5.0 → 0.5.1

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 CHANGED
@@ -183,6 +183,8 @@ scoring: {
183
183
 
184
184
  `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.
185
185
 
186
+ The bundled inventories ship with policies (PHQ-9/GAD-7/DASS-21/Mini-IPIP prorate with thresholds, WHO-5/ASRS/AQ-10 require-complete, AUDIT ignores to match its skip logic) — see [SOURCES.md](SOURCES.md#missing-data-policies) for the rationale and how to override.
187
+
186
188
  ## Custom evaluation
187
189
 
188
190
  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:
package/SOURCES.md CHANGED
@@ -28,6 +28,19 @@ Official validated translations exist for most of these instruments, but they we
28
28
 
29
29
  Non-English texts live as one file per inventory per language under [`src/locales/<locale>/`](src/locales) — exactly the unit a native-speaker reviewer needs. Verification contributions are very welcome.
30
30
 
31
+ ## Missing-data policies
32
+
33
+ Bundled inventories ship with declarative missing-data policies (`scoring.missing`). **The prorating thresholds are implementation choices reflecting common research practice — they are not part of the instruments' official scoring rules.** Override by cloning the definition if your protocol differs.
34
+
35
+ | Inventory | Policy | Rationale |
36
+ | --- | --- | --- |
37
+ | `phq9` | prorate, ≥7 of 9 answered | Common research practice (≈75% completion) |
38
+ | `gad7` | prorate, ≥6 of 7 answered | Common research practice |
39
+ | `dass21` | prorate, ≥6 of 7 per subscale | DASS manual tolerates occasional missing items |
40
+ | `mini-ipip` | prorate, ≥3 of 4 per trait | IPIP scoring is mean-based; prorating is equivalent |
41
+ | `who5`, `asrs6`, `aq10` | require-complete | Short instruments; cutoffs/counts are undefined for partial data |
42
+ | `audit` | ignore | Unanswered items score 0, matching the instrument's skip logic (e.g. non-drinkers skipping items 2–8) |
43
+
31
44
  ## PHQ-9 — Patient Health Questionnaire-9 (`phq9`)
32
45
 
33
46
  **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>.
@@ -112,6 +112,7 @@ exports.aq10 = {
112
112
  ],
113
113
  scoring: {
114
114
  kind: "count",
115
+ missing: { strategy: "require-complete" },
115
116
  items: [
116
117
  { questionId: "aq10-1", minValue: 2 },
117
118
  { questionId: "aq10-2", minValue: 2 },
@@ -70,6 +70,7 @@ exports.asrs6 = {
70
70
  ],
71
71
  scoring: {
72
72
  kind: "count",
73
+ missing: { strategy: "require-complete" },
73
74
  items: [
74
75
  { questionId: "asrs6-1", minValue: 2 },
75
76
  { questionId: "asrs6-2", minValue: 2 },
@@ -169,6 +169,7 @@ exports.audit = {
169
169
  ],
170
170
  scoring: {
171
171
  kind: "sum",
172
+ missing: { strategy: "ignore" },
172
173
  bands: [
173
174
  {
174
175
  id: "zone-1",
@@ -200,6 +200,7 @@ exports.dass21 = {
200
200
  ],
201
201
  scoring: {
202
202
  kind: "subscales",
203
+ missing: { strategy: "prorate", minAnswered: 6 },
203
204
  subscales: [
204
205
  {
205
206
  id: "depression",
@@ -68,6 +68,7 @@ exports.gad7 = {
68
68
  ],
69
69
  scoring: {
70
70
  kind: "sum",
71
+ missing: { strategy: "prorate", minAnswered: 6 },
71
72
  bands: [
72
73
  {
73
74
  id: "minimal",
@@ -190,6 +190,7 @@ exports.miniIpip = {
190
190
  ],
191
191
  scoring: {
192
192
  kind: "subscales",
193
+ missing: { strategy: "prorate", minAnswered: 3 },
193
194
  subscales: [
194
195
  {
195
196
  id: "extraversion",
@@ -81,6 +81,7 @@ exports.phq9 = {
81
81
  ],
82
82
  scoring: {
83
83
  kind: "sum",
84
+ missing: { strategy: "prorate", minAnswered: 7 },
84
85
  bands: [
85
86
  {
86
87
  id: "minimal",
@@ -87,6 +87,7 @@ exports.who5 = {
87
87
  ],
88
88
  scoring: {
89
89
  kind: "sum",
90
+ missing: { strategy: "require-complete" },
90
91
  multiplier: 4,
91
92
  bands: [
92
93
  {
@@ -109,6 +109,7 @@ export const aq10 = {
109
109
  ],
110
110
  scoring: {
111
111
  kind: "count",
112
+ missing: { strategy: "require-complete" },
112
113
  items: [
113
114
  { questionId: "aq10-1", minValue: 2 },
114
115
  { questionId: "aq10-2", minValue: 2 },
@@ -67,6 +67,7 @@ export const asrs6 = {
67
67
  ],
68
68
  scoring: {
69
69
  kind: "count",
70
+ missing: { strategy: "require-complete" },
70
71
  items: [
71
72
  { questionId: "asrs6-1", minValue: 2 },
72
73
  { questionId: "asrs6-2", minValue: 2 },
@@ -166,6 +166,7 @@ export const audit = {
166
166
  ],
167
167
  scoring: {
168
168
  kind: "sum",
169
+ missing: { strategy: "ignore" },
169
170
  bands: [
170
171
  {
171
172
  id: "zone-1",
@@ -197,6 +197,7 @@ export const dass21 = {
197
197
  ],
198
198
  scoring: {
199
199
  kind: "subscales",
200
+ missing: { strategy: "prorate", minAnswered: 6 },
200
201
  subscales: [
201
202
  {
202
203
  id: "depression",
@@ -65,6 +65,7 @@ export const gad7 = {
65
65
  ],
66
66
  scoring: {
67
67
  kind: "sum",
68
+ missing: { strategy: "prorate", minAnswered: 6 },
68
69
  bands: [
69
70
  {
70
71
  id: "minimal",
@@ -187,6 +187,7 @@ export const miniIpip = {
187
187
  ],
188
188
  scoring: {
189
189
  kind: "subscales",
190
+ missing: { strategy: "prorate", minAnswered: 3 },
190
191
  subscales: [
191
192
  {
192
193
  id: "extraversion",
@@ -78,6 +78,7 @@ export const phq9 = {
78
78
  ],
79
79
  scoring: {
80
80
  kind: "sum",
81
+ missing: { strategy: "prorate", minAnswered: 7 },
81
82
  bands: [
82
83
  {
83
84
  id: "minimal",
@@ -84,6 +84,7 @@ export const who5 = {
84
84
  ],
85
85
  scoring: {
86
86
  kind: "sum",
87
+ missing: { strategy: "require-complete" },
87
88
  multiplier: 4,
88
89
  bands: [
89
90
  {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "psytools",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
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",
@@ -111,6 +111,7 @@ export const aq10: AssessmentDefinition = {
111
111
  ],
112
112
  scoring: {
113
113
  kind: "count",
114
+ missing: { strategy: "require-complete" },
114
115
  items: [
115
116
  { questionId: "aq10-1", minValue: 2 },
116
117
  { questionId: "aq10-2", minValue: 2 },
@@ -69,6 +69,7 @@ export const asrs6: AssessmentDefinition = {
69
69
  ],
70
70
  scoring: {
71
71
  kind: "count",
72
+ missing: { strategy: "require-complete" },
72
73
  items: [
73
74
  { questionId: "asrs6-1", minValue: 2 },
74
75
  { questionId: "asrs6-2", minValue: 2 },
@@ -170,6 +170,7 @@ export const audit: AssessmentDefinition = {
170
170
  ],
171
171
  scoring: {
172
172
  kind: "sum",
173
+ missing: { strategy: "ignore" },
173
174
  bands: [
174
175
  {
175
176
  id: "zone-1",
@@ -202,6 +202,7 @@ export const dass21: AssessmentDefinition = {
202
202
  ],
203
203
  scoring: {
204
204
  kind: "subscales",
205
+ missing: { strategy: "prorate", minAnswered: 6 },
205
206
  subscales: [
206
207
  {
207
208
  id: "depression",
@@ -67,6 +67,7 @@ export const gad7: AssessmentDefinition = {
67
67
  ],
68
68
  scoring: {
69
69
  kind: "sum",
70
+ missing: { strategy: "prorate", minAnswered: 6 },
70
71
  bands: [
71
72
  {
72
73
  id: "minimal",
@@ -189,6 +189,7 @@ export const miniIpip: AssessmentDefinition = {
189
189
  ],
190
190
  scoring: {
191
191
  kind: "subscales",
192
+ missing: { strategy: "prorate", minAnswered: 3 },
192
193
  subscales: [
193
194
  {
194
195
  id: "extraversion",
@@ -80,6 +80,7 @@ export const phq9: AssessmentDefinition = {
80
80
  ],
81
81
  scoring: {
82
82
  kind: "sum",
83
+ missing: { strategy: "prorate", minAnswered: 7 },
83
84
  bands: [
84
85
  {
85
86
  id: "minimal",
@@ -86,6 +86,7 @@ export const who5: AssessmentDefinition = {
86
86
  ],
87
87
  scoring: {
88
88
  kind: "sum",
89
+ missing: { strategy: "require-complete" },
89
90
  multiplier: 4,
90
91
  bands: [
91
92
  {