Imager

class gunagala.imager.Imager(optic, camera, filters, psf, sky, num_imagers=1, num_per_computer=1)

Bases: object

Class representing an astronomical imaging instrument.

Class representing a complete astronomical imaging system, including optics, optical filters and camera.

Also includes point spread function and sky background models. Optionally it can be used to represent an array of identical, co-aligned imager using the num_imagers parameter to specify the number of copies.

Parameters:

optic : gunagala.optic.Optic

Optical system model.

camera : gunagala.camera.Camera

Camera (image sensor) model.

filters : dict of gunagala.filter.Filter

Dictionary of optical filter models.

psf : gunagala.psf.PSF

Point spread function model.

sky : gunagala.sky.Sky

Sky background model.

num_imagers : int, optional

the number of identical, co-aligned imagers represented by this Imager. The default is 1.

num_per_computer : int, optional

number of cameras connected to each computer. Used in situations where multiple cameras must be readout sequentially so the effective readout time is equal to the readout time of a single camera multiplied by the num_per_computer. The default is 1.

Attributes:

optic : gunagala.optic.Optic

Same as parameters.

camera : gunagala.camera.Camera

Same as parameters.

filters : dict

Same as parameters.

psf : gunagala.psf.PSF

Same as parameters.

sky : gunagala.sky.Sky

Same as parameters.

num_imagers : int

Same as parameters.

num_per_computer : int

Same as parameters.

filter_names : list of str

List of filter names from filters.

pixel_scale : astropy.units.Quantity

Pixel scale in arcseconds/pixel units.

pixel_area : astropy.units.Quantity

Pixel area in arseconds^2/pixel units.

field_of_view : astropy.units.Quantity

Field of view (horizontal, vertical) in degrees.

wcs : astropy.wcs.WCS

Template world coordinate system (WCS) for sky coordinate/pixel coordinate mapping.

wavelengths : astropy.units.Quantity

List of wavelengths used for wavelength dependent attributes/calculations.

efficiencies : dict of astropy.units.Quantity

End to end efficiency as a function of wavelegth for each filter bandpass.

efficiency : dict of astropy.units.Quantity

Mean end to end efficiencies for each filter bandpass.

mean_wave : dict of astropy.units.Quantity

Mean wavelength for each filter bandpass.

pivot_wave : dict of astropy.units.Quantity

Pivot wavelength for each filter bandpass.

bandwidth : dict of astropy.units.Quantity

Bandwidths for each filter bandpass (STScI definition).

sky_rate : dict of astropy.units.Quantity

Detected electrons/s/pixel due to the sky background for each filter bandpass.

Methods Summary

ABmag_to_flux(mag, filter_name)	Converts brightness of the target to total flux, integrated over the filter band.
ABmag_to_rate(mag, filter_name)	Converts AB magnitudes to photo-electrons per second in the image sensor
SB_to_rate(mag, filter_name)	Converts surface brightness AB magnitudes (per arcsecond squared) to photo-electrons per pixel per second.
exp_time_sequence(filter_name[, …])	Calculates a sequence of sub exposures to use to span a given range of either point source brightness or exposure time.
extended_source_etc(surface_brightness, …)	Calculates the total exposure time required to reach a given signal to noise ratio for a given extended source surface brightness.
extended_source_limit(total_exp_time, …[, …])	Calculates the limiting extended source surface brightness for a given minimum signal to noise ratio and total exposure time.
extended_source_saturation_exp(…[, n_sigma])	Calculates the maximum (sub) exposure time that will definitely avoid saturation for an extended source of given surface brightness.
extended_source_saturation_mag(sub_exp_time, …)	Calculates the surface brightness of the brightest extended source that would definitely not saturate the image sensor in a given (sub) exposure time.
extended_source_signal_noise(…[, …])	Calculates the signal and noise for an extended source with given surface brightness.
extended_source_snr(surface_brightness, …)	Calculates the signal to noise ratio for an extended source with given surface brightness.
flux_to_ABmag(flux, filter_name)	Converts total flux of the target, integrated over the filter band, to magnitudes.
point_source_etc(brightness, filter_name, …)	Calculates the total exposure time required to reach a given signal to noise ratio for a given point source brightness.
point_source_limit(total_exp_time, …[, …])	Calculates the limiting point source surface brightness for a given minimum signal to noise ratio and total exposure time.
point_source_saturation_exp(brightness, …)	Calculates the maximum (sub) exposure time that will definitely avoid saturation for point source of given brightness
point_source_saturation_mag(sub_exp_time, …)	Calculates the magnitude of the brightest point source that would definitely not saturate the image sensor in a given (sub) exposure time.
point_source_signal_noise(brightness, …[, …])	Calculates the signal and noise for a point source of a given brightness, assuming PSF fitting photometry
point_source_snr(brightness, filter_name, …)	Calculates the signal to noise ratio for a point source of a given brightness, assuming PSF fitting photometry
rate_to_ABmag(rate, filter_name)	Converts photo-electrons per second in the image sensor to AB magnitudes
rate_to_SB(SB_rate, filter_name)	Converts photo-electrons per pixel per second to surface brightness AB magnitudes (per arcsecond squared)
snr_vs_ABmag(exp_times, filter_name[, …])	Calculates PSF fitting signal to noise ratio as a function of point source brightness for the combined data resulting from a given sequence of sub exposures.
total_elapsed_time(exp_list)	Calculates the total elapsed time required for a given a list of sub-exposure times.
total_exposure_time(total_elapsed_time, …)	Calculates total exposure time given a total elapsed time and sub-exposure time.

