@vitessce/config 2.0.3-beta.0 → 3.0.0

package/dist-tsc/VitessceAutoConfig.test.js

@@ -0,0 +1,442 @@
+import { generateConfigs } from './VitessceAutoConfig.js';
+describe('src/VitessceAutoConfig.js', () => {
+    it('generates config for OME-TIFF file correctly', async () => {
+        const urls = ['somefile.ome.tif'];
+        const expectedName = urls[0].split('/').at(-1);
+        const expectedConfig = {
+            version: '1.0.15',
+            name: 'An automatically generated config. Adjust values and add layout components if needed.',
+            description: 'Populate with text relevant to this visualisation.',
+            datasets: [
+                {
+                    uid: 'A',
+                    name: expectedName,
+                    files: [
+                        {
+                            fileType: 'raster.json',
+                            options: {
+                                images: [
+                                    {
+                                        metadata: {
+                                            isBitmask: false,
+                                        },
+                                        name: expectedName,
+                                        type: 'ome-tiff',
+                                        url: urls[0],
+                                    },
+                                ],
+                                schemaVersion: '0.0.2',
+                                usePhysicalSizeScaling: false,
+                            },
+                        },
+                    ],
+                },
+            ],
+            coordinationSpace: {
+                dataset: {
+                    A: 'A',
+                },
+            },
+            layout: [
+                {
+                    component: 'description',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 0,
+                    y: 0,
+                    w: 6,
+                    h: 6,
+                },
+                {
+                    component: 'spatial',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 6,
+                    y: 0,
+                    w: 6,
+                    h: 6,
+                },
+                {
+                    component: 'layerController',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 0,
+                    y: 6,
+                    w: 6,
+                    h: 6,
+                    props: {
+                        disable3d: [],
+                        disableChannelsIfRgbDetected: true,
+                    },
+                },
+            ],
+            initStrategy: 'auto',
+        };
+        const config = await generateConfigs(urls);
+        expect(config).toEqual(expectedConfig);
+    });
+    it('generates config for OME-ZARR file correctly', async () => {
+        const urls = ['anotherfile.ome.zarr'];
+        const expectedName = urls[0].split('/').at(-1);
+        const expectedConfig = {
+            version: '1.0.15',
+            name: 'An automatically generated config. Adjust values and add layout components if needed.',
+            description: 'Populate with text relevant to this visualisation.',
+            datasets: [
+                {
+                    uid: 'A',
+                    name: expectedName,
+                    files: [
+                        {
+                            url: urls[0],
+                            fileType: 'raster.ome-zarr',
+                        },
+                    ],
+                },
+            ],
+            coordinationSpace: {
+                dataset: {
+                    A: 'A',
+                },
+            },
+            layout: [
+                {
+                    component: 'description',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 0,
+                    y: 0,
+                    w: 6,
+                    h: 6,
+                },
+                {
+                    component: 'spatial',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 6,
+                    y: 0,
+                    w: 6,
+                    h: 6,
+                },
+                {
+                    component: 'layerController',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 0,
+                    y: 6,
+                    w: 6,
+                    h: 6,
+                },
+                {
+                    component: 'status',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 6,
+                    y: 6,
+                    w: 6,
+                    h: 6,
+                },
+            ],
+            initStrategy: 'auto',
+        };
+        const config = await generateConfigs(urls);
+        expect(config).toEqual(expectedConfig);
+    });
+    it('generates config for Anndata-ZARR file correctly', async () => {
+        const urls = ['http://localhost:51204/@fixtures/zarr/partials/.anndata.zarr'];
+        const expectedName = urls[0].split('/').at(-1);
+        const expectedConfig = {
+            version: '1.0.15',
+            name: 'An automatically generated config. Adjust values and add layout components if needed.',
+            description: 'Populate with text relevant to this visualisation.',
+            datasets: [
+                {
+                    uid: 'A',
+                    name: expectedName,
+                    files: [
+                        {
+                            url: urls[0],
+                            fileType: 'anndata.zarr',
+                            coordinationValues: {
+                                obsType: 'cell',
+                                featureType: 'gene',
+                                featureValueType: 'expression',
+                            },
+                            options: {
+                                obsEmbedding: [
+                                    {
+                                        path: 'obsm/X_umap',
+                                        embeddingType: 'UMAP',
+                                    },
+                                ],
+                                obsFeatureMatrix: {
+                                    path: 'X',
+                                },
+                                obsSets: [
+                                    {
+                                        name: 'Cell Type',
+                                        path: [
+                                            'obs/cell_type',
+                                            'obs/disease',
+                                            'obs/leiden',
+                                            'obs/organism',
+                                            'obs/self_reported_ethnicity',
+                                            'obs/sex',
+                                            'obs/tissue'
+                                        ],
+                                    },
+                                ],
+                            },
+                        },
+                    ],
+                },
+            ],
+            coordinationSpace: {
+                dataset: {
+                    A: 'A',
+                },
+                embeddingType: {
+                    A: 'UMAP',
+                },
+            },
+            layout: [
+                {
+                    component: 'obsSets',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 0,
+                    y: 0,
+                    w: 6,
+                    h: 6,
+                },
+                {
+                    component: 'scatterplot',
+                    coordinationScopes: {
+                        dataset: 'A',
+                        embeddingType: 'A',
+                    },
+                    x: 6,
+                    y: 0,
+                    w: 6,
+                    h: 6,
+                },
+                {
+                    component: 'heatmap',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 0,
+                    y: 6,
+                    w: 6,
+                    h: 6,
+                    props: {
+                        transpose: true,
+                    },
+                },
+                {
+                    component: 'featureList',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 6,
+                    y: 6,
+                    w: 6,
+                    h: 6,
+                },
+            ],
+            initStrategy: 'auto',
+        };
+        const config = await generateConfigs(urls);
+        expect(config).toEqual(expectedConfig);
+    });
+    it('generates empty config for Anndata-ZARR file with empty .zmetadata', async () => {
+        const urls = ['http://localhost:51204/@fixtures/zarr/partials/emptymeta.h5ad.zarr'];
+        const expectedName = urls[0].split('/').at(-1);
+        const expectedConfig = {
+            version: '1.0.15',
+            name: 'An automatically generated config. Adjust values and add layout components if needed.',
+            description: 'Populate with text relevant to this visualisation.',
+            datasets: [
+                {
+                    uid: 'A',
+                    name: expectedName,
+                    files: [
+                        {
+                            url: urls[0],
+                            fileType: 'anndata.zarr',
+                            coordinationValues: {
+                                obsType: 'cell',
+                                featureType: 'gene',
+                                featureValueType: 'expression',
+                            },
+                            options: {
+                                obsEmbedding: [],
+                                obsFeatureMatrix: {
+                                    path: 'X',
+                                },
+                            },
+                        },
+                    ],
+                },
+            ],
+            coordinationSpace: {
+                dataset: {
+                    A: 'A',
+                },
+            },
+            layout: [],
+            initStrategy: 'auto',
+        };
+        const config = await generateConfigs(urls);
+        expect(config).toEqual(expectedConfig);
+    });
+    it('raises an error for Anndata-ZARR file with misconfigured .zmetadata', async () => {
+        const urls = ['http://localhost:51204/@fixtures/zarr/partials/invalidmeta.adata.zarr'];
+        await generateConfigs(urls).catch(e => expect(e.message).toContain('Could not generate config: .zmetadata file is not valid.'));
+    });
+    it('generates config for multiple files correctly', async () => {
+        const urls = ['somefile.ome.tif', 'anoterfile.ome.zarr'];
+        const expectedNames = [urls[0].split('/').at(-1), urls[1].split('/').at(-1)];
+        const expectedConfig = {
+            version: '1.0.15',
+            name: 'An automatically generated config. Adjust values and add layout components if needed.',
+            description: 'Populate with text relevant to this visualisation.',
+            datasets: [
+                {
+                    uid: 'A',
+                    name: expectedNames[0],
+                    files: [
+                        {
+                            fileType: 'raster.json',
+                            options: {
+                                images: [
+                                    {
+                                        metadata: {
+                                            isBitmask: false,
+                                        },
+                                        name: expectedNames[0],
+                                        type: 'ome-tiff',
+                                        url: urls[0],
+                                    },
+                                ],
+                                schemaVersion: '0.0.2',
+                                usePhysicalSizeScaling: false,
+                            },
+                        },
+                    ],
+                },
+                {
+                    uid: 'B',
+                    name: expectedNames[1],
+                    files: [
+                        {
+                            url: urls[1],
+                            fileType: 'raster.ome-zarr',
+                        },
+                    ],
+                },
+            ],
+            coordinationSpace: {
+                dataset: {
+                    A: 'A',
+                    B: 'B',
+                },
+            },
+            layout: [
+                {
+                    component: 'description',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 0,
+                    y: 0,
+                    w: 4,
+                    h: 4,
+                },
+                {
+                    component: 'spatial',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 4,
+                    y: 0,
+                    w: 4,
+                    h: 4,
+                },
+                {
+                    component: 'layerController',
+                    coordinationScopes: {
+                        dataset: 'A',
+                    },
+                    x: 8,
+                    y: 0,
+                    w: 4,
+                    h: 4,
+                    props: {
+                        disable3d: [],
+                        disableChannelsIfRgbDetected: true,
+                    },
+                },
+                {
+                    component: 'description',
+                    coordinationScopes: {
+                        dataset: 'B',
+                    },
+                    x: 0,
+                    y: 4,
+                    w: 4,
+                    h: 4,
+                },
+                {
+                    component: 'spatial',
+                    coordinationScopes: {
+                        dataset: 'B',
+                    },
+                    x: 4,
+                    y: 4,
+                    w: 4,
+                    h: 4,
+                },
+                {
+                    component: 'layerController',
+                    coordinationScopes: {
+                        dataset: 'B',
+                    },
+                    x: 8,
+                    y: 4,
+                    w: 4,
+                    h: 4,
+                },
+                {
+                    component: 'status',
+                    coordinationScopes: {
+                        dataset: 'B',
+                    },
+                    x: 0,
+                    y: 8,
+                    w: 4,
+                    h: 4,
+                },
+            ],
+            initStrategy: 'auto',
+        };
+        const config = await generateConfigs(urls);
+        expect(config).toEqual(expectedConfig);
+    });
+    it('raises an Error when .zmetadata file not present in folder', async () => {
+        const urls = ['http://localhost:51204/@fixtures/zarr/partials/invalid.adata.zarr'];
+        await generateConfigs(urls).catch(e => expect(e.message).toContain('Could not generate config. File .zmetadata not found in supplied file URL'));
+    });
+    it('raises an error when URL with unsupported file format is passed', async () => {
+        const urls = ['http://localhost:51204/@fixtures/zarr/anndata-0.7/somefile.zarr'];
+        await generateConfigs(urls).catch(e => expect(e.message).toContain('This file type is not supported.'));
+    });
+});

