compileprofile-spacetests 0.2.1 → 0.4.0

package/CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a TypeScript package that evaluates cognitive test results from "Vzhuru do vesmiru" (To Space) cognitive testing platform. The package analyzes performance data from four different cognitive tests: N-back memory tests, spatial cognition tests, Go/No-Go response inhibition tests, and emotion recognition tests.
+
+## Build Commands
+
+- `npm run build` - Build both CommonJS and ESM distributions
+- `npm run build:csj` - Build CommonJS distribution only
+- `npm run build:esm` - Build ESM distribution only
+- `npm test` - Run all tests using Jest
+- `npm run prepare` - Automatically builds before publishing
+
+## Testing
+
+- Jest is configured with TypeScript support
+- Test files should follow patterns: `**/__tests__/**/*.ts` or `**/?(*.)+(spec|test).ts`
+- Tests are located in `src/__tests__/integration/`
+- Test utilities and shared data are in `src/__tests__/test-utils/`
+- Run single test: `npm test -- --testNamePattern="test_name"`
+- Run tests for specific file: `npm test -- emotions.test.ts`
+
+## Architecture
+
+### Core Structure
+
+The package exports four main calculation functions from `src/index.ts`:
+- `NbackResults(data)` - Analyzes N-back memory test performance
+- `SpatialCognitionResults(data)` - Evaluates spatial cognition test results
+- `GonogoResults(data)` - Processes Go/No-Go inhibition test data
+- `EmotionResults(data)` - Analyzes emotion recognition test performance
+
+### Data Processing Pipeline
+
+Each cognitive test follows a consistent three-step processing pattern:
+
+1. **Extract Trials**: Filter raw test data to identify relevant trial records
+   - `nback_extract_trials()` - Filters for records with `is_target` field
+   - `spatial_extract_trials()` - Filters for records with image stimulus data
+   - `gonogo_extract_trials()` - Filters for records with image responses
+   - `emotion_extract_trials()` - Filters for records with emotion response data
+
+2. **Calculate Results**: Compute accuracy, reaction time, and derived metrics
+   - All tests calculate: trial count (`n`), average accuracy (`avg_acc`), average reaction time (`avg_rt`)
+   - Each test has specific performance scoring algorithms
+
+   - the results should have a uniform structure
+   - common - should be common structure for all tests
+      - n_trials (number of trials)
+      - n_correct_trials (number of correct trials)
+      - n_incorrect_trials (number of incorrect trials)
+      - n_missing_trials (number of missing trials)
+      - avg_rt_total (in ms)
+      - avg_rt_correct (in ms)
+      - avg_rt_incorrect (in ms)
+      - avg_rt_missing (in ms)
+      - performance_score - score calculated as per test instruction - differs for each test slightly
+ - special - special results inherent for the test itself
+
+3. **Performance Scoring**: Convert raw metrics to normalized 0-100 performance scores
+   - Go/No-Go: Uses RT/(accuracy^5) with 300-5000ms bounds; RT = mean RT of hits, accuracy = balanced (hit rate and correct-rejection rate weighted equally), 0 when there is no hit
+   - Emotions: Uses RT/(accuracy^5) with 1000-10000ms bounds
+   - Spatial: Uses RT/accuracy with 1000-10000ms bounds
+   - N-back: Uses raw accuracy as performance score
+
+### Key Implementation Details
+
+**N-back Test** (`src/nback.ts`):
+- Processes target vs non-target trials separately
+- Returns comprehensive breakdown of both trial types
+- Performance score is simply average accuracy
+
+**Spatial Cognition Test** (`src/spatial-cognition.ts`):
+- Extracts map direction (left/right), distance, angle, and rotation from image URLs
+- Compares user response direction against correct answer
+- Uses simpler RT/accuracy performance formula
+
+**Go/No-Go Test** (`src/gonogo.ts`):
+- Determines correct response based on block number and stimulus type
+- Block 1: respond to astronaut, Block 2: respond to alien, Block 3: respond to rocket, Block 4: respond to non-rocket
+- Extracts stimulus type from image URL patterns
+
+**Emotion Recognition Test** (`src/emotions.ts`):
+- Maps numeric responses (0-4) to emotion labels: neutral, sad, happy, surprised, angry
+- Extracts emotion type and image number from file paths
+- Compares recognized emotion against correct emotion
+
+### Data Formats
+
+All tests expect arrays of trial objects with specific fields:
+- N-back: `is_target`, `rt`, `correct`
+- Spatial: `stimulus` (HTML img tag), `response`, `rt`
+- Go/No-Go: `image` (URL), `response`, `rt`, `block_number`
+- Emotions: `emotion` (URL), `response`, `rt`
+
+## Utilities
+
+**Browser Information** (`src/getters.ts`):
+- `getBrowserInformation(data)` extracts browser/system info from test data
+- Returns OS, browser version, screen dimensions, hardware capabilities
+
+**Normative Data** (`src/norms/`):
+- JSON files contain normative performance data for each test type
+- Used for percentile calculations and age/gender adjustments
+
+## Development Notes
+
+- Package supports both CommonJS and ESM exports
+- TypeScript configurations: `tsconfig.cjs.json` and `tsconfig.esm.json`
+- All calculation functions include comprehensive TypeScript interfaces
+- Console logging is used in some functions for debugging
+- Error handling throws descriptive errors for empty trial datasets