Methods Documentation

ABmag_to_flux(mag, filter_name)

Converts brightness of the target to total flux, integrated over the filter band.

Parameters:

mag : astropy.units.Quantity

Brightness of the target in AB magnitudes

filter_name : str

Name of the optical filter to use

Returns:

flux : astropy.units.Quantity

Corresponding total flux in Watts per square metre

Notes

The conversion between band averaged magnitudes and total flux depends somewhat on the spectrum of the source. For this calculation we assume \(F_\nu\) is constant.

ABmag_to_rate(mag, filter_name)

Converts AB magnitudes to photo-electrons per second in the image sensor

Parameters:

mag : astropy.units.Quantity

Source brightness in AB magnitudes

filter_name : str

Name of the optical filter to use

Returns:

rate : astropy.units.Quantity

Corresponding photo-electrons per second

SB_to_rate(mag, filter_name)

Converts surface brightness AB magnitudes (per arcsecond squared) to photo-electrons per pixel per second.

Parameters:

mag : astropy.units.Quantity

Source surface brightness in AB magnitudes

filter_name : str

Name of the optical filter to use

Returns:

rate : astropy.units.Quantity

Corresponding photo-electrons per pixel per second

Notes

At the time of writing astropy.units did not support the commonly used (but dimensionally nonsensical) expression of surface brightness in ‘magnitudes per arcsecond squared’. Consequently the mag surface brightness parameter should have a units of astropy.unit.ABmag, the ‘per arcsecond squared’ is implied.

exp_time_sequence(filter_name, bright_limit=None, shortest_exp_time=None, longest_exp_time=None, faint_limit=None, num_long_exp=None, exp_time_ratio=2.0, snr_target=5.0)

Calculates a sequence of sub exposures to use to span a given range of either point source brightness or exposure time.

If required the sequence will begin with an ‘HDR block’ of progressly increasing exposure time, followed by 1 or more exposures of equal length with the number of long exposures either specified directly or calculated from the faintest point source that the sequence is intended to detect.

Parameters:

filter_name : str

Name of the optical filter to use.

bright_limit : astropy.units.Quantity, optional

Brightness in ABmag of the brightest point sources that we want to avoid saturating on, will be used to calculate a suitable shortest exposure time. Optional, but one and only one of bright_limit and shortest_exp_time must be specified.

shortest_exp_time : astropy.units.Quantity, optional

Shortest sub exposure time to include in the sequence. Optional, but one and only one of bright_limit and shortest_exp_time must be specified.

longest_exp_time : astropy.units.Quantity

Longest sub exposure time to include in the sequence.

faint_limit : astropy.units.Quantity, optional

Brightness in ABmag of the faintest point sources that we want to be able to detect in the combined data from the sequence. Optional, but one and only one of faint_limit and num_long_exp must be specified.

num_long_exp : int, optional

Number of repeats of the longest sub exposure to include in the sequence. Optional, but one and only one of faint_limit and num_long_exp must be specified.

exp_time_ratio : float, optional

