# 4. IRISpy Introduction¶

IRISpy was originally developed as a community effort by members of the SunPy team. The IRISpy package was never released to the public and exists only in a development form. Recent changes within the way that SunPy is organized have seen the more general functionality of IRISpy superseded in the SunPy package by a more instrument agnostic module for analysis of imaging spectrometer data named sunraster. IRISpy has therefore been taken over by the IRIS team at LMSAL. As it exists today, IRISpy has two main functions, which both do essentially the same thing, but for slit jaw imager (SJI) and Spectrograph respectively: Those being functions to load in fits files extract the data from them into the format of NDCube which the preferred method of looking at spectral data with Sunpy. An alternate way of looking at this is that IRISpy will form the instrument specific portion of sunraster and thus provide the gateway for pulling IRIS data into that package. However, the line between packages hasn’t been really drawn formally: The feeling right now is that anything that is instrument/satellite/mission independent should be in sunraster, but these things cannot be separated that easily, and these discussions are likely to continue.

IRISpy therefore remains in an unreleased format, and is under heavy development, and as such, great care should be taken when using these codes. However, we expect rapid development and the addition of new features on a continuous basis. Our recommendation is to clone IRISpy and import sunraster and follow developments, they will be reported on this page.

## 4.1. Installation¶

A full installation guide for IRISpy can be found at the following link. However a quick install can be done as follows.

1. Make sure that you have a version of both the sunraster, sunpy and ndcube packages installed in your Python build. If not, these can be installed using pip or conda.

2. It is then necessary to clone the current IRISpy development version from gitlab, and save it in a convenient directory, say LMSAL_HUB/iris_hub:

cd LMSAL_HUB/iris_hub

git clone https://gitlab.com/LMSAL_HUB/iris_hub/irispy-lmsal.git

1. Now we install the package:

>>> cd irispy-lmsal
>>> python setup.py install


4. we can then check that the install has worked by importing irispy into an open Python session:

>>>import irispy


## 4.2. Basic functions¶

### 4.2.1. NDCubes¶

In order to allow easier use of multidimensional data sets (which are common in astronomy), the SunPy-affiliated package NDCube was developed. This package combines N-dimensional data with their corresponding word coordinate system (WCS) information in an NDCube or NDSequence object. This allows the data be sliced, visualized and to undergo wcs transforms to alternative coordinate systems.

To load IRIS raster data into your Python session we make use of the function read_iris_spectrograph_level2_fits. This will produce a NDCubeSequence that contains all of the raster data for the list of IRIS fits files that it takes as an input. This function has several optional inputs to give the user control over how the fits data are read into the Python session. The following example shows the basic usage of the function, with default parameters.

>>> import irispy.io as io

>>> spec = io.read_iris_spectrograph_level2_fits('path_to_iris_raster_fits_files')


We can see what is contained within this new object spec:

>>> spec

NDCollection
------------
Cube keys: ('C II 1336', 'O I 1356', 'Si IV 1394', 'Si IV 1403', '2832', '2814', 'Mg II k 2796')
Number of Cubes: 7
Aligned dimensions: [<Quantity 1. pix> <Quantity 320. pix> <Quantity 548. pix>]
Aligned world physical axis types: ('meta.obs.sequence', 'custom:pos.helioprojective.lon', 'custom:pos.helioprojective.lat')


We see that this NDcube object contains the data of the observation and its coordinates, which spectral windows are contained in the observation along with their dimensions ( in the form [time, x, y, wavelength]). Looking closer into one of the cube keys allows us to see how the data for a single spectral line is packaged:

>>> spec['C II 1336']

RasterSequence
--------------
Time Range: ('2018-01-02T15:31:55.870', '2018-01-02T16:20:52.810')
Pixel Dimensions: (<Quantity 1. pix>, <Quantity 320. pix>, <Quantity 548. pix>, <Quantity 335. pix>)
Longitude range: [-0.10703502 -0.07552185] deg
Latitude range: [0.05417307 0.10507361] deg
Spectral range: [1.33176765e-07 1.34043829e-07] m
Data unit: DN_IRIS_FUV


We can get further information that was contained in the fits header using the following:

>>> spec.meta

