## MAXI All-Sky Map Visualization

This playbook describes how to visualize the **pre-generated all-sky maps** provided by the MAXI team.
For generating maps from event-by-event photon data, see the separate playbook `maxi-allskymap-from-events`.

MAXI provides all-sky X-ray maps from two instruments: the Solid-state Slit Camera (SSC) and the Gas Slit Camera (GSC).
File URLs for each energy band are listed on the dataset pages at DARTS:

- SSC: https://darts.isas.jaxa.jp/datasets/darts:maxi-ssc-allsky/
- GSC: https://darts.isas.jaxa.jp/datasets/darts:maxi-gsc-allsky/

---

### Available Energy Bands

#### MAXI/SSC (0.7–4.0 keV, 2009–2011)

Units: counts deg⁻² cm⁻² s⁻¹

| Energy (keV) | PI Channel |
|---|---|
| 0.7–1.0 | 192–273 |
| 1.0–2.0 | 274–547 |
| 2.0–4.0 | 548–1095 |

#### MAXI/GSC (2–16 keV, 2009–2020)

Units: counts cm⁻² s⁻¹

| Energy (keV) | PI Channel |
|---|---|
| 2–4  | 40–80   |
| 4–8  | 80–160  |
| 8–16 | 160–320 |

Both instruments share the same FITS structure:

- **Primary HDU**: 2D image in Aitoff-Hammer projection (Galactic coordinates)
- **Secondary HDU**: HEALPix table (Equatorial coordinates, NESTED, NSIDE=128); intensity column is `RATE` (SSC) or `CNTS` (GSC)

---

### Visualization with Python

#### Requirements

```
pip install astropy matplotlib numpy
```

#### Example 1: Display a single-band image

```python
import numpy as np
import matplotlib.pyplot as plt
from astropy.io import fits

# Obtain the URL from the dataset page
url = "https://..."

with fits.open(url) as hdul:
    image = hdul[0].data

image = np.where(image > 0, image, np.nan)

fig, ax = plt.subplots(figsize=(12, 6))
im = ax.imshow(np.log10(image), origin="lower", cmap="afmhot", aspect="auto")
fig.colorbar(im, ax=ax, label=r"log$_{10}$ Intensity")
ax.set_title("MAXI/SSC All-Sky Map (Galactic, Aitoff-Hammer)")
ax.set_xlabel("Galactic Longitude")
ax.set_ylabel("Galactic Latitude")
plt.tight_layout()
plt.close()
```

#### Example 2: Three-color (RGB) composite image

```python
import numpy as np
import matplotlib.pyplot as plt
from astropy.io import fits

# Obtain the URLs from the dataset page; assign soft→R, mid→G, hard→B
url_r = "https://..."
url_g = "https://..."
url_b = "https://..."

channels = {}
for key, url in [("r", url_r), ("g", url_g), ("b", url_b)]:
    with fits.open(url) as hdul:
        data = hdul[0].data
    channels[key] = np.where(data > 0, data, 0.0)

def normalize(arr):
    vmax = np.nanpercentile(arr[arr > 0], 99)
    return np.clip(arr / vmax, 0, 1)

rgb = np.stack([normalize(channels["r"]),
                normalize(channels["g"]),
                normalize(channels["b"])], axis=-1)

fig, ax = plt.subplots(figsize=(12, 6))
ax.imshow(rgb, origin="lower", aspect="auto")
ax.set_title("MAXI All-Sky RGB Map")
ax.set_xlabel("Galactic Longitude")
ax.set_ylabel("Galactic Latitude")
plt.tight_layout()
plt.close()
```

#### Example 3: Read the HEALPix data from the secondary HDU

```python
from astropy.io import fits
from astropy.table import Table

# SSC: intensity column is "RATE"; GSC: "CNTS"
url = "https://..."

with fits.open(url) as hdul:
    table = Table(hdul[1].data)

print(table.colnames)
print(table[:5])
```

---

### Acknowledgement

When using this data in publications, please include:

> "This research has made use of MAXI data provided by RIKEN, JAXA and the MAXI team."

and cite:

- Matsuoka, M. et al. (2009), PASJ, 61, 999. [doi:10.1093/pasj/61.5.999](https://doi.org/10.1093/pasj/61.5.999)
- Nakahira, S. et al. (2020), PASJ, 72, 17. [doi:10.1093/pasj/psz139](https://doi.org/10.1093/pasj/psz139) — for SSC maps
- Sugizaki, M. et al. (2011), PASJ, 63, S635. [doi:10.1093/pasj/63.sp3.S635](https://doi.org/10.1093/pasj/63.sp3.S635) — for GSC instrument