Manual for the tool IRIS_getAIAdata
(Martin Wiesmann, UIO)
2015-12-18

This tool downloads, if necessary, AIA data that correspond to a specific IRIS OBS and transforms it to IRIS SJI-like level 2 fits file.

Usage:
IRIS_getAIAdata, obs [, usehcr=usehcr, nowidget=nowidget, outdir=outdir, adddatetree=adddatetree, addobsid=addobsid, waves=waves, fovexpand=fovexpand, timeexpand=timeexpand, method=method, deletetempfiles=deletetempfiles , maxframes=maxframes, tres=tres, extra=extra]

Input:
obs: where obs is the OBS ID of the IRIS OBS. It can be given in 3 different styles:
1) Just the OBS ID (e.g. '20130829_005500_4203300028')
2) The directory in which the IRIS files reside (e.g. '/mn/xsan/d2/iris/data/level2/2014/01/01/20140101_000431_3840257196/')
3) The full path of one of the IRIS files, which you can print out from iris_xfiles (e.g. '/mn/xsan/d2/iris/data/level2/2014/01/01/20140101_000431_3840257196/iris_l2_20140101_000431_3840257196_SJI_1400_t000.fits')

Optional keyword parameters:
usehcr: instead of getting some information from IRIS level 2 files, the program
will call iris_obs2hcr(), this option is not (yet) supported
nowidget: suppresses the widget interface, the parameters to use for the
processing of the AIA data are either taken from the provided keywords,
or the defaults. If nowidget is set, outdir is required as well.
outdir: the directory in which to save the resulting fits files, may be modified
(internally) by the keywords adddatetree and addobsid. If download is
necessary, subfolder 'original' will be created and the original files saved
into that. Required, if the keyword nowidget is set (doesn’t have to exist)
adddatetree: adds a date-tree structure to outdir (i.e. outdir/2015/10/23/)
addobsid: adds the OBS ID to outdir (i.e. 
outdir/20151023_171023_4203300028/), if adddatetree is also set
the OBS ID will be added at the end (i.e.
outdir/2015/10/23/20151023_171023_4203300028/)
waves: a list of wavelengths to be transformed, must be an array of strings
(default: ['94','131','171','193','211','304','335','1600','1700','4500'] (all
wavelengths))
fovexpand: defines by how much the FOV should be expanded, as compared to
IRIS FOV, in arcsecond, can be scalar, then the same expansion will be
applied to both the x- and y-axis. It can also be a 2-element vector, one
element for x- and one for y-axis, respectively. (default: 100.0 arcsec)
timeexpand: defines by how much the time window of the IRIS OBS is expanded
for AIA data, in minutes. If scalar, the value will be applied to the start and
the end time. Can be also a 2-element vector, for different expansions
at the start and at the end, respectively. (Positive numbers result in a
wider time-window). (default: 10.0 minutes)
deletetempfiles: if set, the downloaded files will be deleted after use
maxframes: maximum number of frames per wavelength, used in method 0
tres: temporal resolution of AIA data, used in method 1
_extra: will be passed to aia_prep (by default no keywords are set) and
ssw_cutout_service
method: choose the method (set to the corresponding number)
	0: SSW_CUTOUT: Calls ssw_cutout_service. The data is prepared on the
server and when it is ready it will be downloaded, the files to download
are very small, but the preparation can take a very long time (up to
several hours).
1: FULL FRAME: The full frame AIA data is first downloaded and then
prepared locally. The files to download are very large, but download
speed is much higher compared to ssw_cutout, and there is no waiting
time for the data. This method is recommended if you have good internet
connection and lots of space on your harddisk
2: ARCHIVE: No download of any data, it is assumed that you have
access to /archive/sdo/AIA/lev1/. Preparation is done directly on the
archived file. Max # frames (and tres) is ignored, all available file are used.
Recommended if you run this program at Lockheed. (default when
nowidget keyword is set)

Output:
IRIS-SJI-like level 2 fits files of AIA data and a log file. Also an errorlog file will be written if the tool crashed.

Calls:

Using the widget-interface:

IRIS_getAIAdata, obs [, outdir=outdir, addobsid=addobsid, waves=waves, fovexpand=fovexpand, timeexpand=timeexpand, method=method, deletetempfiles=deletetempfiles , maxframes=maxframes, tres=tres, extra=extra]

More input/keywords are not required. However, if the keywords outdir, addobsid, fovexpand, timeexpand, deletetempfiles, maxframes, tres and/or method are set, then those will overwrite the default value or the values saved in the user-parameter file. The keyword waves is ignored for now, might change in the future. Adddatetree is ignored and nowidget must not be set.

A widget appears, and some information on the IRIS OBS, and how the AIA data should be transformed. The first line displays the OBS ID, and the second line the directory in which the IRIS OBS was found. In the third line, you can enter an email address, and if you activitate the field ‘Send email notification’ you will receive an email when you use the SSW_cutout service and the AIA is ready to be downloaded. This email has purely informational character, the download of the data will be started automatically.