{'TELESCOP': 'IRIS',
'INSTRUME': 'SPEC',
'DATA_LEV': 2.0,
'OBSID': '3610108077',
'OBS_DESC': 'Very large dense 320-step raster 105.3x175 320s   Deep x 8 Spatial x',
'STARTOBS': <Time object: scale='utc' format='isot' value=2018-01-02T15:31:55.700>,
'ENDOBS': <Time object: scale='utc' format='isot' value=2018-01-02T16:21:01.960>,
'SAT_ROT': <Quantity 0.00023047 deg>,
'AECNOBS': 0,
'FOVX': <Quantity 112.35192871 arcsec>,
'FOVY': <Quantity 182.32 arcsec>,
'SUMSPTRN': 2,
'SUMSPTRF': 2,
'SUMSPAT': 2,
'NEXPOBS': 960,
'NRASTERP': 320,
'KEYWDDOC': 'http://www.lmsal.com/iris_science/irisfitskeywords.pdf'}


If we want to look at a single spectral line, we can access it from the NDCubeSequence through the data attribute e.g.:

>>> spec['Si IV 1403'].data

SpectrogramCube
---------------
Time Period: (<Time object: scale='utc' format='isot' value=2018-01-02T15:31:55.870>, <Time object: scale='utc' format='isot' value=2018-01-02T16:20:52.810>)
Pixel dimensions (Slit steps, Slit height, Spectral): [320. 548. 338.] pix
Longitude range: [-0.10703502 -0.07552185] deg
Latitude range: [0.05417307 0.10507361] deg
Spectral range: [1.39812215e-07 1.40669543e-07] m
Data unit: DN_IRIS_FUV]


If we wish to access the data for the chosen spectral line, we can access using:

>>> import numpy as np

>>> data=np.vstack([cube.data for cube in spec['Si IV 1403'].data])


This will produce a list of arrays corresponding to each loaded raster. Each array in the list will have dimensions [X, Y, wavelength], e.g:

>>> data.shape
(320, 548, 338)


We can similarly load IRIS SJI data into our Python session using IRISpy. This is done through the function read_iris_sji_level2_fits. As was the case with the spectrograph data above, this function has several optional inputs to allow the user to control the memory usage, however we will only focus on the basic use of this function with default parameters.

>>> from irispy.io import sji

>>> sj_im = sji.read_iris_sji_level2_fits('path_to_iris_sji_fits_file')


We can see what is contained within the new object sj_im:

>>> sj_im
IRISMapCube
-----------
Observatory:           IRIS
Instrument:                    SJI
Bandpass:                      1400.0
Obs. Start:                    2018-01-02T15:31:55.700
Obs. End:                      2018-01-02T16:21:01.960
Instance Start:                2018-01-02T15:32:23.340
Instance End:          2018-01-02T16:20:52.740
Roll:                  0.00022743 deg
Total Frames in Obs.:  80
IRIS Obs. id:          3610108077
IRIS Obs. Description:         Very large dense 320-step raster 105.3x175 320s   Deep x 8 Spatial x
Cube dimensions:               [ 80. 548. 845.] pix
Axis Types:                    ('time', 'custom:pos.helioprojective.lat', 'custom:pos.helioprojective.lon')


Further meta data can be viewed by using:

>>> sj_im.meta
{'TELESCOP': 'IRIS',
'INSTRUME': 'SJI',
'DATA_LEV': 2.0,
'TWAVE1': 1400.0,
'OBSID': '3610108077',
'STARTOBS': <Time object: scale='utc' format='isot' value=2018-01-02T15:31:55.700>,
'ENDOBS': <Time object: scale='utc' format='isot' value=2018-01-02T16:21:01.960>,
'SAT_ROT': <Quantity 0.00022743 deg>,
'NBFRAMES': 80,
'OBS_DESC': 'Very large dense 320-step raster 105.3x175 320s   Deep x 8 Spatial x',
'FOVX': <Quantity 281.132 arcsec>,
'FOVY': <Quantity 182.32 arcsec>,
'XCEN': <Quantity -329.321 arcsec>,
'YCEN': <Quantity 286.652 arcsec>}


To access the data and see its dimensions we can do the following:

>>> sj_im.data.shape
(80, 548, 845)


We see that the data has the form [time, x , y]. The data can be plotted as follows:

>>> import matplotlib.pyplot as plt

>>> plt.imshow(sj_im.data[1,:,:])


Though to view SJ images, or for that matter spectra, we also recommend the reader check out the other methods presented in this manual.