FireflyClient#
- class firefly_client.FireflyClient(url, channel, html_file='', token=None, viewer_override=None)#
Bases:
objectFor Firefly client to build interface to remotely communicate to the Firefly viewer.
Parameters#
- urlstr
URL for Firefly server, e.g. https://lsst-demo.ncsa.illinois.edu/firefly. Defaults to the value of the environment variable FIREFLY_URL, if defined; or to ‘http://localhost:8080/firefly’ if FIREFLY_URL is not defined.
- channelstr
WebSocket channel ID. Default is None which auto-generates a unique string.
- html_filestr
HTML file that is the ‘landing page’ for users, appended to the URL. Defaults to ‘’. If the landing page in ‘slate.html’ it puts FireflyClient into slate mode.
- make_defaultbool
If True, make this the default FireflyClient instance. Default False.
- use_lab_envbool
If True, try to use environment variables for Jupyterlab. This can only be True in the Jupyter lab environment, otherwise there is an error. Default False.
- start_tab: bool
If True, bring up a Jupyterlab or a browser tab for Firefly. Default False.
- start_browser_tab: bool
If True, and start_tab is true and in use_lab_env is true then start a browser tab. Default False.
- token: str or None
A token for connecting to a Firefly server that requires authentication. The provided token will be appended to the string “Bearer “ to form the value of the “Authorization” header in the sessions attribute.
Attributes Summary
All events are enabled for the listener (str).
Methods Summary
add_cell(row, col, width, height, element_type)Add a slate viewer cell.
add_extension(ext_type[, plot_id, title, ...])Add an extension to the plot.
add_listener(callback[, name])Add a callback function to listen for events on the Firefly client.
add_mask(bit_number, image_number, plot_id)Add a mask layer.
add_region_data(region_data, region_layer_id)Add region entries to a region layer with the given ID.
align_images([match_type, lock_match])Align the images being displayed.
apply_table_filters(tbl_id, filters)Apply filters to a loaded table.
call_response(response)change_triview_layout(layout)Change the tri view layout
create_image_url(image_source)Create image url or data uri according to the image source.
delete_region_layer(region_layer_id[, plot_id])Delete region layer from the loaded FITS images.
DEPRECATED.
dispatch(action_type, payload[, ...])Dispatch the action to the server by using 'POST' request.
display_url([url])Display URL in a user-friendly format
fetch_table(file_on_server[, tbl_id, title, ...])Fetch table data without showing them
get_firefly_url([channel])Get URL to Firefly Tools viewer and the channel set.
Get all current instances
get_viewer_mode(html_file, viewer_override)is_slate()launch_browser([channel, force, verbose])Launch a browser with the Firefly Tools viewer and the channel set.
make_client([url, html_file, ...])Factory method to create a Firefly client in a plain Python, IPython, or notebook session, and attempt to open a display.
make_lab_client([start_browser_tab, ...])Factory method to create a Firefly client in the Jupyterlab environment.
overlay_footprints(footprint_file[, ...])Overlay a footprint dictionary on displayed images.
overlay_region_layer([file_on_server, ...])Overlay a region layer on the loaded FITS images.
parse_rvstring(rvstring)parse a Firefly RangeValues string into a dictionary
re-initialize the viewer
remove_listener(callback[, name])Remove an event name from the callback listener.
remove_mask(plot_id, mask_id)Remove a mask layer from the plot with the given plot ID.
remove_region_data(region_data, region_layer_id)Remove region entries from a region layer with the give ID.
rvstring_from_dict(rvdict)create an rvstring from a dictionary
set_color(plot_id[, colormap_id, bias, contrast])Change the color attributes (color map, bias, constrast) of an image plot.
set_pan(plot_id[, x, y, coord])Relocate the image to center on the given image coordinate or EQ_J2000 coordinate.
set_rgb_colors(plot_id[, use_red, ...])Change the color attributes of a 3-color fits image plot.
set_stretch(plot_id[, stype, algorithm, band])Change the stretch of the image (no band or 3-color per-band cases).
set_stretch_hprgb(plot_id[, asinh_q_value, ...])Change the stretch of RGB image (hue-preserving rgb case).
set_zoom(plot_id[, factor])Zoom the image.
show_chart([group_id])Show a plot.ly chart
show_coverage([viewer_id, table_group])Show image coverage associated with the active table in the specified table group
show_fits([file_on_server, plot_id, viewer_id])Show a FITS image.
show_fits_3color(three_color_params[, ...])Show a 3-color image constructed from the three color parameters
show_hips([plot_id, viewer_id, ...])Show HiPS image.
show_histogram(tbl_id[, group_id])Show a histogram
show_image_metadata([viewer_id, table_group])Show the image associated with the active (image metadata) table in the specified table group
show_image_or_hips([plot_id, viewer_id, ...])Show a FiTS or HiPS image.
show_lab_tab([html_file])If using a jupyter lab tab - show it or reopen it.
show_table([file_on_server, url, tbl_id, ...])Show a table.
show_xyplot(tbl_id[, standalone, group_id])Show a XY plot
sort_table_column(tbl_id, column_name[, ...])Sort a loaded table by a given column name.
table_highlight_callback(func, columns)Set a user-defined callback for table highlights
upload_data(stream, data_type)Upload a file like object to the Firefly server.
upload_file(path)Upload a file to the Firefly Server.
upload_fits_data(stream)Upload a FITS file like object to the Firefly server.
upload_text_data(stream)Upload a text file like object to the Firefly server.
Wait over events from the server.
Attributes Documentation
- BIVIEW_IChCov_T = 'BIVIEW_IChCov_T'#
- BIVIEW_ICov_Ch = 'BIVIEW_ICov_Ch'#
- BIVIEW_I_ChCov = 'BIVIEW_I_ChCov'#
- BIVIEW_T_IChCov = 'BIVIEW_T_IChCov'#
- NO_VIEWER = 'NO_VIEWER'#
- PINNED_CHART_VIEWER_ID = 'PINNED_CHART_VIEWER_ID'#
- PINNED_IMAGE_VIEWER_ID = 'DEFAULT_FITS_VIEWER_ID'#
- SLATE_VIEWER = 'FireflySlate'#
- TAB_ID = 'firefly-viewer-tab-id'#
- TRIVIEW_ICov_Ch_T = 'TRIVIEW_ICov_Ch_T'#
- TRIVIEW_I_ChCov_T = 'TRIVIEW_I_ChCov_T'#
- TRIVIEW_VIEWER = 'FireflyViewer'#
- instances = []#
All events are enabled for the listener (str).
- tri_view_layout_desc = {'BIVIEW_IChCov_T': 'left: image/charts/cov, right: tables', 'BIVIEW_ICov_Ch': 'left: image/cov, right: charts', 'BIVIEW_I_ChCov': 'left: image, right: charts/cov', 'BIVIEW_T_IChCov': 'left: tables, right: image/charts/cov', 'TRIVIEW_ICov_Ch_T': 'top left: image/cov, top right: charts, bottom: tables', 'TRIVIEW_I_ChCov_T': 'top left: image, top right: charts/cov, bottom: tables'}#
- tri_view_types_list = ['TRIVIEW_ICov_Ch_T', 'TRIVIEW_I_ChCov_T', 'BIVIEW_ICov_Ch', 'BIVIEW_I_ChCov', 'BIVIEW_T_IChCov', 'BIVIEW_IChCov_T']#
Methods Documentation
- add_cell(row, col, width, height, element_type, cell_id=None)#
Add a slate viewer cell.
Parameters#
- rowint
Cell row position.
- colint
Cell column position.
- widthint
Cell horizontal size.
- heightint
Cell vertical size.
- element_type{‘tables’, ‘images’, ‘xyPlots’, ‘tableImageMeta’, ‘coverageImage’}
Cell element type. Use ‘xyPlots’ for histograms.
- cell_idstr, optional
Cell Id.
Returns#
- outdict
Status of the request, like {‘success’: True, ‘cell_id’: ‘Cell-1’}.
- add_extension(ext_type, plot_id=None, title='', tool_tip='', shortcut_key='', extension_id=None, image_src=None)#
Add an extension to the plot. Extensions are context menus that allows you to extend what Firefly can do when certain actions happen.
Parameters#
- ext_type{‘AREA_SELECT’, ‘LINE_SELECT’, ‘POINT’, ‘table.select’, ‘table.highlight’}
Extension type. It can be one of the values in the list or any Firefly action, or it will be reset to be ‘NONE’.
- plot_idstr, optional
Plot ID of the plot which the extension is added to, if not specified, this request is applied to all plots in the same group of the active plot.
- titlestr, optional
The title for the extension.
- tool_tipstr, optional
Tooltip for the extension.
- extension_idstr, optional
Extension ID. It will be created automatically if not specified.
- shortcut_keystr, optional
use a letter for or a prefix it with ‘meta’ or ‘ctrl’ for example ‘a’, ‘m’, ‘meta-m’, ‘ctrl-m’
- image_srcstr, optional
Image source of an icon to be displayed on the toolbar instead of the title. Image source could be an image path or an image url.
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
If image_src is not specified, then no extension is added.
- add_listener(callback, name='ALL_EVENTS_ENABLED')#
Add a callback function to listen for events on the Firefly client.
Parameters#
- callbackFunction
The function to be called when a event happens on the Firefly client.
- namestr, optional
The name of the events (the default is ALL, all events).
Returns#
out : none
- add_mask(bit_number, image_number, plot_id, mask_id=None, color=None, title=None, file_on_server=None)#
Add a mask layer.
Parameters#
- bit_numberint
Bit number of the mask to overlay.
- image_numberint
Image number of the mask layer HDU extension in FITS. This is a zero-based index.
- plot_idstr
ID of the plot to overlay the mask on.
- mask_idstr, optional
Mask ID. It will be created automatically if not specified.
- colorstr, optional
Color as an html color (eg. ‘#ff0000’(red), ‘#00ff00’ (green)). A color will be created in default if not specified.
- titlestr, optional
Title of the mask layer.
- file_on_serverstr, optional
File to get the mask from. The mask will be taken from the original file if not specified.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- add_region_data(region_data, region_layer_id, title=None, plot_id=None)#
Add region entries to a region layer with the given ID.
Parameters#
- region_datastr or list of str
Region entries to be added.
- region_layer_idstr
ID of region layer where the entries are added to.
- titlestr, optional
Title of the region layer. If the layer exists, the original title is replaced. If the layer doesn’t exist, a new layer with the given title is created.
- plot_idstr or list of str, optional
Plot ID. This is for the case that the region layer doesn’t exist. If the region layer exists, this request applies to all plots attached to the layer.
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
If no region layer with the given ID exists, a new region layer will be created automatically just like how function overlay_region_layer works.
- align_images(match_type='Standard', lock_match=False)#
Align the images being displayed.
Parameters#
- match_type{‘Standard’, ‘Target’, ‘Pixel’, ‘PixelCenter’}, optional
Match type to use to align the images: align by WCS (‘Standard’), by target (‘Target’), by pixel prigins (‘Pixel’), and by pixel at image centers (‘PixelCenter’).
- lock_matchbool, optional
Whether to lock the alignment. Panning/zooming in one image will preserve the alignment in other images. Default is False.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- apply_table_filters(tbl_id, filters)#
Apply filters to a loaded table.
Parameters#
- tbl_idstr
ID of the table where you want to apply filters
- filtersstr
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#
- outdict
Status of the request, like {‘success’: True}
- call_response(response)#
- change_triview_layout(layout)#
Change the tri view layout
Parameters#
- layoutstr
should be one of FireflyClient.TRIVIEW_ICov_Ch_T - top left: image/cov, top right: charts, bottom: tables FireflyClient.TRIVIEW_I_ChCov_T - top left: image, top right: charts/cov, bottom: tables FireflyClient.BIVIEW_ICov_Ch - left: image/cov, right: charts FireflyClient.BIVIEW_I_ChCov - left: image, right: charts/cov FireflyClient.BIVIEW_T_IChCov- left: tables, right: image/charts/cov FireflyClient.BIVIEW_IChCov_T- left: image/charts/cov, right: tables
- static create_image_url(image_source)#
Create image url or data uri according to the image source.
Parameters#
- image_sourcestr
An image path or image url.
Returns#
- outstr
Data URI or image url.
- delete_region_layer(region_layer_id, plot_id=None)#
Delete region layer from the loaded FITS images.
Parameters#
- region_layer_idstr
Region layer ID. The region layer with the region layer ID is to be removed.
- plot_idstr or a list of str, optional
Plot ID. The region layer is removed from the plot with the plot ID. If not specified, then remove region layer from all plots in the same group of the active plot.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- disconnect()#
DEPRECATED. Now just remove the listeners. Disconnect the WebSocket.
- dispatch(action_type, payload, override_channel=None)#
Dispatch the action to the server by using ‘POST’ request.
Parameters#
- action_typestr
Action type, one of the actions from FireflyClient’s attribute, ACTION_DICT.
- payloaddict
Payload, the content varies based on the value of action_type.
- override_channelstr
overrides the default channel
Returns#
- outdict
Status of the remote dispatch, like {‘success’: True}.
- display_url(url=None)#
Display URL in a user-friendly format
Parameters#
- urlstr, optional
A url overriding the default (the default retrieves from self.get_firefly_url).
- fetch_table(file_on_server, tbl_id=None, title=None, page_size=1, table_index=None, meta=None)#
Fetch table data without showing them
Parameters#
- file_on_serverstr
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.
- tbl_idstr, optional
A table ID. It will be created automatically if not specified.
- titlestr, optional
Title associated with the table.
- page_sizeint, optional
The number of rows to fetch.
- table_indexint, optional
The table to be fetched in case file_on_server contains multiple tables. It is the extension number for a FITS file or the table index for a VOTable file. In unspecified, the server will fetch extension 1 from a FITS file or the table at index 0 from a VOTable file.
- metadict
META_INFO for the table search request.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- get_firefly_url(channel=None)#
Get URL to Firefly Tools viewer and the channel set. Normally this method will be called without any parameters.
Parameters#
- channelstr, optional
A different channel string than the default.
Returns#
- outstr
url string.
- static get_viewer_mode(html_file, viewer_override)#
- is_slate()#
- is_triview()#
- launch_browser(channel=None, force=False, verbose=True)#
Launch a browser with the Firefly Tools viewer and the channel set.
The page is launched when force is True or the page is not opened yet. Normally this method will be called without any parameters.
Parameters#
- channelstr, optional
A different channel than the default (the default is set as self.channel).
- forcebool, optional
If the browser page is forced to be opened (the default is False).
- verbose: bool, optional
If True, print instructions if web browser is not opened (default True)
Returns#
- open_successbool
If True, the web browser open was successful.
- urlstr
The URL that is used in the user’s web browser.
- classmethod make_client(url='http://localhost:8080/firefly', html_file='', launch_browser=True, channel_override=None, verbose=False, token=None, viewer_override=None)#
Factory method to create a Firefly client in a plain Python, IPython, or notebook session, and attempt to open a display. If a display cannot be opened, a link will be displayed.
Parameters#
- url: str, optional
URL of the Firefly server. The default is determined by checking environment variables ‘fireflyURLLab’ and ‘FIREFLY_URL’; if these are undefined, then the default is ‘http://localhost:8080/firefly’ for the case of a user running a Firefly server on their desktop.
- html_file: str, optional
HTML file that is the ‘landing page’ for users, appended to the URL. Defaults to the value of the environment variable ‘FIREFLY_URL’ if it is defined: otherwise defaults to ‘’. If the landing page in ‘slate.html’ it puts FireflyClient into slate mode.
- launch_browser: bool, optional
If True, attempt to launch a browser tab for the Firefly viewer. If that attempt is unsuccessful, a link for the Firefly viewer is displayed.
- channel_override: str or None
If channel_override is None, the value of the environment variable ‘FIREFLY_CHANNEL’ is checked. If unset, then a URL-safe channel string is generated. If channel_override is set to a string, it is used for the Firefly channel.
- verbose: bool
If True, print instructions if web browser is not opened (default false)
- token: str or None
A token for connecting to a Firefly server that requires authentication. The provided token will be appended to the string “Bearer “ to form the value of the “Authorization” header in the sessions attribute.
- viewer_override: str
This parameter is almost never used, default to None. It is only for those special circumstances that you would use firefly_client to control a custom created interface that is not a triview ora slate view. maybe one of FireflyClient.TRIVIEW_VIEWER, FireflyClient.SLATE_VIEWER, FireflyClient.NO_VIEWER,
Returns#
- fcFireflyClient
A FireflyClient that works in the lab environment
- classmethod make_lab_client(start_browser_tab=False, html_file='', start_tab=True, verbose=False, token=None)#
Factory method to create a Firefly client in the Jupyterlab environment. If you are using Jupyterlab with the jupyter_firefly_extension installed, then this method is the best way to construct a FireflyClient. If called in a non-Jupyterlab environment, the method raises a RuntimeError.
Parameters#
- start_browser_tabbool
If True start a browser tab, if False start a lab tab. start_tab must also be True. To start a new tab you will have to disable popup blocking for the Jupyterlab site.
Chrome: look at the right side of the address bar Firefox: a preference bar appears at the top Safari: shows an animation to follow on the left side bar
- html_file: str, optional
HTML file that is the ‘landing page’ for users, appended to the URL. Defaults to the value of the environment variable ‘FIREFLY_URL’ if it is defined: otherwise defaults to ‘’. If the landing page in ‘slate.html’ it puts FireflyClient into slate mode.
- start_tab: bool, optional
If True, bring up a Jupyterlab or a browser tab for Firefly. You should almost always take the default.
- token: str or None
A token for connecting to a Firefly server that requires authentication. The provided token will be appended to the string “Bearer “ to form the value of the “Authorization” header in the sessions attribute.
- verbose: boolean
If True, print instructions if web browser is not opened (default false)
Returns#
- outFireflyClient
A FireflyClient that works in the lab environment
- overlay_footprints(footprint_file, footprint_image=None, title=None, footprint_layer_id=None, plot_id=None, table_index=None, **additional_params)#
Overlay a footprint dictionary on displayed images. The dictionary must be convertible to JSON format.
Parameters#
- footprint_filestr
footprint file with a table containing measurements and footprints
- footprint_image: str
footprint image file
- titlestr, optional
Title of the footprint layer.
- footprint_layer_idstr, optional
ID of the footprint layer to be created. It is automatically created if not specified.
- plot_idstr or list of str, optional
ID of the plot that the footprint layer is created on. If None, then overlay the footprint on all plots in the same group of the active plot.
- table_indexint, optional
The table to be shown in case file_on_server contains multiple tables. It is the extension number for a FITS file or the table index for a VOTable file. In unspecified, the server will fetch extension 1 from a FITS file or the table at index 0 from a VOTable file.
- **additional_paramsoptional keyword arguments
parameters for footprint overlays, the options are shown as below:
- colorstr, optional
color for the footprint. it is color name like ‘red’ or color code like ‘rgb(0,0,0)’
- stylestr, optional
footprint display style, ‘outline’ or ‘fill’
- showTextbool, optional
show text, footprint id if there is, by the ‘outline’ display
- selectColor‘str`, optional
color for selected footprint
- highlightColorstr optional
color for highlighted footprint
Returns#
- outdict
Status of the request, like {‘success’: True}.
- overlay_region_layer(file_on_server=None, region_data=None, title=None, region_layer_id=None, plot_id=None)#
Overlay a region layer on the loaded FITS images. The regions are defined either by a file or by text region description.
Parameters#
- file_on_serverstr, optional
This is 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 read access to.
- region_datastr or list of str, optional
Region description, either a list of strings or a string.
- titlestr, optional
Title of the region layer.
- region_layer_idstr, optional
ID of the region layer to be created. It is automatically created if not specified.
- plot_idstr or list of str, optional
ID of the plot that the region layer is created on. If None, then overlay region(s) on all plots in the same group of the active plot.
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
file_on_server and region_data are exclusively required. If both are specified, file_on_server takes the priority. If none is specified, no region layer is created.
- static parse_rvstring(rvstring)#
parse a Firefly RangeValues string into a dictionary
Parameters#
- rvstringstr
RangeValues string as returned by the set_stretch method.
Returns#
- outdictdict
dictionary of the inputs
- reinit_viewer()#
re-initialize the viewer
Returns#
- outdict
Status of the request, like {‘success’: True}.
- remove_listener(callback, name='ALL_EVENTS_ENABLED')#
Remove an event name from the callback listener.
Parameters#
- callbackFunction
A previously set callback function.
- namestr, optional
The name of the event to be removed from the callback listener (the default is ALL, all events).
Returns#
out : none
Note
callback in the listener list is removed if all events are removed from the callback.
- remove_mask(plot_id, mask_id)#
Remove a mask layer from the plot with the given plot ID.
Parameters#
- plot_idstr
ID of the plot where the mask layer to be removed from.
- mask_idstr
ID of the mask layer to be removed.
Returns#
- outdict
Status of the request, like {‘success’: True}
- remove_region_data(region_data, region_layer_id)#
Remove region entries from a region layer with the give ID.
Parameters#
- region_datastr or list of str
Region entries to be removed.
- region_layer_idstr
ID of the region layer where the region entries are removed from.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- static rvstring_from_dict(rvdict)#
create an rvstring from a dictionary
Parameters#
- rvdictdict
Dictionary with the same keys as those returned by parse_rvstring
Returns#
- rvstringstr
RangeValues string that can be passed to the show_fits methods
- set_color(plot_id, colormap_id=0, bias=0.5, contrast=1)#
Change the color attributes (color map, bias, constrast) of an image plot.
Parameters#
- plot_idstr or list of str
ID of the image plot to be colored.
- colormap_idint, optional
ID of the colormap or color-table to use, ranging from 0 to 21. (the default is 0 i.e. grayscale). For HiPS image, -1 can be used to set the default hips image colors. Refer to the color dropdown on the image toolbar to see how IDs are mapped.
- biasfloat, optional
Bias to use, between 0 and 1 (the default is 0.5)
- contrastfloat, optional
Contrast to use, between 0 and 10 (the default is 1)
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
when colormap_id is -1 for HiPS image, contrast and bias have no effect.
- set_pan(plot_id, x=None, y=None, coord='image')#
Relocate the image to center on the given image coordinate or EQ_J2000 coordinate. If no (x, y) is given, the image is re-centered at the center of the image.
Parameters#
- plot_idstr or list of str
ID of the plot to be panned. If plot_id is a list or tuple, then each plot in the list or the tuple is panned in order.
- x, yint or float, optional
New center of x and y position to scroll to. Not required if coord is set ‘image’ because it will center on the image.
- coordstr, optional
Coordinate system to use if x and y is specified like J2000, EQB2000, GAL, etc. The default is ‘image’ which will center on the image.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- set_rgb_colors(plot_id, use_red=True, use_green=True, use_blue=True, bias=[0.5, 0.5, 0.5], contrast=[1, 1, 1])#
Change the color attributes of a 3-color fits image plot.
Parameters#
- plot_idstr or list of str
ID of the image plot to be colored.
- use_redbool, optional
Whether to use red band in coloring the image (default is True)
- use_greenbool, optional
Whether to use green band in coloring the image (default is True)
- use_bluebool, optional
Whether to use blue band in coloring the image (default is True)
- biaslist of float, optional
Bias to use for each band, between 0 and 1 (the default is [0.5, 0.5, 0.5])
- contrastlist of float, optional
Contrast to use for each band, between 0 and 10 (the default is [1, 1, 1])
Returns#
- outdict
Status of the request, like {‘success’: True}.
- set_stretch(plot_id, stype=None, algorithm=None, band=None, **additional_params)#
Change the stretch of the image (no band or 3-color per-band cases).
Parameters#
- plot_idstr or list of str
ID of the plot to be stretched. If plot_id is a list or tuple, then each plot in the list or the tuple is stretched in order.
- stype{‘percent’, ‘minmax’, ‘absolute’, ‘zscale’, ‘sigma’}, optional
Stretch method (the default is ‘percent’).
- algorithm{‘linear’, ‘log’, ‘loglog’, ‘equal’, ‘squared’, ‘sqrt’, ‘asinh’, ‘powerlaw_gamma’}, optional
Stretch algorithm (the default is ‘linear’).
- band{‘RED’, ‘GREEN’, ‘BLUE’, ‘ALL’}, optional
3-color band to apply stretch to
- **additional_paramsoptional keyword arguments
Parameters for changing the stretch. The options are shown as below:
- zscale_contrastint, optional
zscale contrast (the default is 25).
- zscale_samplesint, optional
zscale samples, int (the default is 600).
- zscale_samples_perlineint, optional
zscale samples per line (the default is 120).
- lower_valueint or float, optional
Lower end of stretch (the default is 1).
- upper_valueint or float, optional
Upper end of stretch (the default is 90).
- asinh_q_valuefloat, optional
The asinh softening parameter for Asinh stretch. Use Q=0 for linear stretch, increase Q to make brighter features visible. When not specified, Q is calculated by Firefly to use full color range.
- gamma_value
The gamma value for Power Law Gamma stretch
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
zscale_contrast, zscale_samples, and zscale_samples_perline are used when stype is ‘zscale’, and lower_value and upper_value are used when stype is not ‘zscale’.
- set_stretch_hprgb(plot_id, asinh_q_value=None, scaling_k=1.0, pedestal_value=1, pedestal_type='percent')#
Change the stretch of RGB image (hue-preserving rgb case). When a parameter is a list, it must contain three elements, for red, green and blue bands respectively. Otherwise the parameter is a scalar that is used for all three bands.
Parameters#
- plot_idstr or list of str
ID of the plot to be stretched. If plot_id is a list or tuple, then each plot in the list or the tuple is stretched in order.
- asinh_q_valuefloat, optional
The asinh softening parameter for Asinh stretch. Use Q=0 for linear stretch, increase Q to make brighter features visible. When not specified, Q is calculated by Firefly to use full color range for intensity.
- scaling_kfloat or list of float, optional
Scaling coefficient from 0.1 to 10 (the default is 1).
- pedestal_type{‘percent’, ‘minmax’, ‘absolute’, ‘zscale’, ‘sigma’} or list of str, optional
Method to obtain pedestal value (the default is ‘percent’).
- pedestal_valuefloat or list of float, optional
Minimum value (the default is 1 percent).
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
pedestal_value is used when pedestal_type is not ‘zscale’.
- set_zoom(plot_id, factor=1.0)#
Zoom the image.
Parameters#
- plot_idstr or list of str
ID of the plot to be zoomed. If plot_id is a list or tuple, then each plot in the list or the tuple is zoomed in order.
- factorint or float, optional
Zoom factor for the image.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- show_chart(group_id='PINNED_CHART_VIEWER_ID', **chart_params)#
Show a plot.ly chart
Plotly chart is described by a list of trace data and a layout. Any list in trace data can come from a table.
For example, if a trace is defined by {‘tbl_id’: ‘wise’, ‘x’: ‘tables::w1pro’, ‘y’: ‘tables::w2mpro’ }, x and y points of the trace will come from w1mpro and w2mpro columns of the table with the id wise.
See plotly.js attribute reference for the supported trace types and attributes. Note, that data and layout are expected to be basic Python object hierarchies, as json.dumps is used to convert them to JSON.
Parameters#
- group_idstr, optional
Group ID of the chart group where the chart belongs to. If grid view is used, group id is the cell id of the cell which contains the chart.
- **chart_paramsoptional keyword arguments
Parameters for the chart. The options are shown as below:
- chartId: str, optional
The chart ID.
- data: list of dict, optional
A list of data for all traces of the plot.ly chart. Firefly-specific keys: tbl_id, firefly (for Firefly chart types).
- layout: dict, optional
The layout for plot.ly layout. Optional firefly key refers to the information processed by Firefly.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- show_coverage(viewer_id=None, table_group='main')#
Show image coverage associated with the active table in the specified table group
Parameters#
- viewer_idstr, optional
Viewer id, the cell id of the cell which contains the coverage image.
- table_groupstr, optional
Table group which the image coverage associated table belongs to.
Returns#
- outdict
Status of the request, like {‘success’: True}
- show_fits(file_on_server=None, plot_id=None, viewer_id=None, **additional_params)#
Show a FITS image.
Parameters#
- file_on_serverstr, optional
The is 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.
- plot_idstr, optional
The ID you assign to the image plot. This is necessary to further control the plot.
- viewer_idstr, optional
The ID you assign to the viewer (or cell) used to contain the image plot. If grid view is used for display, the viewer id is the cell id of the cell which contains the image plot.
- **additional_paramsoptional keyword arguments
Any valid fits viewer plotting parameter, please see the details in FITS plotting parameters.
More options are shown as below:
- MultiImageIdxint, optional
Display only a particular image extension from the file (zero-based index).
- Titlestr, optional
Title to display with the image.
- urlstr, optional
URL of the fits image file, if it’s not a local file you can upload.
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
Either file_on_server or the target information set by additional_params is used for image search.
- show_fits_3color(three_color_params, plot_id=None, viewer_id=None)#
Show a 3-color image constructed from the three color parameters
Parameters#
- three_color_paramslist of dict or dict
A list or objects contains image viewer plotting parameters for either all bands or one single band. For valid image viewer plotting parameter, please see the details in FITS plotting parameters or the description of additional_params in function show_fits.
- plot_idstr, optional
The ID you assign to the image plot. This is necessary to further control the plot.
- viewer_idstr, optional
The ID you assign to the viewer (or cell) used to contain the image plot. If grid view is used for display, the viewer id is the cell id of the cell which contains the image plot.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- show_hips(plot_id=None, viewer_id=None, hips_root_url=None, hips_image_conversion=None, **additional_params)#
Show HiPS image.
Parameters#
- plot_idstr, optional
The ID you assign to the image plot. This is necessary to further control the plot.
- viewer_idstr, optional
The ID you assign to the viewer (or cell) used to contain the image plot. If grid view is used for display, the viewer id is the cell id of the cell which contains the image plot.
- hips_root_urlstr
HiPS access URL
- hips_image_conversion: dict, optional
The info used to convert between image and HiPS
- **additional_paramsoptional keyword arguments
parameters for HiPS viewer plotting, the options are shown as below:
- WorldPtstr, optional
World point as the center of the HiPS, if not defined, then get it from HiPS properties or set as the origin of the celestial coordinates.
- Titlestr, optional
Title to display with the HiPS.
- SizeInDegint or float, optional
Field of view for HiPS.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- show_histogram(tbl_id, group_id='PINNED_CHART_VIEWER_ID', **histogram_params)#
Show a histogram
Parameters#
- tbl_idstr
A table ID of the data to be plotted.
- group_idstr, optional
Group ID of the chart group where the histogram belongs to. If grid view is used, group id is the cell id of the cell which contains the histogram.
- **histogram_paramsoptional keyword arguments
Parameters for histogram. The options are shown as below:
- col: str
Column or expression to use for x values, can contain multiple column names, ex. log(col) or (col1-col2)/col3.
- xOptions: str
comma separated list of x axis options: flip,log.
- yOptions: str
comma separated list of y axis options: flip,log.
- falsePositiveRate: int or float
false positive rate for bayesian blocks algorithm.
- numBinsint
Number of bins for fixed bins algorithm, default is 50.
- binWidthint or float
Bin width.
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
For the histogram parameters, col is required.
- show_image_metadata(viewer_id=None, table_group='main')#
Show the image associated with the active (image metadata) table in the specified table group
Parameters#
- viewer_idstr, optional
Viewer id, the cell id of the cell which contains the image from image metadata table.
- table_groupstr, optional
Table group which the image metadata table belongs to.
Returns#
- outdict
Status of the request, like {‘success’: True}
- show_image_or_hips(plot_id=None, viewer_id=None, image_request=None, hips_request=None, fov_deg_fallover=0.12, allsky_request=None, plot_allsky_first=False)#
Show a FiTS or HiPS image.
Parameters#
- plot_idstr, optional
The ID you assign to the image plot. This is necessary to further control the plot.
- viewer_idstr, optional
The ID you assign to the viewer (or cell) used to contain the image plot. If grid view is used for display, the viewer id is the cell id of the cell which contains the image plot.
- image_requestdict, optional
Request with fits plotting parameters. For valid fits viewer plotting parameter, please see the the description of show_fits or show_fits_3color.
- hips_requestdict, optional
Request with hips plotting parameters. For valid HiPS viewer plotting parameter, please see the description of show_hips.
- fov_deg_falloverfloat, optional
The size in degrees that the image will switch between hips and a image cutout.
- allsky_requestdict, optional
Allsky type request, like {‘Type’: ‘ALL_SKY’}
- plot_allsky_firstbool, optional
Plot all sky first If there is an all sky set up.
Returns#
- outdict
Status of the request, like {‘success’: True}.
- show_lab_tab(html_file='')#
If using a jupyter lab tab - show it or reopen it. If not using a lab tab then noop
- show_table(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)#
Show a table.
Parameters#
- file_on_serverstr, 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.
- urlstr, optional
URL of the table file, if it’s not a local file you can upload.
- tbl_idstr, optional
A table ID. It will be created automatically if not specified.
- titlestr, optional
Title associated with the table.
- page_sizeint, optional
The number of rows that are shown in the table page (the default is 100).
- is_catalogbool, optional
If the table file is a catalog (the default is True) or not.
- metadict
META_INFO for the table search request.
- target_search_infodict, optional
The information for target search, it may contain the following fields:
- catalogProjectstr
Catalog project, such as ‘WISE’.
- catalogstr
Table to be searched, such as ‘allwise_p3as_psd’.
- usestr
Usage of the table search, such as ‘catalog_overlay’.
- positionstr
Target position, such as ‘10.68479;41.26906;EQ_J2000’.
- SearchMethod{‘Cone’, ‘Eliptical’, ‘Box’, ‘Polygon’, ‘Table’, ‘AllSky’}
Target search method.
- radiusfloat
The radius for ‘Cone’ or the semi-major axis for ‘Eliptical’ search in terms of unit arcsec.
- posangfloat
Position angle for ‘Eliptical’ search in terms of unit arcsec.
- ratiofloat
Axial ratio for ‘Eliptical’ search.
- sizefloat
Side size for ‘Box’ search in terms of unit arcsec.
- polygonstr
ra/dec of polygon corners, such as ‘ra1, dec1, ra2, dec2,… raN, decN’.
- filenamestr
The name of file on server on multi-objects for ‘Table’ search.
- optionsdict, optional
Containing parameters for table display, such as,
- removablebool
if table is removable.
- showUnitsbool
if table shows units for the columns.
- showFiltersbool
if table shows filter button
- table_indexint, optional
The table to be shown in case file_on_server contains multiple tables. It is the extension number for a FITS file or the table index for a VOTable file. In unspecified, the server will fetch extension 1 from a FITS file or the table at index 0 from a VOTable file.
- column_specstr, optional
A string specifying column names from the table that will be shown. Column names must appear in the string in quotes, eg. ‘“ra”,”dec”,”mag”’ It is possible to derive columns, e.g. ‘“flux”/”flux_err” as “SNR”’
- filtersstr, optional
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. Similar to fetch_table()
Returns#
- outdict
Status of the request, like {‘success’: True}.
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
- show_xyplot(tbl_id, standalone=False, group_id=None, **chart_params)#
Show a XY plot
Parameters#
- tbl_idstr
A table ID of the data to be plotted.
- standalonebool, optional
When it is True, the chart is always present in the chart area, no matter if the related table is present or not.
- group_idstr, optional
Group ID of the chart group where the chart belongs to. If grid view is used, group id is the cell id of the cell which contains the chart.
- **chart_paramsoptional keyword arguments
Parameters for XY Plot. The options are shown as below:
- xCol: str
Column or expression to use for x values, can contain multiple column names, ex. log(col) or (col1-col2)/col3.
- xError: str
Column or expression to use for x error, can contain multiple column names
- yCol: str
Column or expression to use for y values, can contain multiple column names, ex. sin(col) or (col1-col2)/col3.
- yError: str
Column or expression to use for x error, can contain multiple column names.
- xyRatioint or float
Aspect ratio (must be between 1 and 10).
- stretch{‘fit’, ‘fill’}
Stretch method.
- plotStyle{‘points’, ‘line’, ‘linepoints’}
Style of XY plot.
- chartTitlestr
Title of the chart.
- xLabelstr
Label to use with x axis.
- yLabelstr
Label to use with y axis.
- xUnitstr
Unit for x axis.
- yUnitstr
Unit for y axis.
- xOptionsstr
Comma separated list of x axis options: grid,flip,log.
- yOptionsstr
Comma separated list of y axis options: grid,flip,log.
Returns#
- outdict
Status of the request, like {‘success’: True}.
Note
For the chart parameters, xCol and yCol are required, then all other parameters are valid.
- sort_table_column(tbl_id, column_name, sort_direction='')#
Sort a loaded table by a given column name.
Parameters#
- tbl_idstr
ID of the table where you want to apply sort
- column_namestr
Name of the table column to sort
- sort_direction{‘’, ‘ASC’, ‘DESC’}, optional
Direction of sort: ‘’ for unsorted (or for removing the sort), ‘ASC’ for ascending, and ‘DESC’ for descending. Default is ‘’.
Returns#
- outdict
Status of the request, like {‘success’: True}
- table_highlight_callback(func, columns)#
Set a user-defined callback for table highlights
Parameters#
- funcfunction
The function to apply to the callback data. It must take as arguments: absolute_row, relative_row, column_data, table_id. absolute_row is a zero-based index to the highlighted row,
in the original table data.
relative_row is the index to the highlighted row in the table view. column_data is a dictionary of column name:data value pairs,
for the highlighted row.
table_id is a string identifying the table in Firefly.
- columnslist or None
List of column names for which to return data. If the list is empty, the column_data will be an empty dictionary. If None, all columns are included.
Returns#
func : the callback function that was added
- upload_data(stream, data_type)#
Upload a file like object to the Firefly server. The method should allow either FITS or non-FITS file like data to be streamed without using an actual file.
Parameters#
- streamobject
A file like object containing FITS data or others.
- data_type{‘FITS’, ‘UNKNOWN’}
Data type, FITS or others.
Returns#
- outdict
Status, like {‘success’: True}.
- upload_file(path)#
Upload a file to the Firefly Server.
Parameters#
- pathstr
Path of uploaded file. It can be fits, region, and various types of table files.
Returns#
- out: str
Path of file after the upload.
Note
‘pre_load’ is not implemented in the server (will be removed later).
- upload_fits_data(stream)#
Upload a FITS file like object to the Firefly server. The method should allow file like data to be streamed without using an actual file.
Parameters#
- streamobject
A FITS file like object containing fits data, such as if f = open(<a_fits_path>), f is a file object.
Returns#
- outdict
Status, like {‘success’: True}.
- upload_text_data(stream)#
Upload a text file like object to the Firefly server. The method should allow text file like data to be streamed without using an actual file.
Parameters#
- streamobject
A text file like object containing text data, such as if f = open(<a_textfile_path>), f is a file object.
Returns#
- outdict
Status, like {‘success’: True}.
- wait_for_events()#
Wait over events from the server.
Pause and do not exit.
This is optional. You should not use this method in ipython notebook. Event will get called anyway.