siaf

Module to handle Science Instrument Aperture Files (SIAF).

The siaf module defined classes and functions to support working with SIAF files. The main class is ApertureCollection, and the Siaf class inherits from it. The class methods support basic operations and plotting.

ApertureCollection is essentially a container for a set of pysiaf

aperture objects.

Authors

• Johannes Sahlmann

References

Some of the Siaf class methods were adapted from the jwxml package (https://github.com/mperrin/jwxml).

class pysiaf.siaf.ApertureCollection(aperture_dict=None)

Structure class for an aperture collection, e.g. read from a SIAF file.

Initialize and generate table of contents.

generate_toc(attributes=None)

Generate a table of contents.

list_apertures(instrument=None, shape=None)

Print a list of apertures to screen.

class pysiaf.siaf.Siaf(instrument, filename=None, basepath=None, AperNames=None)

Science Instrument Aperture File class.

This is a class interface to SIAF information, e.g. stored in an XML file in the PRD. It enables apertures retrieval by name, plotting, and other functionality. See the Aperture class for the detailed implementation of the transformations.

Adapted from https://github.com/mperrin/jwxml

The HST case is treated here as an instrument, because it’s single SIAF contains all apertures of all HST-instruments

Attributes:

observatorystr

Name of observatory

Examples

fgs_siaf = SIAF(‘FGS’) fgs_siaf.apernames # returns a list of aperture names ap = fgs_siaf[‘FGS1_FULL’] # returns an aperture object ap.plot(frame=’Tel’) # plot one aperture fgs_siaf.plot() # plot all apertures in this file

Read a SIAF from disk.

Parameters:

instrumentstring

one of ‘NIRCam’, ‘NIRSpec’, ‘NIRISS’, ‘MIRI’, ‘FGS’; case-insensitive.

basepathstring

Directory to look in for SIAF files

filenamestring, optional

Alternative method to specify a specific SIAF XML file.

property apernames

List of aperture names defined in this SIAF.

delete_aperture(aperture_name)

Remove an aperture from the Siaf.

Parameters:

aperture_name – str or list

Returns:

find_apernames(substring)

Return aperture names containing some substring. Simple utility function to search through names of available apertures.

plot(frame='tel', names=None, label=False, units=None, clear=True, show_frame_origin=None, mark_ref=False, subarrays=True, ax=None, **kwargs)

Plot all apertures in this SIAF.

Parameters:

nameslist of strings

A subset of aperture names, if you wish to plot only a subset

subarraysbool

Plot all the minor subarrays if True, else just plot the “main” apertures

labelbool

Add text labels stating aperture names

unitsstr

one of ‘arcsec’, ‘arcmin’, ‘deg’

clearbool

Clear plot before plotting (set to false to overplot)

show_frame_originstr or list

Plot frame origin (goes to plot_frame_origin()): None, ‘all’, ‘det’, ‘sci’, ‘raw’, ‘idl’, or a list of these.

mark_refbool

Add markers for the reference (V2Ref, V3Ref) point in each apertyre

framestr

Which coordinate system to plot in: ‘tel’, ‘idl’, ‘sci’, ‘det’

axmatplotlib.Axes

Desired destination axes to plot into (If None, current axes are inferred from pyplot.)

Other matplotlib standard parameters may be passed in via **kwargs

to adjust the style of the displayed lines.

plot_detector_channels(frame=None, ax=None)

Mark on the plot the various detector readout channels.

These are depicted as alternating light/dark bars to show the regions read out by each of the output amps.

Parameters:

framestr

Which coordinate system to plot in: ‘Tel’, ‘Idl’, ‘Sci’, ‘Det’ Optional if you have already called plot() to specify a coordinate frame.

axmatplotlib.Axes

Desired destination axes to plot into (If None, current axes are inferred from pyplot.)

plot_frame_origin(frame=None, which='sci', units='arcsec', ax=None)

Mark on the plot the frame’s origin in Det and Sci coordinates.

Parameters:

framestr

Which coordinate system to plot in: ‘tel’, ‘idl’, ‘sci’, ‘det’ Optional if you have already called plot() to specify a coordinate frame.

whichstr or list

Which origin to plot: ‘all’, ‘det’, ‘sci’, ‘raw’, ‘idl’, or a list

unitsstr

one of ‘arcsec’, ‘arcmin’, ‘deg’

axmatplotlib.Axes

Desired destination axes to plot into (If None, current axes are inferred from pyplot.)

pysiaf.siaf.get_jwst_apertures(apertures_dict, include_oss_apertures=False, exact_pattern_match=False)

Return ApertureCollection that corresponds to constraints specified in apertures_dict.

Parameters:

apertures_dictdict

Dictionary of apertures

include_oss_aperturesbool

Whether to include OSS apertures

exact_pattern_matchbool

Returns:

ApertureCollectionApertureCollection object

Collection of apertures corresponding to selection criteria

Examples

apertures_dict = {‘instrument’:[‘FGS’]} apertures_dict[‘pattern’] = [‘FULL’]*len(apertures_dict[‘instrument’]) fgs_apertures_all = get_jwst_apertures(apertures_dict)

pysiaf.siaf.get_main_apertures(mission='jwst', frame='tel', **kwargs)

Return lists of main apertures, sorted into apertures for imaging, spectroscopy, and coronagraphy

The “main” apertures” per each observatory and instrument are defined in hard-coded lists within this function. In general this includes the major instrument imaging detectors, spectrograph slits, coronagraph apertures, etc.

This is used in plot_main_apertures, but is provided here as a separate function since these lists of main apertures can be useful in other contexts as well.

Returns 3 lists of pysiaf Aperture instances

Parameters:

missionstr

observatory name, one of ‘JWST’, ‘HST’, or ‘Roman’. Case insensitive.

pysiaf.siaf.plot_all_apertures(subarrays=True, showorigin=True, detector_channels=True, **kwargs)

Plot all apertures.

pysiaf.siaf.plot_main_apertures(label=False, darkbg=False, detector_channels=False, frame='tel', attitude_matrix=None, mission='jwst', **kwargs)

Plot main/master apertures

Note, distinct colors are used to indicate imaging, spectroscopy, and coronagraphic apertures. Colors also distinguish between apertures for different missions, for cases in which HST, JWST, and Roman focal planes might be plotted together.

Parameters:

framestring

Either ‘tel’ or ‘sky’. (It does not make sense to plot apertures from multiple instruments in any of the other frames)

attitude_matrix3x3 ndarray

Rotation matrix representing observatory attitude. Needed for sky frame plots.

missionstr

observatory name, one of ‘JWST’, ‘HST’, or ‘Roman’. Case insensitive.

pysiaf.siaf.plot_master_apertures(**kwargs)

Plot only master apertures contours.