Add table filter/sorting methods with documentation

Author: jaladh-singhal

docs/reference.rst

@@ -4,5 +4,4 @@ API reference
 
 .. automodapi:: firefly_client
    :no-inheritance-diagram:
-   :no-heading:
-
+   :skip: PackageNotFoundError, Env, FFWs, RangeValues

docs/usage/viewing-tables.rst

@@ -1,5 +1,6 @@
+###############################
 Visualizing Tables and Catalogs
--------------------------------
+###############################
 
 Tables can be uploaded to the Firefly server with :meth:`FireflyClient.upload_file`,
 and displayed in a table viewer component with :meth:`FireflyClient.show_table`.
@@ -11,25 +12,58 @@ if the table contains recognizable celestial coordinates.
     tval = fc.upload_file('m31-2mass-2412-row.tbl')
     fc.show_table(file_on_server=tval, tbl_id='m31-table')
 
+Modifying Table Display Parameters
+----------------------------------
+
 If it is desired to overlay the table on an image, or to make plots from it,
 without showing the table in the viewer, use :meth:`FireflyClient.fetch_table`:
 
 .. code-block:: py
 
     fc.fetch_table(file_on_server=tval, tbl_id='invisible-table')
 
+Alternatively, you can turn off the `visible` parameter in :meth:`FireflyClient.fetch_table`:
+
+.. code-block:: py
+
+    fc.show_table(file_on_server=tval, tbl_id='invisible-table', visible=False)
+
 If the table does not contain celestial coordinates recognized by Firefly,
-the image overlay will not appear. BUt if you specifically do not want
-the table overlaid on the image, `is_catalog=False` can be specified:
+the image overlay will not appear. But if you specifically do not want
+the table overlaid on the image, `is_catalog=False` can be specified (it is 
+`True` by default):
 
 .. code-block:: py
 
     fc.show_table(file_on_server=tval, tbl_id='2mass-tbl', is_catalog=False)
 
+
+Displaying Table from a URL
+---------------------------
+
 If you have the URL of a table, you can pass it directly instead of 
 downloading it and then uploading it to firefly:
 
 .. code-block:: py
 
     table_url = "http://irsa.ipac.caltech.edu/TAP/sync?FORMAT=IPAC_TABLE&QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',70.0,20.0,0.1))=1"
-    fc.show_table(url=table_url, tbl_id='2mass-point-source-catalog')
+    tbl_id_2mass_psc = '2mass-point-source-catalog'
+    fc.show_table(url=table_url, tbl_id=tbl_id_2mass_psc)
+
+Filtering/Sorting a loaded Table
+--------------------------------
+
+After displaying a table in firefly, you can also apply filters on it. 
+You will need to pass the `tbl_id` of that table and specify `filters` as an
+SQL WHERE clause-like string with column names quoted:
+
+.. code-block:: py
+    
+    fc.apply_table_filters(tbl_id=tbl_id_2mass_psc, filters='"j_m">15 and "j_m"<16 and "j_cmsig"<0.06')
+
+You can sort the table by a column in ascending (`ASC`) or descending (`DESC`)
+order:
+
+.. code-block:: py
+    
+    fc.sort_table_column(tbl_id=tbl_id_2mass_psc, column_name='j_m', sort_direction='ASC')

firefly_client/fc_utils.py

@@ -70,6 +70,8 @@ def ensure3(val, name):
     'AddExtension': 'ExternalAccessCntlr/extensionAdd',
     'FetchTable': 'table.fetch',
     'ShowTable': 'table.search',
+    'TableFilter': 'table.filter',
+    'TableSort': 'table.sort',
     'ShowXYPlot': 'charts.data/chartAdd',
     'ShowPlot': 'charts.data/chartAdd',
     'ZoomImage': 'ImagePlotCntlr.ZoomImage',

firefly_client/firefly_client.py

@@ -1915,3 +1915,55 @@ def remove_mask(self, plot_id, mask_id):
 
         payload = {'plotId': plot_id, 'imageOverlayId': mask_id}
         return self.dispatch(ACTION_DICT['DeleteOverlayMask'], payload)
+
+    # ----------------------------
+    # actions on table
+    # ----------------------------
+
+    def apply_table_filters(self, tbl_id, filters):
+        """
+        Apply filters to a loaded table.
+
+        Parameters
+        ----------
+        plot_id : `str`
+            ID of the table where you want to apply filters
+        filters : `str`
+            SQL WHERE clause-like string specifying filters. Column names must be quoted.
+            For e.g. '("ra" > 185 AND "ra" < 185.1) OR ("dec" > 15 AND "dec" < 15.1) AND "band" IN (1,2)'.
+
+        Returns
+        --------
+        out : `dict`
+            Status of the request, like {'success': True}
+        """
+        tbl_req = {'tbl_id': tbl_id, 'filters': filters}
+        payload = {'request': tbl_req}
+        return self.dispatch(ACTION_DICT['TableFilter'], payload)
+    
+    def sort_table_column(self, tbl_id, column_name, sort_direction=''):
+        """
+        Sort a loaded table by a given column name.
+
+        Parameters
+        ----------
+        plot_id : `str`
+            ID of the table where you want to apply sort
+        column_name : `str`
+            Name of the table column to sort
+        sort_direction : {'', 'ASC', 'DESC'}, optional
+            Direction of sort: '' for unsorted, 'ASC' for ascending, and 'DESC'
+            for descending. Default is ''.
+
+        Returns
+        --------
+        out : `dict`
+            Status of the request, like {'success': True}
+        """
+        sort_directions = ['', 'ASC', 'DESC']
+        if sort_direction not in sort_directions:
+            raise ValueError(f'Invalid sort_direction. Valid values are {sort_directions}')
+        
+        tbl_req = {'tbl_id': tbl_id, 'sortInfo': f'{sort_direction},{column_name}'}
+        payload = {'request': tbl_req}
+        return self.dispatch(ACTION_DICT['TableSort'], payload)