firefly_client - Python API to Firefly visualization¶

firefly_client provides a Python API to the Firefly visualization framework. You can find it on Github at https://github.com/Caltech-IPAC/firefly_client

Introduction¶

Firefly is a web framework for astronomical data access and visualization, developed at Caltech/IPAC and deployed for the archives of several major facilities including Spitzer, WISE, Plank and others. Firefly is the framework for the Portal Aspect of the LSST Science User Platform. Its client-server architecture is designed to enable a user to easily visualize images and catalog data from a remote site.

The firefly_client package provides a lightweight client class that includes a Python interface to Firefly’s Javascript API. This document contains examples of how to start a FireflyClient instance with details about the server location, and how to use the instance to upload and display astronomical images, tables and catalogs.

Prerequisites¶

Python 3
firefly_client (installable with pip install firefly_client)
URL for a Firefly server

Getting Started¶

First, download some data by using wget or curl:

wget http://web.ipac.caltech.edu/staff/roby/demo/2mass-m31-green.fits
wget http://web.ipac.caltech.edu/staff/roby/demo/m31-2mass-2412-row.tbl

curl -o 2mass-m31-green.fits http://web.ipac.caltech.edu/staff/roby/demo/2mass-m31-green.fits
curl -o m31-2mass-2412-row.tbl http://web.ipac.caltech.edu/staff/roby/demo/m31-2mass-2412-row.tbl

Second, start a Python session and connect an instance of firefly_client.FireflyClient to a Firefly server. In this example, we use a public server. For ease of demonstration, please start the Python session in the directory from which you downloaded the sample files.

from firefly_client import FireflyClient
fc = FireflyClient('https://irsa.ipac.caltech.edu/irsaviewer')

Third, open a new browser tab using the FireflyClient.launch_browser() method. If a browser cannot be opened, a URL will be displayed for your web browser.

fc.launch_browser()

Fourth, display an image in a FITS file by uploading the file to the server with FireflyClient.upload_file() and then showing the image.

fval = fc.upload_file('2mass-m31-green.fits')
fc.show_fits(fval)

Fifth, display a table by uploading a catalog table (here, in IPAC format) and then showing the table. The sources are also overlaid automatically on the image since the catalog contains celestial coordinates, and a default chart is displayed.

tval = fc.upload_file('m31-2mass-2412-row.tbl')
fc.show_table(tval)

Using firefly_client¶

The firefly_client package contains the class FireflyClient which provides the Python API to Firefly.

Initializing a FireflyClient instance¶

Once a Firefly server has been identified, the connection parameters can be used to initialize a FireflyClient instance. By default, the value of the environment variable FIREFLY_URL will be used as the server URL, if defined. If FIREFLY_URL is not defined, the default server URL is http://localhost:8080/firefly which is often used for a Firefly server running locally.

Optional arguments for initializing a FireflyClient instance include channel and html_file.

For a default server running locally, use localhost or 127.0.0.1 together with the port that the server is using, and append /firefly. The default port is 8080.

import firefly_client
fc = firefly_client.FireflyClient('http://127.0.0.1:8080/firefly')

If the Python session is running on your own machine, you can use the FireflyClient.launch_browser() method to open up a browser tab.

fc.launch_browser()

The FireflyClient.launch_browser() method will return two values: a boolean indicating whether the web browser open was successful, and the URL for your web browser.

Warning

On Mac OS X 10.12.5, an error message may be displayed with a URL and a note that it doesn’t understand the “open location message”. If a browser tab is not automatically opened, copy and paste the displayed URL into the address bar of your browser. This issue has been fixed in Mac OS X 10.12.6.

If your Python session is not running on your local machine, the FireflyClient.launch_browser() method will display the URL for your web browser. Alternatively, you can use the FireflyClient.display_url() method to print the browser URL if running in a terminal, and to show a clickable link if running in a Jupyter notebook.

fc.display_url()

In typical usage, it is unnecessary to set the channel parameter when instantiating FireflyClient. A unique string will be auto-generated. If you do wish to set the channel explicitly, e.g. for sharing your display with someone else, take care to make the channel unique.

Warning

After initializing FireflyClient, make sure you have opened a web browser to the appropriate URL, before proceeding to use the Python API described in the following sections.

Displaying Images¶

Since Firefly was originally developed to visualize data products from astronomical archives, displaying an image is a two-step process of uploading a file and then showing it. The examples here use the data products downloaded in Getting Started.

The FireflyClient.upload_file() method uploads the file and returns a location understood by the Firefly server. The location string is passed to FireflyClient.show_fits() to display the image. In the display step, it is recommended to explicitly specify the plot_id parameter for later use in modifying the image display.

fval = fc.upload_file('2mass-m31-green.fits')
fc.show_fits(fval, plot_id='m31-green', title='2MASS H, M31')

Modifying an Image Display¶

Zooming, panning, and changing the stretch (mapping of pixels to display values) is accomplished by corresponding methods, passing in the plot_id as the first argument.

