Merge pull request #41 from jaladh-singhal/openuniverse-firefly

bsipocz · web-flow · commit 5a674f469217 · 2025-01-06T20:43:26.000-08:00
Improve OpenUniverse2024 Firefly notebook
diff --git a/tutorials/firefly/OpenUniverse2024Preview_Firefly.md b/tutorials/firefly/OpenUniverse2024Preview_Firefly.md
@@ -39,18 +39,13 @@ OpenUniverse2024 is a project to simulate spatially overlapping imaging surveys
 - Overlapping Roman Wide-Area Survey (WAS) in the same region
 - A deep-field calibration region of the Roman WAS in the same region
 
-This data preview release consists of a subset of data from each of the five categories above. More information about data preview can be found at:
-https://irsa.ipac.caltech.edu/data/theory/openuniverse2024/overview.html
+This data preview release consists of a subset of data from each of the five categories above. More information about data preview can be found at [IRSA holding of this dataset](https://irsa.ipac.caltech.edu/data/theory/openuniverse2024/overview.html). 
 
-Firefly is an open-source web-based UI library for astronomical data archive access and visualization developed at Caltech and used by multiple space- and ground-based astrophysics archives. More information can be found here:
-https://github.com/Caltech-IPAC/firefly/blob/dev/README.md
+Firefly is an open-source web-based UI library for astronomical data archive access and visualization developed at Caltech and used by multiple space- and ground-based astrophysics archives. More information on Firefly can be found [here](https://github.com/Caltech-IPAC/firefly/blob/dev/README.md).
 
-In addition to being used to make web applications, Firefly can be used from Python. More information can be found here:
-https://caltech-ipac.github.io/firefly_client/usage/index.html
+In addition to being used to make web applications, Firefly can be used from Python. More information on Firefly Python client can be found [here](https://caltech-ipac.github.io/firefly_client/usage/index.html).
 
-The Firefly JupyterLab Extension makes it particularly easy to use Firefly to efficiently visualize cloud-hosted astronomical data using cloud-based JupyterLab instances. More information can be found here:
-
-https://github.com/Caltech-IPAC/jupyter_firefly_extensions/blob/master/README.md
+The Firefly JupyterLab Extension makes it particularly easy to use Firefly to efficiently visualize cloud-hosted astronomical data using JupyterLab instances running locally or on cloud. More information on Firefly JupyterLab Extension can be found [here](https://github.com/Caltech-IPAC/jupyter_firefly_extensions/blob/master/README.md).
 
 +++
 
@@ -70,6 +65,11 @@ https://github.com/Caltech-IPAC/jupyter_firefly_extensions/blob/master/README.md
 - reproject.reproject_interp to convert Roman coadds from STG to TAN projection
 - io.BytesIO for writing a fits file to an in-memory stream
 
+```{code-cell} ipython3
+# Uncomment the next line to install dependencies if needed.
+# !pip install numpy astropy s3fs matplotlib firefly_client reproject
+```
+
 ```{code-cell} ipython3
 from astropy.io import fits
 import numpy as np
@@ -155,7 +155,7 @@ def get_roman_coadd_fpath(coord, filter):
     return coadd_fpath
 ```
 
-Now we use this access path and prefix it with `s3://` and use astropy.fits to extract a subset of it (for more info see https://docs.astropy.org/en/stable/io/fits/usage/cloud.html#subsetting-fits-files-hosted-in-amazon-s3-cloud-storage).
+Now we use this access path and prefix it with `s3://` and use astropy.fits to extract a subset of it (for more info see [this section](https://docs.astropy.org/en/stable/io/fits/usage/cloud.html#subsetting-fits-files-hosted-in-amazon-s3-cloud-storage) of astropy docs).
 
 We use `.section` to retrieve just the science image data from fits HDU as a 2D `numpy.array`, and extract WCS information from fits header as `astropy.wcs.WCS` object. The following function returns a dictionary of both.
 
@@ -389,9 +389,7 @@ fc.reinit_viewer() # to clean the state, if this cell ran earlier
 
 ### Send the simulated Rubin coadd to Firefly using show_fits.
 
-For more information on `show_fits`, see: 
-
-https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.show_fits
+For displaying the FITS image of Rubin coadd in Firefly, we use [`show_fits`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.show_fits):
 
 ```{code-cell} ipython3
 coadd_ff_id_rubin = 'rubin-coadd-filter-r'
@@ -404,11 +402,9 @@ fc.show_fits(url=https_url(coadd_s3_fpath_rubin),
 ### Use ds9 region syntax to overplot the simulated Roman image blocks on the interactive display
 
 The Firefly client includes several methods related to controlling ds9 region overlays. To 
-overlay a region layer on the loaded FITS images, we can use `overlay_region_layer`:
-
-https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.overlay_region_layer
+overlay a region layer on the loaded FITS images, we can use [`overlay_region_layer`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.overlay_region_layer).
 
-Region data is defined in ds9 region syntax that can be found at https://ds9.si.edu/doc/ref/region.html
+Region data is defined in ds9 region syntax that can be found [here](https://ds9.si.edu/doc/ref/region.html).
 
 ```{code-cell} ipython3
 # mark the roman coadd blocks as boxes
@@ -443,17 +439,13 @@ coords_of_interest = SkyCoord('0h38m25.35s -44d00m10.1s', frame='icrs') # locate
 coords_of_interest
 ```
 
-We can now use this `SkyCoord` object to compare our coadds. More information on `SkyCoord` can be found here:
-
-https://docs.astropy.org/en/stable/api/astropy.coordinates.SkyCoord.html#astropy.coordinates.SkyCoord
+We can now use this [astropy `SkyCoord` object](https://docs.astropy.org/en/stable/api/astropy.coordinates.SkyCoord.html#astropy.coordinates.SkyCoord) to compare our coadds.
 
 +++
 
 ### Use ds9 region syntax to overplot the selected position
 
-For this we use the id of the region layer we defined above, and add more region data using `add_region_data`:
-
-https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.add_region_data
+For this we use the id of the region layer we defined above, and add more region data using [`add_region_data`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.add_region_data).
 
 ```{code-cell} ipython3
 point_region = f'icrs;point {coords_of_interest.ra.value}d {coords_of_interest.dec.value}d # point=cross 15 text={{Blended source}}'
@@ -540,11 +532,7 @@ The input truth files cover a region much larger than the data preview, so we de
 
 +++
 
-You can visualize catalogs interactively with Firefly using `show_table`. This capability can take many parameters. Here we will simply send our catalog to Firefly so that we can (a) see an interactive table; (b) see this table plotted over the image that we've already sent; and (c) use the GUI to quickly create exploratory plots. See if you can use the GUI to quickly determine approximately how many galaxies cover the Rubin image and what the redshift distribution of these galaxies is.
-
-For more information on `show_table`, see: 
-
-https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.show_table
+You can visualize catalogs interactively with Firefly using [`show_table`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.show_table). This capability can take many parameters. Here we will simply send our catalog to Firefly so that we can (a) see an interactive table; (b) see this table plotted over the image that we've already sent; and (c) use the GUI to quickly create exploratory plots. See if you can use the GUI to quickly determine approximately how many galaxies cover the Rubin image and what the redshift distribution of these galaxies is.
 
 ```{code-cell} ipython3
 cat_filters = [
@@ -577,7 +565,7 @@ For each row in the table you can notice a marker in the image. Selecting a row
 
 High redshift galaxies are the most interesting, so let's filter the table we sent to Firefly to only include z>3 galaxies. Notice how the table display and image overlay change. Notice how the chart becomes a scatterplot from a heatmap because the sources reduce. You can remove this filter or add new ones through the GUI.
 
-For filtering, we will use `apply_table_filters` method on the galaxy table we loaded above. More info about this method: https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.apply_table_filters
+For filtering, we will use [`apply_table_filters`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.apply_table_filters) method on the galaxy table we loaded above.
 
 ```{code-cell} ipython3
 fc.apply_table_filters(tbl_id=gal_cat_tbl_id,
@@ -596,9 +584,7 @@ ROMAN_RGB_FILTERS = ['H158', 'J129', 'Y106']
 RUBIN_RGB_FILTERS = ['r', 'g', 'u']
 ```
 
-We already have Rubin coadd with catalog overlaid, let's make a 3 color image to see colors of marked objects more clearly. For this we will use `show_fits_3color` method:
-
-https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.show_fits_3color
+We already have Rubin coadd with catalog overlaid, let's make a 3 color image to see colors of marked objects more clearly. For this we will use [`show_fits_3color`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.show_fits_3color) method:
 
 ```{code-cell} ipython3
 coadd_ff_id_rubin_3color = 'rubin-coadd-3color'
@@ -694,11 +680,7 @@ for filter_name in ROMAN_RGB_FILTERS:
 
 ### Use Firefly's show_fits_3color to create a 3 color image of Roman coadds
 
-Now we upload each fits stream (in-memory fits file) to firefly using `upload_fits_data()` and prepare color params to pass to the `show_fits_3color()`. More info here:
-
-- https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.upload_fits_data
-
-- https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.show_fits_3color
+Now we upload each fits stream (in-memory fits file) to firefly using [`upload_fits_data()`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.upload_fits_data) and prepare color params to pass to the [`show_fits_3color()`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.show_fits_3color).
 
 ```{code-cell} ipython3
 three_color_params = [
@@ -717,10 +699,10 @@ fc.show_fits_3color(three_color_params=three_color_params,
 We can see 3 color image of Roman coadd containing the high-redshift galaxy sources. Try panning and zomming out, you can notice it spans over one block compared to the Rubin coadd which is much larger.
 
 ### Use Firefly's pan/zoom/align methods to locate high redshift sources
-Now, let's pan & zoom to the region where we located high-redshift galaxy sources. Also align & lock all images being displayed by WCS. For these operations we use these 3 methods:
-- `set_pan`: https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.set_pan
-- `set_zoom`: https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.set_zoom
-- `align_images`: https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.align_images
+Now, let's pan & zoom to the region where we located high-redshift galaxy sources. Also align & lock all images being displayed by WCS. For these operations we use these 3 methods (click on them to see their documentation):
+- [`set_pan`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.set_pan)
+- [`set_zoom`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.set_zoom)
+- [`align_images`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.align_images)
 
 ```{code-cell} ipython3
 fc.set_pan(plot_id=coadd_ff_id_roman_3color, x=high_z_gal_coords.ra.deg, y=high_z_gal_coords.dec.deg, coord='j2000')
@@ -730,9 +712,7 @@ fc.align_images(lock_match=True)
 
 ### Use Firefly's set_stretch method to change the stretch of the image display via Python
 
-The image has a lot of noise that obscures our high redshift sources of interest. You can use the Firefly GUI to change the stretch of the image display. We identify that squared stretch from -2 to 10 sigma highlights the colors of our sources better. You can also use the Firefly client's `set_stretch` to do this via Python. This is helpful for reproducibility and for scaling up to many images.
-
-More info about this method: https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.set_stretch
+The image has a lot of noise that obscures our high redshift sources of interest. You can use the Firefly GUI to change the stretch of the image display. We identify that squared stretch from -2 to 10 sigma highlights the colors of our sources better. You can also use the Firefly client's [`set_stretch`](https://caltech-ipac.github.io/firefly_client/api/firefly_client.FireflyClient.html#firefly_client.FireflyClient.set_stretch) to do this via Python. This is helpful for reproducibility and for scaling up to many images.
 
 ```{code-cell} ipython3
 fc.set_stretch(plot_id=coadd_ff_id_roman_3color, stype='sigma', algorithm='squared', 