package/README.md

@@ -1,6 +1,6 @@
 # compileprofile-spacetests
 
-A package for evaluating cognitive test results, specifically designed for memory tests.
+A package for evaluating cognitive test results from "Vzhuru do vesmiru" (To Space) cognitive testing platform. This package analyzes performance data from four different cognitive tests: N-back memory tests, spatial cognition tests, Go/No-Go response inhibition tests, and emotion recognition tests.
 
 ## Installation
 
@@ -11,25 +11,162 @@ npm install compileprofile-spacetests
 ## Usage
 
 ```typescript
-import { evaluateMemoryTest, MemoryTestData, SubjectParameters } from 'compileprofile-spacetests';
-// Evaluate the test results
-const results = evaluateMemoryTest(testData, subjectParams);
-console.log(results);
+import {
+  NbackResults,
+  SpatialCognitionResults,
+  GonogoResults,
+  EmotionResults
+} from 'compileprofile-spacetests';
+
+// Analyze N-back memory test
+const nbackResults = NbackResults(nbackData);
+
+// Analyze spatial cognition test
+const spatialResults = SpatialCognitionResults(spatialData);
+
+// Analyze Go/No-Go test
+const gonogoResults = GonogoResults(gonogoData);
+
+// Analyze emotion recognition test
+const emotionResults = EmotionResults(emotionData);
 ```
 
+## Test Results
 
-## Development
+All cognitive tests return results in two parts: **common metrics** (same for all tests) and **special metrics** (specific to each test type).
+
+### Common Metrics (All Tests)
+
+Every test provides these basic performance measures:
+
+- **n_trials** - Total number of test trials completed
+- **n_correct_trials** - How many responses were correct
+- **n_incorrect_trials** - How many responses were wrong
+- **avg_rt_total** - Average reaction time across all trials (milliseconds)
+- **avg_rt_correct** - Average reaction time for correct answers only
+- **avg_rt_incorrect** - Average reaction time for wrong answers only
+- **performance_score** - Overall performance score (0-100, higher is better)
+
+### Special Metrics by Test Type
+
+#### N-back Memory Test
+
+Analyzes working memory by comparing performance on different trial types:
+
+- **target_trials** - Performance when participant should respond (saw matching stimulus)
+  - Number of target trials, average reaction time, accuracy rate
+- **non_target_trials** - Performance when participant should not respond
+  - Number of non-target trials, average reaction time, accuracy rate
+
+Version 2 data (trials carry `n_back`, `block` and `block_index`) also gets:
+
+- **by_block** - Results for each block, in block order, with its `block`, `block_index` and `n_back`
+- **by_nback** - Results for each N level, pooling all blocks with that N, sorted by N
+
+Each entry of both has `n_trials`, `n_correct_trials`, `performance_score`, `n_targets`,
+`n_non_targets`, `hits`, `misses`, `false_alarms`, `correct_rejections`, `hit_rate`,
+`false_alarm_rate`, `d_prime`, `n_lures`, `lure_false_alarms`, `lure_false_alarm_rate`,
+`avg_rt_hits` and `avg_rt_false_alarms`. Lures (`is_lure: true`) are non-targets repeating an image
+from a distance other than N; their false alarms also count in `false_alarms` and `d_prime`, and a
+high `lure_false_alarm_rate` means the participant responds to familiarity rather than position. `d_prime` uses the
+log-linear correction (Hautus 1995), so it stays finite at 0 % or 100 % rates; it is `null` for a
+group without targets or without non-targets. Version 1 data has neither field, and its results are
+unchanged from 0.3.0.
+
+About 80 % of trials are non-targets, so not responding at all already gives a high
+`performance_score`. Compare levels by `hit_rate` or `d_prime`.
+
+#### Spatial Cognition Test
+
+Analyzes spatial reasoning by breaking down performance across map characteristics:
+
+- **by_distance** - Performance grouped by how far the destination is (1, 2, 3 units)
+- **by_angle** - Performance grouped by map rotation angle (90°, 180°, 270°)
+- **by_rotation** - Performance grouped by how much the view was rotated
+
+Each group shows number of trials, average reaction time, and accuracy rate.
+
+#### Go/No-Go Response Inhibition Test
+
+Analyzes impulse control by examining when to respond vs. when to inhibit:
+
+- **balanced_acc** - Mean of the go hit rate and the no-go correct-rejection rate
+- **by_block** - Performance in each test phase (blocks 1-4 have different rules)
+  - Average RT of hits, accuracy, hit rate, correct-rejection rate, balanced accuracy
+- **go_trials** - Trials where participant should press the button
+  - Number of trials, average RT of hits, hit rate, number of omissions (misses)
+- **nogo_trials** - Trials where participant should NOT press the button
+  - Number of trials, average RT of false alarms, correct-rejection rate, number of commissions (false alarms)
 
