Reading

irisreader.observation

class irisreader.observation(path, keep_null=False)

Presents an abstract representation of a whole observation. This class opens all the SJI and raster files associated to an observation (in a given directory, as is the structure of IRIS data), possibly combines multiple raster to a combined_raster structure and sets a few observation parameters.

Parameters

• path (string) – Path to the IRIS observation directory where the FITS files are stored.

• keep_null (boolean) – Controls whether images that are NULL (-200) everywhere are removed from the data cube. keep_null=True keeps NULL images and keep_null=False removes them.

Variables

• sji (sji_loader) – sji_loader instance that holds the sji attributes.

• raster (raster_loader) – raster_loader instance that holds the raster attributes.

• n_raster (integer) – Number of individual raster files in the selected observation.

• n_sji (integer) – Number of individual sji files in the selected observation.

• obsid (string) – Observation ID of the selected observation.

• desc (string) – Description of the selected observation.

• mode (string) – Observation mode of the selected observation (‘sit-and-stare’ or ‘raster’).

• start_date (string) – Start date of the selected observation.

• end_date (string) – End date of the selected observation.

• full_obsid (string) – Full OBSID uniquely specifying the observation, in the format YYYYmmdd_HHMMSS_OBSID

• goes (irisreader.coalignment.goes) – Instance of irisreader.coalignment.goes containing GOES X-ray data for this observation

• hek (irisreader.coalignment.hek) – Instance of irisreader.coalignment.hek containing HEK event data for this observation

close()

Closes all associated FITS files.

irisreader.obs_iterator

class irisreader.obs_iterator(path='', keep_null=False, read_v4=False, display_errors=True, error_log=None)

This class implements a generator class to iterate over a set of observations that is given as a path. In case of a reading error, the iterator automatically jumps to the next valid observation. As this iterator is not a regular list, it can only be iterated once.

Parameters

• path (string) – Path to the directory holding all the observations. This function assumes IRIS data structure where observations are stored in directories with the format <DATE>_<TIME>_<OBSID>.

• keep_null (boolean) – Controls whether images that are NULL (-200) everywhere are removed from the data cube. keep_null=True keeps NULL images and keep_null=False removes them.

• read_v4 (boolean) – Whether to read observations with an OBSID starting with 4 (obs table generation v4, mostly for tests and maintenance, see ITN 31).

• display_errors (boolean) – Whether to show errors that occured in opening individual observations or just to ignore them

• error_log (str) – Path to logfile for errors (will be appended, clear the file if necessary)

Variables

• path (string) – Path that has been passed as a parameter.

• directories (string) – List of valid IRIS data directories that have been found during the traversal.

irisreader.get_lines

irisreader.get_lines(file_object)

Returns the available lines in a raster or SJI file. Both filenames and open iris_data_cube objects are accepted.

Parameters

file_object (string or iris_data_cube) – The function accepts either an open iris_data_cube or the path to the FITS file to assess the lines in the observation.

Returns

Data frame with info about available lines.

Return type

pandas.DataFrame

irisreader.has_line

irisreader.has_line(file_object, description)

Returns True if the supplied raster or SJI contains the line in question and False if not. If the line is ambiguously specified, an error will be raised. Both filenames and open iris_data_cube objects are accepted.

Parameters

• file_object (string or iris_data_cube) – The function accepts either an open iris_data_cube or the path to the FITS file to assess the lines in the observation.

• description (string) – Any abbreviation of the line description to look for.

Returns

True / False

Return type

bool

irisreader.sji_cube

class irisreader.sji_cube(file, keep_null=False, force_valid_steps=False)

This class implements an abstraction of an IRIS SJI FITS file.

Parameters

• file (string) – Path to the IRIS SJI FITS file.

• keep_null (boolean) – Controls whether images that are NULL (-200) everywhere are removed from the data cube. keep_null=True keeps NULL images and keep_null=False removes them.

Variables

• type (str) – Observation type: ‘sji’ or ‘raster’.

• obsid (str) – Observation ID of the selected observation.

• desc (str) – Description of the selected observation.

• start_date (str) – Start date of the selected observation.

• end_date (str) – Endt date of the selected observation.

• mode (str) – Observation mode of the selected observation (‘sit-and-stare’ or ‘raster’).

• line_info (str) – Description of the selected line.

