@vitessce/config 3.1.3 → 3.2.0

package/src/VitessceConfig.js

@@ -102,7 +102,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:
@@ -111,7 +111,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]: [
@@ -143,7 +143,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]: {
@@ -278,14 +278,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(
+    const [nextCoordinationScopes, nextCoordinationScopesBy] = useCoordinationByObjectHelper(
       scopes,
       this.view.coordinationScopes,
       this.view.coordinationScopesBy,
@@ -396,6 +402,19 @@ 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;
   }
 }
 
@@ -467,14 +486,21 @@ export class VitessceConfigMetaCoordinationScope {
     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(
+    const [metaScopesVal, metaByScopesVal] = useCoordinationByObjectHelper(
       scopes,
       this.metaScope.cValue,
       this.metaByScope.cValue,
@@ -483,16 +509,6 @@ export class VitessceConfigMetaCoordinationScope {
     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;
-  }
 }
 
 /**
@@ -635,6 +651,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]
@@ -663,13 +684,26 @@ export class VitessceConfig {
     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([
@@ -686,7 +720,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([
@@ -710,13 +744,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]: [
@@ -748,8 +782,10 @@ 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__');
@@ -758,15 +794,30 @@ 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;
@@ -799,6 +850,35 @@ 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/src/VitessceConfig.test.js

@@ -269,7 +269,7 @@ describe('src/api/VitessceConfig.js', () => {
         schemaVersion: '1.0.16',
         name: 'My config',
       });
-      config.addComplexCoordination({
+      config.addCoordinationByObject({
         spatialImageLayer: CL([
           {
             image: 'S-1905-017737_bf',
@@ -342,7 +342,14 @@ describe('src/api/VitessceConfig.js', () => {
       });
       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',
@@ -351,11 +358,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],
               },
             ]),
           },
@@ -369,17 +376,17 @@ 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,
               },
             ]),
           },
@@ -387,7 +394,7 @@ describe('src/api/VitessceConfig.js', () => {
       });
 
       const spatialView = config.addView(dataset, 'spatial');
-      spatialView.useComplexCoordination(scopes);
+      spatialView.useCoordinationByObject(scopes);
 
       const configJSON = config.toJSON();
       expect(configJSON).toEqual({
@@ -407,9 +414,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__' },
@@ -435,7 +440,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' },
@@ -446,7 +451,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,
@@ -465,7 +470,7 @@ describe('src/api/VitessceConfig.js', () => {
       });
       const dataset = config.addDataset('My dataset');
 
-      const scopes = config.addComplexCoordination({
+      const scopes = config.addCoordinationByObject({
         spatialImageLayer: CL([
           {
             image: 'S-1905-017737_bf',
@@ -510,7 +515,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');
@@ -601,6 +606,144 @@ describe('src/api/VitessceConfig.js', () => {
       });
     });
 
+    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/src/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';