-Basic js distribution
+Reaction times are averaged only over trials with a response; a trial without a click has no RT.
 
-## API
+#### Emotion Recognition Test
 
-Evaluates memory test results and returns a comprehensive analysis including:
-- Overall accuracy
-- Average reaction time
-- Total correct responses
-- Total number of trials
-- Age-adjusted score (for subjects between 18-65)
-- Gender-specific percentile (when gender is specified)
+Analyzes emotion processing by examining recognition patterns:
+
+- **by_emotion** - Performance for each emotion type (neutral, sad, happy, surprised, angry)
+  - For each emotion: number of trials, average reaction time, accuracy rate
+- **confusion_matrix** - Shows which emotions get confused with which others
+  - Rows = actual emotion, columns = what participant guessed
+
+## Performance Scoring
+
+Each test uses a specific algorithm to calculate the performance score (0-100):
+
+- **N-back**: Raw accuracy percentage
+- **Spatial Cognition**: RT/(accuracy) formula with 1000-10000ms bounds
+- **Go/No-Go**: RT/(accuracy^5) formula with 300-5000ms bounds, where RT is the mean RT of hits and accuracy is the balanced accuracy; 0 when there is no hit
+- **Emotions**: RT/(accuracy^5) formula with 1000-10000ms bounds
+
+## Input Data Format
+
+Each test expects an array of trial objects with specific fields:
+
+### N-back Test Data
+
+Each trial object should have:
+- **is_target** - `true` if participant should respond, `false` if they shouldn't
+- **rt** - Reaction time in milliseconds
+- **correct** - `true` if response was correct, `false` if wrong
+- **response** - What the participant pressed (0 or 1, or null if no response)
+- **n_back**, **block**, **block_index** - Version 2 only: N, block name and block position
+- **is_lure** - Version 2 only: `true` for a non-target repeating an image from a distance other than N
+
+### Spatial Cognition Test Data
+
+Each trial object should have:
+- **stimulus** - HTML image tag containing the map image
+- **rt** - Reaction time in milliseconds
+- **response** - Direction chosen (0 = left, 1 = right)
+
+### Go/No-Go Test Data
+
+Each trial object should have:
+- **image** - URL to the stimulus image (astronaut, alien, or rocket)
+- **rt** - Reaction time in milliseconds
+- **response** - Button press (any number = pressed, null = no press)
+- **block_number** - Which test phase (1, 2, 3, or 4)
+
+### Emotion Recognition Test Data
+
+Each trial object should have:
+- **emotion** - URL to the emotion face image
+- **rt** - Reaction time in milliseconds
+- **response** - Emotion chosen (0=neutral, 1=sad, 2=happy, 3=surprised, 4=angry)
+
+## Development
+
+Build the package:
+```bash
+npm run build        # Build both CommonJS and ESM
+npm run build:cjs    # Build CommonJS only
+npm run build:esm    # Build ESM only
+```
+
+Run tests:
+```bash
+npm test             # Run all tests
+npm test -- emotions.test.ts  # Run specific test file
+```
 
 ## License

package/dist/cjs/common-interfaces.d.ts

