FireflyClient

class firefly_client.FireflyClient(url, channel, html_file='', token=None, viewer_override=None)

Bases: object

For 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

BIVIEW_IChCov_T
BIVIEW_ICov_Ch
BIVIEW_I_ChCov
BIVIEW_T_IChCov
NO_VIEWER
PINNED_CHART_VIEWER_ID
PINNED_IMAGE_VIEWER_ID
SLATE_VIEWER
TAB_ID
TRIVIEW_ICov_Ch_T
TRIVIEW_I_ChCov_T
TRIVIEW_VIEWER
instances	All events are enabled for the listener (str).
tri_view_layout_desc
tri_view_types_list

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.
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.
disconnect()	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_instances()	Get all current instances
get_viewer_mode(html_file, viewer_override)
is_slate()
is_triview()
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
reinit_viewer()	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, tbl_id, title, ...])	Show a table.
show_xyplot(tbl_id[, standalone, group_id])	Show a XY plot
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_for_events()	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.

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.

classmethod get_instances()

Get all current instances

Returns

list

list of instances

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.

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, 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

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 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

Returns

outdict

Status of the request, like {‘success’: True}.

Note

file_on_server and target_search_info are exclusively required.

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.

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.