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

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

Usage:
 IRIS_getHINODEdata, obs [, nodisplay=nodisplay, noprep=noprep, yscrsize=yscrsize, usehcr=usehcr,  nowidget=nowidget, outdir=outdir, adddatetree=adddatetree, addobsid=addobsid, fovexpand=fovexpand, timeexpand=timeexpand, deletetempfiles=deletetempfiles, fulltime=fulltime, fullfov=fullfov, timelowlimit=timelowlimit, arealowlimit=arealowlimit, _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
nodisplay: if set, suppresses the graphical output of iris_sot_umodes()
noprep: if set, suppresses the use of fg_prep (can also be set within the widget)
yscrsize: maximum size of the widget as a fraction of the screen size (default
0.85)
nowidget: suppresses the widget interface, the parameters to use for the
processing of the HINODE 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/)
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
fulltime: If set, all HINODE files of the selected umodes will be used, regardless of
the time window
fullfov: If set, the original FOV of the HINODE umode will be transfered,
regardless of IRIS FOV
timelowlimit: used only if nowidget is set, Defines the lower limit of the IRIS time
window covered by HINODE in percent (default: 10.0 %)
arealowlimit: used only if nowidget is set, Defines the lower limit of the IRIS
raster FOV covered by HINODE in percent (default: 10.0 %)
_extra: will be passed to fg_prep (by default no keywords are set)

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

Calls:

Using the widget-interface:

IRIS_getHINODEdata, obs [, nodisplay=nodisplay, noprep=noprep, yscrsize=yscrsize, outdir=outdir, addobsid=addobsid, fovexpand=fovexpand, timeexpand=timeexpand, deletetempfiles=deletetempfiles, fulltime=fulltime, fullfov=fullfov, _extra=_extra]

More input/keywords are not required. However, if the keywords outdir, addobsid, fovexpand, timeexpand, deletetempfiles, fulltime and/or fullfov are set, then those will overwrite the default value or the values saved in the user-parameter file. Adddatetree is ignored and nowidget must not be set.

A widget appears, and some information on the IRIS OBS, and how the HINODE data should be transformed. The first line displays the OBS ID, and the second line the directory in which the IRIS OBS was found.

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 four 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 HINODE fits files after use’: All downloaded HINODE files will be deleted
after creating the level 2 files.

Below that information about the IRIS window is shown, and it lets you control the HINODE 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 HINODE 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 HINODE data.

The lower half of the window contains two tables. The first one displays the SOT HCR entries found for this IRIS OBS. The time window of the IRIS OBS is expanded by +/- 1 hour for the search of SOT HCR entries. Each SOT HCR entry contains information about the start time, stop time, target, x/ycen and fovx/y. Additionally, four values of the overlap with the IRIS OBS are calculated and shown. ‘% AREA SJI’ is the percentage of the IRIS OBS total FOV that is covered by the HINODE data. ‘% AREA RAS’ is the percentage of the IRIS OBS raster FOV that is covered by the HINODE data. ‘% TIME SOT’ is the percentage of SOT files that are within the IRIS OBS time window (excluding the expanded time window). ‘% TIME IRIS’ is the percentage of the IRIS OBS time window covered by the HINODE data (excluding the expanded time window). The AREA percentages are rough estimates calculated from the HCR entry values, and not from the values within the fits files.

The second table displays all umodes of the selected SOT HCR entry. Each has information about the OBS_TYPE, WAVE, NAXIS1 and NAXIS2. ‘FILES_TOT’ is the total number of files for this umode. ‘FILES_WIN’ is the number of files that fall within the IRIS OBS time window (including the expanded time window). ‘% TIME SOT’ is the percentage of umode files that are within the IRIS OBS time window (excluding the expanded time window). ‘% TIME IRIS’ is the percentage of the IRIS OBS time window covered by this umode (excluding the expanded time window).

If the keyword nodisplay is not set, additional windows appear, one for each SOT HCR entry. These show a graphical overview of the temporal distributions of all files divided into the different umodes. The IRIS OBS time window is also shown for comparison.

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_getHINODEdata without the nowidget keyword. It can be found in the hidden IDL folder (.idl/mwiesmann/iris_gethinodedata/).

Not using the widget-interface

IRIS_getHINODEdata, obs, /nowidget, outdir=outdir [, nodisplay=nodisplay, noprep=noprep, adddatetree=adddatetree, addobsid=addobsid, fovexpand=fovexpand, timeexpand=timeexpand, deletetempfiles=deletetempfiles, fulltime=fulltime, fullfov=fullfov, timelowlimit=timelowlimit, arealowlimit=arealowlimit, _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. All umodes of all SOT HCR entries that exceed timelowlimit and arealowlimit will be processed. Timelowlimit refers to the percentage of the IRIS OBS time window that is covered. Arealowlimit refers to the percentage of the IRIS OBS raster FOV that is covered.

Procedure
Depending on your location up to two steps will be performed:

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

Download the data

If your machine is at Lockheed, no download is needed,.The data is loaded directly from the archive. Outside of Lockheed the data needs to be downloaded first, this is done automatically, and can take quite some time, depending on the number of files to be downloaded. The files are saved into a subfolder ‘original’ in the output directory.

Transform the data to level 2

The tool then reads the data and preps them using fg_prep. If the keyword noprep is set, or the respective button on the widget is active, the data is read using read_sot, fg_prep is then not called.

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 HINODE 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 HINODE 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.

In case the HINODE fits file contains more than one image, i.e. it is 3-dimensional, i.e. the I/V files, than each image will be saved into separate files.