@@ -0,0 +1,92 @@
+interface CommonResults {
+    n_trials: number;
+    n_correct_trials: number;
+    n_incorrect_trials: number;
+    avg_rt_total: number;
+    avg_rt_correct: number;
+    avg_rt_incorrect: number;
+    performance_score: number;
+}
+interface NbackGroupResults {
+    n_trials: number;
+    n_correct_trials: number;
+    performance_score: number;
+    n_targets: number;
+    n_non_targets: number;
+    hits: number;
+    misses: number;
+    false_alarms: number;
+    correct_rejections: number;
+    hit_rate: number | null;
+    false_alarm_rate: number | null;
+    d_prime: number | null;
+    n_lures: number;
+    lure_false_alarms: number;
+    lure_false_alarm_rate: number | null;
+    avg_rt_hits: number | null;
+    avg_rt_false_alarms: number | null;
+}
+interface NbackBlockResults extends NbackGroupResults {
+    block: string;
+    block_index: number;
+    n_back: number;
+}
+interface NbackLevelResults extends NbackGroupResults {
+    n_back: number;
+}
+interface NbackSpecialResults {
+    target_trials: {
+        n: number;
+        avg_rt: number;
+        avg_acc: number;
+    };
+    non_target_trials: {
+        n: number;
+        avg_rt: number;
+        avg_acc: number;
+    };
+    by_block?: NbackBlockResults[];
+    by_nback?: NbackLevelResults[];
+}
+interface SpatialSpecialResults {
+    by_distance: any[];
+    by_angle: any[];
+    by_rotation: any[];
+}
+interface GonogoSpecialResults {
+    balanced_acc: number;
+    by_block: any[];
+    go_trials: {
+        n: number;
+        avg_rt: number;
+        avg_acc: number;
+        n_omissions: number;
+    };
+    nogo_trials: {
+        n: number;
+        avg_rt: number;
+        avg_acc: number;
+        n_commissions: number;
+    };
+}
+interface EmotionSpecialResults {
+    by_emotion: any[];
+    confusion_matrix: any;
+}
+interface NbackResultsStructure {
+    common: CommonResults;
+    special: NbackSpecialResults;
+}
+interface SpatialResultsStructure {
+    common: CommonResults;
+    special: SpatialSpecialResults;
+}
+interface GonogoResultsStructure {
+    common: CommonResults;
+    special: GonogoSpecialResults;
+}
+interface EmotionResultsStructure {
+    common: CommonResults;
+    special: EmotionSpecialResults;
+}
+export { CommonResults, NbackResultsStructure, SpatialResultsStructure, GonogoResultsStructure, EmotionResultsStructure, NbackSpecialResults, NbackGroupResults, NbackBlockResults, NbackLevelResults, SpatialSpecialResults, GonogoSpecialResults, EmotionSpecialResults };

package/dist/cjs/common-interfaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/emotions.d.ts

@@ -1,10 +1,5 @@
-interface EmotionResultsStructure {
-    n: number;
-    avg_rt: number;
-    avg_acc: number;
-    performance: number;
-}
+import { EmotionResultsStructure } from './common-interfaces';
 declare const emotion_calculate_results: (obj: any[]) => EmotionResultsStructure;
-declare const emotion_results: (obj: any[]) => EmotionResultsStructure;
 declare const emotion_extract_trials: (obj: any[]) => any[];
+declare const emotion_results: (obj: any[]) => EmotionResultsStructure;
 export { EmotionResultsStructure, emotion_calculate_results, emotion_extract_trials, emotion_results };

package/dist/cjs/emotions.js

@@ -1,36 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.emotion_results = exports.emotion_extract_trials = exports.emotion_calculate_results = void 0;
+var EMOTION_MAP = ["neutral", "sad", "happy", "surprised", "angry"];
 var emotion_calculate_results = function (obj) {
     var trials = emotion_extract_trials(obj);
-    // throw if trials is empty
     if (trials.length === 0) {
         throw new Error("No trials found");
     }
     return emotion_results(trials);
 };
 exports.emotion_calculate_results = emotion_calculate_results;
