rosalia-wfi 0.9.7.3

A software to calibrate the sky background of Space Telescope images

ROSALIA: ROman Sky Analyst for Low surface brightness Imaging & Astronomy

Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

ROSALIA (Roman Sky Analyst for Low surface brightness Imaging & Astronomy) is a pipeline to model the sky background level on astronomical images obtained with NASA/Nancy Grace Roman Space Telescope and its direct predecessor, the legendary NASA/Hubble Space Telescope. In particular ROSALIA is focused on the prediction and calibration of stray-light in the Roman Wide Field Instrument, one of the main contaminants in ultra deep low surface brightness observations, and the main source of gradients of parasitic light for space telescopes. ROSALIA combines the information from existing photometric catalogs (Gaia, 2MASS, WISE) with precise optical and payload ray-tracing models of the Roman Space Telescope, allowing to generate images of stray-light and other components of the sky-background for user-defined observational conditions.

ROSALIA is funded through a NASA Grant (D.14 Roman 2022), ROSES/Nancy Grace Roman Space Telescope Research and Support Participation Opportunities.

Sci-PI: Alejandro S. Borlaff (NASA ARC). Admin-PI: Pamela M. Marcum (NASA ARC)

(back to top)

Installation

Managing dependencies

ROSALIA is based on multiple packages, including Astropy, Astroquery, and Romanisim, NumPy, SciPy, and Matplotlib among many others. The easiest way to install all the dependencies is through a package manager like Conda or Mamba. If you have a Conda/Mamba package manager already installed in your system, skip to the following section. If you do not have a package manager, follow the Conda installation instructions at the Space Telescope stenv environment webpage.

Installing ROSALIA

For developers

Create a clean environment for ROSALIA

conda create -n rosalia python=3.12 conda-forge::astromatic-swarp

After the new environment is created, we can activate it.

conda activate rosalia

Once in a clean conda environment, we need to download the ROSALIA package from GitHub.

For general users (not yet available!)

Create a clean environment for ROSALIA

conda create -n rosalia python=3.12 conda-forge::astromatic-swarp

After the new environment is created, we can activate it.

conda activate rosalia

Once in a clean conda environment, we can install ROSALIA. The preferred method to install it is through pip.

pip install rosalia

(back to top)

That is it! We are ready to start analyzing Space Telescope images.

Minimal Use Example

ROSALIA estimates the amount of stray-light from Roman Space Telescope images. To do this, it calculates how many photons reach the focal plane array from secondary optical paths, based on a function called Normalized Detector Irradiance (NDI).

Those photons represent a source of contamination and typically must be modeled and removed before the images are ready for science. ROSALIA calculates the flux of photons for each pixel of the focal plane array. For Roman/WFI, that is a total of 300,811,392 pixels! (18 4088x4088 H4RG-10 detectors).

ROSALIA focuses on modeling three types of backgrounds:

1. Stray-light from sources outside the field of view (Normalized Detector Irradiance)
2. Stray-light from sources inside the field of view (Point Spread Function)
3. Zodiacal light

Out-of-field Stray-light

Open a Python terminal and type:

import rosalia as rs 
from astropy.time import Time

# First define a Roman Space Telescope WFI exposure basic parameters.
ra = 123  # Right ascension at the center of the FOV, in degrees. 
dec = 23  # Declination at the center of the FOV, in degrees.
PA = 45   # Position angle, counter-clockwise from North, in degrees.
date = Time("2024-06-01T00:00:00")  # Date of the observation, in Astropy Time format.
bandpass = "F129"  # A string with the bandpass name for WFI. See https://roman.gsfc.nasa.gov/science/WFI_technical.html
exptime = 600  # Exposure time, in seconds.

rosalia_stray = rs.correct.rosalia_stray(ra=ra, dec=dec, PA=PA, date=date, 
                                         bandpass=bandpass, exptime=exptime, 
                                         radius=1, g_mag_max=15, 
                                         sun_block=False, verbose=False, 
                                         catalog=None)

While Nancy Grace Roman Space Telescope is scheduled to be launched no earlier than September 2026, you can start simulating the observations using romanisim.

Generating Mock Roman/WFI Observations

