Reference Guide to Firefly Python Client API#

This notebook aims to give a high-level overview of the Firefly Python client API and important methods to get you started. For full explanation of each method and its parameter, check FireflyClient API reference.

[1]:

from firefly_client import FireflyClient

# Following imports are just for example data fetching and processing (not needed always)
from astropy.utils.data import download_file
from astropy.io import fits
from astropy.convolution import convolve, Gaussian2DKernel
import io

Initialize Firefly Client#

Firefly is a web application (with a URL) that can be controlled from Python with a FireflyClient object.

To indicate which Firefly server to talk to from our Python client, we set the environment variable FIREFLY_URL. In this notebook, we use a public Firefly server: the IRSA Viewer (https://irsa.ipac.caltech.edu/irsaviewer). However, you can also run a local Firefly server via a Firefly Docker image and access it at http://localhost:8080/firefly.

There are two ways to initialize FireflyClient from Python, depending on whether you’re running the notebook in JupyterLab or not:

From Jupyter Lab#

Assuming you have jupyter-firefly-extensions set up in your environment as explained here, you can use make_lab_client() in JupyterLab, which will open the Firefly viewer in a new tab within the Lab.

[2]:

# fc = FireflyClient.make_lab_client()

From Jupyter Notebook (or even a Python shell)#

You can use make_client() in a Jupyter Notebook (or even a Python shell), which will open the Firefly viewer in a new web browser tab. make_client() also allows you to pass the URL directly (other than through environment variable) as the url parameter.

[3]:

# fc = FireflyClient.make_client() # URL is taken from FIREFLY_URL env variable

# URL can be defined explicitly as a parameter
fc = FireflyClient.make_client(url="https://irsa.ipac.caltech.edu/irsaviewer")

[Optional] Reinitialize Firefly Client#

To clean the state of Firefly server (aka remove all displayed components and start fresh), you can reinitialise it. This is specifically helpful if a Python connection with server is already open and re-running make_lab_client (or make_client) leads to stale state.

[4]:

fc.reinit_viewer()

[4]:

{'success': True}

Show FITS Image in Firefly#

Use the show_fits_image method of the FireflyClient object to display a FITS image. It can take a local file path, URL, or a file-like object as input via the file_input parameter.

From a URL#

You can specify url of any FITS image. Here we use cutout of a WISE all-sky image of M51 galaxy in W2 band:

[5]:

cutout_image_url = 'https://irsa.ipac.caltech.edu/ibe/data/wise/allsky/4band_p1bm_frm/9a/05379a/141/05379a141-w2-int-1b.fits?center=202.4841667,47.23055556&size=400pix'

[6]:

cutout_image_plot_id = 'wise-cutout'
fc.show_fits_image(file_input=cutout_image_url,
                   plot_id=cutout_image_plot_id,
                   title='WISE Cutout')

[6]:

{'success': True}

From a local file#

You can specify path of any local FITS file. Here we download the full WISE all-sky image of M51 in W2 and use its file path:

[7]:

full_image_url = 'https://irsa.ipac.caltech.edu/ibe/data/wise/allsky/4band_p1bm_frm/9a/05379a/141/05379a141-w2-int-1b.fits'
full_image_fpath = download_file(full_image_url, cache=True, timeout=120)
full_image_fpath

[7]:

'/Users/jsinghal/.astropy/cache/download/url/ef686a664b2c17e3d8590b511be8a400/contents'

[8]:

full_image_plot_id = 'wise-fullimage'
fc.show_fits_image(file_input=full_image_fpath,
                   plot_id=full_image_plot_id, # using a different plot id to not overwrite previous plot
                   title='WISE Full Image')

[8]:

{'success': True}

From an in-memory file-like object#

You can also use a file-like object (e.g. BytesIO stream) instead of a local file path or URL. This is useful when you are working with a FITS file in memory and don’t want to write it to disk.

[9]:

processed_fits = io.BytesIO()

with fits.open(cutout_image_url) as hdul:
    # Do some processing on FITS image data (like simple Gaussian smoothing here)
    img_data = hdul[0].data
    gaussian_kernel = Gaussian2DKernel(x_stddev=2)
    img_data = convolve(img_data, gaussian_kernel)

    new_hdu = fits.PrimaryHDU(data=img_data, header=hdul[0].header)
    new_hdu.writeto(processed_fits, overwrite=True)
    processed_fits.seek(0) # to bring reading pointer to the beginning of file

[10]:

fc.show_fits_image(file_input=processed_fits,
                   plot_id='wise-processed',
                   title='Processed WISE Cutout')

[10]:

{'success': True}

Modify the displayed image(s)#

Panning to a coordinate#

To pan the full image to center on the M51 cutout’s center:

[11]:

fc.set_pan(plot_id=full_image_plot_id, # note we use the plot id we defined above
           x=202.4841667, y=47.23055556, coord='j2000')

[11]:

{'success': True}

Zooming#

To zoom into the full image by a factor of 2:

[12]:

fc.set_zoom(plot_id=full_image_plot_id, factor=2)

[12]:

{'success': True}

Aligning multiple images#

To align both full image and cutout image by WCS and to lock the WCS matching:

[13]:

fc.align_images(lock_match=True)

[13]:

{'success': True}

Changing the color stretch#

Set the stretch for the full image based on IRAF zscale interval with a linear algorithm:

[14]:

fc.set_stretch(plot_id=full_image_plot_id, stype='zscale', algorithm='linear')

[14]:

{'success': True,
 'rv_string': '91,1.000000,91,1.000000,NaN,2.000000,44,25,600,120,0,NaN,1.000000'}

Show Table/Catalogs in Firefly#

Use the show_table method of the FireflyClient object to display a table/catalog. Similar to show_fits_image, it can take a local file path, URL, or a file-like object as input via the same file_input parameter.

Here we use a 2MASS catalog (using IRSA VO TAP):

[15]:

table_url = "http://irsa.ipac.caltech.edu/TAP/sync?FORMAT=IPAC_TABLE&QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),CIRCLE('J2000',202.4841667,47.23055556,0.125))=1"

[16]:

table_id = '2mass-catalog'
fc.show_table(file_input=table_url, # can also be a local file path or file-like object
              tbl_id=table_id,
              title='2MASS Catalog')

[16]:

{'success': True}

Note: Displaying a catalog table also caused Firefly to overlay the image with markers by default. The markers can be visible on all the WISE images we displayed earlier since they would include the same field of view. Also we see the active chart and coverage tab as bonus!

Modify the displayed table#

Sorting by a column#

You can sort the table by a column in ascending (ASC) or descending (DESC) order:

[17]:

fc.sort_table_column(tbl_id=table_id,
                     column_name='j_m', sort_direction='ASC')

[17]:

{'success': True}

Filtering the rows#

Filters can be specified as an SQL WHERE clause-like string with column names quoted:

[18]:

fc.apply_table_filters(tbl_id=table_id, # note: we use the table id we defined above
                       filters='"j_m"<15 and "j_cmsig"<0.05')

[18]:

{'success': True}

To remove the filters:

[19]:

fc.apply_table_filters(tbl_id=table_id, filters='')

[19]:

{'success': True}

Plot Chart from the displayed table#

We can use the dispalyed table data to plot columns on X and Y axis:

[20]:

fc.show_xyplot(tbl_id=table_id, xCol='j_m', yCol='h_m-k_m')

[20]:

{'success': True}

Alternatively, more generic method show_chart() can be used to create the same plot which accepts a lot of configuration parameters as Plotly data structure:

[21]:

trace0 = {'tbl_id': table_id, 'x': "tables::j_m", 'y': "tables::h_m-k_m",
          'type' : 'scatter', 'mode': 'markers',
          'marker': dict(size=4, color='red', opacity=0.6)}
layout = {'title': '2MASS color-mag',
           'xaxis': dict(title='J'), 'yaxis': dict(title='H - K')}

status = fc.show_chart(data=[trace0], layout=layout)

Plot Region overlays on the displayed image#

ds9-style regions can be overlaid on the image displayed by Firefly:

[22]:

sources_box = "icrs;box 202.4841667d 47.23055556d 15' 15' 0d # color=yellow"
image_regions_id = 'wise-regions'
fc.overlay_region_layer(region_data=sources_box,
                        title='WISE all-sky Annotations',
                        region_layer_id=image_regions_id)

[22]:

{'success': True}

Add region data to an existing region layer:

[23]:

ra, dec = 202.49808, 47.26617
point_source = f'icrs;point {ra}d {dec}d # point=cross 25 text={{NGC 5195}} color=yellow'
fc.add_region_data(region_data=point_source,
                   region_layer_id=image_regions_id) # note: we use same region_layer_id

[23]:

{'success': True}

To remove region layer:

[24]:

fc.delete_region_layer(image_regions_id)

[24]:

{'success': True}

Show HiPS image#

[ ]:

hips_url = 'http://alasky.u-strasbg.fr/DSS/DSSColor'
hips_plot_id = 'hips-img-id'
target = '202.4841667;47.23055556;EQ_J2000'

fc.show_hips(plot_id=hips_plot_id,
             hips_root_url=hips_url,
             Title='HiPS-DSS',
             WorldPt=target)

{'success': True}

Show 3-color image#

[26]:

# [W4, W2, W1] from WISE all-sky as [R, G, B]
rgb_urls = [f'https://irsa.ipac.caltech.edu/ibe/data/wise/allsky/4band_p1bm_frm/9a/05379a/141/05379a141-{band}-int-1b.fits'
            for band in ['w4', 'w3', 'w2']]

[27]:

three_color_params = [
    {
        'url': url,
        'Title': "3 color image"
    } for url in rgb_urls]

fc.show_fits_3color(three_color_params=three_color_params,
                    plot_id='3color-img')

[27]:

{'success': True}

[28]:

# Because we added more images, align and lock them by WCS again
fc.align_images(lock_match=True)

[28]:

{'success': True}

Show any data file#

To explore any data file you have at hand without delving into image or table specific options, you can use the show_data method of the FireflyClient object.

Preview metadata#

It’s often useful to preview the metadata of a data file you have no information about. preview_metadata parameter allows you to do that:

[29]:

spherex_l2_url = 'https://irsa.ipac.caltech.edu/ibe/data/spherex/qr/level2/2025W19_2B/l2b-v11-2025-163/6/level2_2025W19_2B_0336_3D6_spx_l2b-v11-2025-163.fits'

fc.show_data(spherex_l2_url, preview_metadata=True) # first argument can also be a local file path or file-like object

[29]:

{'success': True}

This allows you to select which extensions/HDUs to load from a multi-extension FITS file. Same can be done for a VOTable with multiple tables.

Directly view data#

[30]:

euclid_spec_url = 'http://irsa.ipac.caltech.edu/api/spectrumdm/convert/euclid/q1/SIR/102159776/EUC_SIR_W-COMBSPEC_102159776_2024-11-05T16:21:17.235160Z.fits?dataset_id=euclid_combspec&hdu=217'

fc.show_data(euclid_spec_url, preview_metadata=False)

[30]:

{'success': True}

NOTE: show_data is a recent addition to firefly_client and is still evolving. It doesn’t allow as much customization as image/table specific methods yet, but it is a quick way to get a look at your data.