-var emotion_results = function (obj) {
-    // throw error if obj is empty
-    if (obj.length === 0) {
-        throw new Error("No trials found");
-    }
-    var results = {
-        n: obj.length,
-        avg_rt: obj.reduce(function (a, b) { return a + b.rt; }, 0) / obj.length,
-        avg_acc: obj.reduce(function (a, b) { return a + b.correct; }, 0) / obj.length,
-        performance: NaN
-    };
-    var best_score = 1000;
-    var worst_score = 10000;
-    var performance = results.avg_rt / (Math.pow(results.avg_acc, 5) + 0.001);
-    performance = Math.min(Math.max(performance, best_score), worst_score);
-    results.performance = (1 - ((performance - best_score) / (worst_score - best_score))) * 100;
-    return results;
-};
-exports.emotion_results = emotion_results;
 var emotion_extract_trials = function (obj) {
-    var emotionMap = ["neutral", "sad", "happy", "surprised", "angry"];
     // filter trials where response and rt are defined and not null
     var trials = obj.filter(function (o) { return 'response' in o && 'rt' in o && 'emotion' in o; });
     trials = trials.filter(function (o) { return o.response !== null && o.rt !== null; });
@@ -45,10 +25,64 @@ var emotion_extract_trials = function (obj) {
         }
     });
     trials.forEach(function (o) {
-        o.emotion_response = emotionMap[o.response] || "unknown";
+        o.emotion_response = EMOTION_MAP[o.response] || "unknown";
         o.correct = o.emotion === o.emotion_response;
         // in the older ones there were 15 trials per rotation
     });
     return trials;
 };
 exports.emotion_extract_trials = emotion_extract_trials;
+var emotion_results = function (obj) {
+    if (obj.length === 0) {
+        throw new Error("No trials found");
+    }
+    var correct_trials = obj.filter(function (o) { return o.correct === true; });
+    var incorrect_trials = obj.filter(function (o) { return o.correct === false; });
+    var total_rt = obj.reduce(function (a, b) { return a + (b.rt || 0); }, 0);
+    var correct_rt = correct_trials.reduce(function (a, b) { return a + (b.rt || 0); }, 0);
+    var incorrect_rt = incorrect_trials.reduce(function (a, b) { return a + (b.rt || 0); }, 0);
+    var avg_rt = total_rt / obj.length;
+    var avg_acc = correct_trials.length / obj.length;
+    // Calculate performance score using the existing formula
+    var best_score = 1000;
+    var worst_score = 10000;
+    var performance = avg_rt / (Math.pow(avg_acc, 5) + 0.001);
+    performance = Math.min(Math.max(performance, best_score), worst_score);
+    var performance_score = (1 - ((performance - best_score) / (worst_score - best_score))) * 100;
+    var common = {
+        n_trials: obj.length,
+        n_correct_trials: correct_trials.length,
+        n_incorrect_trials: incorrect_trials.length,
+        avg_rt_total: avg_rt,
+        avg_rt_correct: correct_trials.length > 0 ? correct_rt / correct_trials.length : 0,
+        avg_rt_incorrect: incorrect_trials.length > 0 ? incorrect_rt / incorrect_trials.length : 0,
+        performance_score: performance_score
+    };
+    // Group by emotion for special results
+    var by_emotion = EMOTION_MAP.map(function (emotion) {
+        var emotion_trials = obj.filter(function (o) { return o.emotion === emotion; });
+        return {
+            emotion: emotion,
+            n: emotion_trials.length,
+            avg_rt: emotion_trials.length > 0 ? emotion_trials.reduce(function (a, b) { return a + (b.rt || 0); }, 0) / emotion_trials.length : 0,
+            avg_acc: emotion_trials.length > 0 ? emotion_trials.reduce(function (a, b) { return a + (b.correct ? 1 : 0); }, 0) / emotion_trials.length : 0,
+        };
+    });
+    // Create confusion matrix
+    var confusion_matrix = EMOTION_MAP.reduce(function (matrix, actual) {
+        matrix[actual] = EMOTION_MAP.reduce(function (row, predicted) {
+            row[predicted] = obj.filter(function (o) { return o.emotion === actual && o.emotion_response === predicted; }).length;
+            return row;
+        }, {});
+        return matrix;
+    }, {});
+    var special = {
+        by_emotion: by_emotion,
+        confusion_matrix: confusion_matrix
+    };
+    return {
+        common: common,
+        special: special
+    };
+};
+exports.emotion_results = emotion_results;

package/dist/cjs/gonogo.d.ts

@@ -1,9 +1,4 @@
-interface GonogoResultsStructure {
-    n: number;
-    avg_rt: number;
-    avg_acc: number;
-    performance: number;
-}
+import { GonogoResultsStructure } from './common-interfaces';
 declare const gonogo_calculate_results: (data: any[]) => GonogoResultsStructure;
 declare const gonogo_extract_trials: (obj: any[]) => any[];
 declare const gonogo_results: (data: any[]) => GonogoResultsStructure;