apple-aiml-research/ml-hierarchical-confusion-matrix

Neo – Hierarchical Confusion Matrix

What it is – A JavaScript library that lets you embed an interactive confusion‑matrix visualisation capable of handling hierarchical and multi‑output class labels. It was built for the research paper “Neo: Generalizing Confusion Matrix Visualization to Hierarchical and Multi‑Output Labels” (CHI 2022).

Why it matters – Traditional confusion matrices assume a flat list of classes. Many modern models predict structured labels (e.g., fruit:citrus:lemon or multiple attributes like fruit:apple, taste:sour). Neo lets data scientists explore errors at any level of that hierarchy, renormalise counts, and export the view, making model diagnostics much richer.

How to use it

1. Install via npm or yarn:

   npm install --save @apple/hierarchical-confusion-matrix
   # or
   yarn add @apple/hierarchical-confusion-matrix
   

2. Import the module and call confMat.embed(containerId, spec, confusions) where:
   • spec describes the class hierarchy (e.g., { classes: ['root'] }).
   • confusions is an array of objects { actual: [...], observed: [...], count: N }. The library understands four formats – plain, hierarchical (: separates levels), multi‑output (, separates independent label groups), and a combination of both.
3. Alternative – If you prefer a plain script tag, run yarn install in the repo, copy the compiled public/confMat.js into your site, and embed it exactly as shown in the README’s HTML example.

Data format – Each entry records how many instances (count) with a given actual label set were predicted as a particular observed label set. The README gives concrete JSON snippets for:

• Simple class confusions (fruit:lemon → fruit:apple).
• Hierarchical confusions (fruit:citrus:lemon → fruit:pome:apple).
• Multi‑output confusions (fruit:lemon, taste:sweet → fruit:apple, taste:sour).
• Combined hierarchical + multi‑output confusions.

Development – The repo ships with a typical JavaScript toolchain:

• yarn build – compiles the TypeScript source.
• yarn dev – runs a local dev server for rapid iteration.
• yarn test:unit – runs unit tests.
• yarn lint – lints and auto‑fixes code style.

Where to see it – A live demo is hosted at https://apple.github.io/ml-hierarchical-confusion-matrix/, and a short YouTube walkthrough is linked in the README.

Citation – If you use Neo in a publication, cite the CHI 2022 paper (BibTeX provided).

License – The code is released under the repository’s LICENSE file (Apple’s open‑source terms).

---

All details above are taken directly from the repository’s README; no additional features have been inferred.