Ratio between successive sub exposure times in the HDR block, default 2.0

snr_target : float, optional

Signal to noise ratio threshold for detection at faint_limit, default 5.0

Returns:

exp_times : astropy.units.Quantity

Sequence of sub exposure times

extended_source_etc(surface_brightness, filter_name, snr_target, sub_exp_time, calc_type='per pixel', saturation_check=True, binning=1)

Calculates the total exposure time required to reach a given signal to noise ratio for a given extended source surface brightness.

Calculates the total exposure time required to reach a given signal to noise ratio for a given extended source surface brightness. Alternatively can calculate the required time for measurements of the sky background itself by setting the source surface brightness to None.

Parameters:

surface_brightness : astropy.units.Quantity or None

Surface brightness per arcsecond^2 of the source in ABmag units, or an equivalent count rate in photo-electrons per second per pixel. Set to None or False to calculate the required exposure time for measurements of the sky background.

filter_name : str

Name of the optical filter to use

snr_target : astropy.units.Quantity

The desired signal to noise ratio, dimensionless unscaled units

sub_exp_time : astropy.units.Quantity

length of individual sub-exposures

calc_type : {‘per pixel’, ‘per arcsecond squared’}

Calculation type, either signal to noise ratio per pixel or signal to noise ratio per arcsecond^2. Default is ‘per pixel’

saturation_check : bool, optional

If True will set the exposure time to zero where the electrons per pixel in a single sub-exposure exceed the saturation level. Default is True.

binning : int, optional

Pixel binning factor. Cannot be used with calculation type ‘per arcsecond squared’, will raise ValueError if you try.

Returns:

total_exp_time : astropy.units.Quantity

Total exposure time required to reach a signal to noise ratio of at least snr_target, rounded up to an integer multiple of sub_exp_time.

extended_source_limit(total_exp_time, filter_name, snr_target, sub_exp_time, calc_type='per pixel', binning=1, enable_read_noise=True, enable_sky_noise=True, enable_dark_noise=True)

Calculates the limiting extended source surface brightness for a given minimum signal to noise ratio and total exposure time.

Parameters:

total_exp_time : astropy.units.Quantity

Total length of all sub-exposures. If necessary will be rounded up to an integer multiple of sub_exp_time

filter_name : str

Name of the optical filter to use

snr_target : astropy.units.Quantity

The desired signal to noise ratio, dimensionless unscaled units

sub_exp_time : astropy.units.Quantity

length of individual sub-exposures

calc_type : {‘per pixel’, ‘per arcsecond squared’}

Calculation type, either signal to noise ratio per pixel or signal to noise ratio per arcsecond^2. Default is ‘per pixel’

binning : int, optional

Pixel binning factor. Cannot be used with calculation type ‘per arcsecond squared’, will raise ValueError if you try.

enable_read_noise : bool, optional

If False calculates limit as if read noise were zero, default True

enable_sky_noise : bool, optional

If False calculates limit as if sky background were zero, default True

enable_dark_noise : bool, optional

If False calculates limits as if dark current were zero, default True

Returns:

surface_brightness : astropy.units.Quantity

Limiting source surface brightness per arcsecond squared, in AB mag units.

extended_source_saturation_exp(surface_brightness, filter_name, n_sigma=3.0)

Calculates the maximum (sub) exposure time that will definitely avoid saturation for an extended source of given surface brightness.

Parameters:

surface_brightness : astropy.units.Quantity

Surface brightness per arcsecond^2 of the source in ABmag units, or an equivalent count rate in photo-electrons per second per pixel

filter_name : str

Name of the optical filter to use

n_sigma : float, optional

Safety margin to leave between the maximum expected electrons per pixel and the nominalsaturation level, in multiples of the noise, default 3.0

Returns:

sub_exp_time : astropy.units.Quantity

Maximum length of (sub) exposure that will definitely avoid saturation

extended_source_saturation_mag(sub_exp_time, filter_name, n_sigma=3.0)

Calculates the surface brightness of the brightest extended source that would definitely not saturate the image sensor in a given (sub) exposure time.

Parameters:

sub_exp_time : astropy.units.Quantity

Length of the (sub) exposure.

filter_name : str

Name of the optical filter to use.

n_sigma : float, optional