• n_steps (int) – Number of time steps in the data cube.

• n_files (int) – Number of FITS files (always =1 for SJI)

• primary_headers (dict) – Dictionary with primary headers of the FITS file (lazy loaded).

• time_specific_headers (dict) – List of dictionaries with time-specific headers of the selected line (lazy loaded).

• headers (dict) – List of combined primary and time-specific headers (lazy loaded).

animate(raster_pos=None, index_start=None, index_stop=None, interval_ms=50, gamma=0.4, figsize=(7, 7), cutoff_percentile=99.9, save_path=None)

Creates an animation from the individual images of a data cube. This function can be pretty slow and take 1-2 minutes. Faster alternatives than matplotlib will be researched in the future.

data_cubeiris_data_cube

instance of sji_cube or raster_cube

raster_posint

If not None, only display images at raster postion raster_pos

interval_msint

number of milliseconds between two frames

gammafloat

gamma correction for plotting: number between 0 (infinitely gamma correction) and 1 (no gamma correction)

figsizetuple

figure size: (width,height)

cutoff_percentilefloat

Often the maximum pixels shine out everything else, even after gamma correction. In order to reduce this effect, the percentile at which to cut the intensity off can be specified with cutoff_percentile in a range between 0 and 100.

save_pathstr

path to file where animation output will be written to (use .mp4 extension)

Returns

HTML object with the animation

Return type

IPython.HTML

close()

Closes the FITS file(s)

coords2pix(step, wl_solar_coordinates, round_pixels=True)

Returns pixel coordinates for the list of given wavelength in angstrom / solar y coordinates.

Parameters

• step (int) – The time step in the SJI to get the pixel coordinates for.

• wl_solar_coordinates (np.array) – Numpy array with shape (coordinate_pairs,2) that contains wavelength in angstrom / solar y coordinates in the form [lat/lon] in units of arcseconds

Returns

Numpy array with shape (coordinate_pairs,2) containing pixel coordinates

Return type

float

crop(remove_bad=True, check_coverage=True)

Crops the images in the data cube.

Parameters

• remove_bad (boolean) – Whether to remove corrupt images.

• check_coverage (boolean) – Whether to check the coverage of the cropped image. It can happen that there are patches of negative values in images, either due to loss of data during transmission (typically a band or a large rectangular patch of negative data) or due to overall low data counts (missing data is no data). image_cropper labels an image as corrupt if >5% of its pixels are still negative after cropping. This might be problematic for lines with low data counts (and therefore many missing pixels) and the user is advised to disable the coverage check for such lines. A method that is able to distinguish missing data arising from transmission errors from missing data due to low data counts could be helpful here.

cut(i_start, i_stop)

Cuts out only a part of the observation.

Parameters

• i_start (int) – Index where to start the cut

• i_stop (int) – Index where to stop the cut (not including this index)

get_axis_coordinates(step)

Returns coordinates for the image at the given time step.

Parameters

step (int) – The time step in the SJI to get the coordinates for.

Returns

List [coordinates along x axis, coordinates along y axis]

Return type

float

get_exptimes()

Returns a list of exposure times throughout the observation.

Returns

List of exposure times.

Return type

list

get_global_raster_step(raster_pos, raster_step)

Returns the overall step for a pair (raster_pos, raster_step). When looking at a single raster position, steps are counted as 0,1,2,3,.. etc. Sometimes it is necessary to convert this step into the actual image step of the whole raster.

Example: three raster positions: 0, 1, 2 with three exposures each

raster image step: 0, 1, 2, 3, 4, 5, 6, 7, 8 raster position: 0, 1, 2, 0, 1, 2, 0, 1, 2 raster step: 0, 0, 0, 1, 1, 1, 2, 2, 2

Parameters

• raster_pos (int) – raster position (between 0 and n_raster_pos)

• raster_step (int) – raster step (between 0 and the maximum raster step, can be determined with get_raster_pos_steps( raster_pos ) )

Returns

global raster image step

Return type

int

get_goes_flux()

Interpolates GOES X-ray flux to time steps of the data cube.

Returns

List of X-ray fluxes

Return type

float

get_image_step(step, raster_pos=None, divide_by_exptime=False)

Returns the image at position step. This function uses the section routine of astropy to only return a slice of the image and avoid memory problems.

