fluxcompensator.image.SyntheticImage

class fluxcompensator.image.SyntheticImage(input_array, unit_out='ergs/cm^2/s', name=None)

SyntheticImage is part the FluxCompensator. It converts input_arrays (e. g. HYPERION ModelOutput in 2D) to “realistic” synthetic observations (e. g. by accounting for PSF and noise). It contains attributes like ModelOutput (see Notes). If input_array is already a SyntheticImage object, the attributes are passed. If input_array is not a SyntheticImage object, SyntheticImage specific attributes are defined and then passed.

Parameters:

input_array : SyntheticImage, ModelOutput, optional

input_array also reads arrays with ModelOutput like properties.

unit_out : str, optional

The output units for SyntheticImage val. Valid options are:

  • 'ergs/cm^2/s'
  • 'ergs/cm^2/s/Hz'
  • 'Jy'
  • 'mJy'
  • 'MJy/sr'

The default is 'ergs/cm^2/s'.

name : str

The name of the FluxCompensator object until another input_array is called. The default is None.
Returns:

image : SyntheticImage

2D val array with SyntheticImage properties.

flux : SyntheticFlux

0D val array (scalar) with SyntheticFlux properties.

Notes

unit_in : str

Unit of val in input_array. Valid options are:

  • 'ergs/cm^2/s'
  • 'ergs/cm^2/s/Hz'
  • 'Jy'
  • 'mJy'
  • 'MJy/sr'
grid_unit : float

Physical unit of FOV axis in cm. Valid options are:

  • au in cm
  • pc in cm
  • kpc in cm
grid_unit_name

Astronomical unit of FOV axis. Valid options are:

  • 'au'
  • 'pc'
  • 'kpc'
FOV : tuple

Tuple FOV(x,y) of Field of View pixel entries:

  • pixel in x direction: FOV[0]
  • pixel in y direction: FOV[1]
name : str
The name of the FluxCompensator object until another input_array is called. The default is None.
stage : str
Gives current operation stage of SyntheticImage. E. g. 'SyntheticImage: convolve_PSF'
log : list
List of strings of the previous and current stages.
filter : dict

Dictionary filter = {name, waf_0, waf_min, waf_max} of the applied filter:

  • name of filter: filter['name']
  • central wavelength: filter['waf_0']
  • minimal wavelength: filter['waf_min']
  • maximal wavelength: filter['waf_max']

Attributes

wav numpy.ndarray The wavelength of the val image in microns.
val numpy.ndarray The 2D image with shape (x, y).
units str Current units of the val image.
distance str Distance to the observed object in cm.
x_min float Physical offset from axis origin in FOV in cm.
x_max float Physical offset from axis origin in FOV in cm.
y_min float Physical offset from axis origin in FOV in cm.
y_max float Physical offset from axis origin in FOV in cm.
lon_min float Minimal longitudinal angle.
lon_max float Maximal longitudinal angle.
lat_min float Minimal latitudinal angle.
lat_max float Maximal latitudinal angle.
pix_area_sr float Pixel area per sr.

Methods

extinction(A_v[, input_opacities]) Accounts for reddening.
change_resolution(new_resolution[, grid_plot]) Changes the resolution of val image.
convolve_psf(psf) Convolves the val image with a PSF of choice.
add_noise(mu_noise, sigma_noise[, seed, ...]) Adds normal distributed noise to the val image of SyntheticImage.
get_total_val() Collapses the val image of SyntheticImage into a 0D val array.
plot_image([prefix, name, multi_cut, ...]) Plots the val image of SyntheticImage.
add_to_observation(fits_file, name[, ...]) Blends the modeled realistic synthetic observation to a real observation in a fits file.
add_field_stars(extinction_map[, database, ...]) Adds field stars to synthetic image.

Methods (detail)

extinction(A_v, input_opacities=None)

Accounts for reddening.

Parameters:

A_v : Value of the visible extinction.

input_opacities : None, str

If None standard extinction law is used. Otherwise a e. g. input_opacities.txt file can be passed as a str to read an opacity file with column #1 wav in microns and column #2 in cm^2/g. Default is None.
Returns:

image : SyntheticImage
change_resolution(new_resolution, grid_plot=None)

Changes the resolution of val image.

Parameters:

new_resolution : Resolution which the val array should get in

arcsec/pixel.

grid_plot : None, True