Safety margin to leave between the maximum expected electrons per pixel and the nominal saturation level, in multiples of the noise, default 3.0

Returns:

surface_brightness : astropy.units.Quantity

Surface brightness per arcsecond^2 of the brightest extended source that will definitely not saturate, in AB magnitudes.

extended_source_signal_noise(surface_brightness, filter_name, total_exp_time, sub_exp_time, calc_type='per pixel', saturation_check=True, binning=1)

Calculates the signal and noise for an extended source with given surface brightness.

Calculates the signal and noise for an extended source with given surface brightness. Alternatively can calculate the signal and noise for measurements of the sky background itself by setting the source surface brightness to None.

Parameters:

surface_brightness : astropy.units.Quantity or callable or None

Surface brightness per arcsecond^2 of the source in ABmag units, or an equivalent count rate in photo-electrons per second per pixel, or a callable object that return surface brightness in spectral flux density units as a function of wavelength. Set to None or False to calculate the signal and noise for the sky background.

filter_name : str

Name of the optical filter to use

total_exp_time : astropy.units.Quantity

Total length of all sub-exposures. If necessary will be rounded up to an integer multiple of sub_exp_time

sub_exp_time : astropy.units.Quantity

Length of individual sub-exposures

calc_type : {‘per pixel’, ‘per arcsecond squared’}

Calculation type, either signal & noise per pixel or signal & noise per arcsecond^2. Default is ‘per pixel’

saturation_check : bool, optional

If True will set both signal and noise to zero where the electrons per pixel in a single sub-exposure exceed the saturation level. Default is True.

binning : int, optional

Pixel binning factor. Cannot be used with calculation type ‘per arcsecond squared’, will raise ValueError if you try.

Returns:

signal : astropy.units.Quantity

Total signal, units determined by calculation type.

noise: astropy.units.Quantity

Total noise, units determined by calculaton type.

extended_source_snr(surface_brightness, filter_name, total_exp_time, sub_exp_time, calc_type='per pixel', saturation_check=True, binning=1)

Calculates the signal to noise ratio for an extended source with given surface brightness.

Calculates the signal to noise ratio for an extended source with given surface brightness. Alternatively can calculate the signal to noise for measurements of the sky background itself by setting the source surface brightness to None.

Parameters:

surface_brightness : astropy.units.Quantity or callable or None

Surface brightness per arcsecond^2 of the source in ABmag units, or an equivalent count rate in photo-electrons per second per pixel, or a callable object that return surface brightness in spectral flux density units as a function of wavelength. Set to None or False to calculate the signal to noise ratio for the sky background.

filter_name : str

Name of the optical filter to use

total_exp_time : astropy.units.Quantity

Total length of all sub-exposures. If necessary will be rounded up to an integer multiple of sub_exp_time

sub_exp_time : astropy.units.Quantity

Length of individual sub-exposures

calc_type : {‘per pixel’, ‘per arcsecond squared’}

Calculation type, either signal to noise ratio per pixel or signal to noise ratio per arcsecond^2. Default is ‘per pixel’

saturation_check : bool, optional

If True will set the signal to noise ratio to zero where the electrons per pixel in a single sub-exposure exceed the saturation level. Default is True.

binning : int, optional

Pixel binning factor. Cannot be used with calculation type ‘per arcsecond squared’, will raise ValueError if you try.

Returns:

snr : astropy.units.Quantity

signal to noise ratio, dimensionless unscaled units

flux_to_ABmag(flux, filter_name)

Converts total flux of the target, integrated over the filter band, to magnitudes.

Parameters:

flux : astropy.units.Quantity

Total flux in Watts per square metre

filter_name : str

Name of the optical filter to use

Returns:

mag : astropy.units.Quantity

Corresponding brightness of the target in AB magnitudes

Notes

The conversion between band averaged magnitudes and total flux depends somewhat on the spectrum of the source. For this calculation we assume \(F_\nu\) is constant.

point_source_etc(brightness, filter_name, snr_target, sub_exp_time, saturation_check=True)

Calculates the total exposure time required to reach a given signal to noise ratio for a given point source brightness.

Parameters:

brightness : astropy.units.Quantity

Brightness of the source in ABmag units, or an equivalent count rate in photo-electrons per second.

filter_name : str

Name of the optical filter to use

snr_target : astropy.units.Quantity

