FIREFLY-1862: Cleanup the firefly-client docs and example notebooks

[jaladh-singhal]

Fixes FIREFLY-1862

• Restructured examples/ contents: added meaningful names/titles, merged/deleted duplicate notebooks, moved deprecated and testing notebooks to a sub directory, etc.
  • test/ directory has now become examples/development_tests since that's what they are, they are not unit tests but integration tests in form of notebooks or scripts
• Made examples/ (all notebooks and scripts, except those in subdirectories) render as html pages in the docs website for easy view and download by user
  • This required changes in conf.py and adding a custom extension script_pages.py - we can get rid it when improving infrastructure to use myst-nb instead of nbsphinx (notebook->HTML renderer libraries) similar to https://github.com/Caltech-IPAC/irsa-tutorials
• Converted most of docs/usage/*.rst which were outdated to .ipynb files with up-to-date API usage
  • this makes it easy to test/maintain them. Eventually, we can setup a CI pipeline to test notebook code with pytest (what https://github.com/Caltech-IPAC/irsa-tutorials does)
• Fixed bugs/docstrings in firefly_client.py
• Updated publish doc workflow to build html docs for PR branches too
• Updated dev docs, demo-notebooks page, landing page, etc

Testing

See docs built from this PR-branch at https://caltech-ipac.github.io/firefly_client/pr/76/

Compare them against current docs (built from master branch): https://caltech-ipac.github.io/firefly_client/

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[robyww]

@jaladh-singhal gave me an overview. It looks good.

[stargaser]

I only looked at a few parts, but it looks good to me.

[jonesmg]

Overall I think these docs are really good. There are well structured, clear, and I got nearly all of the examples to run. I especially liked the 3-color image display and the ds9 regions capability, which I didn't know about previously. There are just a few places where I think the docs could be improved (see below).

Initializing:

• It might be helpful to have an idea of what the pros and cons are of choosing a public verses local firefly server. For example, if I want to open a large file (from my HDD) and I have a slow internet connection, does it make sense to use a local rather than public server?
• I suspect you don't want to explain to everyone how to set environment variables, but I think giving just one example would go a long way. E.g., "In bash enter export FIREFLY_URL="https://irsa.ipac.caltech.edu/irsaviewer" before launching the notebook." Or something similar.

Displaying images:

• astropy was not listed as a dependency, but it's used in the examples. I know it's not strictly required for firefly, but it may be good to acknowledge that you need to add it to your environment to run the examples, maybe as an optional dependency or something. As I'd made a new environment, I had to close my Jupyter lab session and install it.
• I had to revert my numpy version to 2.3 because the latest version (2.4) seems to be incompatible with astropy.convolution. This might trip up a less experienced python user.

Displaying 3-color images:

• I could get the example to work, but I was not able to load in my own fits images. I tried giving both absolute and relative paths to the three_color_params list, but it couldn't load the files. I eventually gave up. Below was my final attempt.

local_path = os.getcwd()
three_color_params = [
    {
        'file': path,
        'title': '3 color image'
    } for path in [os.path.join(local_path,'ifmy53020_drc.fits'),
                   os.path.join(local_path,'ifmy53020_drc.fits'),
                   os.path.join(local_path,'ifmy53010_drc.fits')]
]

• Genuine question for my own benefit. I often make 3-color images when I only have two bands. Usually I just open the two fits images and make a third on-the-fly that's the average of the two, and set this as Green. How would I do that in the firefly client? The three_color_params object wants paths to FITS files. Would I have to create and write out a third file, then read it back in? It would be great if there was a way to do this on-the-fly in firefly.

Visualizing tables:

• The show_histogram command turned my viewer window all white and I had to reinit the viewer. I couldn't get it to work (I was using the lab client on the public IRSA url).
• I had the same problem with the show_chart command under "Configurable plots". I changed to a firefly client in a separate window, but this didn't fix the issue.

[jaladh-singhal]

@jonesmg thank you for your feedback. It's very useful! Please see my replies to your comments.

Initializing:

• It might be helpful to have an idea of what the pros and cons are of choosing a public verses local firefly server. For example, if I want to open a large file (from my HDD) and I have a slow internet connection, does it make sense to use a local rather than public server?

Hmm good point. I think this prompts a discussion with developers (and scientists?) to come up with right set of pros/cons.

• I suspect you don't want to explain to everyone how to set environment variables, but I think giving just one example would go a long way. E.g., "In bash enter export FIREFLY_URL="https://irsa.ipac.caltech.edu/irsaviewer" before launching the notebook." Or something similar.

I'll add.

Displaying images:

• astropy was not listed as a dependency, but it's used in the examples. I know it's not strictly required for firefly, but it may be good to acknowledge that you need to add it to your environment to run the examples, maybe as an optional dependency or something. As I'd made a new environment, I had to close my Jupyter lab session and install it.

We don't have installation instructions dedicatedly. Maybe I should have followed format of irsa-tutorials notebooks and added a !pip install ... line at the top.

• I had to revert my numpy version to 2.3 because the latest version (2.4) seems to be incompatible with astropy.convolution. This might trip up a less experienced python user.

Oh, good catch - I wasn't aware. Is this because you had numpy installed in your environment before you installed astropy? I think I created a fresh environment with just firefly-client and astropy so numpy (as a dependency of astropy) was in the right version.

Displaying 3-color images:

• I could get the example to work, but I was not able to load in my own fits images. I tried giving both absolute and relative paths to the three_color_params list, but it couldn't load the files. I eventually gave up. Below was my final attempt.

local_path = os.getcwd()
three_color_params = [
    {
        'file': path,
        'title': '3 color image'
    } for path in [os.path.join(local_path,'ifmy53020_drc.fits'),
                   os.path.join(local_path,'ifmy53020_drc.fits'),
                   os.path.join(local_path,'ifmy53010_drc.fits')]
]

Oh it's because file key expects the return value of fc.upload_file(path). I know it's confusing (because this is low-level API) and different from fc.show_fits_image which can understand paths directly. The example at https://caltech-ipac.github.io/firefly_client/pr/76/usage/displaying-3color.html#From-a-local-file mentions that. Can you try again?

• Genuine question for my own benefit. I often make 3-color images when I only have two bands. Usually I just open the two fits images and make a third on-the-fly that's the average of the two, and set this as Green. How would I do that in the firefly client? The three_color_params object wants paths to FITS files. Would I have to create and write out a third file, then read it back in? It would be great if there was a way to do this on-the-fly in firefly.

I'm not sure if I completely understand how you make the third image on-the-fly. Can you share a code snippet?

I'm assuming that you do some aggreegation function on the data of two fits images as numpy array, in that case you can directly supply it to firefly as IO stream instead of writing it to disk.

Visualizing tables:

• The show_histogram command turned my viewer window all white and I had to reinit the viewer. I couldn't get it to work (I was using the lab client on the public IRSA url).
• I had the same problem with the show_chart command under "Configurable plots". I changed to a firefly client in a separate window, but this didn't fix the issue.

Yes, this was an issue in Irsaviewer that I fixed very recently (today's patch release). Please try again it should be working.

[jonesmg]

Thanks for the responses Jaladh. Some follow-up points below

Displaying images:

• astropy was not listed as a dependency, but it's used in the examples. I know it's not strictly required for firefly, but it may be good to acknowledge that you need to add it to your environment to run the examples, maybe as an optional dependency or something. As I'd made a new environment, I had to close my Jupyter lab session and install it.

We don't have installation instructions dedicatedly. Maybe I should have followed format of irsa-tutorials notebooks and added a !pip install ... line at the top.

That seems reasonable to me, except possibly for the numpy=2.3 issue below, depending on how we address that.

• I had to revert my numpy version to 2.3 because the latest version (2.4) seems to be incompatible with astropy.convolution. This might trip up a less experienced python user.

Oh, good catch - I wasn't aware. Is this because you had numpy installed in your environment before you installed astropy? I think I created a fresh environment with just firefly-client and astropy so numpy (as a dependency of astropy) was in the right version.

I'm not sure exactly why I'm having this issue and you are (I'm running on an M2 Macbook). I deleted my environment and started from scratch, doing the following:

conda create -n firefly python=3 astropy jupyterlab
conda activate firefly
pip install firefly_client
export FIREFLY_URL="https://irsa.ipac.caltech.edu/irsaviewer"
jupyter lab

When I tried to import the modules from astropy.convolution I hit the error: AttributeError: module 'numpy' has no attribute 'in1d'
Doing some Googling, I think this has been deprecated for a while, and removed in numpy v2.4, but astropy (v7.1) is still using it I guess. I rebuilt the environment using:

conda create -n firefly python=3 numpy=2.3 astropy jupyterlab

Then all the astropy stuff imports.

Displaying 3-color images:

• I could get the example to work, but I was not able to load in my own fits images. I tried giving both absolute and relative paths to the three_color_params list, but it couldn't load the files. I eventually gave up. Below was my final attempt.

local_path = os.getcwd()
three_color_params = [
    {
        'file': path,
        'title': '3 color image'
    } for path in [os.path.join(local_path,'ifmy53020_drc.fits'),
                   os.path.join(local_path,'ifmy53020_drc.fits'),
                   os.path.join(local_path,'ifmy53010_drc.fits')]
]

Oh it's because file key expects the return value of fc.upload_file(path). I know it's confusing (because this is low-level API) and different from fc.show_fits_image which can understand paths directly. The example at https://caltech-ipac.github.io/firefly_client/pr/76/usage/displaying-3color.html#From-a-local-file mentions that. Can you try again?

Thanks for clarifying that, I hadn't realised that detail, but I think it's my fault for not reading carefully enough. It does work now (although, it was quite slow, my images were each >100 MB -- maybe this is one of the reasons to use a local server).

• Genuine question for my own benefit. I often make 3-color images when I only have two bands. Usually I just open the two fits images and make a third on-the-fly that's the average of the two, and set this as Green. How would I do that in the firefly client? The three_color_params object wants paths to FITS files. Would I have to create and write out a third file, then read it back in? It would be great if there was a way to do this on-the-fly in firefly.

I'm not sure if I completely understand how you make the third image on-the-fly. Can you share a code snippet?

I'm assuming that you do some aggreegation function on the data of two fits images as numpy array, in that case you can directly supply it to firefly as IO stream instead of writing it to disk.

Sure, here a code snippet of when I've done this for a random HST image:

F606Wfits = fits.open(data_dir+F606Wfitsname)
F606W = F606Wfits[1].data
F814Wfits = fits.open(data_dir+F814Wfitsname)
F814W = F814Wfits[1].data

I omitted some code here that just aligns the two images etc.

HST_RGB_img = numpy.zeros((F814W.shape[0], F814W.shape[1], 3), dtype=float)
HST_RGB_img[:,:,0] = img_scale.linear(F814W, scale_min=0, scale_max=40)
HST_RGB_img[:,:,1] = img_scale.linear((F814W+F606W)/2., scale_min=0, scale_max=40)
HST_RGB_img[:,:,2] = img_scale.linear(F606W, scale_min=0, scale_max=40)

Visualizing tables:

• The show_histogram command turned my viewer window all white and I had to reinit the viewer. I couldn't get it to work (I was using the lab client on the public IRSA url).
• I had the same problem with the show_chart command under "Configurable plots". I changed to a firefly client in a separate window, but this didn't fix the issue.

Yes, this was an issue in Irsaviewer that I fixed very recently (today's patch release). Please try again it should be working.

This all works now!

[jaladh-singhal]

@jonesmg thanks for testing things again.

I've moved numpy pinning discussion to a separate issue: #77 - let's try to debug it there.

About 3 color image creation with 3rd image on the fly, thanks for the snippet. I'll try to do that in firefly and get back to you.