Initializing a FireflyClient instance#

This notebook focuses only on the initialization of a FireflyClient object. Later notebooks will demonstrate how to use it for visualizing your data.

Pick a Firefly server URL#

Firefly, the interactive data visualization tool, is a web application (with a URL) that can be controlled from Python with a FireflyClient object. When we create the FireflyClient instance, we need to provide the URL of the Firefly server we want to connect to.

By default, the value of the environment variable FIREFLY_URL will be used as the Firefly server URL. It can be set to one of the following:

  1. a local Firefly server which can be run via a Firefly Docker image, typically at http://localhost:8080/firefly

  2. a public Firefly server such as:

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.

Note

The environment variable must be defined in the shell where Jupyter (or the Python session) was started. It may not work if defined in a notebook cell through %env or os.environ.

Imports#

The only required import here is FireflyClient.

[1]:

from firefly_client import FireflyClient

Initialize FireflyClient#

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

1. From Jupyter Notebook (or 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.

[2]:

# 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")

Note

When running locally, make_client() will usually try to open a browser tab automatically. If it can’t (for example, if you’re running on a remote machine), it will print or display a URL that you can click to open.

Warning

After initializing fc, make sure you’ve opened the Firefly viewer URL before running methods which update the UI.

2. From JupyterLab#

You can use make_lab_client() in JupyterLab to open the Firefly viewer in a new tab within the Lab, which provides a more integrated UI experience. This requires you to have jupyter_firefly_extensions set up in your environment:

  1. In your Python environment, run pip install jupyter_firefly_extensions.

  2. Set FIREFLY_URL environment variable before running jupyter lab.

[ ]:

# fc = FireflyClient.make_lab_client()

Other helpful methods#

Reinitialize the viewer#

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

[3]:

fc.reinit_viewer()

[3]:

{'success': True}

Explicitly open a browser tab#

By default, make_client() opens a browser tab for Firefly. You can also trigger that behavior explicitly for a FireflyClient object by using the launch_browser method. It will return two values: a boolean indicating whether the web browser open was successful, and the URL for your web browser.

[5]:

fc.launch_browser()

[5]:

(True,
 'https://irsa.ipac.caltech.edu/irsaviewer/?__wsch=anNpbmdoYWwyMDI2LTAxLTA3')

Display Firefly URL#

You can use display_url() to print the browser URL if running in a terminal, and to show a clickable link if running in a Jupyter notebook.

[6]:

fc.display_url()
Open your web browser to this link

Set a custom channel#

FireflyClient opens a connection to the Firefly server on a particular WebSocket channel. You can override it when using make_client() as shown below.

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

[7]:

fc2 = FireflyClient.make_client(url="https://irsa.ipac.caltech.edu/irsaviewer",
                                channel_override="my-custom-channel")