The desired signal to noise ratio, dimensionless unscaled units

sub_exp_time : astropy.units.Quantity

length of individual sub-exposures

saturation_check : bool, optional

If True will set the exposure time to zero where the electrons per pixel in a single sub-exposure exceed the saturation level. Default is True.

Returns:

total_exp_time : astropy.units.Quantity

Total exposure time required to reach a signal to noise ratio of at least snr_target, rounded up to an integer multiple of sub_exp_time.

point_source_limit(total_exp_time, filter_name, snr_target, sub_exp_time, enable_read_noise=True, enable_sky_noise=True, enable_dark_noise=True)

Calculates the limiting point source surface brightness for a given minimum signal to noise ratio and total exposure time.

Parameters:

total_exp_time : astropy.units.Quantity

Total length of all sub-exposures. If necessary will be rounded up to an integer multiple of sub_exp_time

filter_name : str

Name of the optical filter to use

snr_target : astropy.units.Quantity

The desired signal to noise ratio, dimensionless unscaled units

sub_exp_time : astropy.units.Quantity

length of individual sub-exposures

calc_type : {‘per pixel’, ‘per arcsecond squared’}

Calculation type, either signal to noise ratio per pixel or signal to noise ratio per arcsecond^2. Default is ‘per pixel’

enable_read_noise : bool, optional

If False calculates limit as if read noise were zero, default True

enable_sky_noise : bool, optional

If False calculates limit as if sky background were zero, default True

enable_dark_noise : bool, optional

If False calculates limits as if dark current were zero, default True

Returns:

brightness : astropy.units.Quantity

Limiting point source brightness, in AB mag units.

point_source_saturation_exp(brightness, filter_name, n_sigma=3.0)

Calculates the maximum (sub) exposure time that will definitely avoid saturation for point source of given brightness

Parameters:

brightness : astropy.units.Quantity

Brightness of the source in ABmag units, or an equivalent count rate in photo-electrons per second.

filter_name : str

Name of the optical filter to use

n_sigma : float, optional

Safety margin to leave between the maximum expected electrons per pixel and the nominalsaturation level, in multiples of the noise, default 3.0

Returns:

sub_exp_time : astropy.units.Quantity

Maximum length of (sub) exposure that will definitely avoid saturation

point_source_saturation_mag(sub_exp_time, filter_name, n_sigma=3.0)

Calculates the magnitude of the brightest point source that would definitely not saturate the image sensor in a given (sub) exposure time.

Parameters:

sub_exp_time : astropy.units.Quantity

Length of the (sub) exposure.

filter_name : str

Name of the optical filter to use.

n_sigma : float, optional

Safety margin to leave between the maximum expected electrons per pixel and the nominalsaturation level, in multiples of the noise, default 3.0

Returns:

brighness : astropy.units.Quantity

AB magnitude of the brightest point source that will definitely not saturate.

point_source_signal_noise(brightness, filter_name, total_exp_time, sub_exp_time, saturation_check=True)

Calculates the signal and noise for a point source of a given brightness, assuming PSF fitting photometry

The returned signal and noise values are the weighted sum over the pixels in the source image, where the weights are the normalised pixel values of the PSF model being fit to the data.

Parameters:

brightness : astropy.units.Quantity

Brightness of the source in ABmag units, or an equivalent count rate in photo-electrons per second.

filter_name : str

Name of the optical filter to use

total_exp_time : astropy.units.Quantity

Total length of all sub-exposures. If necessary will be rounded up to an integer multiple of sub_exp_time

sub_exp_time : astropy.units.Quantity

Length of individual sub-exposures

calc_type : {‘per pixel’, ‘per arcsecond squared’}

Calculation type, either signal & noise per pixel or signal & noise per arcsecond^2. Default is ‘per pixel’

saturation_check : bool, optional

If True will set both signal and noise to zero where the electrons per pixel in a single sub-exposure exceed the saturation level. Default is True.

Returns:

signal : astropy.units.Quantity

Effective total signal in units of electrons

noise: astropy.units.Quantity

Effective total noise in units of electrons

Notes

The PSF fitting signal to noise calculations follow the example of http://www.stsci.edu/itt/review/ihb_cy14.WFPC2/ch6_exposuretime6.html

