@vitessce/config 3.1.3 → 3.2.0

package/dist-tsc/VitessceConfig.js

@@ -97,7 +97,7 @@ export class VitessceConfigDataset {
         };
     }
 }
-function useComplexCoordinationHelper(scopes, coordinationScopes, coordinationScopesBy) {
+function useCoordinationByObjectHelper(scopes, coordinationScopes, coordinationScopesBy) {
     // Set this.coordinationScopes and this.coordinationScopesBy by recursion on `scopes`.
     /*
       // Destructured, `scopes` might look like:
@@ -106,7 +106,7 @@ function useComplexCoordinationHelper(scopes, coordinationScopes, coordinationSc
           {
             scope: imageLayerScope,
             children: {
-              [CoordinationType.IMAGE]: { scope: imageScope },
+              [CoordinationType.FILE_UID]: { scope: imageScope },
               [CoordinationType.SPATIAL_LAYER_VISIBLE]: { scope: imageVisibleScope },
               [CoordinationType.SPATIAL_LAYER_OPACITY]: { scope: imageOpacityScope },
               [CoordinationType.SPATIAL_IMAGE_CHANNEL]: [
@@ -138,7 +138,7 @@ function useComplexCoordinationHelper(scopes, coordinationScopes, coordinationSc
       };
       this.coordinationScopesBy = {
         [CoordinationType.SPATIAL_IMAGE_LAYER]: {
-          [CoordinationType.IMAGE]: {
+          [CoordinationType.FILE_UID]: {
             [imageLayerScope.cScope]: imageScope.cScope,
           },
           [CoordinationType.SPATIAL_LAYER_VISIBLE]: {
@@ -260,14 +260,20 @@ export class VitessceConfigView {
         });
         return this;
     }
-    useComplexCoordination(scopes) {
+    /**
+     * Attach potentially multi-level coordination scopes to this view.
+     * @param {object} scopes A value returned by `VitessceConfig.addCoordinationByObject`.
+     * Not intended to be a manually-constructed object.
+     * @returns {VitessceConfigView} This, to allow chaining.
+     */
+    useCoordinationByObject(scopes) {
         if (!this.view.coordinationScopes) {
             this.view.coordinationScopes = {};
         }
         if (!this.view.coordinationScopesBy) {
             this.view.coordinationScopesBy = {};
         }
-        const [nextCoordinationScopes, nextCoordinationScopesBy] = useComplexCoordinationHelper(scopes, this.view.coordinationScopes, this.view.coordinationScopesBy);
+        const [nextCoordinationScopes, nextCoordinationScopesBy] = useCoordinationByObjectHelper(scopes, this.view.coordinationScopes, this.view.coordinationScopesBy);
         this.view.coordinationScopes = nextCoordinationScopes;
         this.view.coordinationScopesBy = nextCoordinationScopesBy;
         return this;
@@ -364,6 +370,16 @@ export function vconcat(...views) {
 class CoordinationLevel {
     constructor(value) {
         this.value = value;
+        this.cachedValue = null;
+    }
+    setCached(processedLevel) {
+        this.cachedValue = processedLevel;
+    }
+    getCached() {
+        return this.cachedValue;
+    }
+    isCached() {
+        return this.cachedValue !== null;
     }
 }
 export function CL(value) {
@@ -423,27 +439,25 @@ export class VitessceConfigMetaCoordinationScope {
         this.metaScope.setValue(metaScopesVal);
         return this;
     }
-    useComplexCoordination(scopes) {
+    /**
+     * Attach potentially multi-level coordination scopes to this meta coordination
+     * scope instance.
+     * @param {object} scopes A value returned by `VitessceConfig.addCoordinationByObject`.
+     * Not intended to be a manually-constructed object.
+     * @returns {VitessceConfigView} This, to allow chaining.
+     */
+    useCoordinationByObject(scopes) {
         if (!this.metaScope.cValue) {
             this.metaScope.setValue({});
         }
         if (!this.metaByScope.cValue) {
             this.metaByScope.setValue({});
         }
-        const [metaScopesVal, metaByScopesVal] = useComplexCoordinationHelper(scopes, this.metaScope.cValue, this.metaByScope.cValue);
+        const [metaScopesVal, metaByScopesVal] = useCoordinationByObjectHelper(scopes, this.metaScope.cValue, this.metaByScope.cValue);
         this.metaScope.setValue(metaScopesVal);
         this.metaByScope.setValue(metaByScopesVal);
         return this;
     }
-    /**
-     * Set the coordination value of the coordination scope.
-     * @param {any} cValue The value to set.
-     * @returns {VitessceConfigCoordinationScope} This, to allow chaining.
-     */
-    setValue(cValue) {
-        this.cValue = cValue;
-        return this;
-    }
 }
 /**
  * Class representing a Vitessce view config.
@@ -575,6 +589,11 @@ export class VitessceConfig {
         });
         return result;
     }
+    /**
+     * Initialize a new meta coordination scope in the coordination space,
+     * and get a reference to it in the form of a meta coordination scope instance.
+     * @returns {VitessceConfigMetaCoordinationScope} A new meta coordination scope instance.
+     */
     addMetaCoordination() {
         const prevMetaScopes = (this.config.coordinationSpace[CoordinationType.META_COORDINATION_SCOPES]
             ? Object.keys(this.config.coordinationSpace[CoordinationType.META_COORDINATION_SCOPES])
@@ -595,13 +614,26 @@ export class VitessceConfig {
         this.config.coordinationSpace[CoordinationType.META_COORDINATION_SCOPES_BY][metaContainer.metaByScope.cScope] = metaContainer.metaByScope;
         return metaContainer;
     }
-    addComplexCoordination(input) {
+    /**
+     * Set up the initial values for multi-level coordination in the coordination space.
+     * Get a reference to these values to pass to the `useCoordinationByObject` method
+     * of either view or meta coordination scope instances.
+     * @param {object} input A (potentially nested) object with coordination types as keys
+     * and values being either the initial coordination value, a `VitessceConfigCoordinationScope`
+     * instance, or a `CoordinationLevel` instance.
+     * The CL function takes an array of objects as its argument, and returns a CoordinationLevel
+     * instance, to support nesting.
+     * @returns {object} A (potentially nested) object with coordination types as keys and values
+     * being either { scope }, { scope, children }, or an array of these. Not intended to be
+     * manipulated before being passed to a `useCoordinationByObject` function.
+     */
+    addCoordinationByObject(input) {
         /*
           // The value for `input` might look like:
           {
             [CoordinationType.SPATIAL_IMAGE_LAYER]: CL([
               {
-                [CoordinationType.IMAGE]: 'S-1905-017737_bf',
+                [CoordinationType.FILE_UID]: 'S-1905-017737_bf',
                 [CoordinationType.SPATIAL_LAYER_VISIBLE]: true,
                 [CoordinationType.SPATIAL_LAYER_OPACITY]: 1,
                 [CoordinationType.SPATIAL_IMAGE_CHANNEL]: CL([
@@ -618,7 +650,7 @@ export class VitessceConfig {
             ]),
             [CoordinationType.SPATIAL_SEGMENTATION_LAYER]: CL([
               {
-                [CoordinationType.IMAGE]: 'S-1905-017737',
+                [CoordinationType.FILE_UID]: 'S-1905-017737',
                 [CoordinationType.SPATIAL_LAYER_VISIBLE]: true,
                 [CoordinationType.SPATIAL_LAYER_OPACITY]: 1,
                 [CoordinationType.SPATIAL_SEGMENTATION_CHANNEL]: CL([
@@ -642,13 +674,13 @@ export class VitessceConfig {
             ]),
           }
           // Which would correspond to this `output`,
-          // a valid input for `VitessceConfigMetaCoordinationScope.useComplexCoordination()`:
+          // a valid input for `VitessceConfigMetaCoordinationScope.useCoordinationByObject()`:
           {
             [CoordinationType.SPATIAL_IMAGE_LAYER]: [
               {
                 scope: imageLayerScope,
                 children: {
-                  [CoordinationType.IMAGE]: { scope: imageScope },
+                  [CoordinationType.FILE_UID]: { scope: imageScope },
                   [CoordinationType.SPATIAL_LAYER_VISIBLE]: { scope: imageVisibleScope },
                   [CoordinationType.SPATIAL_LAYER_OPACITY]: { scope: imageOpacityScope },
                   [CoordinationType.SPATIAL_IMAGE_CHANNEL]: [
@@ -680,8 +712,11 @@ export class VitessceConfig {
                 // (otherwise assume it is the coordination value).
                 if (nextLevelOrInitialValue instanceof CoordinationLevel) {
                     const nextLevel = nextLevelOrInitialValue.value;
-                    if (Array.isArray(nextLevel)) {
-                        result[cType] = nextLevel.map((nextEl) => {
+                    if (nextLevelOrInitialValue.isCached()) {
+                        result[cType] = nextLevelOrInitialValue.getCached();
+                    }
+                    else if (Array.isArray(nextLevel)) {
+                        const processedLevel = nextLevel.map((nextEl) => {
                             const [dummyScope] = this.addCoordination(cType);
                             // TODO: set a better initial value for dummy cases.
                             dummyScope.setValue('__dummy__');
@@ -690,17 +725,33 @@ export class VitessceConfig {
                                 children: processLevel(nextEl),
                             };
                         });
+                        nextLevelOrInitialValue.setCached(processedLevel);
+                        result[cType] = processedLevel;
                     }
                     else {
-                        throw new Error('Expected CoordinationLevel.value to be an array.');
+                        const nextEl = nextLevel;
+                        const [dummyScope] = this.addCoordination(cType);
+                        // TODO: set a better initial value for dummy cases.
+                        dummyScope.setValue('__dummy__');
+                        const processedLevel = {
+                            scope: dummyScope,
+                            children: processLevel(nextEl),
+                        };
+                        nextLevelOrInitialValue.setCached(processedLevel);
+                        result[cType] = processedLevel;
                     }
                 }
                 else {
                     // Base case.
                     const initialValue = nextLevelOrInitialValue;
-                    const [scope] = this.addCoordination(cType);
-                    scope.setValue(initialValue);
-                    result[cType] = { scope };
+                    if (initialValue instanceof VitessceConfigCoordinationScope) {
+                        result[cType] = { scope: initialValue };
+                    }
+                    else {
+                        const [scope] = this.addCoordination(cType);
+                        scope.setValue(initialValue);
+                        result[cType] = { scope };
+                    }
                 }
             });
             return result;
@@ -731,6 +782,34 @@ export class VitessceConfig {
         }
         return this;
     }
+    /**
+     * A convenience function for setting up multi-level and meta-coordination scopes
+     * across a set of views.
+     * @param {VitessceConfigView[]} views An array of view objects to link together.
+     * @param {object} input A (potentially nested) object with coordination types as keys
+     * and values being either the initial coordination value, a `VitessceConfigCoordinationScope`
+     * instance, or a `CoordinationLevel` instance.
+     * The CL function takes an array of objects as its argument, and returns a CoordinationLevel
+     * instance, to support nesting.
+     * @param {boolean} meta Should meta-coordination be used? Optional. By default, true.
+     * @returns {VitessceConfig} This, to allow chaining.
+     */
+    linkViewsByObject(views, input, meta = true) {
+        const scopes = this.addCoordinationByObject(input);
+        if (meta) {
+            const metaScope = this.addMetaCoordination();
+            metaScope.useCoordinationByObject(scopes);
+            views.forEach((view) => {
+                view.useMetaCoordination(metaScope);
+            });
+        }
+        else {
+            views.forEach((view) => {
+                view.useCoordinationByObject(scopes);
+            });
+        }
+        return this;
+    }
     /**
      * Set the layout of views.
      * @param {VitessceConfigView|VitessceConfigViewHConcat|VitessceConfigViewVConcat} viewConcat A

package/dist-tsc/VitessceConfig.test.js

@@ -243,7 +243,7 @@ describe('src/api/VitessceConfig.js', () => {
                 schemaVersion: '1.0.16',
                 name: 'My config',
             });
-            config.addComplexCoordination({
+            config.addCoordinationByObject({
                 spatialImageLayer: CL([
                     {
                         image: 'S-1905-017737_bf',
@@ -314,7 +314,11 @@ describe('src/api/VitessceConfig.js', () => {
                 name: 'My config',
             });
             const dataset = config.addDataset('My dataset');
-            const scopes = config.addComplexCoordination({
+            // Coordinate all segmentation channels on the same color,
+            // to test out the use of a coordination scope instance as a value.
+            const [colorScope] = config.addCoordination('spatialChannelColor');
+            colorScope.setValue([255, 0, 0]);
+            const scopes = config.addCoordinationByObject({
                 spatialImageLayer: CL([
                     {
                         image: 'S-1905-017737_bf',
@@ -323,11 +327,11 @@ describe('src/api/VitessceConfig.js', () => {
                         spatialImageChannel: CL([
                             {
                                 spatialTargetC: 0,
-                                spatialChannelColor: [255, 0, 0],
+                                spatialChannelColor: [0, 255, 0],
                             },
                             {
                                 spatialTargetC: 1,
-                                spatialChannelColor: [0, 255, 0],
+                                spatialChannelColor: [0, 0, 255],
                             },
                         ]),
                     },
@@ -341,24 +345,24 @@ describe('src/api/VitessceConfig.js', () => {
                             {
                                 obsType: 'Cortical Interstitia',
                                 spatialTargetC: 0,
-                                spatialChannelColor: [255, 0, 0],
+                                spatialChannelColor: colorScope,
                             },
                             {
                                 obsType: 'Non-Globally Sclerotic Glomeruli',
                                 spatialTargetC: 1,
-                                spatialChannelColor: [255, 0, 0],
+                                spatialChannelColor: colorScope,
                             },
                             {
                                 obsType: 'Globally Sclerotic Glomeruli',
                                 spatialTargetC: 2,
-                                spatialChannelColor: [255, 0, 0],
+                                spatialChannelColor: colorScope,
                             },
                         ]),
                     },
                 ]),
             });
             const spatialView = config.addView(dataset, 'spatial');
-            spatialView.useComplexCoordination(scopes);
+            spatialView.useCoordinationByObject(scopes);
             const configJSON = config.toJSON();
             expect(configJSON).toEqual({
                 version: '1.0.16',
@@ -377,9 +381,7 @@ describe('src/api/VitessceConfig.js', () => {
                     spatialChannelColor: {
                         A: [255, 0, 0],
                         B: [0, 255, 0],
-                        C: [255, 0, 0],
-                        D: [255, 0, 0],
-                        E: [255, 0, 0],
+                        C: [0, 0, 255],
                     },
                     spatialSegmentationLayer: { A: '__dummy__' },
                     spatialSegmentationChannel: { A: '__dummy__', B: '__dummy__', C: '__dummy__' },
@@ -405,7 +407,7 @@ describe('src/api/VitessceConfig.js', () => {
                             },
                             spatialImageChannel: {
                                 spatialTargetC: { A: 'A', B: 'B' },
-                                spatialChannelColor: { A: 'A', B: 'B' },
+                                spatialChannelColor: { A: 'B', B: 'C' },
                             },
                             spatialSegmentationLayer: {
                                 image: { A: 'B' },
@@ -416,7 +418,7 @@ describe('src/api/VitessceConfig.js', () => {
                             spatialSegmentationChannel: {
                                 obsType: { A: 'A', B: 'B', C: 'C' },
                                 spatialTargetC: { A: 'C', B: 'D', C: 'E' },
-                                spatialChannelColor: { A: 'C', B: 'D', C: 'E' },
+                                spatialChannelColor: { A: 'A', B: 'A', C: 'A' },
                             },
                         },
                         x: 0,
@@ -433,7 +435,7 @@ describe('src/api/VitessceConfig.js', () => {
                 name: 'My config',
             });
             const dataset = config.addDataset('My dataset');
-            const scopes = config.addComplexCoordination({
+            const scopes = config.addCoordinationByObject({
                 spatialImageLayer: CL([
                     {
                         image: 'S-1905-017737_bf',
@@ -477,7 +479,7 @@ describe('src/api/VitessceConfig.js', () => {
                 ]),
             });
             const metaCoordinationScope = config.addMetaCoordination();
-            metaCoordinationScope.useComplexCoordination(scopes);
+            metaCoordinationScope.useCoordinationByObject(scopes);
             const spatialView = config.addView(dataset, 'spatial');
             const lcView = config.addView(dataset, 'layerController');
             spatialView.useMetaCoordination(metaCoordinationScope);
@@ -565,6 +567,140 @@ describe('src/api/VitessceConfig.js', () => {
                 initStrategy: 'auto',
             });
         });
+        it('can use _meta_ complex coordination via the linkViewsByObject convenience function', () => {
+            const config = new VitessceConfig({
+                schemaVersion: '1.0.16',
+                name: 'My config',
+            });
+            const dataset = config.addDataset('My dataset');
+            const spatialView = config.addView(dataset, 'spatial');
+            const lcView = config.addView(dataset, 'layerController');
+            config.linkViewsByObject([spatialView, lcView], {
+                spatialImageLayer: CL([
+                    {
+                        image: 'S-1905-017737_bf',
+                        spatialLayerVisible: true,
+                        spatialLayerOpacity: 1,
+                        spatialImageChannel: CL([
+                            {
+                                spatialTargetC: 0,
+                                spatialChannelColor: [255, 0, 0],
+                            },
+                            {
+                                spatialTargetC: 1,
+                                spatialChannelColor: [0, 255, 0],
+                            },
+                        ]),
+                    },
+                ]),
+                spatialSegmentationLayer: CL([
+                    {
+                        image: 'S-1905-017737',
+                        spatialLayerVisible: true,
+                        spatialLayerOpacity: 1,
+                        spatialSegmentationChannel: CL([
+                            {
+                                obsType: 'Cortical Interstitia',
+                                spatialTargetC: 0,
+                                spatialChannelColor: [255, 0, 0],
+                            },
+                            {
+                                obsType: 'Non-Globally Sclerotic Glomeruli',
+                                spatialTargetC: 1,
+                                spatialChannelColor: [255, 0, 0],
+                            },
+                            {
+                                obsType: 'Globally Sclerotic Glomeruli',
+                                spatialTargetC: 2,
+                                spatialChannelColor: [255, 0, 0],
+                            },
+                        ]),
+                    },
+                ]),
+            });
+            const configJSON = config.toJSON();
+            expect(configJSON).toEqual({
+                version: '1.0.16',
+                name: 'My config',
+                datasets: [{ uid: 'A', name: 'My dataset', files: [] }],
+                coordinationSpace: {
+                    dataset: { A: 'A' },
+                    spatialImageLayer: { A: '__dummy__' },
+                    image: { A: 'S-1905-017737_bf', B: 'S-1905-017737' },
+                    spatialLayerVisible: { A: true, B: true },
+                    spatialLayerOpacity: { A: 1, B: 1 },
+                    spatialImageChannel: { A: '__dummy__', B: '__dummy__' },
+                    spatialTargetC: {
+                        A: 0, B: 1, C: 0, D: 1, E: 2,
+                    },
+                    spatialChannelColor: {
+                        A: [255, 0, 0],
+                        B: [0, 255, 0],
+                        C: [255, 0, 0],
+                        D: [255, 0, 0],
+                        E: [255, 0, 0],
+                    },
+                    spatialSegmentationLayer: { A: '__dummy__' },
+                    spatialSegmentationChannel: { A: '__dummy__', B: '__dummy__', C: '__dummy__' },
+                    obsType: {
+                        A: 'Cortical Interstitia',
+                        B: 'Non-Globally Sclerotic Glomeruli',
+                        C: 'Globally Sclerotic Glomeruli',
+                    },
+                    metaCoordinationScopes: {
+                        A: {
+                            spatialImageLayer: ['A'],
+                            spatialSegmentationLayer: ['A'],
+                        },
+                    },
+                    metaCoordinationScopesBy: {
+                        A: {
+                            spatialImageLayer: {
+                                image: { A: 'A' },
+                                spatialLayerVisible: { A: 'A' },
+                                spatialLayerOpacity: { A: 'A' },
+                                spatialImageChannel: { A: ['A', 'B'] },
+                            },
+                            spatialImageChannel: {
+                                spatialTargetC: { A: 'A', B: 'B' },
+                                spatialChannelColor: { A: 'A', B: 'B' },
+                            },
+                            spatialSegmentationLayer: {
+                                image: { A: 'B' },
+                                spatialLayerVisible: { A: 'B' },
+                                spatialLayerOpacity: { A: 'B' },
+                                spatialSegmentationChannel: { A: ['A', 'B', 'C'] },
+                            },
+                            spatialSegmentationChannel: {
+                                obsType: { A: 'A', B: 'B', C: 'C' },
+                                spatialTargetC: { A: 'C', B: 'D', C: 'E' },
+                                spatialChannelColor: { A: 'C', B: 'D', C: 'E' },
+                            },
+                        },
+                    },
+                },
+                layout: [{
+                        component: 'spatial',
+                        coordinationScopes: {
+                            dataset: 'A',
+                            metaCoordinationScopes: ['A'],
+                            metaCoordinationScopesBy: ['A'],
+                        },
+                        // eslint-disable-next-line object-property-newline
+                        x: 0, y: 0, w: 1, h: 1,
+                    }, {
+                        component: 'layerController',
+                        coordinationScopes: {
+                            dataset: 'A',
+                            metaCoordinationScopes: ['A'],
+                            metaCoordinationScopesBy: ['A'],
+                        },
+                        // eslint-disable-next-line object-property-newline
+                        x: 0, y: 0, w: 1, h: 1,
+                    }],
+                initStrategy: 'auto',
+            });
+        });
         it('can add a coordination scope using the link views convenience function', () => {
             const config = new VitessceConfig({
                 schemaVersion: '1.0.4',

package/dist-tsc/index.d.ts

@@ -1,4 +1,4 @@
-export { VitessceConfig, vconcat, hconcat } from "./VitessceConfig.js";
+export { VitessceConfig, vconcat, hconcat, CL as CoordinationLevel } from "./VitessceConfig.js";
 export { generateConfig, getHintOptions } from "./VitessceAutoConfig.js";
 export { HINTS_CONFIG, HINT_TYPE_TO_FILE_TYPE_MAP } from "./constants.js";
 //# sourceMappingURL=index.d.ts.map

package/dist-tsc/index.js

@@ -1,3 +1,3 @@
-export { VitessceConfig, vconcat, hconcat } from './VitessceConfig.js';
+export { VitessceConfig, vconcat, hconcat, CL as CoordinationLevel } from './VitessceConfig.js';
 export { generateConfig, getHintOptions } from './VitessceAutoConfig.js';
 export { HINTS_CONFIG, HINT_TYPE_TO_FILE_TYPE_MAP } from './constants.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitessce/config",
-  "version": "3.1.3",
+  "version": "3.2.0",
   "author": "Gehlenborg Lab",
   "homepage": "http://vitessce.io",
   "repository": {
@@ -16,8 +16,8 @@
     "dist-tsc"
   ],
   "dependencies": {
-    "@vitessce/constants-internal": "3.1.3",
-    "@vitessce/utils": "3.1.3"
+    "@vitessce/constants-internal": "3.2.0",
+    "@vitessce/utils": "3.2.0"
   },
   "scripts": {
     "bundle": "pnpm exec vite build -c ../../scripts/vite.config.js",