first commit

.dockerignore

@@ -0,0 +1,2 @@
+node_modules
+npm-debug.log

.env.example

@@ -0,0 +1,2 @@
+PORT=7860
+VITE_SERVER_URL=http://localhost:7860/

.eslintignore

@@ -0,0 +1,6 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+.eslintcache

.eslintrc.json

@@ -0,0 +1,21 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true,
+    "node": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 12,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "off"
+  }
+}

.github/workflows/hugging-face.yml

@@ -0,0 +1,19 @@
+name: Sync to Hugging Face hub
+on:
+  push:
+    branches: [main]
+
+  # to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Push to hub
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: git push https://lysine:[email protected]/spaces/lysine/marrow-cells main

.gitignore

@@ -0,0 +1,7 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+.eslintcache
+.env

.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+.eslintcache

.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "arrowParens": "avoid",
+  "tabWidth": 2,
+  "trailingComma": "es5"
+}

Dockerfile

@@ -0,0 +1,45 @@
+ARG VITE_SERVER_URL
+
+FROM node:18
+
+# Set up a new user named "user" with user ID 1000
+RUN useradd -o -u 1000 user
+
+# Install pip
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    python3.11 \
+    python3-pip
+
+# Install kaggle silently
+RUN yes | pip3 install kaggle --exists-action i --break-system-packages
+
+# Switch to the "user" user
+USER user
+
+# Set home to the user's home directory
+ENV HOME=/home/user \
+	PATH=/home/user/.local/bin:$PATH
+
+# Set the working directory to the user's home directory
+WORKDIR $HOME/app
+
+# Copy the current directory contents into the container at $HOME/app setting the owner to the user
+COPY --chown=user . $HOME/app
+
+# Install npm dependencies
+RUN npm install
+
+# Build client and server
+RUN export VITE_SERVER_URL=$MODEL_REPO_NAME && npm run build
+
+# Download bone marrow cell dataset from Kaggle
+RUN --mount=type=secret,id=KAGGLE_USERNAME,mode=0444,required=true \
+    --mount=type=secret,id=KAGGLE_KEY,mode=0444,required=true \
+    export KAGGLE_USERNAME=$(cat /run/secrets/KAGGLE_USERNAME) && \
+    export KAGGLE_KEY=$(cat /run/secrets/KAGGLE_KEY) && \
+    kaggle datasets download -d andrewmvd/bone-marrow-cell-classification --unzip -p $HOME/app/dist/app/marrow-cell-data
+
+EXPOSE 7860
+CMD [ "npm", "run", "start" ]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Henry Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,26 @@
+---
+title: marrow-cells
+emoji: 🦴
+colorFrom: red
+colorTo: purple
+sdk: docker
+pinned: false
+---
+
+# marrow-cells
+
+A single-page web app presenting bone marrow cells from the Bone Marrow Cell Classification dataset.
+
+[![Open marrow-cells on HF Spaces](https://huggingface.co/datasets/huggingface/badges/raw/main/open-in-hf-spaces-xl-dark.svg)](https://lysine-marrow-cells.hf.space/)
+
+This app features over 170,000 individual cells from the dataset. You can compare 2 classes of cells side by side or try to identify an unlabelled set of cells.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgments
+
+* Thanks [Bone Marrow Cell Classification](https://www.kaggle.com/datasets/andrewmvd/bone-marrow-cell-classification) for providing cell images and labels.
+* Thanks [kaggle](https://www.kaggle.com/) for hosting the dataset and providing convenient tools to download it.
+* Thanks [Hugging Face](https://huggingface.co/) for hosting the app online for free.

index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/src/app/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Bone Marrow Cell Database</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/app/main.tsx"></script>
+  </body>
+</html>

nodemon.json

@@ -0,0 +1,5 @@
+{
+  "watch": ["src"],
+  "ext": "js,jsx,ts,tsx,json",
+  "exec": "ts-node --esm --project tsconfig.server.json --experimental-specifier-resolution=node ./src/server"
+}

package.json

@@ -0,0 +1,63 @@
+{
+  "name": "marrow-cells",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently \"npm run server:dev\" \"npm run client:dev\"",
+    "client:dev": "vite",
+    "server:dev": "nodemon",
+    "server:build": "tsc --project tsconfig.server.json",
+    "client:build": "vite build",
+    "build": "npm run server:build && npm run client:build",
+    "serve": "vite preview",
+    "test": "tsc && prettier --check . && eslint . && stylelint \"**/*.css\"",
+    "start": "node --experimental-specifier-resolution=node dist/server.js",
+    "docker": "npm run docker:build && npm run docker:run",
+    "docker:build": "docker build -t auscultate .",
+    "docker:run": "docker run -it -p 7860:7860 auscultate",
+    "lint": "eslint **/*.{js,jsx,ts,tsx} --fix --cache",
+    "format": "prettier **/*.{js,jsx,ts,tsx,css,html,json,md,mdx} --write"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.22.10",
+    "@babel/node": "^7.22.10",
+    "@babel/preset-env": "^7.22.10",
+    "@types/cors": "^2.8.13",
+    "@types/express": "^4.17.17",
+    "@types/node": "^20.4.9",
+    "@types/react": "^18.2.20",
+    "@types/react-dom": "^18.2.7",
+    "@types/react-helmet": "^6.1.6",
+    "@types/react-router-dom": "^5.3.3",
+    "@typescript-eslint/eslint-plugin": "^6.3.0",
+    "@typescript-eslint/parser": "^6.3.0",
+    "@vitejs/plugin-react-refresh": "^1.3.6",
+    "autoprefixer": "^10.4.14",
+    "concurrently": "^8.2.0",
+    "daisyui": "^3.5.1",
+    "eslint": "^8.46.0",
+    "eslint-config-prettier": "^9.0.0",
+    "http-proxy-middleware": "^2.0.6",
+    "nodemon": "^3.0.1",
+    "postcss": "^8.4.27",
+    "prettier": "3.0.1",
+    "tailwindcss": "^3.3.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.1.6",
+    "vite": "^4.4.9"
+  },
+  "dependencies": {
+    "@hapi/boom": "^10.0.1",
+    "axios": "^1.4.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "glob": "^10.3.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-helmet": "^6.1.0",
+    "react-router-dom": "^6.15.0",
+    "readable-regexp": "^1.3.4",
+    "zod": "^3.21.4"
+  }
+}

postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

src/app/App.tsx

@@ -0,0 +1,92 @@
+import React, { useEffect, useState } from 'react';
+import { redirect } from 'react-router-dom';
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
+import Compare from './marrow-cells/Compare';
+// import Identify from './marrow-cells/Identify';
+import { Helmet } from 'react-helmet';
+import { CellTypes } from '../marrow-cell-types';
+import { getTypes } from './marrow-cells/api';
+import { DataProvider } from './DataContext';
+
+function Redirect({ to }: { to: string }) {
+  useEffect(() => {
+    redirect(to);
+  }, []);
+  return null;
+}
+
+const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <Redirect to="/compare" />,
+  },
+  {
+    path: '/compare',
+    element: <Compare />,
+  },
+  // {
+  //   path: '/identify',
+  //   element: <Identify />,
+  // },
+]);
+
+export default function App() {
+  const [cellTypes, setCellTypes] = useState<CellTypes>({});
+
+  useEffect(() => {
+    getTypes().then(setCellTypes);
+  }, []);
+
+  return (
+    <>
+      <div className="p-8 flex flex-col gap-2">
+        <Helmet>
+          <title>Bone Marrow Cell Database</title>
+        </Helmet>
+        <div className="text-sm breadcrumbs flex justify-center w-full">
+          <ul>
+            <li>
+              <a href="https://lysine-med.hf.space/">Med</a>
+            </li>
+            <li>Marrow Cells</li>
+          </ul>
+        </div>
+        <p className="text-3xl text-center">Bone Marrow Cell Database</p>
+        <p className="text-center">
+          Filter and access bone marrow cell images from the Bone Marrow Cell
+          Classification dataset.
+        </p>
+        <p className="font-bold">Points to note</p>
+        <ul className="list-disc">
+          <li>Classification of the cells may not be 100% accurate.</li>
+          <li>
+            Not all cells are identifiable, and not all identified cells are
+            classified into a specific cell type.
+          </li>
+        </ul>
+        {cellTypes ? (
+          <DataProvider data={{ cellTypes }}>
+            <RouterProvider router={router} />
+          </DataProvider>
+        ) : (
+          <div className="alert">
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              fill="none"
+              viewBox="0 0 24 24"
+              className="stroke-info shrink-0 w-6 h-6"
+            >
+              <path
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                stroke-width="2"
+                d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+              ></path>
+            </svg>
+            <span>Loading cell types...</span>
+          </div>
+        )}
+      </div>
+    </>
+  );
+}

src/app/DataContext.tsx

@@ -0,0 +1,25 @@
+import React, { PropsWithChildren, createContext, useContext } from 'react';
+import { CellTypes } from '../marrow-cell-types';
+
+interface AppData {
+  cellTypes: CellTypes;
+}
+
+const dataContext = createContext<AppData>({
+  cellTypes: {},
+});
+
+export function useData() {
+  return useContext(dataContext);
+}
+
+interface DataProviderProps {
+  data: AppData;
+}
+
+export function DataProvider({
+  children,
+  data,
+}: PropsWithChildren<DataProviderProps>) {
+  return <dataContext.Provider value={data}>{children}</dataContext.Provider>;
+}

src/app/globals.css

@@ -0,0 +1,16 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
+    Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+code {
+  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
+    monospace;
+}

src/app/main.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import './globals.css';
+import App from './App';
+
+const container = document.querySelector('#root');
+const root = createRoot(container!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

src/app/marrow-cells/Compare.tsx

@@ -0,0 +1,178 @@
+import React, { useEffect, useState } from 'react';
+import { useSearchParams } from 'react-router-dom';
+import { RandomResult } from '../../marrow-cell-types';
+import { getImages } from './api';
+import { useData } from '../DataContext';
+
+interface CompareParams {
+  type1?: string;
+  type2?: string;
+}
+
+function compareToParams(filter: CompareParams): URLSearchParams {
+  const params = new URLSearchParams();
+  if (filter.type1) {
+    params.append('type1', filter.type1);
+  }
+  if (filter.type2) {
+    params.append('type2', filter.type2);
+  }
+  return params;
+}
+
+function paramsToCompare(params: URLSearchParams): CompareParams {
+  const newFilter: CompareParams = {};
+  if (params.has('type1')) {
+    newFilter.type1 = params.get('type1')!;
+  }
+  if (params.has('type2')) {
+    newFilter.type2 = params.get('type2')!;
+  }
+  return newFilter;
+}
+
+export default function Compare(): JSX.Element {
+  const { cellTypes } = useData();
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const [cellType1, setCellType1] = useState<string>();
+  const [imageSet1, setImageSet1] = useState<RandomResult>();
+  const [loading1, setLoading1] = useState<boolean>(false);
+  const [cellType2, setCellType2] = useState<string>();
+  const [imageSet2, setImageSet2] = useState<RandomResult>();
+  const [loading2, setLoading2] = useState<boolean>(false);
+
+  const loadImages = (cell: 1 | 2) => {
+    if (cell === 1) {
+      if (!cellType1) return;
+      setLoading1(true);
+    } else {
+      if (!cellType2) return;
+      setLoading2(true);
+    }
+    getImages({ type: [cell === 1 ? cellType1! : cellType2!] })
+      .then(result => {
+        if (cell === 1) {
+          setImageSet1(result);
+        } else {
+          setImageSet2(result);
+        }
+      })
+      .finally(() => {
+        if (cell === 1) {
+          setLoading1(false);
+        } else {
+          setLoading2(false);
+        }
+      });
+  };
+
+  useEffect(() => {
+    loadImages(1);
+  }, [cellType1]);
+
+  useEffect(() => {
+    loadImages(2);
+  }, [cellType2]);
+
+  useEffect(() => {
+    const newFilter = paramsToCompare(searchParams);
+    setCellType1(newFilter.type1);
+    setCellType2(newFilter.type2);
+  }, [searchParams]);
+
+  const updateParams = (
+    type1: string | undefined,
+    type2: string | undefined
+  ) => {
+    setSearchParams(compareToParams({ type1, type2 }));
+  };
+
+  return (
+    <>
+      <div className="tabs">
+        <a
+          className={`tab tab-bordered ${
+            location.pathname.startsWith('/compare') ? 'tab-active' : ''
+          }`}
+        >
+          Compare
+        </a>
+        <a
+          className={`tab tab-bordered ${
+            location.pathname.startsWith('/compare') ? 'tab-active' : ''
+          }`}
+        >
+          Identify
+        </a>
+      </div>
+      <div className="flex w-full items-center gap-4">
+        <div className="flex flex-col gap-4">
+          <div className="form-control w-full max-w-xs">
+            <select
+              className={`select select-bordered ${
+                loading1 ? 'animate-pulse' : ''
+              }`}
+              disabled={loading1}
+              onChange={e => updateParams(e.target.value, cellType2)}
+            >
+              <option disabled selected>
+                Select a cell type
+              </option>
+              {Object.entries(cellTypes).map(([key, value]) => (
+                <option key={key} value={key}>
+                  {value}
+                </option>
+              ))}
+            </select>
+            <label className="label">
+              <span
+                className={`label-text-alt ${!imageSet1 ? 'invisible' : ''}`}
+              >
+                {imageSet1?.count ?? 0}
+              </span>
+            </label>
+          </div>
+          <div className="flex flex-wrap gap-4">
+            {imageSet1?.images.map(image => (
+              <img key={image} src={image} className="shadow-lg" alt="Cell" />
+            ))}
+          </div>
+        </div>
+        <div className="divider divider-horizontal"></div>
+        <div className="flex flex-col gap-4">
+          <div className="form-control w-full max-w-xs">
+            <select
+              className={`select select-bordered ${
+                loading2 ? 'animate-pulse' : ''
+              }`}
+              disabled={loading2}
+              onChange={e => updateParams(e.target.value, cellType2)}
+            >
+              <option disabled selected>
+                Select a cell type
+              </option>
+              {Object.entries(cellTypes).map(([key, value]) => (
+                <option key={key} value={key}>
+                  {value}
+                </option>
+              ))}
+            </select>
+            <label className="label">
+              <span
+                className={`label-text-alt ${!imageSet2 ? 'invisible' : ''}`}
+              >
+                {imageSet2?.count ?? 0}
+              </span>
+            </label>
+          </div>
+          <div className="flex flex-wrap gap-4">
+            {imageSet2?.images.map(image => (
+              <img key={image} src={image} className="shadow-lg" alt="Cell" />
+            ))}
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}

src/app/marrow-cells/Identify.tsx

@@ -0,0 +1,518 @@
+import React, { useEffect, useState } from 'react';
+import { Link, useSearchParams } from 'react-router-dom';
+import { Helmet } from 'react-helmet';
+import { FilterParams } from '../../marrow-cell-types';
+import { getDataUrl, getImages, getTypes } from './api';
+
+function filterToParams(filter: FilterParams): URLSearchParams {
+  const params = new URLSearchParams();
+  if (filter.type) {
+    filter.type.forEach(type => params.append('type', type));
+  }
+  return params;
+}
+
+function paramsToFilter(params: URLSearchParams): FilterParams {
+  const newFilter: FilterParams = {};
+  if (params.has('type')) {
+    newFilter.type = params.getAll('type') as string[];
+  }
+  return newFilter;
+}
+
+export default function Identify(): JSX.Element {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const [patientId, setPatientId] = useState<number | null>(null);
+  const [resultCount, setResultCount] = useState<number>(-1);
+
+  const [filterParams, setFilterParams] = useState<FilterParams>({});
+
+  const [patient, setPatient] = useState<FullPatient | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState<boolean>(false);
+
+  const [audioZoom, setAudioZoom] = useState(100);
+  const [regionsLevel, setRegionsLevel] = useState<RegionsLevel>(
+    RegionsLevel.None
+  );
+  const [showAnswer, setShowAnswer] = useState(false);
+  const [spectrogram, setSpectrogram] = useState(false);
+
+  const getRandom = () => {
+    setLoading(true);
+    getRandomPatient(filterParams)
+      .then(result => {
+        setPatientId(result.patientId);
+        setResultCount(result.count);
+        setSearchParams(p => {
+          p.set('id', result.patientId.toString());
+          return p;
+        });
+      })
+      .catch(err => {
+        if (err.response.status === 404) {
+          setResultCount(0);
+        }
+      })
+      .finally(() => {
+        setLoading(false);
+      });
+  };
+
+  const loadPatient = () => {
+    setLoading(true);
+    getPatient(patientId!)
+      .then(patient => {
+        setPatient(patient);
+        setError(null);
+      })
+      .catch(err => {
+        setPatient(null);
+        setError(err.response.data.message);
+      })
+      .finally(() => {
+        setLoading(false);
+      });
+  };
+
+  useEffect(() => {
+    setShowAnswer(false);
+    setFilterParams(paramsToFilter(searchParams));
+    if (patientId === null) {
+      if (searchParams.has('id')) {
+        setPatientId(Number(searchParams.get('id')));
+      } else {
+        getRandom();
+      }
+    } else {
+      loadPatient();
+    }
+  }, [searchParams, patientId]);
+
+  const randomClicked = () => {
+    setSearchParams(filterToParams(filterParams));
+    setPatientId(null);
+  };
+
+  const arrayToggle = <T extends string>(
+    array: Exclude<keyof FilterParams, 'murmur'>,
+    value: T,
+    checked: boolean
+  ): void => {
+    setFilterParams(f => {
+      if (checked) {
+        return {
+          ...f,
+          [array]: [...(f[array] ?? []), value],
+        };
+      } else {
+        return {
+          ...f,
+          [array]: (f[array] as string[] | null)?.filter(v => v !== value),
+        };
+      }
+    });
+  };
+
+  return (
+    <div className="p-8 flex flex-col gap-2">
+      <Helmet>
+        <title>Heart Sounds Database - auscultate</title>
+      </Helmet>
+      <div className="text-sm breadcrumbs flex justify-center w-full">
+        <ul>
+          <li>
+            <a href="https://lysine-med.hf.space/">Med</a>
+          </li>
+          <li>
+            <Link to="/">Auscultation</Link>
+          </li>
+          <li>Heart Sounds</li>
+        </ul>
+      </div>
+      <p className="text-3xl text-center">Heart Sounds Database</p>
+      <p className="text-center">
+        Filter and access heart sounds from the CirCor DigiScope Phonocardiogram
+        Dataset.
+      </p>
+      <p className="font-bold">Points to note</p>
+      <ul className="list-disc">
+        <li>
+          The provided analysis may not be 100% accurate and may not be the only
+          abnormalities found.
+        </li>
+        <li>
+          This dataset only records murmur. Other heart sound abnormalities are
+          not considered.
+        </li>
+        <li>
+          A patient with no detected murmur may still have other undocumented
+          abnormalities.
+        </li>
+      </ul>
+      <div className="collapse collapse-arrow bg-base-200 my-4">
+        <input type="checkbox" />
+        <div className="collapse-title text-xl font-medium">Select Filters</div>
+        <div className="collapse-content">
+          <form className="bg-base-200 p-4 pt-0 flex flex-col items-center w-full">
+            <fieldset className="w-full" disabled={loading}>
+              <div className="divider">Auscultation location</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                {Object.values(Location).map(loc => (
+                  <div key={loc} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="checkbox"
+                        checked={filterParams.location?.includes(loc) ?? false}
+                        onChange={e =>
+                          arrayToggle('location', loc, e.target.checked)
+                        }
+                        className="checkbox"
+                      />
+                      <span className="label-text">{nameLocation(loc)}</span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="divider">Murmur Type</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                <div className="form-control">
+                  <label className="label cursor-pointer gap-2">
+                    <input
+                      type="radio"
+                      className="radio"
+                      checked={!filterParams.murmur}
+                      onChange={e => {
+                        if (e.target.checked) {
+                          setFilterParams(f => ({ ...f, murmur: undefined }));
+                        }
+                      }}
+                    />
+                    <span className="label-text">No filter</span>
+                  </label>
+                </div>
+                {Object.values(MurmurFilter).map(filter => (
+                  <div key={filter} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="radio"
+                        className="radio"
+                        checked={filterParams.murmur === filter}
+                        onChange={e => {
+                          if (e.target.checked) {
+                            setFilterParams(f => ({ ...f, murmur: filter }));
+                          }
+                        }}
+                      />
+                      <span className="label-text">{nameMurmur(filter)}</span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="divider">Murmur location</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                {Object.values(Location).map(loc => (
+                  <div key={loc} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="checkbox"
+                        checked={
+                          filterParams.murmurLocation?.includes(loc) ?? false
+                        }
+                        onChange={e =>
+                          arrayToggle('murmurLocation', loc, e.target.checked)
+                        }
+                        className="checkbox"
+                      />
+                      <span className="label-text">{nameLocation(loc)}</span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="divider">Murmur Timing</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                {Object.values(MurmurTiming).map(loc => (
+                  <div key={loc} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="checkbox"
+                        checked={filterParams.timing?.includes(loc) ?? false}
+                        onChange={e =>
+                          arrayToggle('timing', loc, e.target.checked)
+                        }
+                        className="checkbox"
+                      />
+                      <span className="label-text">
+                        {nameTiming(
+                          loc,
+                          ['systolic', 'diastolic'].includes(
+                            filterParams.murmur ?? ''
+                          )
+                            ? (filterParams.murmur as 'systolic' | 'diastolic')
+                            : 'general'
+                        )}
+                      </span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="divider">Murmur Shape</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                {Object.values(MurmurShape).map(loc => (
+                  <div key={loc} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="checkbox"
+                        checked={filterParams.shape?.includes(loc) ?? false}
+                        onChange={e =>
+                          arrayToggle('shape', loc, e.target.checked)
+                        }
+                        className="checkbox"
+                      />
+                      <span className="label-text">{loc}</span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="divider">Murmur Grading</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                {Object.values(MurmurGrading).map(loc => (
+                  <div key={loc} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="checkbox"
+                        checked={filterParams.grading?.includes(loc) ?? false}
+                        onChange={e =>
+                          arrayToggle('grading', loc, e.target.checked)
+                        }
+                        className="checkbox"
+                      />
+                      <span className="label-text">
+                        {nameGrading(
+                          loc,
+                          ['systolic', 'diastolic'].includes(
+                            filterParams.murmur ?? ''
+                          )
+                            ? (filterParams.murmur as 'systolic' | 'diastolic')
+                            : 'general'
+                        )}
+                      </span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="divider">Murmur Pitch</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                {Object.values(MurmurPitch).map(loc => (
+                  <div key={loc} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="checkbox"
+                        checked={filterParams.pitch?.includes(loc) ?? false}
+                        onChange={e =>
+                          arrayToggle('pitch', loc, e.target.checked)
+                        }
+                        className="checkbox"
+                      />
+                      <span className="label-text">{loc}</span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="divider">Murmur Quality</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                {Object.values(MurmurQuality).map(loc => (
+                  <div key={loc} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="checkbox"
+                        checked={filterParams.quality?.includes(loc) ?? false}
+                        onChange={e =>
+                          arrayToggle('quality', loc, e.target.checked)
+                        }
+                        className="checkbox"
+                      />
+                      <span className="label-text">{loc}</span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="divider">Heart Outcome</div>
+              <div className="flex flex-wrap gap-4 justify-center">
+                <div className="form-control">
+                  <label className="label cursor-pointer gap-2">
+                    <input
+                      type="radio"
+                      className="radio"
+                      checked={!filterParams.outcome}
+                      onChange={e => {
+                        if (e.target.checked) {
+                          setFilterParams(f => ({ ...f, outcome: undefined }));
+                        }
+                      }}
+                    />
+                    <span className="label-text">No filter</span>
+                  </label>
+                </div>
+                {Object.values(Outcome).map(filter => (
+                  <div key={filter} className="form-control">
+                    <label className="label cursor-pointer gap-2">
+                      <input
+                        type="radio"
+                        className="radio"
+                        checked={filterParams.outcome === filter}
+                        onChange={e => {
+                          if (e.target.checked) {
+                            setFilterParams(f => ({ ...f, outcome: filter }));
+                          }
+                        }}
+                      />
+                      <span className="label-text">{filter}</span>
+                    </label>
+                  </div>
+                ))}
+              </div>
+            </fieldset>
+          </form>
+        </div>
+
+        <button
+          className="btn btn-primary"
+          onClick={randomClicked}
+          disabled={loading}
+        >
+          {loading ? (
+            <span className="loading loading-spinner loading-sm"></span>
+          ) : (
+            'Random Patient'
+          )}
+        </button>
+      </div>
+      {resultCount < 0 ? null : (
+        <p>{resultCount} patients with the selected filters.</p>
+      )}
+      {error === null ? null : (
+        <div className="alert alert-error">
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            className="stroke-current shrink-0 h-6 w-6"
+            fill="none"
+            viewBox="0 0 24 24"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth="2"
+              d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z"
+            />
+          </svg>
+          <div>
+            <h3 className="font-bold">
+              An error occurred while loading the patient
+            </h3>
+            <div className="text-xs">{error}</div>
+          </div>
+        </div>
+      )}
+      <div className="divider"></div>
+      {patient === null ? null : (
+        <div>
+          <Demographics patient={patient} />
+          <div className="flex gap-4 my-4 justify-end flex-wrap">
+            <div className="flex items-center gap-2">
+              <span>Zoom: </span>
+              <input
+                type="range"
+                min="20"
+                max="1000"
+                value={audioZoom}
+                onChange={e => setAudioZoom(Number(e.target.value))}
+                className="range range-sm min-w-[250px] w-1/4"
+              />
+            </div>
+          </div>
+          {patient.tracks.map(track => (
+            <AuscultationTrack
+              key={track.audioFile}
+              patient={patient}
+              track={track}
+              zoom={audioZoom}
+              showAnswer={showAnswer}
+              spectrogram={showAnswer && spectrogram}
+              regionsLevel={showAnswer ? regionsLevel : RegionsLevel.None}
+            />
+          ))}
+          <div className="collapse collapse-arrow bg-base-200">
+            <input
+              type="checkbox"
+              checked={showAnswer}
+              onChange={e => setShowAnswer(e.target.checked)}
+            />
+            <div className="collapse-title text-xl font-medium">
+              Heart Sound Analysis
+            </div>
+            <div className="collapse-content">
+              <div className="p-4 pt-0 flex flex-col items-center w-full gap-4">
+                <p className="text-lg">{getMurmurDescription(patient)}</p>
+                {patient.murmur !== MurmurStatus.Present ? null : (
+                  <p>
+                    All audible locations:{' '}
+                    {patient.murmurLocations.map(loc => (
+                      <kbd className="kbd" key={loc}>
+                        {nameLocation(loc)}
+                      </kbd>
+                    ))}
+                  </p>
+                )}
+                <p className="text-lg">Heart outcome: {patient.outcome}</p>
+                <div className="flex gap-8 my-4 justify-end flex-wrap">
+                  <div className="flex items-center gap-4">
+                    <span className="label-text">Annotations:</span>
+                    <div>
+                      <input
+                        type="range"
+                        min="0"
+                        max="3"
+                        value={regionsLevel}
+                        onChange={e => setRegionsLevel(Number(e.target.value))}
+                        className="range"
+                        step="1"
+                      />
+                      <div className="w-full flex justify-between text-[5px] px-2">
+                        <span>|</span>
+                        <span>|</span>
+                        <span>|</span>
+                        <span>|</span>
+                      </div>
+                    </div>
+                  </div>
+                  <div className="divider-vertical" />
+                  <div className="form-control">
+                    <label className="label cursor-pointer flex gap-4">
+                      <span className="label-text">Show spectrogram:</span>
+                      <input
+                        type="checkbox"
+                        className="toggle"
+                        checked={spectrogram}
+                        onChange={e => setSpectrogram(e.target.checked)}
+                      />
+                    </label>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

src/app/marrow-cells/api.ts

@@ -0,0 +1,23 @@
+import axios from 'axios';
+import { CellTypes, FilterParams, RandomResult } from '../../marrow-cell-types';
+
+const SERVER_BASE_PATH = import.meta.env.VITE_SERVER_URL;
+
+export async function getImages(params: FilterParams): Promise<RandomResult> {
+  const response = await axios.get(
+    `${SERVER_BASE_PATH}api/marrow-cells/images`,
+    {
+      params,
+    }
+  );
+  return response.data;
+}
+
+export async function getTypes(): Promise<CellTypes> {
+  const response = await axios.get(`${SERVER_BASE_PATH}api/marrow-cells/types`);
+  return response.data;
+}
+
+export function getDataUrl(filename: string): string {
+  return `${SERVER_BASE_PATH}marrow-cell-data/bone_marrow_cecll_dataset/${filename}`;
+}

src/lib/helper.ts

@@ -0,0 +1,58 @@
+import type { Request, Response, NextFunction } from 'express';
+import { AnyZodObject, z } from 'zod';
+import { badRequest } from '@hapi/boom';
+
+function indent(str: string, spaces: number) {
+  return str
+    .split('\n')
+    .map(line => ' '.repeat(spaces) + line)
+    .join('\n');
+}
+
+function extractZodMessage(error: any): string {
+  if (Array.isArray(error)) {
+    return error.map(extractZodMessage).join('\n');
+  } else {
+    let union: string[] = [];
+    if ('unionErrors' in error) {
+      union = error.unionErrors.map(extractZodMessage);
+    } else if ('issues' in error) {
+      union = error.issues.map(extractZodMessage);
+    }
+    if (
+      'message' in error &&
+      typeof error.message === 'string' &&
+      !error.message.includes('\n')
+    ) {
+      if (union.length === 0) return error.message;
+      return error.message + '\n' + indent(union.join('\n'), 2);
+    } else if (union.length > 0) {
+      return union.join('\n');
+    } else {
+      return '';
+    }
+  }
+}
+
+export async function validate<T extends AnyZodObject>(
+  req: Request,
+  schema: T
+): Promise<z.infer<T>> {
+  try {
+    return await schema.parseAsync(req);
+  } catch (error: any) {
+    throw badRequest(extractZodMessage(error));
+  }
+}
+
+export function wrap(
+  fn: (req: Request, res: Response, next: NextFunction) => Promise<any>
+) {
+  return async function (req: Request, res: Response, next: NextFunction) {
+    try {
+      return await fn(req, res, next);
+    } catch (err) {
+      next(err);
+    }
+  };
+}

src/lib/marrow-cells/api.ts

@@ -0,0 +1,71 @@
+import express from 'express';
+import { z } from 'zod';
+import { validate, wrap } from '../helper';
+import { cellTypes, cellImages } from './data';
+import { notFound } from '@hapi/boom';
+import { RandomResult } from '../../marrow-cell-types';
+
+const router = express.Router();
+
+router.get(
+  '/types',
+  wrap(async (_req, res) => {
+    res.status(200).json(cellTypes);
+  })
+);
+
+router.get(
+  '/images',
+  wrap(async (req, res) => {
+    const { query } = await validate(
+      req,
+      z.object({
+        query: z
+          .object({
+            type: z.union([z.string().array(), z.string()]).optional(),
+          })
+          .strict(),
+      })
+    );
+    if (query.type) {
+      const validateType = (type: string) => {
+        if (!(type in cellImages)) {
+          throw notFound(`${query.type} is not a valid cell type`);
+        }
+      };
+      if (Array.isArray(query.type)) {
+        query.type.forEach(validateType);
+      } else {
+        validateType(query.type);
+      }
+    }
+    const typeOptions: string[] = [];
+    if (Array.isArray(query.type) && query.type.length === 0) {
+      throw notFound('No cell types given');
+    } else if (Array.isArray(query.type)) {
+      typeOptions.push(...query.type);
+    } else if (query.type) {
+      typeOptions.push(query.type);
+    }
+    if (typeOptions.length === 0) {
+      typeOptions.push(...Object.keys(cellImages));
+    }
+    const type = typeOptions[Math.floor(Math.random() * typeOptions.length)];
+    const images = cellImages[type].slice();
+    // randomly sample at least 10 images
+    const sampleSize = Math.min(10, images.length);
+    const sample: string[] = [];
+    for (let i = 0; i < sampleSize; i++) {
+      const index = Math.floor(Math.random() * images.length);
+      sample.push(images[index]);
+      images.splice(index, 1);
+    }
+    res.status(200).json({
+      type,
+      images: sample,
+      count: cellImages[type].length,
+    } satisfies RandomResult);
+  })
+);
+
+export default router;

src/lib/marrow-cells/data.ts

@@ -0,0 +1,45 @@
+import fs from 'fs/promises';
+import { CellTypes } from '../../marrow-cell-types';
+import { Glob } from 'glob';
+
+const DATA_DIR = 'dist/app/marrow-cell-data/';
+
+export let cellTypes: CellTypes;
+export let cellImages: { [key: string]: string[] };
+
+export async function readData(): Promise<void> {
+  console.log('Marrow cells: Reading labels');
+
+  cellTypes = {};
+  const data = await fs.readFile(DATA_DIR + 'abbreviations.csv', {
+    encoding: 'utf8',
+  });
+  data
+    .split(/\r?\n/)
+    .slice(1)
+    .forEach(line => {
+      const [key, description] = line.split(';');
+      cellTypes[key] = description;
+    });
+
+  console.log('Marrow cells: Indexing images');
+
+  cellImages = {};
+  const directories = (
+    await fs.readdir(DATA_DIR + 'bone_marrow_cell_dataset', {
+      withFileTypes: true,
+    })
+  )
+    .filter(dirent => dirent.isDirectory())
+    .map(dirent => dirent.name);
+
+  for (const directory of directories) {
+    cellImages[directory] = [];
+    const g = new Glob(directory + '/**/*', {
+      cwd: DATA_DIR + 'bone_marrow_cell_dataset/',
+    });
+    for await (const file of g) {
+      cellImages[directory].push(file);
+    }
+  }
+}

src/marrow-cell-types.ts

@@ -0,0 +1,13 @@
+export interface CellTypes {
+  [key: string]: string;
+}
+
+export interface RandomResult {
+  images: string[];
+  type: string;
+  count: number;
+}
+
+export interface FilterParams {
+  type?: string[];
+}

src/server.ts

@@ -0,0 +1,60 @@
+import 'dotenv/config';
+import express, { Request, Response, NextFunction } from 'express';
+import marrowCellApi from './lib/marrow-cells/api';
+import { readData, cellImages } from './lib/marrow-cells/data';
+import cors from 'cors';
+import { isBoom } from '@hapi/boom';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const { PORT = 7860 } = process.env;
+
+const app = express();
+
+// Enable cross-origin resource sharing
+app.use(cors());
+
+// Middleware that parses json and looks at requests where the Content-Type header matches the type option.
+app.use(express.json());
+
+// Serve API requests from the router
+app.use('/api/marrow-cells', marrowCellApi);
+
+// Serve app production bundle
+app.use(express.static('dist/app'));
+
+app.use((err: unknown, _req: Request, res: Response, next: NextFunction) => {
+  if (res.headersSent) {
+    return next(err);
+  }
+  if (isBoom(err)) {
+    return res.status(err.output.statusCode).json(err.output.payload);
+  }
+  next(err);
+});
+
+// Handle client routing, return all requests to the app
+app.get('*', (_req, res) => {
+  res.sendFile(join(__dirname, 'app/index.html'));
+});
+
+Promise.all([
+  (async () => {
+    await readData();
+    console.log(
+      `Marrow cells: ${
+        Object.keys(cellImages).length
+      } cell types and ${Object.values(cellImages).reduce(
+        (prev, curr) => prev + curr.length,
+        0
+      )} cell images loaded`
+    );
+  })(),
+]).then(() => {
+  app.listen(PORT, () => {
+    console.log(`Server listening at http://localhost:${PORT}`);
+  });
+});

tailwind.config.js

@@ -0,0 +1,8 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
+  theme: {
+    extend: {},
+  },
+  plugins: [require('daisyui')],
+};

tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "moduleResolution": "Node",
+    "strict": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "types": ["vite/client", "node"],
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "jsx": "react",
+    "allowJs": false,
+    "isolatedModules": true,
+    "skipLibCheck": false,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["./src/app", "src/app/marrow-cells/Identify.tsx"]
+}

tsconfig.server.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "module": "ES2022",
+    "target": "ES2022",
+    "noEmit": false
+  },
+  "include": ["src/*.ts"],
+  "exclude": ["src/app"]
+}

vite.config.js

@@ -0,0 +1,23 @@
+import dotenv from 'dotenv';
+dotenv.config();
+
+import { defineConfig } from 'vite';
+import reactRefresh from '@vitejs/plugin-react-refresh';
+
+const { PORT = 7860 } = process.env;
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [reactRefresh()],
+  server: {
+    proxy: {
+      '/api': {
+        target: `http://localhost:${PORT}`,
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    outDir: 'dist/app',
+  },
+});