Updating pointing and observer keywords in the FITS header

This example demonstrates how to update the metadata in an AIA FITS file to ensure that it has the most accurate information regarding the spacecraft pointing and observer position.

import sunpy.map

import aiapy.data.sample as sample_data
from aiapy.calibrate import fix_observer_location, update_pointing

An AIA FITS header contains various pieces of standard. metadata that are critical to the physical interpretation of the data. These include the pointing of the spacecraft, necessary for connecting positions on the pixel grid to physical locations on the Sun, as well as the observer (i.e. satellite) location.

While this metadata is recorded in the FITS header, some values in the headers exported by data providers (e.g. Joint Science Operations Center (JSOC) and the Virtual Solar Observatory may not always be the most accurate. In the case of the spacecraft pointing, a more accurate 3-hourly pointing table is available from the JSOC.

For this example, we will read a 171 Å image from the aiapy sample data into a Map object.

m = sunpy.map.Map(sample_data.AIA_171_IMAGE)

To update the pointing keywords, we can pass our Map to the aiapy.calibrate.update_pointing function. This function will query the JSOC, using sunpy, for the most recent pointing information, update the metadata, and then return a new Map with this updated metadata.

m_updated_pointing = update_pointing(m)

If we inspect the reference pixel and rotation matrix of the original map

print(m.reference_pixel)
print(m.rotation_matrix)

PixelPair(x=<Quantity 2055.310059 pix>, y=<Quantity 2045.709961 pix>)
[[ 9.99999944e-01 -3.34562158e-04]
 [ 3.34562158e-04  9.99999944e-01]]

and the map with the updated pointing information

print(m_updated_pointing.reference_pixel)
print(m_updated_pointing.rotation_matrix)

PixelPair(x=<Quantity 2055.501465 pix>, y=<Quantity 2046.018311 pix>)
[[ 9.99999944e-01 -3.34562158e-04]
 [ 3.34562158e-04  9.99999944e-01]]

we find that the relevant keywords, CRPIX1, CRPIX2, CDELT1, CDELT2, and CROTA2, have been updated.

Similarly, the Heliographic Stonyhurst (HGS) coordinates of the observer location in the header are inaccurate. If we check the HGS longitude keyword in the header, we find that it is 0 degrees which is not the HGS longitude coordinate of SDO.

print(m_updated_pointing.meta["hgln_obs"])
print(m_updated_pointing.meta["hglt_obs"])

0.0
-2.976075

To update the HGS observer coordinates, we can use the aiapy.calibrate.fix_observer_location function. This function reads the correct observer location from Heliocentric Aries Ecliptic (HAE) coordinates in the header, converts them to HGS, and replaces the inaccurate HGS keywords.

m_observer_fixed = fix_observer_location(m_updated_pointing)

Looking again at the HGS longitude and latitude keywords, we can see that they have been updated.

print(m_observer_fixed.meta["hgln_obs"])
print(m_observer_fixed.meta["hglt_obs"])

-0.01480900749072589
-2.976118447285847

Note that in AIAMap, the observer_coordinate attribute is already derived from the HAE coordinates such that it is not strictly necessary to apply aiapy.calibrate.fix_observer_location. For example, the unfixed Map will still have an accurate derived observer position

print(m_updated_pointing.observer_coordinate)

<SkyCoord (HeliographicStonyhurst: obstime=2019-01-01T00:00:09.350, rsun=696000.0 km): (lon, lat, radius) in (deg, deg, m)
    (-0.01480901, -2.97611845, 1.47085021e+11)>

However, we suggest that users apply this fix such that the information stored in meta is accurate and consistent.

Finally, plot the fixed map.

m_observer_fixed.peek()