• Home
  • Getting Started with JWST Data

Getting Started with JWST Data

Some pointers for getting started with JWST data analysis, along with links to relevant documentation, are provided in this article. 

On this page

Whether you have decades of experience working with astronomical data or are just getting involved with data analysis for the first time, it can take a while to become familiar with the JWST data ecosystem. Topics covered in this article may be further explored by either using the links below or through the hierarchical page tree on the left. Depending on your science goals and background, the steps and order may vary.


(tick) Download and inspect your data

After JWST observes a given astronomical program, the raw telemetry is sent to STScI via the Deep Space Network and repackaged into uncalibrated data files. These uncalibrated data are then processed using the JWST Science Calibration Pipeline software, in combination with calibration reference files describing the performance characteristics of the science instruments. The resulting calibrated science data products, along with original uncalibrated data, are then stored in the MAST data archive and provided to the scientific community.

These calibrated science data products include files such as flux-calibrated imaging mosaics, photometric source catalogs, 3-dimensional integral field unit data cubes, and extracted one-dimensional spectra, and are an excellent place to start exploring JWST data.

Accessing JWST Data provides a high-level overview of how to search, explore, and retrieve data from the STScI MAST archive, which is the repository for all JWST data (as well as data from other missions). This can be accomplished using either traditional web-based or programmatic API interfaces.

An overview of the JWST data product file formats and naming conventions can be found at JWST Science Data Overview.


(tick) Optionally reprocess your data

The calibrated science data products available through MAST are generally sufficient for most basic scientific analyses, but extracting the very best scientific information from JWST data can always benefit from expert scientific judgements unique to a given science case. The JWST pipeline has therefore been designed with multiple optional steps so that expert users can download the original uncalibrated science data and rerun the pipeline with custom modifications. Advice on modifications that you may wish to explore for different instrument can be found at the Known Issues with JWST Data articles. Calibration reference files and the pipeline software are continually being updated, and users wishing to take advantage of these updates before they are available in the MAST archive may wish to reprocess the data for themselves.

The JWST Science Calibration Pipeline article gives a basic overview of the 3 primary stages within the pipeline and the associated reference file infrastructure, including a guide to installation. Information about the latest pipeline build is given in JWST Operations Pipeline Build Information (including a high-level summary of "What's New" in the latest pipeline, and what is "Coming Soon"), while a basic guide to running the pipeline can be found at Running the JWST Science Calibration Pipeline. Example Jupyter notebooks can be found on the JWST Pipeline Notebooks article.

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

Note that STScI primarily supports development of software in the Python environment. Most of the software packages you will be using are installed via pip and the instructions assume you are already familiar with creating new environments. If you are new to Python and looking for easy ways to manage your environments, Conda is a common open source package and environment management system*. It may be of interest for you to know the difference between Conda and pip, even though the two are often used synonymously.  

It's also recommended that you become familiar with Git and GitHub. In many cases, software and examples may be stored in GitHub repositories so that cloning an existing GitHub repository is the the easiest way to run the files on your own machine.   


* STScI previously maintained a free Conda channel named AstroConda, which allowed you to install all the necessary packages in one large bundle; however, AstroConda was superseded by the release of a new STScI software distribution called stenv. It supports most of the packages in AstroConda, works with all current versions of Python, and provides a common environment for both the Hubble Space Telescope (HST) and James Webb Space Telescope (JWST) pipelines. Additionally, while AstroConda primarily uses Conda recipes to build and serve packages, which need to be updated separately from PyPI releases, stenv draws most of its packages directly from PyPI with pip (though it still requires use of a Conda environment for hstcal and fitsverify, which are provided by conda-forge). For more details and installation directions go to https://github.com/spacetelescope/stenv. Note that Jdaviz and the JWST Science Calibration Pipeline can be installed via pip, which also installs the required packages for the software. They do not have a dependence on the AstroConda channel or the new STScI stenv software distribution. 


(tick) Check the calibration status of the data

Whether working with calibrated data downloaded directly from MAST or reprocessing the data offline, it is essential to be familiar with the overall JWST Calibration Status of the JWST instrument. These articles provided key information about each instrument mode and describe, for example, the accuracy of the photometric, astrometric, and wavelength calibration of the data. Note that these can change frequently as new calibration reference files are updated based upon analyses performed by the JWST instrument teams.

You can also check "What's New" in the latest JWST pipeline build, and what will be "Coming Soon" in the next build.


(tick) Check for any known issues

It is also critical for users to be familiar with the list of known Issues with JWST data affecting JWST data products. These can vary from instrument artifacts such as dead pixels and stray light to data processing issues where some science cases could benefit from re-running the JWST pipeline using nonstandard parameters. As an example, cosmic rays can sometimes produce large blotchy artifacts that extent across tens or hundreds of pixels (see Shower and Snowball Artifacts). Likewise, spectral fringing inherent to the MIRI medium resolution spectrometer can produce periodic amplitude modulations in the science spectra, and the best methods for dealing with these features can be science-case specific.

A full list of known issues is provided for each individual instrument mode and updated frequently as new issues are discovered and previous issues are retired by ongoing calibration work. These articles also provide guidance for reprocessing data from each of the different JWST observing modes.


(tick) Analyze the data using post-pipeline data analysis tools

While JWST data can be analyzed with any of your favorite tools, STScI also provides a suite of software specifically developed for JWST data formats. The JWST Post-Pipeline Data Analysis article describes a number of Astropy-based astronomical analysis packages, the Jdaviz software (composed of Imviz, Specviz, Specviz2d, Cubeviz, and Mosviz configurations), and a set of Jupyter JWST data analysis (JDAT) notebooks that illustrate potential workflows for analyzing JWST data.

Note that the JWST visualization tools can be opened as standalone tools, but are designed to be integrated into a Python Jupyter notebook workflow. There are many advantages to working in a Jupyter notebook, including, but not limited to, easy documentation, cell by cell execution, visualizing individual steps, and sharing work.  


(tick) Cite JWST 

See the Citing JWST Data article for guidelines to help with citations for publications, including citations for data products, data reduction software, or reference files used for analysis. Recipients of JWST grants are reminded of their obligation to create digital object identifiers (DOIs) for JWST data they analyze in their publications.


(tick) Ask for help

If you're having trouble downloading data, running the JWST calibration pipeline, or puzzling out whether that feature you're seeing in the data is an instrumental artifact or an exiting scientific discovery, you can reach out to STScI for assistance. For general inquiries about JWST data products, contact the JWST Help Desk. For specific problems with MAST data access, visit Archive Support, view the MAST JWST data FAQ to see if your question has already been addressed, or contact the MAST Help Desk.

Additional training resources and examples are also available on the JWebbinar training sessions page, with archived webinars also hosted on the JWST Observer YouTube channel.



Notable updates


Originally published