m2c2kit is a library for cross-platform cognitive assessments. It is produced by the Ambulatory Methods for Measuring Cognitive Change research project (Award #U2CAG060408), sponsored by the National Institute on Aging.
Features:
- Mobile first. Optimized for touch and mobile devices while also usable on desktops.
- Portable. Use on browsers, compile within native apps using webviews, or embed in products like Qualtrics. A shared assessment codebase reduces development time and promotes experiment standardization across devices and services.
- Rapid iteration. Quickly develop and test new assessments with the JavaScript-based library and deploy them in studies.
m2c2kit is written in Typescript and leverages Google's canvaskit-wasm Skia-based graphics engine to present cognitive assessments using HTML5 and JavaScript.
Examples • Documentation • Installation • Building • Packages • Testing • Integrations • Contributing • License
See m2c2kit assessments in your browser at https://m2c2-project.github.io/m2c2kit/docs/category/examples
Documentation, including live tutorials, is available at https://m2c2-project.github.io/m2c2kit. The repository change log documents notable changes.
Go to the m2c2kit playground to modify assessments (or create new ones) in your browser.
Make sure you have installed Node.js (version >=18; version 20 LTS recommended). The CLI can quickly scaffold a demo app and serve it on your local machine:
npm install -g @m2c2kit/cli
m2 new myapp
cd myapp
npm run serve
You can now go to http://localhost:3000 to view the demo app.
See the @m2c2kit/cli package for more information on using the CLI.
The installation steps above are all you need to start using m2c2kit and creating assessments.
To explore m2c2kit in depth, build the library from source. m2c2kit is a mono repository. After you have installed the prerequisites for building and testing the repository (Node.js, Git, and Docker), execute the following from the repository root:
npm install
npm run build
This will build all packages. Optional: see BUILDNOTES.md for a custom build of canvaskit-wasm to increase compatibility with older devices
@m2c2kit/core- The m2c2kit core functionality.@m2c2kit/session- The session runner for m2c2kit activities.@m2c2kit/addons- Convenience elements, such as buttons, grids, dialog boxes, a virtual keyboard, and instructions, constructed out of the core primitives.@m2c2kit/survey- Survey functionality that can be added to m2c2kit apps, using the MIT-licensed survey-js library.@m2c2kit/cli- Command line interface for scaffolding new m2c2kit apps.@m2c2kit/schematics- Rules for the m2c2kit CLI to generate new apps. End users will not need to install this explicitly. It is automatically installed by the CLI as a dependency.@m2c2kit/db- A local database for storing m2c2kit data on the device.@m2c2kit/physics- Physics for m2c2kit, based on the Matter.js engine.@m2c2kit/embedding- Utility functions for embedding m2c2kit assessments in other delivery mechanisms, such as native apps and services like Qualtrics.@m2c2kit/assessments-demo- Demonstration app that shows the assessments created by the m2c2kit team.@m2c2kit/assessment-color-dots- Color Dots is cued-recall, item-location memory binding task, where after viewing 3 dots for a brief period of time, participants report: (1) the color at a cued location; (2) the location of a cued color.@m2c2kit/assessment-grid-memory- Grid Memory is a visuospatial working memory task, with delayed free recall. After a brief exposure, and a short distraction phase, participants report the location of dots on a grid.@m2c2kit/assessment-symbol-search- Symbol Search is a speeded continuous performance test of conjunctive feature search in which respondents identify matching symbol pairs as quickly and as accurately as they can.@m2c2kit/assessment-color-shapes- Color Shapes is a visual array change detection task, measuring intra-item feature binding, where participants determine if shapes change color across two sequential presentations of shape stimuli.@m2c2kit/assessment-cli-starter- The assessment that is created when the CLI scaffolds a new app. It is a simple implementation of a Stroop assessment.@m2c2kit/sage-research- Utility functions for embedding m2c2kit assessments in iOS and Android apps developed by Sage Bionetworks. End users will not need to install this.@m2c2kit/build-helpers- Utility functions for building m2c2kit apps. End users will not need to install this explicitly. It is automatically installed by the CLI as a dependency.@m2c2kit/schema-util- Utility tool to extract the schema used in m2c2kit assessment TypeScript source files. End users do not need this.
Using Jest, some unit tests have been written to provide initial test coverage of the @m2c2kit/core, @m2c2kit/session, @m2c2kit/physics, @m2c2kit/survey, and @m2c2kit/build-helpers packages. The canvaskit-wasm dependency is mocked (with a combination of stubs, node-canvas, and jsdom) so tests can run without invoking this dependency.
To run the tests, execute the following from the repository root:
npm run test
Using Playwright, Verdaccio, and Docker Compose, some integration tests have been written to test the @m2c2kit/cli package. The integration tests build and publish m2c2kit packages to a local npm registry, install the CLI, scaffold a new app with the CLI, and test the new app's appearance and interactivity. The integration tests are fully containerized; you can run them without affecting your local system.
To run the containerized integration tests, execute the following from the repository root:
npm run integration-test
m2c2kit is flexible and can be integrated into many use cases:
-
no-js-bundler-development- How to use m2c2kit in simple JavaScript without bundlers or TypeScript transpilation. -
android-simple-webview- Android Studio project showing m2c2kit assessments integrated into a native Android app. Assessments are bundled into the app and do not require an internet connection. -
ios-simple-webview- Xcode project showing m2c2kit assessments integrated into a native iOS app. Assessments are bundled into the app and do not require an internet connection.
Prettier has been configured to automatically run on each commit. It will format TypeScript, JavaScript, HTML, and JSON to uniform coding styles.
MIT