Create module for plugin JS (#337)

* Create module for plugin JS

* Add docs

* Lint

* Ignore unused imports

Author: keller-mark

docs/data_options.rst

@@ -106,5 +106,44 @@ Jupyter process: remote service like Colab/Binder; Files: remote & accessed via
 
 Unfortunately, this will not work because the remote server cannot access the files that are on another machine behind SSH.
 
+========================================================================
+Jupyter process: anywhere; Files: anywhere that can be accessed via Zarr
+========================================================================
 
+If the data is readable via Zarr (i.e., `zarr.storage.*Store`) and the Jupyter process can access the store contents, then the Vitessce widget can access the data by specifying the Zarr store as the data source for Vitessce data wrapper class instances.
+This is currently supported for the ``AnnDataWrapper`` class using the ``adata_store`` parameter (as opposed to ``adata_path`` or ``adata_url``).
+
+.. code-block:: python
+
+    from vitessce import VitessceConfig, AnnDataWrapper
+
+    # ...
+    adata.write_zarr("my_store.adata.zarr")
+
+    vc = VitessceConfig(name="My Vitessce Configuration")
+    vc.add_dataset(name="My Dataset").add_object(AnnDataWrapper(
+        adata_store="my_store.adata.zarr",
+        # ...
+    ))
+    # ...
+    vc.widget()
+
+
+Or, with a Zarr store instance (instead of a local string path to a DirectoryStore):
+
+.. code-block:: python
+
+    import zarr
+    from vitessce import VitessceConfig, AnnDataWrapper
+
+    # ...
+    store = zarr.storage.FSStore("s3://my_bucket/path/to/my_store.adata.zarr")
+
+    vc = VitessceConfig(name="My Vitessce Configuration")
+    vc.add_dataset(name="My Dataset").add_object(AnnDataWrapper(
+        adata_store=store,
+        # ...
+    ))
+    # ...
+    vc.widget()
 

docs/index.rst

@@ -48,6 +48,7 @@ The Vitessce widget is compatible with the following interactive Python platform
    api_config
    api_data
    data_options
+   widget_plugins
    screenshots
 
 

docs/widget_plugins.rst

@@ -0,0 +1,152 @@
+Widget plugins
+##############
+
+Vitessce supports multiple types of `plugins <http://vitessce.io/docs/dev-plugins/>`_ defined using JavaScript code.
+
+Leveraging concepts from `anywidget <https://github.com/manzt/anywidget>`_, we can define such plugins directly from Python: plugin developers can supply custom JavaScript code via a Python string.
+
+The most minimal example of such plugin JavaScript code is the following:
+
+.. code-block:: python
+
+    PLUGIN_ESM = """
+    function createPlugins(utilsForPlugins) {
+        const {
+            React,
+            PluginFileType,
+            PluginViewType,
+            PluginCoordinationType,
+            PluginJointFileType,
+            z,
+            useCoordination,
+        } = utilsForPlugins;
+        return {
+            pluginViewTypes: undefined,
+            pluginFileTypes: undefined,
+            pluginCoordinationTypes: undefined,
+            pluginJointFileTypes: undefined,
+        };
+    }
+    export default { createPlugins };
+    """
+
+
+The plugin string must be defined as an EcmaScript Module (ESM) that exports a function named ``createPlugins``.
+The ``createPlugins`` function is called (on the initial render of the Jupyter widget) with the ``utilsForPlugins`` argument (to facilitate dependency injection) and returns an object with the following properties:
+
+- ``pluginViewTypes``: an array of objects that define the view types of the plugin.
+- ``pluginFileTypes```: an array of objects that define the file types of the plugin.
+- ``pluginCoordinationTypes``: an array of objects that define the coordination types of the plugin.
+- ``pluginJointFileTypes``: an array of objects that define the joint file types of the plugin.
+
+If defined, these plugin arrays are passed to the Vitessce component as `props <http://vitessce.io/docs/dev-plugins/>`_ with the same names.
+
+**Note**: For maximum stability of plugins, we recommend that plugin developers document which version(s) of the vitessce Python package that plugins have been developed under.
+
+--------------------------------
+Passing plugin ESM to the widget
+--------------------------------
+
+The plugin string can be passed to the widget using the ``plugin_esm`` parameter:
+
+
+.. code-block:: python
+
+    from vitessce import VitessceConfig
+
+    vc = VitessceConfig(
+        description="A Vitessce widget with a custom plugin",
+        widget=[
+            {
+                "plugin": PLUGIN_ESM,
+            },
+        ],
+    )
+    # Some more configuration here...
+
+    vc.widget(plugin_esm=PLUGIN_ESM)
+
+
+-------------------------------
+Defining plugin views using JSX
+-------------------------------
+
+Vitessce plugin view types are defined as React components.
+During typical React component development, JSX syntax is used.
+However, JSX is not valid JavaScript and therefore must be transformed to valid JavaScript before it can be passed to the widget where it will be interpreted as ESM.
+Vitessce plugin developers then have two options for defining React components for plugin view types:
+
+* Use ``React.createElement`` directly (without JSX).
+* Use the ``transform`` function from `esbuild_py <https://github.com/keller-mark/esbuild-py>`_ to perform JSX to JS transformation.
+
+.. code-block:: python
+
+    from esbuild_py import transform
+
+    PLUGIN_ESM = transform("""
+    function createPlugins(utilsForPlugins) {
+        const {
+            React,
+            PluginFileType,
+            PluginViewType,
+            PluginCoordinationType,
+            PluginJointFileType,
+            z,
+            useCoordination,
+        } = utilsForPlugins;
+
+        function MyPluginView(props) {
+            return (
+                <p>Hello world from JSX!</p>
+            );
+        }
+
+        const pluginViewTypes = [
+            new PluginViewType('myPlugin', MyPluginView, []),
+        ];
+        return { pluginViewTypes };
+    }
+    export default { createPlugins };
+    """)
+
+
+To import additional dependencies, JavaScript (more specifically, ESM) can be dynamically imported from CDN (such as ``unpkg`` or ``esm.sh``) within the ``createPlugins`` function:
+
+.. code-block:: python
+
+    PLUGIN_ESM = """
+    async function createPlugins(utilsForPlugins) {
+        const {
+            React,
+            PluginFileType,
+            PluginViewType,
+            PluginCoordinationType,
+            PluginJointFileType,
+            z,
+            useCoordination,
+        } = utilsForPlugins;
+
+        const d3 = await import('https://cdn.jsdelivr.net/npm/d3@7/+esm');
+
+        // Do something with d3 here...
+
+        return {
+            pluginViewTypes: undefined,
+            pluginFileTypes: undefined,
+            pluginCoordinationTypes: undefined,
+            pluginJointFileTypes: undefined,
+        };
+    }
+    export default { createPlugins };
+    """
+
+
+To support more complex import scenarios, see `dynamic-importmap <https://github.com/keller-mark/dynamic-importmap>`_.
+
+
+
+vitessce.widget_plugins
+***********************
+
+.. automodule:: vitessce.widget_plugins.demo_plugin
+ :members:

pyproject.toml

@@ -73,6 +73,7 @@ docs = [
 ]
 all = [
   'jupyter-server-proxy>=1.5.2',
+  'esbuild_py>=0.1.3',
   'anywidget>=0.9.10',
   'uvicorn>=0.17.0',
   'ujson>=4.0.1',

setup.cfg

@@ -6,6 +6,7 @@ per-file-ignores =
   # Special case: names are reimported from __init__.py, so unused imports are expected.
   vitessce/__init__.py: F401
   vitessce/data_utils/__init__.py: F401
+  vitessce/widget_plugins/__init__.py: F401
 ignore =
   E501, # Ignore line too long
   W605, # Ignore invalid escape sequence '\*'

vitessce/widget_plugins/__init__.py

@@ -0,0 +1 @@
+from .demo_plugin import PLUGIN_ESM as demo_plugin_esm

vitessce/widget_plugins/demo_plugin.py

@@ -0,0 +1,50 @@
+from esbuild_py import transform
+
+PLUGIN_ESM = transform("""
+function createPlugins(utilsForPlugins) {
+    const {
+        React,
+        PluginFileType,
+        PluginViewType,
+        PluginCoordinationType,
+        PluginJointFileType,
+        z,
+        useCoordination,
+    } = utilsForPlugins;
+    function DemoView(props) {
+        const { coordinationScopes } = props;
+        const [{
+            obsType,
+        }, {
+            setObsType,
+        }] = useCoordination(['obsType'], coordinationScopes);
+
+        return (
+            <div className="demo">
+                <p>Demo plugin view</p>
+                <p>obsType: {obsType}</p>
+                <button>This is an example button</button>
+            </div>
+        );
+    }
+
+    const pluginViewTypes = [
+        new PluginViewType('demo', DemoView, ['obsType']),
+    ];
+    return { pluginViewTypes };
+}
+export default { createPlugins };
+""")
+"""
+Example of a minimal plugin view that gets the obsType coordination value from the coordination space and renders a button.
+This plugin view is not meant to be useful for end-users, but rather to demonstrate how to develop a plugin view that uses coordination (and uses eslint_py for JSX transformation).
+
+:meta hide-value:
+
+.. code-block:: python
+
+    from vitessce.widget_plugins import demo_plugin_esm
+
+    # ...
+    vc.widget(plugin_esm=demo_plugin_esm)
+"""

vitessce/wrappers.py

@@ -943,7 +943,7 @@ def __init__(self, adata_path=None, adata_url=None, adata_store=None, obs_featur
 
         :param str adata_path: A path to an AnnData object written to a Zarr store containing single-cell experiment data.
         :param str adata_url: A remote url pointing to a zarr-backed AnnData store.
-        :param adata_store: A path to pass to zarr.FSStore, or an existing store instance.
+        :param adata_store: A path to pass to zarr.DirectoryStore, or an existing store instance.
         :type adata_store: str or zarr.Storage
         :param str obs_feature_matrix_path: Location of the expression (cell x gene) matrix, like `X` or `obsm/highly_variable_genes_subset`
         :param str feature_filter_path: A string like `var/highly_variable` used in conjunction with `obs_feature_matrix_path` if obs_feature_matrix_path points to a subset of `X` of the full `var` list.