1. Install romanisim and generate a Roman/WFI example image. For our experiment -- and to maximize the visualization of stray-light -- we will simulate an exposure nearby the Orion's Belt.

   pip install romanisim
   romanisim-make-image --radec 83.3419927 -1.9665163 RST_WFI_ROSALIA_test_Orion_Belt_SCA{}.asdf --roll -45 --sca -1 --bandpass F158 --level 2 --usecrds

Note: romanisim is a package in active development. Please visit the official webpage for more information on usage.

The result from the previous command will be a series of files (18 in total, one ASDF file per Roman WFI detector, or SCA) in the local directory.

ls -lah

-rw-r--r--   1 user  staff   391M Nov 26 16:02 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI01.asdf
-rw-r--r--   1 user  staff   391M Nov 26 15:39 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI02.asdf
-rw-r--r--   1 user  staff   391M Nov 26 15:42 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI03.asdf
-rw-r--r--   1 user  staff   391M Nov 26 15:46 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI04.asdf
-rw-r--r--   1 user  staff   391M Nov 26 15:49 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI05.asdf
-rw-r--r--   1 user  staff   391M Nov 26 15:53 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI06.asdf
-rw-r--r--   1 user  staff   391M Nov 26 15:56 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI07.asdf
-rw-r--r--   1 user  staff   391M Nov 26 15:59 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI08.asdf
-rw-r--r--   1 user  staff   391M Nov 26 16:03 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI09.asdf
-rw-r--r--   1 user  staff   391M Nov 26 16:06 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI10.asdf
-rw-r--r--   1 user  staff   391M Nov 26 16:10 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI11.asdf
-rw-r--r--   1 user  staff   391M Nov 26 16:13 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI12.asdf
-rw-r--r--   1 user  staff   391M Nov 26 16:22 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI13.asdf
-rw-r--r--   1 user  staff   391M Nov 27 07:14 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI14.asdf
-rw-r--r--   1 user  staff   391M Nov 27 08:53 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI15.asdf
-rw-r--r--   1 user  staff   391M Nov 27 08:56 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI16.asdf
-rw-r--r--   1 user  staff   391M Nov 27 09:00 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI17.asdf
-rw-r--r--   1 user  staff   391M Nov 27 09:04 RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI18.asdf

These 18 files represent a single Roman/WFI level 2 (calibrated, non-combined) exposure.

Analyze the stray-light level of the Roman/WFI exposures

2. Let's analyze the Roman/WFI example image with ROSALIA. The script rosalia-stray will extract all the necessary information from the Roman/WFI exposure file metadata, and generate a series of ASDF and FITS files with the pixel-to-pixel flux level expected for this particular exposure.

   rosalia-sky RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI01.asdf

For more examples, please refer to the Documentation

(back to top)

What is ASDF? Where are the FITS files?

ASDF is the successor of FITS format and has been adopted since JWST . While GUI visualizers like SAODS9 are not yet compatible with ASDF, ROSALIA provides an easy way to extract most useful information from the ASDF files through exposure-inspector:

   exposure-inspector RST_WFI_ROSALIA_test_Orion_Belt_SCAWFI01.asdf

exposure-inspector will print a series of fields containing basic information from the ASDF tree, including the name of the telescope, instrument, detector, and filter, pointing information like right ascension and declination, transmission curve of the filter, and the WCS of the header.

Roadmap

• Automatic queries of catalogs of bright sources.
  • Gaia, 2MASS, WISE
  • Horizons/JPL Solar System Objects
• Retrieval of stray-light blocking efficiency from ray-tracing models
• Ingestion of ASDF Roman/WFI simulated files (i.e., https://romanisim.readthedocs.io/en/latest/)
• Add diffraction modelling to Roman/WFI.
• Add thermal emission model (internal stray-light).
• Complete support for Hubble Space Telescope ACS & WFC3/IR.
• Automatic identification of SSOs in Roman/WFI observations.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make ROSALIA better, there are two options.

1. You can also simply open an issue with the tag "enhancement" (see below).
2. Fork the repo and create a pull request.
3. Email the PI's of the project ([e-mail]) with your ideas.

Instructions for fork/pull contributions.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

ROSALIA © 2025 by Alejandro S. Borlaff is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.

(back to top)

Contact

Alejandro S. Borlaff - @asborlaff - [e-mail]

Project Link: https://github.com/Borlaff/ROSALIA

(back to top)

Acknowledgments

(back to top)