SpiralMap: A Python library of the Milky Way's spiral arms

SpiralMap is a Python library that compiles nine major models of the Milky Way's spiral arms, enabling users to extract their 2D traces and visualize them in various coordinate frames and tracers.

The Gist

Imagine the Milky Way not as a blurry smear of light in the night sky, but as a giant, swirling city. For decades, astronomers have been trying to draw a map of this city, figuring out where the "downtown" (the bulge), the "suburbs" (the disc), and the "highways" (the spiral arms) are located.

But here's the problem: Different astronomers use different tools to see the city. Some use radio telescopes to spot gas clouds, others use optical telescopes to count stars, and some look for specific types of pulsing stars. Each tool gives a slightly different map. Sometimes these maps agree, and sometimes they look like they were drawn by different cartographers who never talked to each other.

Enter "SpiralMap."

Think of SpiralMap as the ultimate GPS app for the Milky Way, but instead of giving you turn-by-turn directions to the nearest coffee shop, it helps you overlay different historical maps of the galaxy's spiral arms onto a single, clean screen.

Here is the simple breakdown of what this paper is about:

1. The Problem: Too Many Maps, Too Much Confusion

Imagine you are trying to plan a road trip across a country. You have a map from 1992, a map from 2006, and a brand new map from 2024.

• The 1992 map says the highway goes through the mountains.
• The 2024 map says it goes through the valley.
• If you want to compare them, you have to manually draw them on top of each other, which is tedious, confusing, and prone to errors.

In astronomy, researchers often want to compare where the spiral arms should be (according to a specific model) with where they actually see stars or gas. Doing this manually for every new study is a "cumbersome exercise," as the authors put it.

2. The Solution: The "Universal Translator"

SpiralMap is a free, open-source software library (written in Python) that acts as a universal translator. It takes all these different, messy maps from various scientific papers and standardizes them.

• It speaks every language: Whether the original data was based on radio waves, dust, or specific types of stars, SpiralMap converts it into a format you can easily use.
• It has two views: You can look at the galaxy from the perspective of the Sun (Heliocentric) or from the center of the galaxy (Galactocentric). It's like switching from a "street view" to a "satellite view" instantly.
• It's a library of 9 major models: The current version includes maps based on everything from gas clouds (HI) to giant molecular clouds and even pulsing stars (Cepheids).

3. How It Works (The "Magic" Trick)

The authors show that with just a few lines of code, a scientist can:

1. Pick a model: "Let's look at the 2024 map based on Cepheid stars."
2. Pick an arm: "Show me the 'Sag-Car' arm."
3. Plot it: The software instantly draws that arm on a graph, either as a straight line (Cartesian) or a curve (Polar), ready to be compared with new data.

4. Why Does This Matter? (The "Science Case")

The paper gives a great example of why this is useful. Imagine astronomers built a 3D model of where stars should be in the Milky Way. When they looked at the real data, they found "residuals"—places where the stars didn't match the model.

By using SpiralMap, they could instantly overlay the spiral arm maps on top of these "mismatch" spots. It was like putting a transparent sheet with the highway map over a traffic report. Suddenly, they could see: "Ah! The traffic jams (extra stars) are happening exactly where the spiral arms are!"

This helps scientists understand how the galaxy's structure influences the movement and birth of stars.

The Bottom Line

SpiralMap is a tool that saves astronomers hours of manual drawing and math. It gathers the best "maps" of our galaxy's spiral arms from the last 30 years of research, puts them in one neat package, and lets scientists easily compare them to see how the Milky Way really works.

It's not just a map; it's the Google Earth for the Milky Way's spiral structure, making it easier for anyone to explore the shape of our home galaxy.

Technical Summary

Based on the provided draft paper, here is a detailed technical summary of SpiralMap:

1. Problem Statement

Mapping the structure of the Milky Way, particularly its non-axisymmetric features like spiral arms, has been a long-standing challenge in galactic astronomy. While numerous studies have surveyed the Galaxy across various wavelengths (Radio to Optical) and deduced rich spiral structures, the data is often fragmented.