The values will depend on the position of the centre of the PSF relative to the pixel grid, this calculation assumes the worst case of PSF centres on a pixel corner. Conversely it optimistically assumes that the PSF model exactly matches the PSF of the data.

point_source_snr(brightness, filter_name, total_exp_time, sub_exp_time, saturation_check=True)

Calculates the signal to noise ratio for a point source of a given brightness, assuming PSF fitting photometry

The returned signal to noise ratio refers to the weighted sum over the pixels in the source image, where the weights are the normalised pixel values of the PSF model being fit to the data.

Parameters:

brightness : astropy.units.Quantity

Brightness of the source in ABmag units, or an equivalent count rate in photo-electrons per second.

filter_name : str

Name of the optical filter to use

total_exp_time : astropy.units.Quantity

Total length of all sub-exposures. If necessary will be rounded up to an integer multiple of sub_exp_time

sub_exp_time : astropy.units.Quantity

Length of individual sub-exposures

calc_type : {‘per pixel’, ‘per arcsecond squared’}

Calculation type, either signal & noise per pixel or signal & noise per arcsecond^2. Default is ‘per pixel’

saturation_check : bool, optional

If True will set both signal and noise to zero where the electrons per pixel in a single sub-exposure exceed the saturation level. Default is True.

Returns:

snr : astropy.units.Quantity

signal to noise ratio dimensionless unscaled units

rate_to_ABmag(rate, filter_name)

Converts photo-electrons per second in the image sensor to AB magnitudes

Parameters:

rate : astropy.units.Quantity

Photo-electrons per second

filter_name : str

Name of the optical filter to use

Returns:

mag : astropy.units.Quantity

Corresponding source brightness in AB magnitudes

rate_to_SB(SB_rate, filter_name)

Converts photo-electrons per pixel per second to surface brightness AB magnitudes (per arcsecond squared)

Parameters:

SB_rate : astropy.units.Quantity

Photo-electrons per pixel per second

filter_name : str

Name of the optical filter to use

Returns:

mag : astropy.units.Quantity

Corresponding source surface brightness in AB magnitudes

Notes

At the time of writing astropy.units did not support the commonly used (but dimensionally nonsensical) expression of surface brightness in ‘magnitudes per arcsecond squared’. Consequently the mag surface brightness return value has units of astropy.unit.ABmag, the ‘per arcsecond squared’ is implied.

snr_vs_ABmag(exp_times, filter_name, magnitude_interval=<Magnitude 0.02 mag(AB)>, snr_target=1.0, plot=None)

Calculates PSF fitting signal to noise ratio as a function of point source brightness for the combined data resulting from a given sequence of sub exposures.

Optionally generates a plot of the results. Automatically choses limits for the magnitude range based on the saturation limit of the shortest exposure and the sensitivity limit of the combined data.

Parameters:

exp_times : astropy.units.Quantity

Sequence of sub exposure times.

filter_name : str

Name of the optical filter to use.

magnitude_interval : astropy.units.Quantity, optional

Step between consecutive brightness values, default 0.02 mag

snr_target : float, optional

signal to noise threshold used to set faint limit of magnitude range, default 1.0

plot : str, optional

Filename for the plot of SNR vs magnitude. If not given no plots will be generated.

Returns:

magnitudes : astropy.units.Quantity

Sequence of point source brightnesses in AB magnitudes

snrs : astropy.units.Quantity

signal to noise ratios for point sources of the brightnesses in magnitudes

total_elapsed_time(exp_list)

Calculates the total elapsed time required for a given a list of sub-exposure times.

The calculation add readout time overheads (but no others, at present) and sums the elapsed time from all sub-exposures.

Parameters:

exp_list : astropy.units.Quantity

List of sub-exposure times

Returns:

elapsed_time : astropy.units.Quantity

Total elapsed time required to execute the list of sub exposures

total_exposure_time(total_elapsed_time, sub_exp_time)

Calculates total exposure time given a total elapsed time and sub-exposure time.

The calculation includes readout time overheads (but no others, at present) and rounds down to an integer number of sub-exposures.

Parameters:

total_elapsed_time : astropy.units.Quantity

Total elapsed time

sub_exp_time : astropy.units.Quantity

Exposure time of individual sub-exposures

Returns:

total_exposure_time : astropy.units.Quantity

Maximum total exposure time possible in an elapsed time of no more than total_elapsed_time