From 5a8dc8607afd1ee0a1fbc3c179df019980c5c564 Mon Sep 17 00:00:00 2001
From: Kyle Conroy <kyleconroy@gmail.com>
Date: Thu, 17 Oct 2024 12:35:33 -0400
Subject: [PATCH] API hints (#133)

* implement api hints across all plugins
* expose missing API options (and hints) for ephemeris query
---
 CHANGES.rst                                   |  2 +-
 lcviz/components/plugin_ephemeris_select.vue  |  8 +-
 lcviz/plugins/binning/binning.vue             | 19 ++++-
 lcviz/plugins/ephemeris/ephemeris.py          |  5 +-
 lcviz/plugins/ephemeris/ephemeris.vue         | 83 +++++++++++++++----
 lcviz/plugins/flatten/flatten.vue             | 53 ++++++++----
 lcviz/plugins/flux_column/flux_column.vue     |  8 +-
 .../frequency_analysis/frequency_analysis.vue | 30 +++++--
 lcviz/plugins/time_selector/time_selector.py  |  1 +
 9 files changed, 160 insertions(+), 49 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 174bbf47..aa574925 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,7 +1,7 @@
 0.5.0 (unreleased)
 ------------------
 
-* Update jdaviz requirement to 4.0 to include upstream improvements. [#121]
+* Update jdaviz requirement to 4.0 to include upstream improvements including API hints. [#121, #133]
 
 * Prevent duplicate sub-intervals (quarter/sector/campaign) in data labels. [#120]
 
diff --git a/lcviz/components/plugin_ephemeris_select.vue b/lcviz/components/plugin_ephemeris_select.vue
index c06bc90f..f607ccc6 100644
--- a/lcviz/components/plugin_ephemeris_select.vue
+++ b/lcviz/components/plugin_ephemeris_select.vue
@@ -1,13 +1,14 @@
 <template>
   <div>
-  <v-row v-if="items.length > 1 || show_if_single_entry">
+  <v-row v-if="items.length > 1 || show_if_single_entry || api_hints_enabled">
     <v-select
       :menu-props="{ left: true }"
       attach
       :items="items"
       v-model="selected"
       @change="$emit('update:selected', $event)"
-      :label="label ? label : 'Ephemeris'"
+      :label="api_hints_enabled && api_hint ? api_hint : (label ? label : 'Ephemeris')"
+      :class="api_hints_enabled ? 'api-hint' : null"
       :hint="hint ? hint : 'Select ephemeris.'"
       :rules="rules ? rules : []"
       item-text="label"
@@ -34,7 +35,8 @@
 </template>
 <script>
 module.exports = {
-  props: ['items', 'selected', 'label', 'hint', 'rules', 'show_if_single_entry']
+  props: ['items', 'selected', 'label', 'hint', 'rules', 'show_if_single_entry',
+          'api_hint', 'api_hints_enabled']
 };
 </script>
 
diff --git a/lcviz/plugins/binning/binning.vue b/lcviz/plugins/binning/binning.vue
index 6bad2b59..31935263 100644
--- a/lcviz/plugins/binning/binning.vue
+++ b/lcviz/plugins/binning/binning.vue
@@ -1,5 +1,8 @@
 <template>
   <j-tray-plugin
+    :config="config"
+    plugin_key="Binning"
+    :api_hints_enabled.sync="api_hints_enabled"
     description='Bin in time or phase-space.'
     :link="'https://lcviz.readthedocs.io/en/'+vdocs+'/plugins.html#binning'"
     :uses_active_status="uses_active_status"
@@ -15,12 +18,14 @@
           </v-expansion-panel-header>
           <v-expansion-panel-content>
             <v-row>
-              <v-switch
-                v-model="show_live_preview"
+              <plugin-switch
+                :value.sync="show_live_preview"
                 label="Show live preview"
+                api_hint="plg.show_live_preview ="
+                :api_hints_enabled="api_hints_enabled"
                 hint="Whether to show live preview of binning options."
                 persistent-hint
-              ></v-switch>
+              />
             </v-row>
           </v-expansion-panel-content>
         </v-expansion-panel>
@@ -32,6 +37,8 @@
       :selected.sync="dataset_selected"
       :show_if_single_entry="false"
       label="Data"
+      api_hint="plg.dataset ="
+      :api_hints_enabled="api_hints_enabled"
       hint="Select the light curve as input."
     />
 
@@ -45,7 +52,8 @@
 
     <v-row>
       <v-text-field
-        label="N Bins"
+        :label="api_hints_enabled ? 'plg.n_bins =' : 'N Bins'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         type="number"
         v-model.number="n_bins"
         :step="10"
@@ -76,6 +84,9 @@
       action_tooltip="Bin data"
       :action_disabled="!bin_enabled"
       :action_spinner="spinner"
+      add_results_api_hint = 'plg.add_results'
+      action_api_hint='plg.bin(add_data=True)'
+      :api_hints_enabled="api_hints_enabled"
       @click:action="apply"
     ></plugin-add-results>
 
diff --git a/lcviz/plugins/ephemeris/ephemeris.py b/lcviz/plugins/ephemeris/ephemeris.py
index dcc97a9a..69e4c9c3 100644
--- a/lcviz/plugins/ephemeris/ephemeris.py
+++ b/lcviz/plugins/ephemeris/ephemeris.py
@@ -170,8 +170,9 @@ def user_api(self):
             'add_component', 'remove_component', 'rename_component',
             'times_to_phases', 'phases_to_times', 'get_data',
             'dataset', 'method', 'period_at_max_power',
-            'adopt_period_at_max_power', 'query_for_ephemeris',
-            'query_result', 'create_ephemeris_from_query'
+            'adopt_period_at_max_power',
+            'query_name', 'query_ra', 'query_dec', 'query_radius',
+            'query_for_ephemeris', 'query_result', 'create_ephemeris_from_query'
         ]
         return PluginUserApi(self, expose=expose)
 
diff --git a/lcviz/plugins/ephemeris/ephemeris.vue b/lcviz/plugins/ephemeris/ephemeris.vue
index 6f292663..83b22c84 100644
--- a/lcviz/plugins/ephemeris/ephemeris.vue
+++ b/lcviz/plugins/ephemeris/ephemeris.vue
@@ -1,5 +1,8 @@
 <template>
   <j-tray-plugin
+    :config="config"
+    plugin_key="Ephemeris"
+    :api_hints_enabled.sync="api_hints_enabled"
     description='Find and refine ephemerides for phase-folding.'
     :link="'https://lcviz.readthedocs.io/en/'+vdocs+'/plugins.html#ephemeris'"
     :popout_button="popout_button">
@@ -10,13 +13,28 @@
       :items="component_items"
       :selected.sync="component_selected"
       label="Component"
+      api_hint="plg.component ="
+      api_hint_add="plg.add_component"
+      api_hint_rename="plg.rename_component"
+      api_hint_remove="plg.remove_component"
+      :api_hints_enabled="api_hints_enabled"
       hint="Select an ephemeris component."
       >
     </plugin-editable-select>
 
     <v-row justify="end">
-      <v-btn color="primary" text @click="create_phase_viewer" :disabled="phase_viewer_exists || component_selected.length == 0">
-        Show Phase Viewer
+      <v-btn
+        color="primary" 
+        text
+        :class="api_hints_enabled ? 'api-hint' : null"
+        @click="create_phase_viewer"
+        :disabled="phase_viewer_exists || component_selected.length == 0"
+      >
+        {{ api_hints_enabled ? 
+          'plg.create_phase_viewer()'
+          :
+          'Show Phase Viewer'
+        }}
       </v-btn>
     </v-row>
 
@@ -27,7 +45,8 @@
         <v-text-field
           ref="t0"
           type="number"
-          label="Zeropoint (t0)"
+          :label="api_hints_enabled ? 'plg.t0 =' : 'Zeropoint (t0)'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           v-model.number="t0"
           :step="t0_step"
           type="number"
@@ -41,7 +60,8 @@
         <v-text-field
           ref="period"
           type="number"
-          label="Period"
+          :label="api_hints_enabled ? 'plg.period =' : 'Period'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           v-model.number="period"
           :step="period_step"
           hint="The period of the ephemeris, defined at t0."
@@ -64,7 +84,8 @@
         <v-text-field
           ref="dpdt"
           type="number"
-          label="Period derivative"
+          :label="api_hints_enabled ? 'plg.dpdt =' : 'Period derivative'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           v-model.number="dpdt"
           :step="dpdt_step"
           hint="The first time-derivative of the period of the ephemeris."
@@ -77,7 +98,8 @@
         <v-text-field
           ref="wrap_at"
           type="number"
-          label="Wrapping phase"
+          :label="api_hints_enabled ? 'plg.wrap_at =' : 'Wrapping phase'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           v-model.number="wrap_at"
           :step="0.1"
           :hint="'Phased data will encompass the range '+wrap_at_range+'.'"
@@ -93,6 +115,8 @@
         :selected.sync="dataset_selected"
         :show_if_single_entry="false"
         label="Data"
+        api_hint="plg.dataset ="
+        :api_hints_enabled="api_hints_enabled"
         hint="Select the light curve as input."
       />
 
@@ -102,7 +126,8 @@
           attach
           :items="method_items.map(i => i.label)"
           v-model="method_selected"
-          label="Algorithm/Method"
+          :label="api_hints_enabled ? 'plg.method =' : 'Algorithm/Method'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           hint="Method to determine period."
           persistent-hint
         ></v-select>
@@ -116,8 +141,19 @@
           </v-row>
           <v-row v-else>
             <j-tooltip :tooltipcontent="'adopt period into '+component_selected+' ephemeris.'">
-              <v-btn text color='primary' @click='adopt_period_at_max_power' style="padding: 0px">
-                period: {{period_at_max_power}}
+              <v-btn
+                text
+                color='primary'
+                :class="api_hints_enabled ? 'api-hint' : null"
+                @click='adopt_period_at_max_power'
+                style="padding: 0px"
+              >
+                {{ api_hints_enabled ? 
+                  'plg.adopt_period_at_max_power()'
+                  :
+                  'period: '+period_at_max_power
+                }}
+                
               </v-btn>
             </j-tooltip>
           </v-row>
@@ -156,7 +192,8 @@
         <v-text-field
           ref="query_name"
           type="string"
-          label="Object name"
+          :label="api_hints_enabled ? 'plg.query_name =' : 'Object name'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           v-model.number="query_name"
           hint="Object name."
           persistent-hint
@@ -166,7 +203,8 @@
         <v-text-field
           ref="query_ra"
           type="number"
-          label="RA (degrees)"
+          :label="api_hints_enabled ? 'plg.query_ra =' : 'RA (degrees)'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           v-model.number="query_ra"
           :step="ra_dec_step"
           hint="Object right ascension."
@@ -177,7 +215,8 @@
         <v-text-field
           ref="query_dec"
           type="number"
-          label="Dec (degrees)"
+          :label="api_hints_enabled ? 'plg.query_dec =' : 'Dec (degrees)'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           v-model.number="query_dec"
           :step="ra_dec_step"
           hint="Object declination."
@@ -188,7 +227,8 @@
         <v-text-field
           ref="query_radius"
           type="number"
-          label="Radius (arcseconds)"
+          :label="api_hints_enabled ? 'plg.query_radius =' : 'Radius (arcseconds)'"
+          :class="api_hints_enabled ? 'api-hint' : null"
           v-model.number="query_radius"
           :step="1"
           hint="Radius around the query coordinate."
@@ -201,8 +241,13 @@
           <plugin-action-button
             :spinner="query_spinner"
             :results_isolated_to_plugin="false"
+            :api_hints_enabled="api_hints_enabled"
             @click="query_for_ephemeris">
-              Query
+              {{ api_hints_enabled ? 
+                'plg.query_for_ephemeris()'
+                :
+                'Query'
+              }} 
           </plugin-action-button>
         </j-tooltip>
       </v-row>
@@ -214,7 +259,8 @@
             :items="query_result_items"
             :item-value="item => item.label"
             v-model="query_result_selected"
-            label="Ephemerides available"
+            :label="api_hints_enabled ? 'plg.query_result =' : 'Ephemerides available'"
+            :class="api_hints_enabled ? 'api-hint' : null"
             :hint="'Ephemeris parameters from ' + query_result_items.length + ' available query result(s)'"
             persistent-hint
             dense
@@ -246,8 +292,13 @@
             <v-col>
               <plugin-action-button
                 @click="create_ephemeris_from_query"
+                :class="api_hints_enabled ? 'api-hint' : null"
                 :disabled="component_items.map(item => item.label).includes(query_result_selected.replace(/\s/g, ''))">
-                  Create new component
+                  {{ api_hints_enabled ?
+                    'plg.create_ephemeris_from_query()'
+                    :
+                    'Create new component'
+                   }}  
               </plugin-action-button>
             </v-col>
             </v-row>
diff --git a/lcviz/plugins/flatten/flatten.vue b/lcviz/plugins/flatten/flatten.vue
index be51f402..bb0788e4 100644
--- a/lcviz/plugins/flatten/flatten.vue
+++ b/lcviz/plugins/flatten/flatten.vue
@@ -1,5 +1,8 @@
 <template>
   <j-tray-plugin
+    :config="config"
+    plugin_key="Flatten"
+    :api_hints_enabled.sync="api_hints_enabled"
     description='Remove long-term trends.'
     :link="'https://lcviz.readthedocs.io/en/'+vdocs+'/plugins.html#flatten'"
     :uses_active_status="uses_active_status"
@@ -15,23 +18,27 @@
           </v-expansion-panel-header>
           <v-expansion-panel-content>
             <v-row>
-              <v-switch
-                v-model="show_live_preview"
+              <plugin-switch
+                :value.sync="show_live_preview"
+                api_hint="plg.show_live_preview ="
+                :api_hints_enabled="api_hints_enabled"
                 label="Show flattened preview"
                 hint="Whether to show live-preview of the unnormalized flattened light curve."
                 persistent-hint
-              ></v-switch>
+              />
             </v-row>
             <v-row v-if="show_live_preview && !unnormalize">
               <v-alert type="warning">Live preview is unnormalized, but flattening will normalize.</v-alert>
             </v-row>
             <v-row>
-              <v-switch
-                v-model="show_trend_preview"
+              <plugin-switch
+                :value.sync="show_trend_preview"
+                api_hint="plg.show_trend_preview ="
+                :api_hints_enabled="api_hints_enabled"
                 label="Show trend preview"
                 hint="Whether to show live-preview of the trend used for flattening."
                 persistent-hint
-              ></v-switch>
+              />
             </v-row>
           </v-expansion-panel-content>
         </v-expansion-panel>
@@ -43,12 +50,15 @@
       :selected.sync="dataset_selected"
       :show_if_single_entry="false"
       label="Data"
+      api_hint="plg.dataset ="
+      :api_hints_enabled="api_hints_enabled"
       hint="Select the light curve as input."
     />
 
     <v-row>
       <v-text-field
-        label="Window length"
+        :label="api_hints_enabled ? 'plg.window_length =' : 'Window length'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         type="number"
         :step="1"
         v-model.number="window_length"
@@ -62,7 +72,8 @@
 
     <v-row>
       <v-text-field
-        label="Order"
+        :label="api_hints_enabled ? 'plg.polyorder =' : 'Order'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         type="number"
         :step="1"
         v-model.number="polyorder"
@@ -77,7 +88,8 @@
 
     <v-row>
       <v-text-field
-        label="Break tolerance"
+        :label="api_hints_enabled ? 'plg.break_tolerance =' : 'Break tolerance'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         type="number"
         :step="1"
         v-model.number="break_tolerance"
@@ -91,7 +103,8 @@
 
     <v-row>
       <v-text-field
-        label="Iterations"
+        :label="api_hints_enabled ? 'plg.niters =' : 'Iterations'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         type="number"
         :step="1"
         v-model.number="niters"
@@ -105,7 +118,8 @@
 
     <v-row>
       <v-text-field
-        label="Sigma"
+        :label="api_hints_enabled ? 'plg.sigma =' : 'Sigma'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         type="number"
         :step="0.5"
         v-model.number="sigma"
@@ -118,12 +132,14 @@
     </v-row>
 
     <v-row>
-      <v-switch
-        v-model="unnormalize"
+      <plugin-switch
+        :value.sync="unnormalize"
         label="Un-normalize"
+        api_hint="plg.unnormalize ="
+        :api_hints_enabled="api_hints_enabled"
         hint="Whether to multiply the flattened light curve by the median of the trend."
         persistent-hint
-      ></v-switch>
+      />
     </v-row>
 
     <v-row v-if="show_live_preview && !unnormalize">
@@ -136,6 +152,8 @@
       :auto.sync="flux_label_auto"
       :invalid_msg="flux_label_invalid_msg"
       hint="Label for flux column."
+      api_hint="plg.flux_label ="
+      :api_hints_enabled="api_hints_enabled"
     ></plugin-auto-label>
 
     <plugin-previews-temp-disabled
@@ -151,8 +169,13 @@
           :spinner="spinner"
           :disabled="flux_label_invalid_msg.length > 0"
           :results_isolated_to_plugin="false"
+          :class="api_hints_enabled ? 'api-hint' : null"
           @click="apply">
-            Flatten{{flux_label_overwrite ? ' (Overwrite)' : ''}}
+            {{ api_hints_enabled ?
+              'plg.flatten(add_data=True)'
+              :
+              'Flatten'+(flux_label_overwrite ? ' (Overwrite)' : '') 
+             }}
         </plugin-action-button>
       </j-tooltip>
     </v-row>
diff --git a/lcviz/plugins/flux_column/flux_column.vue b/lcviz/plugins/flux_column/flux_column.vue
index 810dad29..8a6347bf 100644
--- a/lcviz/plugins/flux_column/flux_column.vue
+++ b/lcviz/plugins/flux_column/flux_column.vue
@@ -1,5 +1,8 @@
 <template>
   <j-tray-plugin
+    :config="config"
+    plugin_key="Flux Column"
+    :api_hints_enabled.sync="api_hints_enabled"
     description='Choose which column to use as flux across lcviz.'
     :link="'https://lcviz.readthedocs.io/en/'+vdocs+'/plugins.html#flux-column'"
     :uses_active_status="uses_active_status"
@@ -12,6 +15,8 @@
       :selected.sync="dataset_selected"
       :show_if_single_entry="false"
       label="Data"
+      api_hint='plg.dataset ='
+      :api_hints_enabled="api_hints_enabled"
       hint="Select the light curve to modify."
     />
 
@@ -21,7 +26,8 @@
         attach
         :items="flux_column_items.map(i => i.label)"
         v-model="flux_column_selected"
-        label="Flux Column"
+        :label="api_hints_enabled ? 'plg.flux_column =' : 'Flux Column'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         hint="Select the column to adopt as flux."
         persistent-hint
       ></v-select>
diff --git a/lcviz/plugins/frequency_analysis/frequency_analysis.vue b/lcviz/plugins/frequency_analysis/frequency_analysis.vue
index 44cd0431..0f812abc 100644
--- a/lcviz/plugins/frequency_analysis/frequency_analysis.vue
+++ b/lcviz/plugins/frequency_analysis/frequency_analysis.vue
@@ -1,5 +1,8 @@
 <template>
   <j-tray-plugin
+    :config="config"
+    plugin_key="Frequency Analysis"
+    :api_hints_enabled.sync="api_hints_enabled"
     description='Frequency/period analysis.'
     :link="'https://lcviz.readthedocs.io/en/'+vdocs+'/plugins.html#frequency_analysis'"
     :popout_button="popout_button">
@@ -9,6 +12,8 @@
       :selected.sync="dataset_selected"
       :show_if_single_entry="false"
       label="Data"
+      api_hint="plg.dataset ="
+      :api_hints_enabled="api_hints_enabled"
       hint="Select the light curve as input."
     />
 
@@ -18,7 +23,8 @@
         attach
         :items="method_items.map(i => i.label)"
         v-model="method_selected"
-        label="Algorithm/Method"
+        :label="api_hints_enabled ? 'plg.method =' : 'Algorithm/Method'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         :hint="'Method to determine power at each '+xunit_selected+'.'"
         persistent-hint
       ></v-select>
@@ -30,19 +36,22 @@
         attach
         :items="xunit_items.map(i => i.label)"
         v-model="xunit_selected"
-        label="X Units"
+        :label="api_hints_enabled ? 'plg.xunit =' : 'X Units'"
+        :class="api_hints_enabled ? 'api-hint' : null"
         hint="Whether to plot in frequency or period-space."
         persistent-hint
       ></v-select>
     </v-row>
 
     <v-row>
-      <v-switch
-        v-model="auto_range"
+      <plugin-switch
+        :value.sync="auto_range"
         :label="'Auto '+xunit_selected+' range'"
+        api_hint="plg.auto_range ="
+        :api_hints_enabled="api_hints_enabled"
         :hint="'Whether to automatically or manually set the range on sampled '+xunit_selected+'s.'"
         persistent-hint
-      ></v-switch>
+      />
     </v-row>
 
     <v-row>
@@ -50,7 +59,8 @@
         v-if="!auto_range"
         ref="min"
         type="number"
-        :label="'Minimum '+xunit_selected"
+        :label="api_hints_enabled ? 'plg.minimum =' : 'Minimum '+xunit_selected"
+        :class="api_hints_enabled ? 'api-hint' : null"
         v-model.number="minimum"
         :step="minimum_step"
         type="number"
@@ -65,7 +75,8 @@
         v-if="!auto_range"
         ref="max"
         type="number"
-        :label="'Maximum '+xunit_selected"
+        :label="api_hints_enabled ? 'plg.maximum =' : 'Maximum '+xunit_selected"
+        :class="api_hints_enabled ? 'api-hint' : null"
         v-model.number="maximum"
         :step="maximum_step"
         type="number"
@@ -75,6 +86,11 @@
       ></v-text-field>
     </v-row>
 
+    <v-row v-if="api_hints_enabled">
+        <span class="api-hint">
+          plg.periodogram
+        </span>
+    </v-row>
 
     <div style="display: grid"> <!-- overlay container -->
       <div style="grid-area: 1/1">
diff --git a/lcviz/plugins/time_selector/time_selector.py b/lcviz/plugins/time_selector/time_selector.py
index 017d1cea..2677155e 100644
--- a/lcviz/plugins/time_selector/time_selector.py
+++ b/lcviz/plugins/time_selector/time_selector.py
@@ -39,6 +39,7 @@ def __init__(self, *args, **kwargs):
 
         """
         super().__init__(*args, **kwargs)
+        self.plugin_key = "Time Selector"
         self.docs_description = "Select time to sync across all viewers (as an indicator in all time/phase viewers or to select the active slice in any image/cube viewers).  The slice can also be changed interactively in any time viewer by activating the slice tool."  # noqa
         self.value_label = 'Time'
         self.value_unit = 'd'