@vitessce/config 3.0.0 → 3.1.0

package/dist-tsc/VitessceAutoConfig.d.ts

@@ -1,2 +1,14 @@
-export function generateConfigs(fileUrls: any): Promise<object>;
+/**
+ * Returns the hints that are available for the given file URLs, depending on their types.
+ * @param {Array} fileUrls containing urls of files to be loaded into Vitessce
+ * @returns the hints available for these file URLs
+ */
+export function getHintOptions(fileUrls: any[]): any;
+/**
+ *
+ * @param {Array} fileUrls containing urls of files to be loaded into Vitessce
+ * @param {String} the hints config to be used for the dataset. Null by default
+ * @returns ViewConfig as JSON
+ */
+export function generateConfig(fileUrls: any[], hintTitle?: null): Promise<object>;
 //# sourceMappingURL=VitessceAutoConfig.d.ts.map

package/dist-tsc/VitessceAutoConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VitessceAutoConfig.d.ts","sourceRoot":"","sources":["../src/VitessceAutoConfig.js"],"names":[],"mappings":"AAqWA,gEAwBC"}
+{"version":3,"file":"VitessceAutoConfig.d.ts","sourceRoot":"","sources":["../src/VitessceAutoConfig.js"],"names":[],"mappings":"AA+jBA;;;;GAIG;AACH,qDAgBC;AAED;;;;;GAKG;AACH,mFA8CC"}

package/dist-tsc/VitessceAutoConfig.js

@@ -1,5 +1,32 @@
-import { CoordinationType, FileType } from '@vitessce/constants-internal';
+import { CoordinationType as ct, FileType } from '@vitessce/constants-internal';
 import { VitessceConfig, } from './VitessceConfig.js';
