Add an example and documents about how to use the `aia_scale` option to export AIA lev1.5 data from JSOC through `drms`

Start with the drms.client.export() entry point and the existing cutout export example linked in the issue. Document the aia_scale_aialev1 process, including the minimal and cutout examples, and verify that the example explains the accepted parameters and produces the intended AIA level 1.5 export.

Describe the feature

JSOC provides several useful processing procedures when exporting AIA and HMI data, such as the cutout service and aia_scale. The latter scales the plate size to 0.6 arcsec per pixel across the AIA channels. According to this tutorial, the aia_scale option "essentially converts the data level 1 to level 1.5 and removes the latter use of aia_prep". Therefore, JSOC users can save a lot of time processing their level 1 AIA data to level 1.5 using aia_prep.pro in SolarSoft or its corresponding implementation in aiapy.

However, how to use the aia_scale option in drms is unclear to the users and poorly documented in both drms and JSOC reference. Since the cutout service has been well illustrated in the example and integrated into the JSOC client in sunpy.net.Fido, it would be desirable to provide an example or even, in the future, add an a.Level(1.5) support through the JSOC client.

Many thanks to @wtbarnes for pointing me to this pull request https://github.com/sunpy/drms/pull/43#discussion_r513024285, where @davisite explains the keys passed to enable aia_scale. In summary, there are three accepted keys of the dictionary passed to the process argument in drms.client.export(), which are related to the rescale: aia_scale_orig, aia_scale_aialev1, and aia_scale_other. After testing these keys with the method mentioned in this issue https://github.com/sunpy/drms/issues/25, I found something different with what @davisite mentioned in the original pull request. aia_scale_aialev1 works for the AIA level 1 data (both aia.lev1_euv_12s and aia.lev1_uv_24s) that I tested, and aia_scale_other works for the HMI Blos data (e.g., hmi.M_45s). Please also see the screenshots of the JSOC export below:

Therefore, a minimal example of exporting AIA level 1.5 data using drms is

import os
from pathlib import Path
import drms

client = drms.Client()
email = os.environ["JSOC_EMAIL"]

# Create download directory if it does not exist yet.
out_dir = Path("downloads")
if not out_dir.exists():
    Path(out_dir).mkdir(parents=True)

qstr = "aia.lev1_euv_12s[2022-10-25T19:00][171]"
result = client.export(qstr, method="url", email=email, protocol="fits",
process={"aia_scale_aialev1":{None:None}})

result.wait()
result.download(out_dir)

Note that we used None in the value to fool drms because drms.client.export() assumes the value of aia_scale_aialev1 is another dictionary, or one may use {"aia_scale_aialev1":{'high':4096}} (cut 4096 of the 4096 pixels); maybe we can change that in the future.

A more complicated example of using aia_scale with both updating the master pointing and cutout the data in a box will be

process = {"aia_scale_aialev1":
            {"xc": 200.0, #The X coordinate (pixels) of the cutout center; at Sun Center, X == 0 
             "yc": 100.0, #The Y coordinate (pixels) of the cutout center; at Sun Center, Y == 0
             "wide": 300, #The width of the cutout, in integer pixels 
             "high": 600, #The height of the cutout, in integer pixels 
             "mpt": "aia.master_pointing3h" # Use a master pointing table to scale images (instead of keyword values) 
             # or "sdo.master_pointing", "aia_test-master_pointing3h",
             # "lm_jps.master_pointing3h"
            }
        }

result = client.export(qstr, method="url", email=email,protocol="fits",
process=process)

I hope this can save people like me who want to download nearly science-ready AIA files. This question was initially raised by Henrik Jentgens. I give him credit here.

Proposed solution

No response