From 616939891d610b59289e0b93774a3a00990638ce Mon Sep 17 00:00:00 2001 From: Jaladh Singhal Date: Mon, 9 Dec 2024 19:04:46 -0800 Subject: [PATCH 1/3] FIREFLY-1623: Add url param to show_table (and fits) Also add it to documentation --- docs/usage/displaying-images.rst | 12 ++++++++++++ docs/usage/viewing-tables.rst | 7 +++++++ firefly_client/firefly_client.py | 23 +++++++++++++++-------- 3 files changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/usage/displaying-images.rst b/docs/usage/displaying-images.rst index 143a068..8f5e47b 100644 --- a/docs/usage/displaying-images.rst +++ b/docs/usage/displaying-images.rst @@ -221,3 +221,15 @@ It is possible to create a 3-color composite image using a list of dictionaries fc.show_fits_3color(threeC, plot_id='wise_m101', viewer_id='3C') + + +Displaying Image from a URL +--------------------------- + +If you have the URL of an image, you can pass it directly instead of +downloading it and then uploading it to firefly: + +.. code-block:: py + + image_url = 'http://irsa.ipac.caltech.edu/ibe/data/wise/allsky/4band_p1bm_frm/6a/02206a/149/02206a149-w1-int-1b.fits?center=70,20&size=200pix' + fc.show_fits(url=image_url, plot_id='wise-allsky', title='WISE all-sky') diff --git a/docs/usage/viewing-tables.rst b/docs/usage/viewing-tables.rst index 8272cb6..3f5376d 100644 --- a/docs/usage/viewing-tables.rst +++ b/docs/usage/viewing-tables.rst @@ -26,3 +26,10 @@ the table overlaid on the image, `is_catalog=False` can be specified: fc.show_table(file_on_server=tval, tbl_id='2mass-tbl', is_catalog=False) +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') diff --git a/firefly_client/firefly_client.py b/firefly_client/firefly_client.py index a08f47c..a2ad58f 100644 --- a/firefly_client/firefly_client.py +++ b/firefly_client/firefly_client.py @@ -732,6 +732,8 @@ def show_fits(self, file_on_server=None, plot_id=None, viewer_id=None, **additio Display only a particular image extension from the file (zero-based index). **Title** : `str`, optional Title to display with the image. + **url** : `str`, optional + URL of the fits image file, if it's not a local file you can upload. Returns ------- @@ -803,7 +805,7 @@ def show_fits_3color(self, three_color_params, plot_id=None, viewer_id=None): warning and r.update({'warning': warning}) return r - def show_table(self, file_on_server=None, tbl_id=None, title=None, page_size=100, is_catalog=True, + def show_table(self, file_on_server=None, url=None, tbl_id=None, title=None, page_size=100, is_catalog=True, meta=None, target_search_info=None, options=None, table_index=None, column_spec=None, filters=None, visible=True): """ @@ -811,10 +813,12 @@ def show_table(self, file_on_server=None, tbl_id=None, title=None, page_size=100 Parameters ---------- - file_on_server : `str` + file_on_server : `str`, optional The name of the file on the server. If you use `upload_file()`, then it is the return value of the method. Otherwise it is a file that Firefly has direct access to. + url : `str`, optional + URL of the table file, if it's not a local file you can upload. tbl_id : `str`, optional A table ID. It will be created automatically if not specified. title : `str`, optional @@ -872,28 +876,32 @@ def show_table(self, file_on_server=None, tbl_id=None, title=None, page_size=100 A string specifying filters. Column names must be quoted. For example, '("coord_dec" > -0.478) and ("parent" > 0)'. visible: `bool`, optional - If false, only load the table to Firefly but don't show it in the UI + If false, only load the table to Firefly but don't show it in the UI. + Similar to `fetch_table()` Returns ------- out : `dict` Status of the request, like {'success': True}. - .. note:: `file_on_server` and `target_search_info` are exclusively required. + .. note:: `url`, `file_on_server`, and `target_search_info` are exclusively required. + If more than one of these 3 parameters are passed, precedence order is: + `url` > `file_on_server` > `target_search_info` """ if not tbl_id: tbl_id = gen_item_id('Table') if not title: - title = tbl_id if file_on_server else target_search_info.get('catalog', tbl_id) + title = tbl_id if file_on_server or url else target_search_info.get('catalog', tbl_id) meta_info = {'title': title, 'tbl_id': tbl_id} meta and meta_info.update(meta) tbl_req = {'startIdx': 0, 'pageSize': page_size, 'tbl_id': tbl_id} - if file_on_server: + if file_on_server or url: tbl_type = 'table' if not is_catalog else 'catalog' - tbl_req.update({'source': file_on_server, 'tblType': tbl_type, + source = url if url else file_on_server + tbl_req.update({'source': source, 'tblType': tbl_type, 'id': 'IpacTableFromSource'}) table_index and tbl_req.update({'tbl_index': table_index}) elif target_search_info: @@ -941,7 +949,6 @@ def fetch_table(self, file_on_server, tbl_id=None, title=None, page_size=1, tabl out : `dict` Status of the request, like {'success': True}. """ - if not tbl_id: tbl_id = gen_item_id('Table') if not title: From 4a83b9b9527af8659b37a1e9edf6beef6bb3eb10 Mon Sep 17 00:00:00 2001 From: Jaladh Singhal Date: Tue, 10 Dec 2024 18:04:17 -0800 Subject: [PATCH 2/3] Add table filter/sorting methods with documentation --- docs/reference.rst | 3 +- docs/usage/viewing-tables.rst | 42 +++++++++++++++++++++++--- firefly_client/fc_utils.py | 2 ++ firefly_client/firefly_client.py | 52 ++++++++++++++++++++++++++++++++ 4 files changed, 93 insertions(+), 6 deletions(-) diff --git a/docs/reference.rst b/docs/reference.rst index 60ea4c1..740a843 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -4,5 +4,4 @@ API reference .. automodapi:: firefly_client :no-inheritance-diagram: - :no-heading: - + :skip: PackageNotFoundError, Env, FFWs, RangeValues diff --git a/docs/usage/viewing-tables.rst b/docs/usage/viewing-tables.rst index 3f5376d..5437d06 100644 --- a/docs/usage/viewing-tables.rst +++ b/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,6 +12,9 @@ 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`: @@ -18,18 +22,48 @@ without showing the table in the viewer, use :meth:`FireflyClient.fetch_table`: 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') diff --git a/firefly_client/fc_utils.py b/firefly_client/fc_utils.py index a6559e4..36f0a69 100644 --- a/firefly_client/fc_utils.py +++ b/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', diff --git a/firefly_client/firefly_client.py b/firefly_client/firefly_client.py index a2ad58f..b15792f 100644 --- a/firefly_client/firefly_client.py +++ b/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) From 9383656686cab5d6b464963a5d7f67b0ab2a8ab0 Mon Sep 17 00:00:00 2001 From: Jaladh Singhal Date: Wed, 11 Dec 2024 13:54:09 -0800 Subject: [PATCH 3/3] Make sorting documentation more clear --- docs/usage/viewing-tables.rst | 4 +++- firefly_client/firefly_client.py | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/usage/viewing-tables.rst b/docs/usage/viewing-tables.rst index 5437d06..6d87145 100644 --- a/docs/usage/viewing-tables.rst +++ b/docs/usage/viewing-tables.rst @@ -22,7 +22,7 @@ without showing the table in the viewer, use :meth:`FireflyClient.fetch_table`: fc.fetch_table(file_on_server=tval, tbl_id='invisible-table') -Alternatively, you can turn off the `visible` parameter in :meth:`FireflyClient.fetch_table`: +Alternatively, you can turn off the `visible` parameter in :meth:`FireflyClient.show_table`: .. code-block:: py @@ -67,3 +67,5 @@ order: .. code-block:: py fc.sort_table_column(tbl_id=tbl_id_2mass_psc, column_name='j_m', sort_direction='ASC') + +If a column has sorting, it can be removed by specifying `sort_direction=''`. diff --git a/firefly_client/firefly_client.py b/firefly_client/firefly_client.py index b15792f..1c6d228 100644 --- a/firefly_client/firefly_client.py +++ b/firefly_client/firefly_client.py @@ -1952,8 +1952,8 @@ def sort_table_column(self, tbl_id, column_name, sort_direction=''): 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 ''. + Direction of sort: '' for unsorted (or for removing the sort), + 'ASC' for ascending, and 'DESC' for descending. Default is ''. Returns --------