+import { HINTS_CONFIG, HINT_TYPE_TO_FILE_TYPE_MAP } from './constants.js';
+/**
+ * @param {Object} hintsConfig. The hints config for the given dataset.
+ *
+ * @param {Array} possibleViews. All views for a given file type, supported by the dataset.
+ * The array contains arrays of strings, each of size >= 1, where the first element of each string
+ * is a VitessceConfig view name ('description', 'spatial', 'layerController', etc.)
+ *
+ * @returns {Array of strings} the intersection of VitessceConfig view names in
+ * possibleViews and requiredViews.
+ */
+const filterViews = (hintsConfig, possibleViews) => {
+    const requiredViews = Object.keys(hintsConfig.views);
+    if (requiredViews.length === 0) {
+        return possibleViews;
+    }
+    const resultViews = [];
+    requiredViews.forEach((requiredView) => {
+        const match = possibleViews.find(possibleView => possibleView[0] === requiredView);
+        if (match)
+            resultViews.push(match);
+    });
+    if (resultViews.length === 0) {
+        throw new Error('No views found that are compatible with the supplied dataset URLs and hint.');
+    }
+    return resultViews;
+};
 class AbstractAutoConfig {
     async composeViewsConfig() {
         throw new Error('The composeViewsConfig() method has not been implemented.');
@@ -15,12 +42,8 @@ class OmeTiffAutoConfig extends AbstractAutoConfig {
         this.fileType = FileType.RASTER_JSON;
         this.fileName = fileUrl.split('/').at(-1);
     }
-    async composeViewsConfig() {
-        return [
-            ['description'],
-            ['spatial'],
-            ['layerController'],
-        ];
+    async composeViewsConfig(hintsConfig) {
+        return filterViews(hintsConfig, [['description'], ['spatial'], ['layerController']]);
     }
     async composeFileConfig() {
         return {
@@ -49,13 +72,8 @@ class OmeZarrAutoConfig extends AbstractAutoConfig {
         this.fileType = FileType.RASTER_OME_ZARR;
         this.fileName = fileUrl.split('/').at(-1);
     }
-    async composeViewsConfig() {
-        return [
-            ['description'],
-            ['spatial'],
-            ['layerController'],
-            ['status'],
-        ];
+    async composeViewsConfig(hintsConfig) {
+        return filterViews(hintsConfig, [['description'], ['spatial'], ['layerController']]);
     }
     async composeFileConfig() {
         return {
@@ -99,7 +117,7 @@ class AnndataZarrAutoConfig extends AbstractAutoConfig {
             }
         });
         const supportedObsSetsKeys = [
-            'cluster', 'subcluster', 'cell_type', 'leiden', 'louvain', 'disease', 'organism', 'self_reported_ethnicity', 'tissue', 'sex',
+            'cluster', 'clusters', 'subcluster', 'cell_type', 'celltype', 'leiden', 'louvain', 'disease', 'organism', 'self_reported_ethnicity', 'tissue', 'sex',
         ];
         this.metadataSummary.obs.forEach((key) => {
             supportedObsSetsKeys.forEach((supportedKey) => {
@@ -118,6 +136,18 @@ class AnndataZarrAutoConfig extends AbstractAutoConfig {
                 }
             });
         });
+        // if length of path is 1, storing the value as an array doesn't work
+        // es-lint-disable-next-line max-len
+        // Example: https://s3.amazonaws.com/vitessce-data/0.0.33/main/human-lymph-node-10x-visium/human_lymph_node_10x_visium.h5ad.zarr
+        options.obsSets = options.obsSets?.map((obsSet) => {
+            if (obsSet.path.length === 1) {
+                return {
+                    ...obsSet,
+                    path: obsSet.path[0],
+                };
+            }
+            return obsSet;
+        });
         return {
             options,
             fileType: this.fileType,
@@ -129,77 +159,140 @@ class AnndataZarrAutoConfig extends AbstractAutoConfig {
             },
         };
     }
-    async composeViewsConfig() {
+    async composeViewsConfig(hintsConfig) {
         this.metadataSummary = await this.setMetadataSummary();
-        const views = [];
+        const possibleViews = [];
         const hasCellSetData = this.metadataSummary.obs
-            .filter(key => key.toLowerCase().includes('cluster') || key.toLowerCase().includes('cell_type'));
+            .filter(key => key.toLowerCase().includes('cluster')
+            || key.toLowerCase().includes('cell_type')
+            || key.toLowerCase().includes('celltype'));
         if (hasCellSetData.length > 0) {
-            views.push(['obsSets']);
+            possibleViews.push(['obsSets']);
         }
         this.metadataSummary.obsm.forEach((key) => {
             if (key.toLowerCase().includes('obsm/x_umap')) {
-                views.push(['scatterplot', { mapping: 'UMAP' }]);
+                possibleViews.push(['scatterplot', { mapping: 'UMAP' }]);
             }
             if (key.toLowerCase().includes('obsm/x_tsne')) {
-                views.push(['scatterplot', { mapping: 't-SNE' }]);
+                possibleViews.push(['scatterplot', { mapping: 't-SNE' }]);
             }
             if (key.toLowerCase().includes('obsm/x_pca')) {
-                views.push(['scatterplot', { mapping: 'PCA' }]);
+                possibleViews.push(['scatterplot', { mapping: 'PCA' }]);
             }
             if (key.toLowerCase().includes(('obsm/x_segmentations'))) {
-                views.push(['layerController']);
+                possibleViews.push(['layerController']);
             }
             if (key.toLowerCase().includes(('obsm/x_spatial'))) {
-                views.push(['spatial']);
+                possibleViews.push(['spatial']);
             }
         });
+        possibleViews.push(['obsSetSizes']);
+        possibleViews.push(['obsSetFeatureValueDistribution']);
         if (this.metadataSummary.X) {
-            views.push(['heatmap']);
-            views.push(['featureList']);
+            possibleViews.push(['heatmap']);
+            possibleViews.push(['featureList']);
         }
+        const views = filterViews(hintsConfig, possibleViews);
         return views;
     }
+    async setMetadataSummaryWithZmetadata(response) {
+        const metadataFile = await response.json();
+        if (!metadataFile.metadata) {
+            throw new Error('Could not generate config: .zmetadata file is not valid.');
+        }
+        const obsmKeys = Object.keys(metadataFile.metadata)
+            .filter(key => key.startsWith('obsm/X_'))
+            .map(key => key.split('/.zarray')[0]);
+        const obsKeysArr = Object.keys(metadataFile.metadata)
+            .filter(key => key.startsWith('obs/')).map(key => key.split('/.za')[0]);
+        function uniq(a) {
+            return a.sort().filter((item, pos, ary) => !pos || item !== ary[pos - 1]);
+        }
+        const obsKeys = uniq(obsKeysArr);
+        const X = Object.keys(metadataFile.metadata).filter(key => key.startsWith('X'));
+        return {
+            // Array of keys in obsm that are found by the fetches above
+            obsm: obsmKeys,
+            // Array of keys in obs that are found by the fetches above
+            obs: obsKeys,
+            // Boolean indicating whether the X array was found by the fetches above
+            X: X.length > 0,
+        };
+    }
+    async setMetadataSummaryWithoutZmetadata() {
+        const knownMetadataFileSuffixes = [
+            '/obsm/X_pca/.zarray',
+            '/obsm/X_umap/.zarray',
+            '/obsm/X_tsne/.zarray',
+            '/obsm/X_spatial/.zarray',
+            '/obsm/X_segmentations/.zarray',
+            '/obs/.zattrs',
+            '/X/.zarray',
+            '/X/data/.zarray', // for https://s3.amazonaws.com/vitessce-data/0.0.33/main/human-lymph-node-10x-visium/human_lymph_node_10x_visium.h5ad.zarr
+        ];
+        const getObsmKey = (url) => {
+            // Get the substring "X_pca" from a URL like
+            // http://example.com/foo/adata.zarr/obsm/X_pca/.zarray
+            const obsmKeyStartIndex = `${this.fileUrl}/`.length;
+            const obsmKeyEndIndex = url.length - '/.zarray'.length;
+            return url.substring(obsmKeyStartIndex, obsmKeyEndIndex);
+        };
+        const promises = knownMetadataFileSuffixes.map(suffix => fetch(`${this.fileUrl}${suffix}`));
+        const fetchResults = await Promise.all(promises);
+        const okFetchResults = fetchResults.filter(j => j.ok);
+        const metadataSummary = {
+            // Array of keys in obsm that are found by the fetches above
+            obsm: [],
+            // Array of keys in obs that are found by the fetches above
+            obs: [],
+            // Boolean indicating whether the X array was found by the fetches above
+            X: false,
+        };
+        const obsPromiseResult = okFetchResults.find(r => r.url === (`${this.fileUrl}/obs/.zattrs`));
+        const isObsValid = obsAttr => Object.keys(obsAttr).includes('column-order')
+            && Object.keys(obsAttr).includes('encoding-version')
+            && Object.keys(obsAttr).includes('encoding-type')
+            && obsAttr['encoding-type'] === 'dataframe'
+            && (obsAttr['encoding-version'] === '0.1.0' || obsAttr['encoding-version'] === '0.2.0');
+        if (obsPromiseResult) {
+            const obsAttrs = await obsPromiseResult.json();
+            if (isObsValid(obsAttrs)) {
+                obsAttrs['column-order'].forEach(key => metadataSummary.obs.push(`obs/${key}`));
+            }
+            else {
+                throw new Error('Could not generate config: /obs/.zattrs file is not valid.');
+            }
+        }
+        okFetchResults
+            .forEach((r) => {
+            if (r.url.startsWith(`${this.fileUrl}/obsm`)) {
+                const obsmKey = getObsmKey(r.url);
+                if (obsmKey) {
+                    metadataSummary.obsm.push(obsmKey);
+                }
+            }
+            else if (r.url.startsWith(`${this.fileUrl}/X`)) {
+                metadataSummary.X = true;
+            }
+        });
+        return metadataSummary;
+    }
     async setMetadataSummary() {
         if (Object.keys(this.metadataSummary).length > 0) {
             return this.metadataSummary;
         }
-        const parseMetadataFile = (metadataFile) => {
-            if (!metadataFile.metadata) {
-                throw new Error('Could not generate config: .zmetadata file is not valid.');
-            }
-            const obsmKeys = Object.keys(metadataFile.metadata)
-                .filter(key => key.startsWith('obsm/X_'))
-                .map(key => key.split('/.zarray')[0]);
-            const obsKeysArr = Object.keys(metadataFile.metadata)
-                .filter(key => key.startsWith('obs/')).map(key => key.split('/.za')[0]);
-            function uniq(a) {
-                return a.sort().filter((item, pos, ary) => !pos || item !== ary[pos - 1]);
-            }
-            const obsKeys = uniq(obsKeysArr);
-            const X = Object.keys(metadataFile.metadata).filter(key => key.startsWith('X'));
-            const out = {
-                obsm: obsmKeys,
-                obs: obsKeys,
-                X: X.length > 0,
-            };
-            return out;
-        };
         const metadataExtension = '.zmetadata';
         const url = [this.fileUrl, metadataExtension].join('/');
         return fetch(url).then((response) => {
             if (response.ok) {
-                return response.json();
+                return this.setMetadataSummaryWithZmetadata(response);
             }
-            return Promise.reject(response);
-        })
-            .then(responseJson => parseMetadataFile(responseJson))
-            .catch((error) => {
-            if (error.status === 404) {
-                const errorMssg = `Could not generate config. File ${metadataExtension} not found in supplied file URL. Check docs for more explanation.`;
-                return Promise.reject(new Error(errorMssg));
+            if (response.status === 404) {
+                return this.setMetadataSummaryWithoutZmetadata();
             }
-            return Promise.reject(error);
+            throw new Error(`Could not generate config: ${response.statusText}`);
+        }).catch((error) => {
+            throw new Error(`Could not generate config for URL ${this.fileUrl}: ${error}`);
         });
     }
 }
@@ -207,23 +300,19 @@ const configClasses = [
     {
         extensions: ['.ome.tif', '.ome.tiff', '.ome.tf2', '.ome.tf8'],
         class: OmeTiffAutoConfig,
+        name: 'OME-TIFF',
     },
     {
         extensions: ['.h5ad.zarr', '.adata.zarr', '.anndata.zarr'],
         class: AnndataZarrAutoConfig,
+        name: 'AnnData-Zarr',
     },
     {
         extensions: ['ome.zarr'],
         class: OmeZarrAutoConfig,
+        name: 'OME-Zarr',
     },
 ];
-function getFileType(url) {
-    const match = configClasses.find(obj => obj.extensions.filter(ext => url.endsWith(ext)).length === 1);
-    if (!match) {
-        throw new Error(`Could not generate config for URL: ${url}. This file type is not supported.`);
-    }
-    return match.class;
-}
 function calculateCoordinates(viewsNumb) {
     const rows = Math.ceil(Math.sqrt(viewsNumb));
     const cols = Math.ceil(viewsNumb / rows);
@@ -235,14 +324,120 @@ function calculateCoordinates(viewsNumb) {
         const col = i % cols;
         const x = col * width;
         const y = row * height;
-        coords.push([x, y, width, height]);
+        // The coordinates have to be integer values:
+        coords.push([
+            Math.floor(x),
+            Math.floor(y),
+            // Ensure width/height is at least 1.
+            Math.max(1, Math.floor(width)),
+            Math.max(1, Math.floor(height)),
+        ]);
     }
     return coords;
 }
-async function generateConfig(url, vc) {
+const spatialSegmentationLayerValue = {
+    radius: 65,
+    stroked: true,
+    visible: true,
+    opacity: 1,
+};
+/**
+ * Inserts the spatial coordination space into the VitessceConfig views.
+ * @param {Array of VitessceConfigView} of views
+ * @param {VitessceConfig} vc instance
+ */
+function insertCoordinationSpaceForSpatial(views, vc) {
+    const [spatialSegmentationLayer, spatialImageLayer, spatialZoom, spatialTargetX, spatialTargetY,] = vc.addCoordination(ct.SPATIAL_SEGMENTATION_LAYER, ct.SPATIAL_IMAGE_LAYER, ct.SPATIAL_ZOOM, ct.SPATIAL_TARGET_X, ct.SPATIAL_TARGET_Y);
+    // Note: this always assumes the segmentation is polygon-based.
+    // In the future, we may want to support both polygon-based and bitmask-based.
+    spatialSegmentationLayer.setValue(spatialSegmentationLayerValue);
+    // Note: this always assumes the image is RGB.
+    // In the future, we may want to support both RGB and multi-channel.
+    spatialImageLayer.setValue([
+        {
+            type: 'raster',
+            index: 0,
+            colormap: null,
+            transparentColor: null,
+            opacity: 1,
+            domainType: 'Min/Max',
+            channels: [
+                {
+                    selection: {
+                        c: 0,
+                    },
+                    color: [
+                        255,
+                        0,
+                        0,
+                    ],
+                    visible: true,
+                    slider: [
+                        0,
+                        255,
+                    ],
+                },
+                {
+                    selection: {
+                        c: 1,
+                    },
+                    color: [
+                        0,
+                        255,
+                        0,
+                    ],
+                    visible: true,
+                    slider: [
+                        0,
+                        255,
+                    ],
+                },
+                {
+                    selection: {
+                        c: 2,
+                    },
+                    color: [
+                        0,
+                        0,
+                        255,
+                    ],
+                    visible: true,
+                    slider: [
+                        0,
+                        255,
+                    ],
+                },
+            ],
+        },
+    ]);
+    views.forEach((view) => {
+        if (view.view.component === 'spatial' || view.view.component === 'layerController') {
+            view.useCoordination(spatialImageLayer);
+            view.useCoordination(spatialSegmentationLayer);
+            view.useCoordination(spatialZoom);
+            view.useCoordination(spatialTargetX);
+            view.useCoordination(spatialTargetY);
+        }
+    });
+}
+/**
+ * Returns the type of the file, based on the file extension.
+ * @param {string} url of the file.
+ * @returns {object} An element from the `configClasses` array, which will be an object with
+ * the properties `extensions: string[]`, `class` (an AutoConfig class definition) and
+ * `name`: string.
+ */
+function getFileType(url) {
+    const match = configClasses.find(obj => obj.extensions.filter(ext => url.endsWith(ext)).length === 1);
+    if (!match) {
+        throw new Error('One or more of the URLs provided point to unsupported file types.');
+    }
+    return match;
+}
+async function generateViewDefinition(url, vc, dataset, hintsConfig) {
     let ConfigClassName;
     try {
-        ConfigClassName = getFileType(url);
+        ConfigClassName = getFileType(url).class;
     }
     catch (err) {
         return Promise.reject(err);
@@ -252,15 +447,13 @@ async function generateConfig(url, vc) {
     let viewsConfig;
     try {
         fileConfig = await configInstance.composeFileConfig();
-        viewsConfig = await configInstance.composeViewsConfig();
+        viewsConfig = await configInstance.composeViewsConfig(hintsConfig);
     }
     catch (error) {
         console.error(error);
         return Promise.reject(error);
     }
-    const dataset = vc
-        .addDataset(configInstance.fileName)
-        .addFile(fileConfig);
+    dataset.addFile(fileConfig);
     let layerControllerView = false;
     let spatialView = false;
     const views = [];
@@ -274,7 +467,7 @@ async function generateConfig(url, vc) {
         }
         // this piece of code can be removed once these props are added by default to layerController
         // see this issue: https://github.com/vitessce/vitessce/issues/1454
-        if (v[0] === 'layerController' && configInstance instanceof OmeTiffAutoConfig) {
+        if (v[0] === 'layerController') {
             view.setProps({
                 disable3d: [],
                 disableChannelsIfRgbDetected: true,
@@ -287,36 +480,74 @@ async function generateConfig(url, vc) {
         views.push(view);
     });
     if (layerControllerView && spatialView && configInstance instanceof AnndataZarrAutoConfig) {
-        const spatialSegmentationLayerValue = {
-            opacity: 1,
-            radius: 0,
-            visible: true,
-            stroked: false,
-        };
         vc.linkViews([spatialView, layerControllerView], [
-            CoordinationType.SPATIAL_ZOOM,
-            CoordinationType.SPATIAL_TARGET_X,
-            CoordinationType.SPATIAL_TARGET_Y,
-            CoordinationType.SPATIAL_SEGMENTATION_LAYER,
-        ], [-5.5, 16000, 20000, spatialSegmentationLayerValue]);
+            ct.SPATIAL_SEGMENTATION_LAYER,
+        ], [spatialSegmentationLayerValue]);
     }
     return views;
 }
-export async function generateConfigs(fileUrls) {
+/**
+ * Returns the hints that are available for the given file URLs, depending on their types.
+ * @param {Array} fileUrls containing urls of files to be loaded into Vitessce
+ * @returns the hints available for these file URLs
+ */
+export function getHintOptions(fileUrls) {
+    const fileTypes = {};
+    fileUrls.forEach((url) => {
+        const match = getFileType(url);
+        // hints config only has OME-TIFF, since settings are the same for both OME-TIFF and OME-Zarr
+        if (match.name === 'OME-Zarr') {
+            fileTypes['OME-TIFF'] = true;
+        }
+        else {
+            fileTypes[match.name] = true;
+        }
+    });
+    const datasetType = Object.keys(fileTypes).sort().join(',');
+    return HINT_TYPE_TO_FILE_TYPE_MAP?.[datasetType] || [];
+}
+/**
+ *
+ * @param {Array} fileUrls containing urls of files to be loaded into Vitessce
+ * @param {String} the hints config to be used for the dataset. Null by default
+ * @returns ViewConfig as JSON
+ */
+export async function generateConfig(fileUrls, hintTitle = null) {
     const vc = new VitessceConfig({
         schemaVersion: '1.0.15',
         name: 'An automatically generated config. Adjust values and add layout components if needed.',
         description: 'Populate with text relevant to this visualisation.',
     });
     const allViews = [];
+    const dataset = vc.addDataset('An automatically generated view config for dataset. Adjust values and add layout components if needed.');
+    const hintsConfig = !hintTitle ? { views: {} } : HINTS_CONFIG?.[hintTitle];
+    if (!hintsConfig) {
+        throw new Error(`Hints config not found for the supplied hint: ${hintTitle}.`);
+    }
+    const useHints = Object.keys(hintsConfig?.views)?.length > 0;
     fileUrls.forEach((url) => {
-        allViews.push(generateConfig(url, vc));
+        allViews.push(generateViewDefinition(url, vc, dataset, hintsConfig));
     });
     return Promise.all(allViews).then((views) => {
         const flattenedViews = views.flat();
-        const coord = calculateCoordinates(flattenedViews.length);
-        for (let i = 0; i < flattenedViews.length; i++) {
-            flattenedViews[i].setXYWH(...coord[i]);
+        // If coordinationSpaceRequired field is set to true in the HINTS_CONFIG,
+        // then insert coordination space.
+        // NOTE: the user needs to manually add the coordination values for the image and
+        // segmentation layers which will be visualized in the spatial/layer controller views.
+        if (hintsConfig?.coordinationSpaceRequired) {
+            insertCoordinationSpaceForSpatial(flattenedViews, vc);
+        }
+        if (!useHints) {
+            const coord = calculateCoordinates(flattenedViews.length);
+            for (let i = 0; i < flattenedViews.length; i++) {
+                flattenedViews[i].setXYWH(...coord[i]);
+            }
+        }
+        else {
+            flattenedViews.forEach((vitessceConfigView) => {
+                const coordinates = Object.values(hintsConfig.views[vitessceConfigView.view.component]);
+                vitessceConfigView.setXYWH(...coordinates);
+            });
         }
         return vc.toJSON();
     });