On the next line ‘Output directory’, you define the directory in which the resulting fits files should be saved. You can change it by clicking on ‘Change’ next to the line. Note in the dialog that appears you have to be in the directory in which you want to save the files before clicking ‘OK’, highlighting it is not enough.

Below the output directory are three options.
‘Save in IRIS_DATA/level3 folder’: This option is for users at UIO only (for now at
least). The output directory will be changed to the IRIS directory of the
level 3 files.
‘Add OBS ID to output directory’: Same effect as setting the keyword addobsid.
The OBS ID will be added at the end of the output directory.
‘Delete AIA level 1.5 fits files after use’: All downloaded AIA files will be deleted
after creating the level 2 files.

The instrument pulldown menu has only one option, AIA.
Below that, you can choose which wavelengths should be downloaded and transformed. ‘all’ will select/deselect all available wavelengths. Note: ‘blos’ and ‘cont’ don’t seem to exist and might cause a crash.

The lowest third of the window shows information about the IRIS window, and lets you control the AIA window relative to the IRIS window.
Cutout center shows the X- and YCEN of the IRIS OBS.
Cutout FOV shows the field of view of the IRIS OBS, which can be expanded for the AIA data, separately. The expansion given by the user is the sum of the expansion on both sides, i.e. if FOV X is xxx + 20.0, then 10 arcsec is added both on the right and the left side of the FOV.
Similarly, start and stop time shows the time window of the IRIS OBS, and this time window can be expanded by the user for the AIA data.

Max # frames is a limit of the number of frames to be downloaded and transformed for each wavelength band. This is directly related to the temporal resolution, which is the total IRIS OBS time divided by the number of frames. Typical temporal resolution is 12 seconds for AIA.

At the lower part of the window, you can choose which method you want to use, see keyword description for method.

By clicking ‘QUIT’ the window disappears and nothing happens.
You start the download and transformation by clicking ‘Request Data’. After clicking this button, the window disappears, and the parameters used in this session will be saved into a user-parameter file. This file will be read when recalling IRIS_getAIAdata without the nowidget keyword. It can be found in the hidden IDL folder (.idl/mwiesmann/iris_getaiadata/).

Not using the widget-interface

IRIS_getAIAdata, obs, outdir=outdir, /nowidget [, adddatetree=adddatetree, addobsid=addobsid, waves=waves, fovexpand=fovexpand, timeexpand=timeexpand, method=method, deletetempfiles=deletetempfiles , maxframes=maxframes, tres=tres, extra=extra]

In this case the keyword nowidget has to be set and the output directory provided through the keyword outdir. The output directory doesn’t have to exist. Other keywords are optional, and the default values will be used if not provided.

No widget appears, and the tool automatically starts the download, if necessary, and the transformation of the data to level 2.

Procedure
Depending on the method chosen up to three steps will be performed:

1)	Request the data
2)	Download the data
3)	Transform the data to level 2

Request the data

Method 0 (SSW_CUTOUT): ssw_cutout_service is called. The server then takes a cutout of the AIA data and calls aia_prep on it. When done, the service makes the requested data available through a webpage and an email is sent, if an email address is provided.

Method 1 (FULL FRAME): the tool calls vso_search to find the requested AIA files.

Method 2 (ARCHIVE): the tool searches the AIA files itself in the directory /archive/sdo/AIA/lev1/

Download the data

Method 0 (SSW_CUTOUT): the tool checks periodically if the data is ready to be downloaded, and when it is ready, downloads the data into a subfolder ‘original’ in the output directory, using ssw_service_get_data.

Method 1 (FULL FRAME): the tool calls vso_get to download the full frame AIA files into a subfolder ‘original’ in the output directory.

Method 2 (ARCHIVE): no download needed.

Transform the data to level 2

Method 0 (SSW_CUTOUT): the tool reads the data using read_sdo.

Method 1 (FULL FRAME): the tool reads and preps the data using aia_prep.

Method 2 (ARCHIVE): the tool reads and preps the data using aia_prep.

For each image the new X-/YCEN is calculated from the X-/YCEN of the IRIS images. A regression line is calculated using the X-/YCEN of all IRIS images as a function of time, and these regression parameters are used to calculate the X-/YCEN of the AIA image. The point in the image with these x- and y-values is set as the center of the FOV, this involves also a sub-pixel shift of the image using INF_POLY_2D(). The AIA image is then rotated to the roll angle of IRIS. The roll angle is taken from the wcs-parameters, not from SAT_ROT, which may be off by 0.6 degrees. The SAT_ROT keyword in the new level 2 file contains the same value as SAT_ROT in IRIS, and the wcs-parameters are calculated using the actual roll angle. The images are then assembled into a 3-D cube and saved into a fits file. CRVAL1/2 values are taken from the picture whose index is stored in CRPIX3, the same way as in the IRIS level 2 files.