• The Issue: Although some literature provides machine-readable data for specific spiral arm models, accessing and utilizing this data is often a "cumbersome exercise" for researchers.
• The Need: Astronomers frequently need to extract coordinates of spiral arms or overplot them onto other datasets (e.g., velocity fields or stellar density maps) to compare models with observations. Currently, there is no unified, user-friendly Python library that aggregates these diverse models, handles coordinate transformations (Heliocentric vs. Galactocentric), and facilitates easy visualization.

2. Methodology

The authors developed SpiralMap, a Python library designed to centralize, standardize, and visualize major spiral arm models of the Milky Way.

• Data Aggregation: The library compiles 9 distinct spiral arm models derived from various tracers (HII regions, HI gas, dust, stars, masers, and Cepheid variables) and wavelengths.
• Coordinate Transformation: The package supports both Heliocentric (HC) and Galactocentric (GC) reference frames. It allows users to convert and plot data in both Cartesian and Polar coordinates.
• Implementation:
  • The code is written in Python and relies on standard astronomical packages (Astropy, NumPy, Matplotlib, Pandas).
  • It includes pre-processed data files (including .pickle files for contour maps) to ensure user-friendliness.
  • It provides functions to read out specific arms, retrieve model metadata, and generate plots with polar grids.
• Model Selection: The library currently includes models ranging from 1992 to 2024, covering a wide spectrum of observational techniques.

3. Key Contributions

• Unified Library: SpiralMap is the first comprehensive Python package to aggregate 9 major spiral arm models into a single interface.
• Diverse Tracer Integration: The library bridges gaps between different observational methods by including models based on:
  • Radio/Optical: HII regions (Taylor & Cordes 1992), HI gas (Levine 2006).
  • Infrared/Magnetic: Dust and magnetic fields (Vallee 1995), NIR emission (Drimmel 2000).
  • Astrometry: High-precision maser parallaxes (Reid 2019), Gaia EDR3/DR3 data for Upper Main Sequence stars (Poggio 2021) and OB stars (Gaia 2022).
  • Cepheids: Dynamically young Cepheid variables (Drimmel Ceph 2024).
• Standardized Output: It provides a consistent API to extract 2D traces and overplot them, regardless of the original model's format (logarithmic spirals, polynomial-logarithmic formulations, or contour maps).
• Extensibility: The architecture allows for the easy inclusion of future 3D spiral arm traces and new models upon request.

4. Results and Demonstrations

The paper demonstrates the utility of SpiralMap through several visualizations and a specific scientific application:

• Visualization Capabilities:
  • Figure 1 & 2: Show Cartesian projections of single and multiple models (e.g., Drimmel Ceph 2024, Taylor Cordes 1992, Poggio 2021) in both HC and GC frames, with and without polar grids.
  • Figure 3: Displays polar projections, highlighting how different models align or diverge in angular space.
• Scientific Application (Case Study):
  • The authors reproduced results from Khanna et al. (2025), where SpiralMap was used to overlay spiral arm models onto residual plots of stellar density (Red Clump stars).
  • This allowed for a direct visual comparison between the residuals of a best-fit stellar density model and the locations of non-axisymmetric structures (spiral arms), validating the library's utility in analyzing galactic dynamics.

5. Significance

• Efficiency: SpiralMap significantly reduces the time and effort required for researchers to access and visualize complex galactic structure data, removing the need to manually parse individual papers or raw data tables.
• Comparative Analysis: By allowing multiple models to be overplotted in a single frame (e.g., comparing a 1992 radio model with a 2024 Cepheid model), it facilitates direct comparison of how different tracers reveal the Galaxy's structure.
• Community Resource: The package promotes reproducibility and standardization in galactic astronomy. The authors emphasize fair practice by providing a BibTeX file to ensure individual model papers are cited alongside the library usage.
• Future-Proofing: The library is designed to evolve, anticipating the inclusion of 3D spiral arm traces as they become available in literature, ensuring it remains a relevant tool for the next generation of galactic mapping.

Availability: The software is open-source, with documentation on ReadTheDocs, a demonstration Jupyter notebook, and the source code hosted on GitHub.