Getting Started with JWST Data

General guides to understanding and getting started with JWST data are covered in this article. 

On this page

A general workflow on getting started with JWST data is provided below. Depending on your science goals and background, the steps and order may vary.

(tick) Know how to navigate the documentation

Unlike HST, JWST has a unified science calibration pipeline for all  instruments. To keep the software technical documentation closely tied to each version of the calibration pipeline, it is distributed with the software via Read the Docs. Much of this documentation is external to JDox, and is updated with each public release of the JWST Science Calibration Pipeline. Similarly, the MAST portal maintains their own cross-mission general user documentation with some highlights relevant to JWST here in JDox.

The JDox pages are grouped into 6 categories, each containing their respective collection of articles that provide an introductory level approach with links to more detailed information:

  1. Understanding JWST Data Files includes information about the data products, file types and formats, naming conventions, and header keywords.
  2. Accessing JWST Data provides highlights on how to search, explore, and retrieve data using the MAST portal, which is the repository for all JWST data (as well as data from other missions).
  3. JWST Science Calibration Pipeline articles hold information on installing and running the pipeline, as well as descriptions of each pipeline step and stage.
  4. Data Artifacts and Features articles provide information about different kinds of artifacts that have been identified in data files from pre-launch testing as well as on-orbit operations.
  5. JWST Calibration Pipeline Caveats articles cover general data processing caveats  and know issues that might be applicable to all, multiple, or specific instruments and modes. 
  6. Post-Pipeline Data Analysis Tools describes software available for analyzing JWST data, such as visualization tools and example Jupyter notebooks.

Additional training resources and examples are available at the JWebbinar training sessions (see "Materials and Recordings"). These archived webinars will be hosted on the JWST Observer YouTube channel in the near future. 

(tick) Install the necessary software

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

The following steps are recommended for working with JWST data on your machine:

  1. Install the JWST Science Calibration Pipeline and calibration references files
  2. Install Astropy
  3. Install the JWST Data Analysis Visualization Tool, Jdaviz
  4. Clone the JWST Data Analysis Tools Notebooks repo for examples on your local machine

STScI currently 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.   

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.  

* 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 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) Download and inspect your data

  1. Download data. Real JWST data can be downloaded from MAST. You can also use example simulated data or generate your own using JWST simulated data software such as MIRAGE and MIRISim. There are detailed example instructions for MIRAGE simulations and MIRISim simulations in the user guides for the software. 

  2. Inspect your data. You can use JWST data analysis tools to inspect the highest level of science calibration pipeline products produced for a given instrument mode's data to determine whether they are satisfactory for your science.

(tick)  Optionally reprocess your data

The JWST Operational Pipeline produces quality data products, in most cases. If you want to explore different parameters for your science, you can reprocess your data by running the JWST Science Calibration Pipeline yourself.

(tick) Analyzing data

While JWST data can be analyzed with any of your favorite tools, STScI recommends working with a suite of software specifically developed for JWST data formats. The post-pipeline data analysis ecosystem includes a number of Astropy astronomical analysis packages (partly maintained by STScI). Also included are the previously-mentioned JWST data analysis visualization tools (composed of Imviz, Specviz, Cubeviz, and Mosviz configurations), and a set of Jupyter notebooks that illustrate workflows for analyzing JWST data.

(tick) Citation for publications

See the How to Cite JWST Data Processing Versions and Reference Files article for guidelines to help with citations for publications, including citations for software, data reduction, or reference files used for analysis. 

Latest updates
    Included information about artifacts and caveats

  • Added section for new citation article
Originally published