Prototype: Atlas Explorer

Caution

• This implementation has been suspended in favour of the network graph prototype

1. Overview

Important

• This experiment was developed on the instruction of HDRUK's Disease Atlas team, a project being built alongside the BHF Data Science Centre and NHS Digital

This repository implements a 3d data explorer to allow users to navigate through each of the diseases defined within the Disease Atlas.

2. Technology & Implementation

This application was developed with:

Type	Details
Tech Stack	SolidJS & Three.JS
Languages	TypeScript & GLSL
Tooling	Vite

3. Usage

Caution

Please note that you will need the Atlas dataset to use this app:

• This app requires the pre-processed explorer-data.json file to display datapoints
• See .processing/create_data.R to process & produce the json data output file

3.1. Prerequisites

1. Install git

   • Instructions on installing git for different platforms can be found here

2. Download the Javascript runtime

   • Install Node.JS and npm - note that installing node would usually install npm alongside it
   • Either download the prebuilt installer here or consider downloading nvm instead to manage your node install

3.2. Cloning

1. Open a terminal and navigate to a directory in which you'd like to install the app, e.g. cd /some/path/to/folder

2. Enter the following into your terminal to clone the repository:

$ git clone https://github.com/JackScanlon/atlas-explorer.git

3.3. Local Development

1. Open a terminal and navigate to the project directory, e.g. cd /path/to/atlas-explorer

2. Install the application dependencies first by running the following:

$ npm install

3. To host the app locally enter the following:

$ npm run dev

3. The application will now be accessible at http://localhost:8000

3.4. Building for Production

1. The following command builds/bundles the app for production into the dist folder:

$ npm run build

2. Enter the following to preview the prod build, and then visit http://localhost:4173

$ npm run preview

4. Notes & Changelog

Note

• The following describes the changes & decisions made to the implementation across meeting(s)

4.1. Initial Plan & Implementation

1. Implement base site

2. Implement base renderer & scene

3. Parse R data

   • Column processing
     • Add: [ORGAN], [CATEGORY], [SEX] etc
   • Output targets
     • Json: jsonify as explorer-data.json
     • Zip: create encrypted archive

4. Parse the JSON data

   • Create clusters of points from categories; need to fake the rotation on cat
   • X / Y is age / prev etc

5. Add three UI/UX buttons

   Button	Functionality
   Search	Search available phenotypes, retarget scene to object
   Camera Reset	Reset camera to scene origin
   Theme Switch	Toggle Light / Dark themes for accessibility

6. Add in ability to interact with objects

   • project 3d->2d
   • hover tooltip render
   • object click to info panel

7. Impl. search functionality

   • Allow search by name, show list of results
   • Selection should zoom + open new panel

8. Camera tween on focus

   • Click world object to zoom (zoom btn also on the panel in case they move away) - need to tween cam towards object

9. Impl. axes

   • Implement basic axes with intention to update later

10. Finalise design

    • Impl. version component
    • Impl. hover effect for button(s)?

4.2. First Meeting & Plan

Tip

• Implementation was discussed & reviewed on 11th November 2024
• It was agreed that changes would be implemented by 19th November 2024; follow-up meeting at 11am on the same date

1. Attempt to render SMR prev / Mortality measure(s)

   • Determine whether incl. in current dataset; if not, send Harry an e-mail
   • Await access to data after discussing with Harry

2. Change branding

   • Remove current branding & apply "Atlas Explorer" title
   • Create new temporary logo in Inkscape

3. UX changes

   • Improve camera tween interp & easing
   • Improve input handling

4. Render step improvements

   • Update tooltip position when tweening if pointer isn't moved

5. Update Tooltip / Version / Search CSS

   • No selection
   • No pointer clickthrough on elements above canvas
   • Ensure context menu & wheel scrolling functions in select / card components
   • Thin scrollbar & theme on searchbar

6. Apply animation to presentation card on display

7. Tween improvements

   • Allow cancellation
   • Camera focus tween dependent on distance travelled

8. Use Hovercard-like interface instead of Tooltip

   • Fix Z-fighting of elements
   • Improve style reactivity
   • Display subset of card information on hover
   • Mini/Maximisable

9. Dataset loading changes

   • Implement spreading

     • Revisit data loader
     • Impl. spreading across angle interval

   • Compute domain & intervals:

     • Intervals for Age
     • Log10 intervals for Frequency

10. Implement new axes

    • Base axes

      • Compute interval
      • Render radial axes in reference to Age field, i.e. 2d circle (line) geometry for each interval
      • Render vertical axes in reference to Frequency field, i.e. 2d line geometry

    • Interaction

      • Use closestPointOnRay instead of closestPointOnCircle - better UX flow on linear axis than radial
      • Track axes intersection to display (x, y) at coordinate along the line on both horizontal & vertical plane(s)