Parameters

• step (int) – Time step in the data cube

• raster_pos (int) – Raster position. If raster_pos is not None, get_image_step will return the image_step on the given raster position.

• divide_by_exptime (bool) – Whether to divide image by its exposure time or not. Dividing by exposure time will present a normalized image instead of the usual data numbers.

Returns

2D image at time step <step>. Format: [y,x].

Return type

numpy.ndarray

get_nsatpix(step)

Returns the number of saturated pixels in an image. According to iris_prep.pro, a pixel is saturated if it has a data number >= 1.6e4.

Parameters

step (int) – Time step in the data cube.

Returns

Number of saturated pixels at time step <step>.

Return type

int

get_raster_pos_data(raster_pos)

Returns a data cube only for the given raster position.

Parameters

raster_pos (int) – raster position (between 0 and n_raster_pos)

Returns

Data cube with dimensions [t,y,x/lambda]

Return type

np.array

get_raster_pos_headers(raster_pos)

Returns headers only for the given raster position.

Parameters

raster_pos (int) – raster position (between 0 and n_raster_pos)

Returns

List of header dictionaries for the given raster position

Return type

list

get_raster_pos_steps(raster_pos)

Returns total number of image steps for the given raster position.

Parameters

raster_pos (int) – raster position (between 0 and n_raster_pos)

Returns

Number of available image steps

Return type

int

get_slit_pos(step)

Returns position of the slit in pixels (takes into account cropping).

Parameters

step (int) – Time step in the data cube.

Returns

slit_position – Slit position in pixels

Return type

int

get_timestamps(raster_pos=None)

Converts DATE_OBS to milliseconds since 1970 with the aim to make timestamp comparisons easier.

Parameters

raster_pos (int) – raster position (between 0 and n_raster_pos)

Returns

List of millisecond timestamps.

Return type

float

pix2coords(step, pixel_coordinates)

Returns solar coordinates for the list of given pixel coordinates.

Caution: This function takes pixel coordinates in the form [x,y] while images come as [y,x]

Parameters

• step (int) – The time step in the SJI to get the solar coordinates for.

• pixel_coordinates (np.array) – Numpy array with shape (pixel_pairs,2) that contains pixel coordinates in the format [x,y]

Returns

Numpy array with shape (pixel_pairs,2) containing solar coordinates

Return type

float

plot(step, units='pixels', grid=False, gamma=None, cutoff_percentile=99.9, **kwargs)

Plots the slit-jaw image at time step <step>.

Parameters

• step (int) – The time step in the SJI.

• units (str) – Tick units: ‘pixels’ for indices in the array or ‘coordinates’ for units in arcseconds on the sun.

• grid (bool) – Whether to draw a grid on the plot.

• gamma (float) – Gamma exponent for gamma correction that adjusts the plot scale. If gamma is None (default), gamma=1 is used for the photospheric SJI 2832 and gamma=0.4 otherwise.

• cutoff_percentile (float) – Often the maximum pixels shine out everything else, even after gamma correction. In order to reduce this effect, the percentile at which to cut the intensity off can be specified with cutoff_percentile in a range between 0 and 100.

uncrop()

Removes the cropping of the images in the data cube (but keeps the corrupt image steps removed).

irisreader.raster_cube

class irisreader.raster_cube(files, line='', keep_null=False, force_valid_steps=False)

This class implements an abstraction of an IRIS raster FITS file.

Parameters

• files (string) – Path or list of paths to the (sorted) IRIS FITS file(s).

• line (string) – Line to select: this can be any unique abbreviation of the line name (e.g. “Mg”). For non-unique abbreviations, an error is thrown.

• keep_null (boolean) – Controls whether images that are NULL (-200) everywhere are removed from the data cube. keep_null=True keeps NULL images and keep_null=False removes them.

Variables

• type (str) – Observation type: ‘sji’ or ‘raster’.

• obsid (str) – Observation ID of the selected observation.

• desc (str) – Description of the selected observation.

• start_date (str) – Start date of the selected observation.

• end_date (str) – Endt date of the selected observation.

• mode (str) – Observation mode of the selected observation (‘sit-and-stare’ or ‘raster’).

• line_info (str) – Description of the selected line.

• n_steps (int) – Number of time steps in the data cube.

• n_files (int) – Number of FITS files (abstracted to one)

