From 1f31e995110511ff7282f768ce3fca5cc19384f5 Mon Sep 17 00:00:00 2001
From: Kyle Conroy <kyleconroy@gmail.com>
Date: Thu, 17 Mar 2022 13:46:42 -0400
Subject: [PATCH] generalize subset select component to handle spatial and
 spectral

---
 CHANGES.rst                                   |   2 +-
 jdaviz/components/plugin_subset_select.vue    |   8 +-
 .../plugins/moment_maps/moment_maps.vue       |   1 +
 .../default/plugins/collapse/collapse.vue     |   1 +
 .../plugins/model_fitting/model_fitting.py    |   5 +
 .../plugins/model_fitting/model_fitting.vue   |   1 +
 .../aper_phot_simple/aper_phot_simple.py      |  18 +-
 .../aper_phot_simple/aper_phot_simple.vue     |  31 ++-
 .../plugins/line_analysis/line_analysis.py    |  26 ++-
 .../plugins/line_analysis/line_analysis.vue   |   4 +-
 jdaviz/core/template_mixin.py                 | 205 +++++++++++++-----
 11 files changed, 211 insertions(+), 91 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 2c6b066593..b3cfe3cba0 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -66,7 +66,7 @@ Other Changes and Additions
 - Redshifts imported with a custom line list are now ignored.  Redshift must be set app-wide via 
   viz.set_redshift or the line list plugin. [#1134]
 
-- Subset selection dropdowns in plugins now show synced color indicators. [#1156]
+- Subset selection dropdowns in plugins now show synced color indicators. [#1156, #1175]
 
 2.3 (2022-03-01)
 ================
diff --git a/jdaviz/components/plugin_subset_select.vue b/jdaviz/components/plugin_subset_select.vue
index 48a567ee18..f1569906f1 100644
--- a/jdaviz/components/plugin_subset_select.vue
+++ b/jdaviz/components/plugin_subset_select.vue
@@ -5,8 +5,8 @@
       :items="items"
       v-model="selected"
       @change="$emit('update:selected', $event)"
-      :label="label ? label : 'Spectral Region'"
-      :hint="hint ? hint : 'Select spectral region.'"
+      :label="label ? label : 'Subset'"
+      :hint="hint ? hint : 'Select subset.'"
       :rules="rules ? rules : []"
       item-text="label"
       item-value="label"
@@ -15,7 +15,7 @@
       <template slot="selection" slot-scope="data">
         <div class="single-line">
           <v-icon v-if="data.item.color" left :color="data.item.color">
-            mdi-chart-bell-curve
+            {{ data.item.type=='spectral' ? 'mdi-chart-bell-curve' : 'mdi-chart-scatter-plot' }}
           </v-icon>
           <span>
             {{ data.item.label }}
@@ -25,7 +25,7 @@
       <template slot="item" slot-scope="data">
         <div class="single-line">
           <v-icon v-if="data.item.color" left :color="data.item.color">
-            mdi-chart-bell-curve
+            {{ data.item.type=='spectral' ? 'mdi-chart-bell-curve' : 'mdi-chart-scatter-plot' }}
           </v-icon>
           <span>
             {{ data.item.label }}
diff --git a/jdaviz/configs/cubeviz/plugins/moment_maps/moment_maps.vue b/jdaviz/configs/cubeviz/plugins/moment_maps/moment_maps.vue
index 3f1c9f177f..29c11033dc 100644
--- a/jdaviz/configs/cubeviz/plugins/moment_maps/moment_maps.vue
+++ b/jdaviz/configs/cubeviz/plugins/moment_maps/moment_maps.vue
@@ -19,6 +19,7 @@
       :selected.sync="spectral_subset_selected"
       :has_subregions="spectral_subset_selected_has_subregions"
       has_subregions_warning="The selected selected subset has subregions, the entire range will be used, ignoring any gaps."
+      label="Spectral region"
       hint="Spectral region to compute the moment map."
     />
 
diff --git a/jdaviz/configs/default/plugins/collapse/collapse.vue b/jdaviz/configs/default/plugins/collapse/collapse.vue
index a31de45949..386ac3e171 100644
--- a/jdaviz/configs/default/plugins/collapse/collapse.vue
+++ b/jdaviz/configs/default/plugins/collapse/collapse.vue
@@ -30,6 +30,7 @@
         :selected.sync="spectral_subset_selected"
         :has_subregions="spectral_subset_selected_has_subregions"
         has_subregions_warning="The selected selected subset has subregions, the entire range will be used, ignoring any gaps."
+        label="Spectral region"
         hint="Select spectral region to apply the collapse."
       />
 
diff --git a/jdaviz/configs/default/plugins/model_fitting/model_fitting.py b/jdaviz/configs/default/plugins/model_fitting/model_fitting.py
index 21f7a5b795..7c80e40f49 100644
--- a/jdaviz/configs/default/plugins/model_fitting/model_fitting.py
+++ b/jdaviz/configs/default/plugins/model_fitting/model_fitting.py
@@ -67,6 +67,7 @@ class ModelFitting(PluginTemplateMixin, SpectralSubsetSelectMixin):
     available_models = List(list(MODELS.keys())).tag(sync=True)
 
     def __init__(self, *args, **kwargs):
+        self._spectrum1d = None
         super().__init__(*args, **kwargs)
 
         self._units = {}
@@ -274,6 +275,10 @@ def _selected_data_changed(self, event):
     @observe("spectral_subset_selected")
     def _on_spectral_subset_selected(self, event):
         # If "Entire Spectrum" selected, reset based on bounds of selected data
+        if self._spectrum1d is None:
+            # TODO: this should be removed as soon as the data dropdown component is
+            # created and defaults at init
+            return
         if self.spectral_subset_selected == "Entire Spectrum":
             self._window = None
             self.spectral_min = self._spectrum1d.spectral_axis[0].value
diff --git a/jdaviz/configs/default/plugins/model_fitting/model_fitting.vue b/jdaviz/configs/default/plugins/model_fitting/model_fitting.vue
index 65f1a1e95c..8a12adf663 100644
--- a/jdaviz/configs/default/plugins/model_fitting/model_fitting.vue
+++ b/jdaviz/configs/default/plugins/model_fitting/model_fitting.vue
@@ -19,6 +19,7 @@
       <plugin-subset-select 
         :items="spectral_subset_items"
         :selected.sync="spectral_subset_selected"
+        label="Spectral region"
         hint="Select spectral region to fit."
       />
     </v-form>
diff --git a/jdaviz/configs/imviz/plugins/aper_phot_simple/aper_phot_simple.py b/jdaviz/configs/imviz/plugins/aper_phot_simple/aper_phot_simple.py
index 967f2d0bc0..9493f16b0e 100644
--- a/jdaviz/configs/imviz/plugins/aper_phot_simple/aper_phot_simple.py
+++ b/jdaviz/configs/imviz/plugins/aper_phot_simple/aper_phot_simple.py
@@ -13,7 +13,7 @@
 from jdaviz.configs.imviz.helper import layer_is_image_data
 from jdaviz.core.events import AddDataMessage, RemoveDataMessage, SnackbarMessage
 from jdaviz.core.registries import tray_registry
-from jdaviz.core.template_mixin import TemplateMixin
+from jdaviz.core.template_mixin import TemplateMixin, SubsetSelect
 
 __all__ = ['SimpleAperturePhotometry']
 
@@ -41,6 +41,18 @@ class SimpleAperturePhotometry(TemplateMixin):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
+        self.subset = SubsetSelect(self,
+                                   'subset_items',
+                                   'subset_selected',
+                                   default_text=None,
+                                   allowed_type='spatial')
+
+        self.bg_subset = SubsetSelect(self,
+                                      'bg_subset_items',
+                                      'bg_subset_selected',
+                                      default_text='Manual',
+                                      allowed_type='spatial')
+
         self.hub.subscribe(self, AddDataMessage, handler=self._on_viewer_data_changed)
         self.hub.subscribe(self, RemoveDataMessage, handler=self._on_viewer_data_changed)
         self.hub.subscribe(self, SubsetCreateMessage, handler=self._on_viewer_data_changed)
@@ -64,10 +76,6 @@ def _on_viewer_data_changed(self, msg=None):
         self.dc_items = [lyr.label for lyr in self.app.data_collection
                          if layer_is_image_data(lyr)]
 
-        self.subset_items = [lyr.label for lyr in self.app.data_collection.subset_groups
-                             if lyr.label.startswith('Subset')]
-        self.bg_subset_items = ['Manual'] + self.subset_items
-
     @observe('data_selected')
     def _data_selected_changed(self, event={}):
         data_selected = event.get('new', self.data_selected)
diff --git a/jdaviz/configs/imviz/plugins/aper_phot_simple/aper_phot_simple.vue b/jdaviz/configs/imviz/plugins/aper_phot_simple/aper_phot_simple.vue
index fb0bfca911..5d69629b60 100644
--- a/jdaviz/configs/imviz/plugins/aper_phot_simple/aper_phot_simple.vue
+++ b/jdaviz/configs/imviz/plugins/aper_phot_simple/aper_phot_simple.vue
@@ -17,26 +17,21 @@
     </v-row>
 
     <div v-if='data_selected'>
-      <v-row>
-        <v-select
-          :items="subset_items"
-          v-model="subset_selected"
-          label="Subset"
-          hint="Select subset region for photometry."
-          persistent-hint
-        ></v-select>
-      </v-row>
+      <plugin-subset-select
+        :items="subset_items"
+        :selected.sync="subset_selected"
+        label="Aperture"
+        hint="Select aperture region for photometry."
+      />
 
       <div v-if="subset_selected">
-        <v-row>
-          <v-select
-            :items="bg_subset_items"
-            v-model="bg_subset_selected"
-            label="Subset (background)"
-            hint="Select subset region for background calculation."
-            persistent-hint
-          ></v-select>
-        </v-row>
+        <plugin-subset-select
+          :items="bg_subset_items"
+          :selected.sync="bg_subset_selected"
+          :rules="[() => bg_subset_selected!==subset_selected || 'Must not match aperture.']"
+          label="Background"
+          hint="Select subset region for background calculation."
+        />
 
         <v-row>
           <v-text-field
diff --git a/jdaviz/configs/specviz/plugins/line_analysis/line_analysis.py b/jdaviz/configs/specviz/plugins/line_analysis/line_analysis.py
index 1bb2dacfbc..bbc51568f4 100644
--- a/jdaviz/configs/specviz/plugins/line_analysis/line_analysis.py
+++ b/jdaviz/configs/specviz/plugins/line_analysis/line_analysis.py
@@ -13,7 +13,7 @@
                                LineAnalysisContinuumRight,
                                Shadow)
 from jdaviz.core.registries import tray_registry
-from jdaviz.core.template_mixin import PluginTemplateMixin, SpectralSubsetSelect
+from jdaviz.core.template_mixin import PluginTemplateMixin, SubsetSelect
 
 __all__ = ['LineAnalysis']
 
@@ -31,11 +31,11 @@ class LineAnalysis(PluginTemplateMixin):
     dc_items = List([]).tag(sync=True)
     selected_spectrum = Unicode("").tag(sync=True)
 
-    spectral_subset_items = List([{"label": "Entire Spectrum", "color": False}]).tag(sync=True)
-    spectral_subset_selected = Unicode("Entire Spectrum").tag(sync=True)
+    spectral_subset_items = List().tag(sync=True)
+    spectral_subset_selected = Unicode().tag(sync=True)
 
-    continuum_subset_items = List([{"label": "Surrounding", "color": False}]).tag(sync=True)
-    continuum_selected = Unicode("Surrounding").tag(sync=True)
+    continuum_subset_items = List().tag(sync=True)
+    continuum_selected = Unicode().tag(sync=True)
 
     width = FloatHandleEmpty(3).tag(sync=True)
     results_computing = Bool(False).tag(sync=True)
@@ -50,12 +50,16 @@ def __init__(self, *args, **kwargs):
         self._units = {}
         self.update_results(None)
 
-        self.spectral_subset = SpectralSubsetSelect(self,
-                                                    'spectral_subset_items',
-                                                    'spectral_subset_selected')
-        self.continuum = SpectralSubsetSelect(self,
-                                              'continuum_subset_items',
-                                              'continuum_selected')
+        self.spectral_subset = SubsetSelect(self,
+                                            'spectral_subset_items',
+                                            'spectral_subset_selected',
+                                            default_text="Entire Spectrum",
+                                            allowed_type='spectral')
+        self.continuum = SubsetSelect(self,
+                                      'continuum_subset_items',
+                                      'continuum_selected',
+                                      default_text='Surrounding',
+                                      allowed_type='spectral')
 
         self.hub.subscribe(self, AddDataMessage,
                            handler=self._on_viewer_data_changed)
diff --git a/jdaviz/configs/specviz/plugins/line_analysis/line_analysis.vue b/jdaviz/configs/specviz/plugins/line_analysis/line_analysis.vue
index befbcd8af9..f393e21edf 100644
--- a/jdaviz/configs/specviz/plugins/line_analysis/line_analysis.vue
+++ b/jdaviz/configs/specviz/plugins/line_analysis/line_analysis.vue
@@ -24,6 +24,7 @@
     <plugin-subset-select 
       :items="spectral_subset_items"
       :selected.sync="spectral_subset_selected"
+      label="Spectral region"
       hint="Select spectral region that defines the line."
     />
 
@@ -40,7 +41,8 @@
       :items="continuum_subset_items"
       :selected.sync="continuum_selected"
       :rules="[() => continuum_selected!==spectral_subset_selected || 'Must not match line selection.']"
-      hint="Select spectral region that defines the line."
+      label="Continuum"
+      hint="Select spectral region that defines the continuum."
     />
 
     <v-row v-if="continuum_selected=='Surrounding' && spectral_subset_selected!='Entire Spectrum'">
diff --git a/jdaviz/core/template_mixin.py b/jdaviz/core/template_mixin.py
index 4e12936af0..d8e054da70 100644
--- a/jdaviz/core/template_mixin.py
+++ b/jdaviz/core/template_mixin.py
@@ -12,7 +12,7 @@
 
 __all__ = ['TemplateMixin', 'PluginTemplateMixin',
            'BasePluginComponent',
-           'SpectralSubsetSelect', 'SpectralSubsetSelectMixin']
+           'SubsetSelect', 'SpatialSubsetSelectMixin', 'SpectralSubsetSelectMixin']
 
 
 class TemplateMixin(VuetifyTemplate, HubListener):
@@ -125,7 +125,7 @@ def spectrum_viewer(self):
         return self._plugin.app.get_viewer("spectrum-viewer")
 
 
-class SpectralSubsetSelect(BasePluginComponent):
+class SubsetSelect(BasePluginComponent):
     """
     Traitlets (in the object, custom traitlets in the plugin):
 
@@ -136,61 +136,103 @@ class SpectralSubsetSelect(BasePluginComponent):
     Properties (in the object only):
 
     * ``labels`` (list of labels corresponding to items)
-    * ``selected_obj`` (subset object corresponding to selected, cached)
+    * ``selected_item`` (dictionary in ``items`` coresponding to ``selected``, cached)
+    * ``selected_obj`` (subset object corresponding to ``selected``, cached)
 
     Methods (in the object only):
 
-    * ``selected_min(cube)`` (float)
-    * ``selected_max(cube)`` (float)
+    * ``selected_min(cube)`` (float, only applicable for spectral subsets)
+    * ``selected_max(cube)`` (float, only applicable for spectral subsets)
 
     To use in a plugin:
 
-    * create traitlets with default values
+    * create (empty) traitlets in the plugin
     * register with all the automatic logic in the plugin's init by passing the string names
-      of the respective traitlets.
+      of the respective traitlets.  Pass ``allowed_type='spectral'`` or ``allowed_type='spatial'``
+      to only support spectral or spatial subsets, respectively.
     * use component in plugin template (see below)
     * refer to properties above based on the interally stored reference to the
       instantiated object of this component
+    * observe the traitlets created and defined in the plugin, as necessary
 
     Example template (label and hint are optional)::
 
       <plugin-subset-select
         :items="spectral_subset_items"
         :selected.sync="spectral_subset_selected"
-        label="Spectral region"
-        hint="Select spectral region."
+        label="Subset"
+        hint="Select subset."
       />
 
     """
-    def __init__(self, plugin, items, selected, selected_has_subregions=None):
+    def __init__(self, plugin, items, selected, selected_has_subregions=None,
+                 default_text=None, allowed_type=None):
+        """
+        Parameters
+        ----------
+        plugin :
+            the parent plugin object
+        items : str
+            the name of the items traitlet defined in ``plugin``
+        selected : str
+            the name of the selected traitlet defined in ``plugin``
+        selected_has_subregions: str
+            the name of the selected_has_subregions traitlet defined in ``plugin``, optional
+        default_text: str or None
+            the text to show for no selection.  If not provided or None, no entry will be provided
+            in the dropdown for no selection.
+        allowed_type: str or None
+            whether to filter to 'spatial' or 'spectral' types of subsets.  If not provided or None,
+            will include both entries.
+        """
         super().__init__(plugin,
                          items=items,
                          selected=selected,
                          selected_has_subregions=selected_has_subregions)
-        self.hub.subscribe(self, SubsetUpdateMessage, handler=self._update_spectral_subset)
-        self.hub.subscribe(self, SubsetDeleteMessage, handler=self._delete_spectral_subset)
+
+        self._default_text = default_text
+        if allowed_type not in [None, 'spatial', 'spectral']:
+            raise ValueError("allowed_type must be None, 'spatial', or 'spectral'")
+        self._allowed_type = allowed_type
+
+        # set default values for traitlets
+        if default_text is not None:
+            self.items = [{"label": default_text}]
+            self.selected = default_text
+        if selected_has_subregions is not None:
+            self.selected_has_subregions = False
+
+        self.hub.subscribe(self, SubsetUpdateMessage, handler=self._update_subset)
+        self.hub.subscribe(self, SubsetDeleteMessage, handler=self._delete_subset)
         self.add_observe(selected, self._selected_changed)
 
-    def _subset_to_dict(self, subset):
-        # find layer artist in default spectrum-viewer
-        for layer in self.spectrum_viewer.layers:
-            if layer.layer.label == subset.label:
-                color = layer.state.color
-                break
+    @staticmethod
+    def _subset_type(subset):
+        if isinstance(subset.subset_state, RoiSubsetState):
+            # then this is a spatial subset, we want to ignore
+            return 'spatial'
         else:
-            color = False
-        return {"label": subset.label, "color": color}
+            return 'spectral'
 
-    def _delete_spectral_subset(self, msg):
+    def _subset_to_dict(self, subset):
+        # find layer artist in default spectrum-viewer
+        for viewer in [self.app.get_viewer_by_id(id) for id in self.app.get_viewer_ids()]:
+            for layer in viewer.layers:
+                if layer.layer.label == subset.label:
+                    color = layer.state.color
+                    subset_type = self._subset_type(subset)
+                    return {"label": subset.label, "color": color, "type": subset_type}
+        return {"label": subset.label, "color": False, "type": False}
+
+    def _delete_subset(self, msg):
         # NOTE: calling .remove will not trigger traitlet update
         self.items = [s for s in self.items
                       if s['label'] != msg.subset.label]
         if self.selected not in self.labels:
             self.selected = "Entire Spectrum"
 
-    def _update_spectral_subset(self, msg):
-        if isinstance(msg.subset.subset_state, RoiSubsetState):
-            # then this is a spatial subset, we want to ignore
+    def _update_subset(self, msg):
+        if self._allowed_type is not None and self._subset_type(msg.subset) != self._allowed_type:
             return
 
         if msg.subset.label not in self.labels:
@@ -209,19 +251,20 @@ def _update_spectral_subset(self, msg):
 
         if msg.attribute == 'subset_state' and msg.subset.label == self.selected:
             # updated the currently selected subset
-            self._clear_cache("selected_obj")
+            self._clear_cache("selected_obj", "selected_item")
             self._update_has_subregions()
 
     def _selected_changed(self, event):
         if event['new'] not in self.labels:
-            self.selected = self.labels[0]
+            if len(self.labels):
+                self.selected = self.labels[0]
             raise ValueError(f"{event['new']} not one of {self.labels}")
-        self._clear_cache("selected_obj")
+        self._clear_cache("selected_obj", "selected_item")
         self._update_has_subregions()
 
     def _update_has_subregions(self):
         if "selected_has_subregions" in self._plugin_traitlets.keys():
-            if self.selected == "Entire Spectrum":
+            if self.selected == self._default_text:
                 self.selected_has_subregions = False
             else:
                 self.selected_has_subregions = len(self.selected_obj.subregions) > 1
@@ -230,21 +273,35 @@ def _update_has_subregions(self):
     def labels(self):
         return [s['label'] for s in self.items if 'label' in s.keys()]
 
+    @cached_property
+    def selected_item(self):
+        for item in self.items:
+            if item['label'] == self.selected:
+                return item
+
     @cached_property
     def selected_obj(self):
-        if self.selected == "Entire Spectrum":
+        if self.selected == self._default_text:
             return None
-        return self.app.get_subsets_from_viewer("spectrum-viewer",
-                                                subset_type="spectral").get(self.selected)
+        subset_type = self.selected_item['type']
+        for viewer in ['spectrum-viewer', 'flux-viewer']:
+            match = self.app.get_subsets_from_viewer(viewer,
+                                                     subset_type=subset_type).get(self.selected)
+            if match is not None:
+                return match
 
     def selected_min(self, spectrum1d):
-        if self.selected == "Entire Spectrum":
+        if self.selected_item['type'] != 'spectral':
+            raise TypeError("currently selected subset is not spectral")
+        if self.selected == self._default_text:
             return np.nanmin(spectrum1d.spectral_axis.value)
         else:
             return self.selected_obj.lower.value
 
     def selected_max(self, spectrum1d):
-        if self.selected == "Entire Spectrum":
+        if self.selected_item['type'] != 'spectral':
+            raise TypeError("currently selected subset is not spectral")
+        if self.selected == self._default_text:
             return np.nanmax(spectrum1d.spectral_axis.value)
         else:
             return self.selected_obj.upper.value
@@ -252,10 +309,10 @@ def selected_max(self, spectrum1d):
 
 class SpectralSubsetSelectMixin(VuetifyTemplate, HubListener):
     """
-    Applies the SpectralSubsetSelect component as a mixin in the base plugin.  This
-    automatically adds traitlets as well as new properties to the plugin with minimal
-    extra code.  For multiple instances or custom traitlet names/defaults, use the
-    SpectralSubsetSelect component instead.
+    Applies the SubsetSelect component with ``allowed_type='spectral'`` as a mixin in the base
+    plugin.  This automatically adds traitlets as well as new properties to the plugin with
+    minimal extra code.  For multiple instances or custom traitlet names/defaults, use the
+    SubsetSelect component instead.
 
     Traitlets (available from the plugin):
 
@@ -280,22 +337,68 @@ class SpectralSubsetSelectMixin(VuetifyTemplate, HubListener):
 
     Example template (label and hint are optional)::
 
-        <v-row>
-          <plugin-subset-select
-            :items="spectral_subset_items"
-            :selected.sync="spectral_subset_selected"
-            label="Spectral region"
-            hint="Select spectral region."
-          />
-        </v-row>
+      <plugin-subset-select
+        :items="spectral_subset_items"
+        :selected.sync="spectral_subset_selected"
+        label="Spectral region"
+        hint="Select spectral region."
+      />
     """
-    spectral_subset_items = List([{"label": "Entire Spectrum", "color": False}]).tag(sync=True)
-    spectral_subset_selected = Unicode("Entire Spectrum").tag(sync=True)
+    spectral_subset_items = List().tag(sync=True)
+    spectral_subset_selected = Unicode().tag(sync=True)
     spectral_subset_selected_has_subregions = Bool(False).tag(sync=True)
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
-        self.spectral_subset = SpectralSubsetSelect(self,
-                                                    'spectral_subset_items',
-                                                    'spectral_subset_selected',
-                                                    'spectral_subset_selected_has_subregions')
+        self.spectral_subset = SubsetSelect(self,
+                                            'spectral_subset_items',
+                                            'spectral_subset_selected',
+                                            'spectral_subset_selected_has_subregions',
+                                            default_text='Entire Spectrum',
+                                            allowed_type='spectral')
+
+
+class SpatialSubsetSelectMixin(VuetifyTemplate, HubListener):
+    """
+    Applies the SubsetSelect component with ``allowed_type='spatial'`` as a mixin in the base
+    plugin.  This automatically adds traitlets as well as new properties to the plugin with
+    minimal extra code.  For multiple instances or custom traitlet names/defaults, use the
+    SubsetSelect component instead.
+
+    Traitlets (available from the plugin):
+
+    * ``spatial_subset_items``
+    * ``spatial_subset_selected``
+    * ``spatial_subset_selected_has_subregions``
+
+    Properties (available from the plugin):
+
+    * ``spatial_subset.labels``
+    * ``spatial_subset.selected_obj``
+
+    To use in a plugin:
+
+    * add ``SpatialSubsetSelectMixin`` as a mixin to the class
+    * use the traitlets and properties above as needed (note the prefix for properties)
+
+    Example template (label and hint are optional)::
+
+      <plugin-subset-select
+        :items="spatial_subset_items"
+        :selected.sync="spatial_subset_selected"
+        label="Spatial region"
+        hint="Select spatial region."
+      />
+    """
+    spatial_subset_items = List().tag(sync=True)
+    spatial_subset_selected = Unicode().tag(sync=True)
+    spatial_subset_selected_has_subregions = Bool(False).tag(sync=True)
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.spatial_subset = SubsetSelect(self,
+                                           'spatial_subset_items',
+                                           'spatial_subset_selected',
+                                           'spatial_subset_selected_has_subregions',
+                                           default_text='No Subset',
+                                           allowed_type='spatial')