If True old and new resolution is visualized in a plot. Default is None.
Returns:

image : SyntheticImage
convolve_psf(psf)

Convolves the val image with a PSF of choice.

Parameters:

psf : GaussianPSF, FilePSF, database, FunctionPSF

  • GaussianPSF(self, diameter): Convolves val with Gaussian PSF.
  • FilePSF(self, psf_file, condensed) : Reads PSF from input file.
  • database : object
    If PSF name_PSF from FluxCompensator database is used.
  • FunctionPSF(self, psf_function, width): Convolves defined PSF.
    2D val image of SyntheticImage.val convolved with PSF.
Returns:

image : SyntheticImage
add_noise(mu_noise, sigma_noise, seed=None, diagnostics=None)

Adds normal distributed noise to the val image of SyntheticImage.

Parameters:

mu_noise : float

Mean of the normal distribution. Good choice: mu_noise = 0.

sigma_noise : float

Standard deviation of the normal distribution.

Good choice arround:
  • 'ergs/cm^2/s' : sigma_noise = 10.**(-13)
  • 'ergs/cm^2/s/Hz' : sigma_noise = 10.**(-26)
  • 'Jy' : sigma_noise = 10.**(-3)
  • 'mJy' : sigma_noise = 10.**(-1)
  • 'MJy/sr' : sigma_noise = 10.**(-10)

seed : float, None

When float seed fixes the random numbers to a certain sequence in order to create reproducible results. Default is None.

diagnostics : truetype

When True noise array is stored in a fits file.
Returns:

image : SyntheticImage
get_total_val()

Collapses the val image of SyntheticImage into a 0D val array.

Returns:flux : SyntheticFlux
plot_image(prefix=None, name=None, multi_cut=None, single_cut=None, set_cut=None, dpi=None)

Plots the val image of SyntheticImage. The wavelength interval around the central wavelength labels the plot.

Parameters:

prefix : str

Name of the image. Default naming chain is switched off.

name : str

Name of image within the default naming chain to distinguish the plot files. E. g. ‘PSF_gaussian’

mulit_cut : True, None

  • True : plots chosen image slice at cuts of [100, 99, 95, 90]%.
  • None : no mulit-plot is returned.

Default is None.

single_cut : float [0,100], None

  • float : cut level for single plot of image slice.
  • None : no single plot is returned.

set_cut : tuple, None

  • tuple : set_cut(v_min, v_max)
    Minimal and maximal physical val presented in the colorbars.
  • None : no plot with minimal and maximal cut is returned.

Default is None.

dpi : None, scalar > 0

The resolution in dots per inch. None is default and will use the val savefig.dpi in the matplotlibrc file.
Returns:

image : SyntheticImage
add_to_observation(fits_file, name, position_pix=None, position_world=None, zero_edges=None)

Blends the modeled realistic synthetic observation to a real observation in a fits file.

Parameters:

fits_file : str

fits_file of the observation.

name : str

Name of the output fits file.

position_pix : list, None

Center position of the model in observation pixel coordinates. Default is None.

position_world : list, None

Center position of the model in observation world coordinates. Default is None.

zero_edges : True, None

If True edges of model are normalized to zero. Default is None.
Returns:

image : SyntheticImage
add_field_stars(extinction_map, database=None, star_file=None, seed=None, ISMextinction=None)

Adds field stars to synthetic image.

Parameters:

extinction_map : object

Created with fluxcompensator.utils.fieldstars.extract_extinction_map.

database : dict, None

Dictionary sets the parameters for field stars loaded for the respective band from the built-in database.

dict = {‘number’:200, ‘distance_range’:[3*kpc, 50*kpc], ‘ground’: 0.02}

The dictionary is structured as follows:

  • 'number' : int in [0,288]

  • 'distance_range' : list

    Distance lower and upper limit in units of cm

  • 'ground' : str, float

    Distribution of stars before ('foreground') or behind ('background') the synthetic object. When 'ground' is a float in the limits of [0,1] then this is the fraction of foreground stars.

Default is None.

star_file : str, None

To load individual file with field stars in the format of (distance[pc], mag[band]). Default is None.

seed : int, None

To create reproducible results for the positions of field stars. Default is None.

ISMextinction : float, None

Optical extinction A_V along the line of sight in units mag/kpc. Default is None.
Returns:

image : SyntheticImage