• primary_headers (dict) – Dictionary with primary headers of the FITS file (lazy loaded).

• time_specific_headers (dict) – List of dictionaries with time-specific headers of the selected line (lazy loaded).

• headers (dict) – List of combined primary and time-specific headers (lazy loaded).

animate(raster_pos=None, index_start=None, index_stop=None, interval_ms=50, gamma=0.4, figsize=(7, 7), cutoff_percentile=99.9, save_path=None)

Creates an animation from the individual images of a data cube. This function can be pretty slow and take 1-2 minutes. Faster alternatives than matplotlib will be researched in the future.

data_cubeiris_data_cube

instance of sji_cube or raster_cube

raster_posint

If not None, only display images at raster postion raster_pos

interval_msint

number of milliseconds between two frames

gammafloat

gamma correction for plotting: number between 0 (infinitely gamma correction) and 1 (no gamma correction)

figsizetuple

figure size: (width,height)

cutoff_percentilefloat

Often the maximum pixels shine out everything else, even after gamma correction. In order to reduce this effect, the percentile at which to cut the intensity off can be specified with cutoff_percentile in a range between 0 and 100.

save_pathstr

path to file where animation output will be written to (use .mp4 extension)

Returns

HTML object with the animation

Return type

IPython.HTML

close()

Closes the FITS file(s)

coords2pix(step, wl_solar_coordinates, round_pixels=True)

Returns pixel coordinates for the list of given wavelength in angstrom / solar y coordinates.

Parameters

• step (int) – The time step in the SJI to get the pixel coordinates for.

• wl_solar_coordinates (np.array) – Numpy array with shape (coordinate_pairs,2) that contains wavelength in angstrom / solar y coordinates in the form [lat/lon] in units of arcseconds

Returns

Numpy array with shape (coordinate_pairs,2) containing pixel coordinates

Return type

float

crop(remove_bad=True, check_coverage=True)

Crops the images in the data cube.

Parameters

• remove_bad (boolean) – Whether to remove corrupt images.

• check_coverage (boolean) – Whether to check the coverage of the cropped image. It can happen that there are patches of negative values in images, either due to loss of data during transmission (typically a band or a large rectangular patch of negative data) or due to overall low data counts (missing data is no data). image_cropper labels an image as corrupt if >5% of its pixels are still negative after cropping. This might be problematic for lines with low data counts (and therefore many missing pixels) and the user is advised to disable the coverage check for such lines. A method that is able to distinguish missing data arising from transmission errors from missing data due to low data counts could be helpful here.

cut(i_start, i_stop)

Cuts out only a part of the observation.

Parameters

• i_start (int) – Index where to start the cut

• i_stop (int) – Index where to stop the cut (not including this index)

get_axis_coordinates(step)

Returns coordinates for the image at the given time step.

Parameters

step (int) – The time step in the SJI to get the coordinates for.

Returns

List [coordinates along x axis, coordinates along y axis]

Return type

float

get_exptimes()

Returns a list of exposure times throughout the observation.

Returns

List of exposure times.

Return type

list

get_global_raster_step(raster_pos, raster_step)

Returns the overall step for a pair (raster_pos, raster_step). When looking at a single raster position, steps are counted as 0,1,2,3,.. etc. Sometimes it is necessary to convert this step into the actual image step of the whole raster.

Example: three raster positions: 0, 1, 2 with three exposures each

raster image step: 0, 1, 2, 3, 4, 5, 6, 7, 8 raster position: 0, 1, 2, 0, 1, 2, 0, 1, 2 raster step: 0, 0, 0, 1, 1, 1, 2, 2, 2

Parameters

• raster_pos (int) – raster position (between 0 and n_raster_pos)

• raster_step (int) – raster step (between 0 and the maximum raster step, can be determined with get_raster_pos_steps( raster_pos ) )

Returns

global raster image step

Return type

int

get_goes_flux()

Interpolates GOES X-ray flux to time steps of the data cube.

Returns

List of X-ray fluxes

Return type

float

get_image_step(step, raster_pos=None, divide_by_exptime=False)

Returns the image at position step. This function uses the section routine of astropy to only return a slice of the image and avoid memory problems.

Parameters

• step (int) – Time step in the data cube.