fc.set_zoom('m31-green', 4)
fc.set_pan('m31-green', 200, 195)
fc.set_stretch('m31-green', 'sigma', 'log', lower_value=-2, upper_value=30)

A “zscale” stretch may be commanded with alternate parameters:

fc.set_stretch('m31-green', 'zscale', 'linear')

At present the API does not include a function for changing the color map for the image. The relevant Javascript action may be invoked using FireflyClient.dispatch_remote_action():

fc.dispatch_remote_action(fc.channel,
    action_type='ImagePlotCntlr.ColorChange',
    payload={'plotId': 'm31-green',
             'cbarId': 16})

The colormap can be reverted to the original grayscale by using the command above together with 'cbarId' : 0.

Visualizing Regions¶

The API includes detailed support for ds9-style regions. A list of strings containing region commands can be added to an overlay layer on an image.

region_data = ['J2000',
               'text 10.6845417 41.2689167{M31 Nucleus} #color=red',
               'point 10.7035000 41.2535833 # point=circle 20',
               'image;line(249.5 164.1 283.8 206.6) # color=blue width=5']
fc.add_region_data(region_data=region_data, region_layer_id='layer1',
                   title='my_marks', plot_id='m31-green')

An individual region command can be removed using FireflyClient.remove_region_data(). To remove the blue line:

fc.remove_region_data(region_data=region_data[-1],
                      region_layer_id='layer1')

An entire region layer can be deleted with FireflyClient.delete_region_layer():

fc.delete_region_layer(region_layer_id='layer1', plot_id='m31-green')

A region layer can be uploaded from a file and overlaid on an image by using FireflyClient.upload_file() and FireflyClient.overlay_region_layer():

with open('myreg.txt', 'w') as fh:
    fh.write('\n'.join(region_data))
rval = fc.upload_file('myreg.txt')
fc.overlay_region_layer(file_on_server=rval,
                        region_layer_id='layer2',
                        plot_id='m31-green')

Visualizing Tables and Catalogs¶

Tables can be uploaded to the Firefly server with FireflyClient.upload_file(), and displayed in a table viewer component with FireflyClient.show_table(). The default is to overlay symbols for each row of the table (is_catalog=True) 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')

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 FireflyClient.fetch_table():

fc.fetch_table(file_on_server=tval, tbl_id='invisible-table')

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:

fc.show_table(file_on_server=tval, tbl_id='2mass-tbl', is_catalog=False)

Making Plots and Histograms¶

Once a table has been uploaded to Firefly, FireflyClient.show_chart() will display a scatter plot. The x and y parameters can be set to use names of columns in the table, or to arithmetic expressions that combine table columns.

trace1 = dict(tbl_id='2mass-tbl', x='tables::j_m',
              y='tables::h_m-k_m', mode='markers', type='scatter',
              marker=dict(size=4))

 layout1 = dict(title='2MASS color-mag',
                xaxis=dict(title='J'), yaxis=dict(title='H - K'))

 fc.show_chart(layout=layout1, data=[trace1])

A histogram can be displayed with FireflyClient.show_chart():

trace2 = dict(type='fireflyHistogram',
              name='j_m',
              marker=dict(color='rgba(153, 51, 153, 0.8)'),
              firefly=dict(tbl_id='2mass-tbl',
                           options=dict(algorithm='fixedsizeBins',
                                        fixedBinSizeSelection='numBins',
                                        numBins=30,
                                        columnOrExpr='j_m')))

layout_hist = dict(title='Photometry histogram',
                 xaxis=dict(title='j_m (mag)'),
                 yaxis=dict(title='Number'))

fc.show_chart(layout=layout_hist, data=[trace2])

Both plot types include options for log scaling as well as other settings.

Advanced: Callbacks and Extensions¶

Callback functions can be added to FireflyClient. Here is a simple example of defining and registering a callback that prints world coordinates to the Python session:

def print_coords(event):
    if 'wpt' in event['data']:
       wpt = event['data']['wpt']
       wdata = wpt.split(';')
       ra = float(wdata[0])
       dec = float(wdata[1])
       print('ra={:.6f}, dec={:.6f}'.format(ra,dec))

fc.add_listener(print_coords)

To activate the callback in point-selection mode, add it as an extension with ext_type='POINT'. By default, the title of the extension will appear as a clickable icon when the Firefly viewer is in point mode. A small image can be passed in instead via the img_src parameter.

fc.add_extension(ext_type='POINT', plot_id=None, title='Print coords',
                 extension_id='pickit')

To activate point-selection mode, in the Firefly browser tab, select the ‘Lock by click’ checkbox at the upper right. Then selecting any point in an image will overlay a box at that point. Finally, click on the ‘Print coords’ icon in the image display window to cause the callback to be triggered, and coordinates to be printed out.

The callback can be deleted with FireflyClient.remove_listener:

fc.remove_listener(print_coords)

Python API reference¶

firefly_client Package¶

Classes¶

FireflyClient([url, channel, html_file, …]) For Firefly client to build interface to remotely communicate to the Firefly viewer.

Navigation