package/dist-tsc/VitessceConfig.d.ts

@@ -0,0 +1,257 @@
+/**
+ * A helper function to create a horizontal concatenation of views.
+ * @param  {...(VitessceConfigView|VitessceConfigViewHConcat|VitessceConfigViewVConcat)} views A
+ * variable number of views or view concatenations.
+ * @returns {VitessceConfigViewHConcat} A new horizontal view concatenation instance.
+ */
+export function hconcat(...views: (VitessceConfigView | VitessceConfigViewHConcat | VitessceConfigViewVConcat)[]): VitessceConfigViewHConcat;
+/**
+ * A helper function to create a vertical concatenation of views.
+ * @param  {...(VitessceConfigView|VitessceConfigViewHConcat|VitessceConfigViewVConcat)} views A
+ * variable number of views or view concatenations.
+ * @returns {VitessceConfigViewVConcat} A new vertical view concatenation instance.
+ */
+export function vconcat(...views: (VitessceConfigView | VitessceConfigViewHConcat | VitessceConfigViewVConcat)[]): VitessceConfigViewVConcat;
+/**
+ * Class representing a file within a Vitessce config dataset.
+ */
+export class VitessceConfigDatasetFile {
+    /**
+     * Construct a new file definition instance.
+     * @param {string} url The URL to the file.
+     * @param {string} dataType The type of data contained in the file.
+     * @param {string} fileType The file type.
+     * @param {object|array|null} options An optional object or array
+     * which may provide additional parameters to the loader class
+     * corresponding to the specified fileType.
+     */
+    constructor(url: string, fileType: string, coordinationValues: any, options: object | array | null);
+    file: {
+        options?: any;
+        coordinationValues?: any;
+        url: string;
+        fileType: string;
+    };
+    /**
+     * @returns {object} This dataset file as a JSON object.
+     */
+    toJSON(): object;
+}
+/**
+ * Class representing a dataset within a Vitessce config.
+ */
+export class VitessceConfigDataset {
+    /**
+     * Construct a new dataset definition instance.
+     * @param {string} uid The unique ID for the dataset.
+     * @param {string} name The name of the dataset.
+     * @param {string} description A description for the dataset.
+     */
+    constructor(uid: string, name: string, description: string);
+    dataset: {
+        uid: string;
+        name: string;
+        description: string;
+        files: never[];
+    };
+    /**
+     * Add a file definition to the dataset.
+     * @param {object} params An object with named arguments.
+     * @param {string|undefined} params.url The URL to the file.
+     * @param {string} params.fileType The file type.
+     * @param {object|undefined} params.coordinationValues The coordination values.
+     * @param {object|array|undefined} params.options An optional object or array
+     * which may provide additional parameters to the loader class
+     * corresponding to the specified fileType.
+     * @returns {VitessceConfigDataset} This, to allow chaining.
+     */
+    addFile(params: {
+        url: string | undefined;
+        fileType: string;
+        coordinationValues: object | undefined;
+        options: object | array | undefined;
+    }, ...args: any[]): VitessceConfigDataset;
+    /**
+     * @returns {object} This dataset as a JSON object.
+     */
+    toJSON(): object;
+}
+/**
+ * Class representing a view within a Vitessce layout.
+ */
+export class VitessceConfigView {
+    /**
+     * Construct a new view instance.
+     * @param {string} component The name of the Vitessce component type.
+     * @param {object} coordinationScopes A mapping from coordination type
+     * names to coordination scope names.
+     * @param {number} x The x-coordinate of the view in the layout.
+     * @param {number} y The y-coordinate of the view in the layout.
+     * @param {number} w The width of the view in the layout.
+     * @param {number} h The height of the view in the layout.
+     */
+    constructor(component: string, coordinationScopes: object, x: number, y: number, w: number, h: number);
+    view: {
+        component: string;
+        coordinationScopes: object;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * Attach coordination scopes to this view.
+     * @param  {...VitessceConfigCoordinationScope} args A variable number of
+     * coordination scope instances.
+     * @returns {VitessceConfigView} This, to allow chaining.
+     */
+    useCoordination(...args: VitessceConfigCoordinationScope[]): VitessceConfigView;
+    /**
+      * Set the x, y, w, h values for this view.
+      * @param {number} x The x-coordinate of the view in the layout.
+      * @param {number} y The y-coordinate of the view in the layout.
+      * @param {number} w The width of the view in the layout.
+      * @param {number} h The height of the view in the layout.
+      * @returns {VitessceConfigView} This, to allow chaining.
+      */
+    setXYWH(x: number, y: number, w: number, h: number): VitessceConfigView;
+    /**
+     * Set props for this view.
+     * @returns {VitessceConfigView} This, to allow chaining.
+     */
+    setProps(props: any): VitessceConfigView;
+    /**
+     * @returns {object} This view as a JSON object.
+     */
+    toJSON(): object;
+}
+/**
+ * Class representing a horizontal concatenation of views.
+ */
+export class VitessceConfigViewHConcat {
+    constructor(views: any);
+    views: any;
+}
+/**
+ * Class representing a vertical concatenation of views.
+ */
+export class VitessceConfigViewVConcat {
+    constructor(views: any);
+    views: any;
+}
+/**
+ * Class representing a coordination scope in the coordination space.
+ */
+export class VitessceConfigCoordinationScope {
+    /**
+     * Construct a new coordination scope instance.
+     * @param {string} cType The coordination type for this coordination scope.
+     * @param {string} cScope The name of the coordination scope.
+     */
+    constructor(cType: string, cScope: string);
+    cType: string;
+    cScope: string;
+    cValue: any;
+    /**
+     * Set the coordination value of the coordination scope.
+     * @param {any} cValue The value to set.
+     * @returns {VitessceConfigCoordinationScope} This, to allow chaining.
+     */
+    setValue(cValue: any): VitessceConfigCoordinationScope;
+}
+/**
+ * Class representing a Vitessce view config.
+ */
+export class VitessceConfig {
+    /**
+     * Create a VitessceConfig instance from an existing view config, to enable
+     * manipulation with the JavaScript API.
+     * @param {object} config An existing Vitessce view config as a JSON object.
+     * @returns {VitessceConfig} A new config instance, with values set to match
+     * the config parameter.
+     */
+    static fromJSON(config: object): VitessceConfig;
+    /**
+     * Construct a new view config instance.
+     * @param {object} params An object with named arguments.
+     * @param {string} params.schemaVersion The view config schema version. Required.
+     * @param {string} params.name A name for the config. Optional.
+     * @param {string|undefined} params.description A description for the config. Optional.
+     */
+    constructor(params: {
+        schemaVersion: string;
+        name: string;
+        description: string | undefined;
+    }, ...args: any[]);
+    config: {
+        version: string;
+        name: string;
+        description: any;
+        datasets: never[];
+        coordinationSpace: {};
+        layout: never[];
+        initStrategy: string;
+    };
+    /**
+     * Add a new dataset to the config.
+     * @param {string} name A name for the dataset. Optional.
+     * @param {string} description A description for the dataset. Optional.
+     * @param {object} options Extra parameters to be used internally. Optional.
+     * @param {string} options.uid Override the automatically-generated dataset ID.
+     * Intended for internal usage by the VitessceConfig.fromJSON code.
+     * @returns {VitessceConfigDataset} A new dataset instance.
+     */
+    addDataset(name?: string, description?: string, options?: {
+        uid: string;
+    }): VitessceConfigDataset;
+    /**
+     * Add a new view to the config.
+     * @param {VitessceConfigDataset} dataset The dataset instance which defines the data
+     * that will be displayed in the view.
+     * @param {string} component A component name, such as "scatterplot" or "spatial".
+     * @param {object} options Extra options for the component.
+     * @param {number} options.x The x-coordinate for the view in the grid layout.
+     * @param {number} options.y The y-coordinate for the view in the grid layout.
+     * @param {number} options.w The width for the view in the grid layout.
+     * @param {number} options.h The height for the view in the grid layout.
+     * @param {number} options.mapping A convenience parameter for setting the EMBEDDING_TYPE
+     * coordination value. Only applicable if the component is "scatterplot".
+     * @returns {VitessceConfigView} A new view instance.
+     */
+    addView(dataset: VitessceConfigDataset, component: string, options: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        mapping: number;
+    }): VitessceConfigView;
+    /**
+     * Get an array of new coordination scope instances corresponding to coordination types
+     * of interest.
+     * @param {...string} args A variable number of coordination type names.
+     * @returns {VitessceConfigCoordinationScope[]} An array of coordination scope instances.
+     */
+    addCoordination(...args: string[]): VitessceConfigCoordinationScope[];
+    /**
+     * A convenience function for setting up new coordination scopes across a set of views.
+     * @param {VitessceConfigView[]} views An array of view objects to link together.
+     * @param {string[]} cTypes The coordination types on which to coordinate the views.
+     * @param {any[]} cValues Initial values corresponding to each coordination type.
+     * Should have the same length as the cTypes array. Optional.
+     * @returns {VitessceConfig} This, to allow chaining.
+     */
+    linkViews(views: VitessceConfigView[], cTypes: string[], cValues?: any[]): VitessceConfig;
+    /**
+     * Set the layout of views.
+     * @param {VitessceConfigView|VitessceConfigViewHConcat|VitessceConfigViewVConcat} viewConcat A
+     * view or a concatenation of views.
+     * @returns {VitessceConfig} This, to allow chaining.
+     */
+    layout(viewConcat: VitessceConfigView | VitessceConfigViewHConcat | VitessceConfigViewVConcat): VitessceConfig;
+    /**
+     * Convert this instance to a JSON object that can be passed to the Vitessce component.
+     * @returns {object} The view config as a JSON object.
+     */
+    toJSON(): object;
+}
+//# sourceMappingURL=VitessceConfig.d.ts.map