How to Overlay non-Roman Source Catalogs into mast-aladin

---

Learning Goals

This is a beginner tutorial on loading non-Roman source catalogs into mast-aladin. We will cover the basics of loading data into mast-aladin and interacting with them. By the end of this tutorial, you will:

• Understand the basics of working with source catalogs and mast-aladin.

• Be able to load a source catalog astropy.table.Table into mast-aladin.

• Know how to programmatically interface tables loaded in mast-aladin.

Table of Contents

• Introduction

• Imports

• Overlaying non-Roman Source Catalogs

  • Setup

  • Query for non-Roman Source Catalogs

  • Overlaying a Source Catalog

  • Update a Table’s Style

  • Removing a Source Catalog

  • Add Source Catalogs thorugh the UI

Introduction

This tutorial describes how to load non-Roman source catalogs into mast-aladin, allowing you to vizualize the data against a sky background. We will use the astroquery.mast library to query for source catalogs from the PanSTARRS and James Webb Space Telescope (JWST) missions. The examples provided will focus on sources near the Andromeda Galaxy (M31).

Imports

We will import the following in this tutorial:

• astroquery.mast: query and download source catalogs for a subset of the astronomical catalogs stored at MAST

• mast_aladin.MastAladin: interactive sky map widget for visualizing source catalogs

• sidecar: organize our mast-aladin viewer widget

from astroquery.mast import Catalogs, MastMissions
from mast_aladin import MastAladin
from sidecar import Sidecar

---

Overlay non-Roman Source Catalogs

Setup

The first step to working with mast-aladin is to set up the notebook workspace. We start by initializing an instance of the mast-aladin class with the target set to M31 and the fov, which controls the zoom level, set to 10 degrees to ensure we can see the source catalogs that we will load later in the notebook. We display the widget in the main panel to the right of the notebook by using sidecar with the anchor set to split-right. More information on this can be found in the interactive_data_exploration/how_to/organize_widgets/organize_widgets.ipynb tutorial.

mast_aladin = MastAladin(target="M31", fov=10)

sc = Sidecar(title="mast-aladin", anchor="split-right")
# Display the widget within the sidecar
with sc:
    display(mast_aladin)

Query for non-Roman Source Catalogs

Next, we query for non-Roman source catalogs. The astroquery.mast.Catalogs and astroquery.mast.MastMissions classes provide access to a subset of the astronomical catalogs stored at MAST. For this example, we will look at the PanSTARRS DR2 and JWST source catalogs.

Note: Both classes provide the same query API interface.

PanSTARRS Source Catalogs

PanSTARRS has a large number of sources near M31, so we will set a smaller radius of .02 degrees to quickly retrieve an example astropy.table.Table

panstarrs_catalog = Catalogs.query_criteria(
    collection="ps1_dr2",
    object_name="M31",
    radius=0.02
)

JWST Source Catalogs

JWST has no observations near the center of M31, so the radius needs to be set to 30 arcminutes to ensure that results are returned.

mm = MastMissions(mission="jwst")
jwst_observations = mm.query_object(object_names="m31", radius=30)

Overlaying a Source Catalog

You can overlay any astropy.table.Table with fields containing ra and dec values onto the sky viewer using the add_table() method. The method returns an Overlay object which can be used to modify its styling properties.

panstarrs_overlay = mast_aladin.add_table(panstarrs_catalog, name="panstarrs", raField="raMean", decField="decMean")
jwst_overlay = mast_aladin.add_table(jwst_observations, name="jwst", raField="targ_ra", decField="targ_dec")

Update a Table’s Style

You can update the name, color, shape, and source size of an Overlay.

# returns the updated Overlay
panstarrs_overlay = panstarrs_overlay.update(
    name="panstarrs-updated",
    color="Blue", 
    shape="circle", 
    source_size=30
)

Removing a Source Catalog

The remove_overlay method allows for the removal of source catalogs.

First, we can view all of the currently loaded Overlays with mast_aladin.overlays, taking note of the source catalog we wish to remove.

mast_aladin.overlays

['jwst', 'panstarrs-updated']

Next, provide the name attached to the source catalog to the remove_overlay method.

mast_aladin.remove_overlay('panstarrs-updated')

Add Source Catalogs through the User Interface

The mast-aladin UI provides the ability to load the following source catalogs:

• Global Astrometric Interferometer for Astrophysics (GAIA) DR3: ESA mission containing over 1.8 billion sources from our galaxy.

• Two Micron All-Sky Survey (2MASS): NASA mission which contains over one-million galaxies and extended Galactic sources covering the entire sky at wavelenghts between 1 and 2 m.

• Simbad Astronomical Database: Provides basic data, cross-identifications, bibliography and measurements for astronomical objects outside the solar system.

The sources will be loaded based on the current viewer position and FOV.

Steps:

1. Click the icon to open the overlays menu

2. Click the icon to add a catalog, MOC or footprint

3. Select “Catalogs”

4. Select “GAIA DR3”

About this Notebook

Author(s): Patrick Custer
Keyword(s): mast-aladin, astroquery, source catalogs
First published: July 2026
Last updated: July 2026

---

Top of Page