11. Implement header:

    • Await resources for search

    • Filter controls

      • Dropdown component design & responsivity
      • Impl. UI to toggle visibility by Speciality
      • Update shaders to incl. an alpha channel for those toggled
      • Add button to user controls to allow each axes to be toggle individually

12. Update presentation card:

    • Improve card responsivity & layout
    • URL to disease atlas website using slug
    • Add virtualised lists that displays related Phecodes e.g. related organ target

13. Start-up animation

    • Tween scene transform on start-up
    • Welcome banner

14. Mobile UX

    • Touch input(s)

      • ShortPress event to open node menu on touch devices
      • LongPress event to replace Hover behaviour on touch devices

    • User-controls changes...

      • DollyPan / Rotate fixes on touch device
      • Fix viewport issues on iOS
      • Add option to toggle visibility of axis label(s)

15. Iterate point frag shader

    • Improve scaling
    • Selection border color

4.3. Post-review Plan

Tip

• Demonstration on the 19th November with a follow-up meeting planned for early December

1. Text content changes

   Current Text	Replacement Text
   'Phecode'	'Disease'
   'Age'	'Median age at first record'
   'Standardised Mortality Ratio'	'Excess Mortality at one year'
   'Visit Disease Atlas'	'View features in Atlas for Health'
   'View related Phecodes'	'View related diseases by Organ'

2. Card changes

   • Reorder Speciality/Organ/Category at top of card

   • Unminimise when clicking filter button in minimised state

   • Changes to relationship rendering:

     • Alphabetical sort relationships
     • Hide current Phecode in relationship panel

3. Make relationship filter more obvious by adding feature popover?

4. Interaction improvements

   • Fix pointer events on app header
   • No user selection & events on tooltip

5. Add mortality measure to tooltip hover

6. Outline on object when focusing / some other way to highlight it

7. Add axes labels, e.g. (A: 0, F: 0) etc

4.4. Improvements & Fixes

1. gl_points max size varies across implementations, e.g. reference @ here

   • Reimplement points to use instanced plane geometry instead of gl_points
   • Initial raycasting for instanced geometry

2. Use interleaved offset & scale buffer to improve data access on instanced geometry

3. Frustum culling of instanced geometry

   [!NOTE]

   • BVH frustum culling is likely over kill and would require a dynamic buffer; instead we'll implement a basic sphere intersection test

   • Compute world-space bounding box & sphere
   • Implement basic bounding sphere frustum culling

4. Reimplement size attenuation to emulate gl_points behaviour

   • Implement attenuation in vertex shader
   • Implement attenuation in InstancedPoints class

5. Project cleanup

   • Cleanup const. usage across project
   • Cleanup documentation

4.5. Scatter Plot & Improvements

1. Initial work for scatter

   • Data extraction
   • Rework explorer & assoc. instances

2. Impl. scatter plot view

   • Tween points between views via vertex shader
   • Improve data access

3. Impl. base scatter axes via frag; drawing grid on backface of box

4. Impl. spring on tween banner; current impl. isn't very smooth & we can easily reduce a dependency here

5. Add labels to scatter axes

   • Paint crosshair target on selection
   • Scaled axes labels on X/Y/Z
   • Select edges of box on the near plane of camera for each axis

4.6. Thoughts, issues & the future

1. Consider reimplmenting points:

   • Mac devices clamps GL_POINT size much more than other platforms so points look many times smaller; attenuation is much more pronounced when the viewport is close to the subject - see reference @ here
   • Will probably need to render the points to a quad before applying the shader

2. Consider object partitioning, e.g. bounding volume hierarchy, for non-naive instanced point raycasting in InstancedPoints

3. Possible additions during future development

   • Impl. post-process outline for selected objects?
   • Depth of Field for nodes instead of fog? Or maybe just custom fog / blur built into shaders? Unsure

4. Node graph, attempt was made to allow user(s) to view connections by organ / some other categorical data (similar to force directed graph)

   • Issue:

     • Examined the feasibility of using organ targets & other categorical tags to build a connectivity graph;
     • Unfortunately there are far too many connections and they're mostly clustered within their own speciality

   • Future:

     • Need to discuss with HDRUK - there may be other data points not yet available to me that we could use for weights in a FDG
     • Based on my examination, I think it would be better to either (a) display this as an FDG using weights generated from shared symptomatology and/or SNOMED codes; or (b) display the data in a 3D scatter plot +/- some clustering visualisation (e.g. convex hull etc)