feat(editor): example of composing multiple tracks within one spatial view (#1147)

* wip: combining multiple tracks within a single spatial view

very very bad so far, just a first checkpoint toward something sorta working

* feat: add a new example for superimposition

* wip: multiple overlaid track

* feat: (wip)example for composing multiple tracks within one spatial view

touches the join implementation a bit

* chore: remove computation of parent views

* chore: clean up of unused properties

* chore: clean up (log, unused var)

* chore: delete commented line

* chore: delete log and commented out line

Author: dvdkouril

editor/example/index.ts

@@ -453,6 +453,12 @@ export const editorExampleObj: {
         image: THUMBNAILS.SPATIAL_YEAST,
         forceShow: true
     },
+    SPATIAL_LAYOUT_SUPERIMP: {
+        group: 'Spatial Layout',
+        name: 'Multiple tracks',
+        spec: JsonExampleSpecs.EX_SPEC_SPATIAL_MULTIPLE_TRACKS,
+        image: THUMBNAILS.SPATIAL_MULTIPLE_TRACKS
+    },
     CORCES_ET_AL: {
         group: 'Coordinated Multiple Views',
         name: 'Corces et al. 2020',

editor/example/json-spec/3d-yeast-model.ts

@@ -95,12 +95,13 @@ export const EX_SPEC_3D_YEAST_MODEL: GoslingSpec = {
     layout: { ...spatialLayoutDef },
     views: [
         {
-            tracks: [{ ...base, height: trackWidth }]
+            tracks: [{ ...base, mark: "sphere", height: trackWidth }]
         },
         {
             tracks: [
                 {
                     ...base,
+                    mark: "sphere",
                     data: undefined,
                     color: { field: 'chr', type: 'nominal', range: colors },
                     height: trackWidth

editor/example/json-spec/spatial-layout.ts

@@ -163,37 +163,128 @@ export const EX_SPEC_SPATIAL_MULTIPLE_TRACKS: GoslingSpec = {
                 type: 'spatial',
                 model: {
                     type: 'csv',
-                    url: 'https://raw.githubusercontent.com/dvdkouril/chromospace-sample-data/main/gosling-3d/yeast_model.csv',
+                    url: 'https://raw.githubusercontent.com/dvdkouril/chromospace-sample-data/refs/heads/main/gosling-3d/stevens-2017/full-model.csv',
                     xyz: ['x', 'y', 'z'],
                     chromosome: 'chr',
                     position: 'coord'
                 }
             },
+            width: 500,
+            height: 500,
+            alignment: "overlay",
+            tracks: [
+                {
+                    color: {
+                        value: 'gainsboro'
+                    },
+                    size: {
+                        value: 0.005,
+                    },
+                    mark: 'sphere',
+                },
+                {
+                    color: {
+                        value: 'darkslateblue'
+                    },
+                    size: {
+                        value: 0.02,
+                    },
+                    mark: 'box',
+                    dataTransform: [{
+                        type: "filter",
+                        field: "chr",
+                        oneOf: ["chr b"],
+                    }],
+                },
+                {
+                    color: {
+                        value: 'darkseagreen'
+                    },
+                    size: {
+                        value: 0.02,
+                    },
+                    mark: 'octahedron',
+                    dataTransform: [{
+                        type: "filter",
+                        field: "chr",
+                        oneOf: ["chr a"],
+                    }],
+                }
+            ]
+        }
+    ]
+};
+
+export const EX_SPEC_SPATIAL_SUPERIMPOSITION: GoslingSpec = {
+    title: 'Spatial Layout: superimposition',
+    views: [
+        {
+            layout: 'spatial',
             tracks: [
                 {
                     data: {
                         type: 'csv',
-                        url: 'https://raw.githubusercontent.com/dvdkouril/chromospace-sample-data/main/gosling-3d/yeast_model.csv'
+                        url: 'https://raw.githubusercontent.com/dvdkouril/chromospace-sample-data/main/gosling-3d/yeast_model.csv',
+                    },
+                    spatial: {
+                        x: "x",
+                        y: "y",
+                        z: "z",
+                        chr: "chr",
+                        coord: "coord",
                     },
                     color: {
-                        value: '#ffffff'
+                        value: "#ff0000",
+                    },
+                    size: {
+                        value: 0.01,
                     },
                     width: 500,
                     height: 500
                 },
                 {
                     data: {
                         type: 'csv',
-                        url: 'https://raw.githubusercontent.com/dvdkouril/chromospace-sample-data/main/gosling-3d/yeast_model_only_one_chromosome.csv'
+                        url: 'https://raw.githubusercontent.com/dvdkouril/chromospace-sample-data/refs/heads/main/gosling-3d/stevens-2017/single_chromosome.csv',
+                    },
+                    spatial: {
+                        x: "x",
+                        y: "y",
+                        z: "z",
+                        chr: "chr",
+                        coord: "coord",
                     },
                     color: {
-                        value: '#ffffff'
+                        value: "#00ff00",
+                    },
+                    size: {
+                        value: 0.01,
+                    },
+                    width: 500,
+                    height: 500
+                },
+                {
+                    data: {
+                        type: 'csv',
+                        url: 'https://raw.githubusercontent.com/dvdkouril/chromospace-sample-data/refs/heads/main/gosling-3d/stevens-2017/single_chromosome.csv',
+                    },
+                    spatial: {
+                        x: "x",
+                        y: "y",
+                        z: "z",
+                        chr: "chr",
+                        coord: "coord",
+                    },
+                    color: {
+                        value: "#0000ff",
+                    },
+                    size: {
+                        value: 0.01,
                     },
-                    mark: 'box',
                     width: 500,
                     height: 500
                 }
             ]
         }
-    ]
+    ],
 };

editor/example/thumbnails.ts

@@ -34,6 +34,7 @@ import SPATIAL_MINIMAL from './thumbnails/SPATIAL_MINIMAL.png';
 import SPATIAL_YEAST from './thumbnails/SPATIAL_YEAST.png';
 import SPATIAL_COLOR from './thumbnails/SPATIAL_COLOR.png';
 import SPATIAL_DENSITY from './thumbnails/SPATIAL_DENSITY.png';
+import SPATIAL_MULTIPLE_TRACKS from './thumbnails/SPATIAL_MULTIPLE_TRACKS.png';
 
 export const THUMBNAILS = {
     ALIGNMENT,
@@ -72,4 +73,5 @@ export const THUMBNAILS = {
     SPATIAL_YEAST,
     SPATIAL_COLOR,
     SPATIAL_DENSITY,
+    SPATIAL_MULTIPLE_TRACKS,
 };

editor/example/thumbnails/SPATIAL_MULTIPLE_TRACKS.png

@@ -62,7 +62,7 @@
     "allotment": "^1.19.0",
     "bezier-js": "4.0.3",
     "buffer": "^6.0.3",
-    "chromospace": "^0.1.6",
+    "chromospace": "^0.1.7",
     "css-element-queries": "^1.2.3",
     "d3-array": "^3.2.4",
     "d3-brush": "^3.0.0",

package.json

@@ -34,7 +34,7 @@ export function _fixTrackToWalkaround(t: Track) {
         }
 
         // @ts-expect-error
-        t.dataTransform = [{ ...dataTransform, to }];
+        t.dataTransform = [{ ...dataTransform, to }, ...(t.dataTransform ?? [])];
         t.layout = 'spatial';
     } else if (typeof layout == 'object') {
         t.layout = layout.type;

pnpm-lock.yaml

@@ -5,6 +5,25 @@ import { tableFromArrays, tableFromIPC, tableToIPC } from '@uwdata/flechette';
 import { transform } from '../../core/utils/data-transform';
 import { getTabularData } from '../gosling-track/data-abstraction';
 
+/**
+ * Make an assertion.
+ *
+ * Usage
+ * @example
+ * ```ts
+ * const value: boolean = Math.random() <= 0.5;
+ * assert(value, "value is greater than than 0.5!");
+ * value // true
+ * ```
+ *
+ * @copyright Trevor Manz 2025
+ * @license MIT
+ * @see {@link https://github.com/manzt/manzt/blob/f7faee/utils/assert.js}
+ */
+export function assert(expression: unknown, msg: string | undefined = ""): asserts expression {
+    if (!expression) throw new Error(msg);
+}
+
 export type SpatialTrackOptions = {
     spec: SingleTrack | OverlaidTrack;
     color: string | undefined;
@@ -25,10 +44,10 @@ async function transformObjectToArrow(t: LoadedTiles, options: SpatialTrackOptio
     // So, create one if missing by running `getTabularData()`.
     // The tile ID of '0.0' extracts all data for a given file at the lowest resolution.
     let tabularData = t['0.0'].tabularData ?? getTabularData(options.spec, t['0.0']);
-    if (options.spec.dataTransform?.[0]) {
-        // This basically ensures to do join operation (e.g., combining bigwig data to 3D model)
-        tabularData = await transform(options.spec.dataTransform?.[0], tabularData, undefined, options.spec.assembly);
-        console.error('Joined Data', tabularData);
+
+    tabularData = structuredClone(tabularData);
+    for (const t of options.spec.dataTransform ?? []) {
+        tabularData = await transform(t, tabularData, undefined, options.spec.assembly);
     }
     const xArr: number[] = [];
     const yArr: number[] = [];
@@ -227,27 +246,10 @@ function handleSizeField(size?: ChannelValue | Size | number, arrowIpc: Uint8Arr
     }
 }
 
-/**
- * The idea is to "cache" scenes associated with particular `views`.
- */
-const spatialViewsMap = new Map<string, chs.ChromatinScene>();
-
-function fetchScene(viewsScenesMap: Map<string, chs.ChromatinScene>, viewId: string): chs.ChromatinScene {
-    const s = viewsScenesMap.get(viewId);
-
-    if (!s) {
-        const newScene = chs.initScene();
-        viewsScenesMap.set(viewId, newScene);
-        return newScene;
-    }
-
-    return s;
-}
-
 export function createSpatialTrack(
     options: SpatialTrackOptions,
     dataFetcher: CsvDataFetcherClass,
-    container: HTMLDivElement
+    container: HTMLDivElement,
 ) {
     console.log('SPEC OPTIONS', options);
     dataFetcher.tilesetInfo(info => {
@@ -260,37 +262,49 @@ export function createSpatialTrack(
                     // This information is needed to create tabular data (i.e., running getTabularData())
                     t['0.0'].tileWidth = info.max_width;
                 }
+
                 const ipcBuffer = await transformObjectToArrow(t, options);
-                if (ipcBuffer) {
-                    const viewId = '123'; //~ TODO: need to actually get the ID of the view parent of this track
-                    let chromatinScene = fetchScene(spatialViewsMap, viewId);
-                    //let chromatinScene = chs.initScene();
-                    const arrowIpc = ipcBuffer.buffer;
-                    const color = handleColorField(options.spec.color, arrowIpc);
-                    const scale = handleSizeField(options.spec.size, arrowIpc);
-                    console.log('scale config', scale);
+                if (!ipcBuffer) {
+                    console.error("could not tranform into Apache Arrow");
+                    return;
+                }
+                console.warn("spec", options.spec);
+                let chromatinScene = chs.initScene();
+                const tracks = options.spec._overlay ?? [options.spec];
+                for (const ov of tracks) {
+                    console.log("ov", ov);
+
+                    const color = handleColorField(ov.color, ipcBuffer.buffer);
+                    const scale = handleSizeField(ov.size, ipcBuffer.buffer);
                     const viewConfig = {
                         scale: scale,
                         color: color,
-                        mark: options.spec.mark
+                        mark: ov.mark
                     };
-                    console.log('viewConfig', viewConfig);
-                    const s = chs.load(ipcBuffer.buffer, { center: true, normalize: true });
 
-                    const result = s;
+                    let s = chs.load(ipcBuffer.buffer, { center: true, normalize: true });
 
-                    const isModel = 'parts' in result; //~ ChromatinModel has .parts
-                    console.log(`isModel: ${isModel}`);
+                    const isModel = "parts" in s; //~ ChromatinModel has .parts
                     if (isModel) {
-                        chromatinScene = chs.addModelToScene(chromatinScene, result, viewConfig);
+                        const filterTransform = (ov.dataTransform ?? []).find(t => t.type === "filter");
+                        if (filterTransform) {
+                            const field: string = filterTransform.field;
+                            assert(field === "chr", "Field for transform should be 'chr'");
+                            const oneOf = filterTransform.oneOf;
+                            const first = oneOf[0];
+                            const res = chs.get(s, first)!;
+                            if (res) {
+                                const [selectedModel, _] = res;
+                                s = { parts: [selectedModel] };
+                            }
+                        }
+                        chromatinScene = chs.addModelToScene(chromatinScene, s, viewConfig);
                     } else {
-                        chromatinScene = chs.addChunkToScene(chromatinScene, result, viewConfig);
+                        chromatinScene = chs.addChunkToScene(chromatinScene, s, viewConfig);
                     }
-                    const [_, canvas] = chs.display(chromatinScene, { alwaysRedraw: false });
-
-                    container.appendChild(canvas);
-                } else {
                 }
+                const [_, createdCanvas] = chs.display(chromatinScene, { alwaysRedraw: false, withHUD: false });
+                container.appendChild(createdCanvas);
             },
             ['0.0']
         );