• divide_by_exptime (bool) – Whether to divide image by its exposure time or not. Dividing by exposure time will present a normalized image instead of the usual data numbers.

• raster_pos (int) – Raster position. If raster_pos is not None, get_image_step will return the image_step on the given raster position.

Returns

2D image at time step <step>. Format: [y,wavelength].

Return type

numpy.ndarray

get_interpolated_image_step(step, lambda_min, lambda_max, n_breaks, raster_pos=None, divide_by_exptime=False)

Returns the image at position step. This function uses the section routine of astropy to only return a slice of the image and avoid memory problems.

Warning: This function by default divides by exposure time, as this is more suitable for automatic processing.

Parameters

• step (int) – Time step in the data cube.

• lambda_min (float) – Minimum wavelength of the interpolation region

• lambda_max (float) – Maximum wavelength of the interpolation region

• n_breaks (int) – Number of uniform breaks in the interpolation region

• divide_by_exptime (bool) – Whether to divide image by its exposure time or not. Dividing by exposure time will present a normalized image instead of the usual data numbers.

• raster_pos (int) – Raster position. If raster_pos is not None, get_image_step will return the image_step on the given raster position.

Returns

interpolated 2D image at time step <step>. Format: [y,x] (SJI), [y,wavelength] (raster).

Return type

numpy.ndarray

get_nsatpix(step)

Returns the number of saturated pixels in an image. According to iris_prep.pro, a pixel is saturated if it has a data number >= 1.6e4.

Parameters

step (int) – Time step in the data cube.

Returns

Number of saturated pixels at time step <step>.

Return type

int

get_raster_pos_data(raster_pos)

Returns a data cube only for the given raster position.

Parameters

raster_pos (int) – raster position (between 0 and n_raster_pos)

Returns

Data cube with dimensions [t,y,x/lambda]

Return type

np.array

get_raster_pos_headers(raster_pos)

Returns headers only for the given raster position.

Parameters

raster_pos (int) – raster position (between 0 and n_raster_pos)

Returns

List of header dictionaries for the given raster position

Return type

list

get_raster_pos_steps(raster_pos)

Returns total number of image steps for the given raster position.

Parameters

raster_pos (int) – raster position (between 0 and n_raster_pos)

Returns

Number of available image steps

Return type

int

get_timestamps(raster_pos=None)

Converts DATE_OBS to milliseconds since 1970 with the aim to make timestamp comparisons easier.

Parameters

raster_pos (int) – raster position (between 0 and n_raster_pos)

Returns

List of millisecond timestamps.

Return type

float

pix2coords(step, pixel_coordinates)

Returns solar coordinates for the list of given pixel coordinates.

Caution: This function takes pixel coordinates in the form [x,y] while images come as [y,x]

Parameters

• step (int) – The time step in the SJI to get the solar coordinates for.

• pixel_coordinates (np.array) – Numpy array with shape (pixel_pairs,2) that contains pixel coordinates in the format [x,y]

Returns

Numpy array with shape (pixel_pairs,2) containing solar coordinates

Return type

float

plot(step, y=None, units='pixels', gamma=None, cutoff_percentile=99.9, **kwargs)

Plots the raster image at time step <step>.

Parameters

• step (int) – The time step in the SJI.

• y (int) – A pixel position on the slit. If set, only values for this position will be plotted.

• units (str) – Tick units: ‘pixels’ for indices in the array or ‘coordinates’ for units in arcseconds on the sun.

• gamma (float) – Gamma exponent for gamma correction that adjusts the plot scale. If gamma is None (default), gamma=1 is used for the photospheric SJI 2832 and gamma=0.4 otherwise.

• cutoff_percentile (float) – Often the maximum pixels shine out everything else, even after gamma correction. In order to reduce this effect, the percentile at which to cut the intensity off can be specified with cutoff_percentile in a range between 0 and 100.

uncrop()

Removes the cropping of the images in the data cube (but keeps the corrupt image steps removed).

irisreader.get_obs_path

irisreader.get_obs_path(full_obsid, basedir)

Finds the full path for a given full OBSID (in the style of ‘20140910_003955_3860358888’).

Parameters

• full_obsid (str) – full OBSID of the observation as a string

• basedir (str) – base directory for search (where iris data lies in the structure year/month/day/observation)

Returns

obs_path – full path to observation

Return type

str