Initial example
Warning
The first time you execute fridadrp-ifu_simulator, the output in the
terminal will show that some auxiliary files are being downloaded and stored in
a cache directory. You don’t need to worry about the specific location unless
you want to examine these files.
To facilitate the identification of the script parameters, we use the
backslash \ symbol to indicate line continuation. The backslash
escapes the next character from being interpreted by the shell. If the
character following the backslash is a newline, then that newline
will not be interpreted as the end of the command. Instead, it
effectively allows a command to span multiple lines.
(venv_frida) $ fridadrp-ifu_simulator \
--scene scene00.yaml \
--grating medium-K \
--scale fine \
--seeing_fwhm_arcsec 0.05 \
--rnoise 4 \
--bias 100 \
--seed 1234 \
--output_dir work --record
The first parameter, --scene, specifies the name of the external YAML file
that contains the scene description. Its content is explained below.
The second and third parameters, --grating and --scale, specify the grating
and scale that define the wavelength range and sampling, as well as the spatial
scale in the IFU field of view. In this example, we use the medium-K grating
and the fine scale camera. We also specify that the seeing FWHM is 0.05 arcsec,
the detector readout noise is 4 ADU, and the bias level is 1000 ADU. Finally,
we set work as the output subdirectory for the resulting files.
The scene file of the initial example
In this specific example, we are using the file scene00.yaml.
scene_block_name: constant flux
spectrum:
type: constant-flux
geometry:
type: point-like
nphotons: 2E6
wavelength_sampling: random # optional: default=random
apply_seeing: True # optional: default=True
apply_atmosphere_transmission: True # optional: default=True
render: True # optional: default=True
The relevant information is provided as mappings and collections using indentation for scope. In this case the following first-order keys are identified:
scene_block_name: the provided string is an arbitrary label defined by the user to identify this scene block.This key has no default value (it is mandatory).
spectrum: this key opens an indented section that contains all the information required to define the kind of spectrum to be associated to the geometry described next. In this example we want to simulate a constant flux spectrum, which is indicated by the keytype: constant-flux.This key has no default value (it is mandatory).
geometry: this key opens an indented section that indicates how the photons generated following the previous spectrum type are going to be distributed in the IFU field of view. In this example, we are usingtype: point-like, meaning that we want to place all the simulated photons at the same point (by default, the center of the IFU field of view).This key has no default value (it is mandatory).
nphotons: total number of photons to be simulated.This key has no default value (it is mandatory).
wavelength_sampling: method employed to assing the wavelength to each simulated photon. Two methods have been implemented:random: the simulated wavelengths are assigned by randomly sampling the cumulative distribution function of the simulated spectrum. This method mimics the Poissonian arrival of photons.fixed: the simulated wavelengths are assigned by uniformly sampling the cumulative distribution function of the simulated spectrum (i.e., avoding the Poissonian noise). This last method should provide a perfectly constant flux (+/- 1 photon due to rounding) for an object with constant PHOTLAM, when using the parameter--spectral_blurring_pixel 0.
Default value:
random.apply_seeing: boolean key indicating whether seeing must be taken into account. IfTrue, each simulated photon is randomly displaced in the focal plane of the IFU according to a probability distribution that is determined by the seeing PSF.Default value:
True.apply_atmosphere_transmission: boolean key indicating whether the atmosphere transmission must be considered. IfTrue, the atmospheric transmission probability at the wavelength of each simulated photon is evaluated, and a random number between 0 and 1 is generated in each case. If the obtained number is greater than the transmission probability, the photon is discarded.Default value:
True.render: boolean key indicate whether the considered scene block must be simulated. In this case, in which we only have a single scene block, this key is not very relevant (it only makes senserender: True). But in more complicated cases, it is useful to be able to set this key toFalsewhen we want to simulate images with several objects and components in the IFU field of view and one needs to remove some particular objects from the simulation without deleting the corresponding lines in the YAML file.Default value:
True.
Files generated by the IFU simulator
The execution of the IFU simulator generates several files. All of them
share the same prefix test. This can be easily modified using the parameter
--prefix_intermediate_FITS when running fridadrp-ifu_simulator.
Filename |
Short description |
BITPIX(*) |
|---|---|---|
test_ifu_white2D_method0_os10.fits |
White light image (IFU, oversampling=10) |
16 / -32 |
test_ifu_white2D_method0_os1.fits |
White light image (IFU, no oversampling) |
16 / -32 |
test_ifu_3D_method0.fits |
3D cube (simulated photons) |
16 / -32 |
test_rss_2D_method0.fits |
RSS version of 3D cube |
16 / -32 |
test_detector_2D_method0.fits |
Hawaii detector image |
(16) / -32 |
test_rss_2D_method1.fits |
Reconstructed RSS from Hawaii |
-32 |
test_ifu_3D_method1.fits |
Reconstructed 3D cube from RSS |
-32 |
(*) Note: the BITPIX column values in this table correspond to the following situations:
BITPIX 16 / -32: The program first attempts to save the image with BITPIX 16. If the number of counts exceeds 65535, the image is automatically promoted to BITPIX -32.
BITPIX (16) / -32: The BITPIX value used depends on the
bitpix_detectorparameter. If this parameter is set to 16 and the output array contains negative numbers, they are set to zero. Similarly, numbers above 65535 are clamped to 65535.BITPIX -32: The images are always saved with BITPIX -32.
The mentioned files store different steps of the simulation procedure. Details follow.
Image test_ifu_white2D_method0_os10.fits
White-light image corresponding to the IFU field of view, using a particular
oversampling. By default, the oversampling is set to 10, and for that reason
the last part of the file name before the extension is os10. The
oversampling can be modified using the parameter --noversampling_whitelight
when running fridadrp-ifu-simulator.
Note that due to the oversampling factor, the shape of this image is
NAXIS1=640 and NAXIS2=600.
(venv_frida) $ numina-ximshow work/test_ifu_white2D_method0_os10.fits \
--cbar_orientation vertical --z1z2 minmax --aspect equal
Image test_ifu_white2D_method0_os1.fits
White-light image without oversampling.
Since we are not using oversampling, in this case NAXIS1=64 and
NAXIS2=60. Note that the number of counts is logically larger than in the
previous case by a factor \(\sim 10^2\).
(venv_frida) $ numina-ximshow work/test_ifu_white2D_method0_os1.fits \
--cbar_orientation vertical --z1z2 minmax --aspect equal
We can easily compare the last two exposures with ds9 by matching their WCS
information (note the use of -match frame wcs).
(venv_frida) $ ds9 \
-scale mode minmax \
-geometry 1000x1000 \
-wcs degrees \
-multiframe \
work/test_ifu_white2D_method0_os1.fits \
work/test_ifu_white2D_method0_os10.fits \
-lock slice image \
-lock frame image \
-zoom to fit \
-cmap viridis \
-match frame colorbar \
-match frame wcs \
-colorbar lock yes \
-view multi yes
Image test_ifu_3D_method0.fits
3D data cube of the simulated photons. In this case
NAXIS1=64, NAXIS2=60 and NAXIS3=2048.
(venv_frida) $ fitsheader test_ifu_3D_method0.fits
It is possible to have a look to this image using QFitsView
(venv_frida) $ qfitsview test_ifu_3D_method0.fits
Image test_rss_2D_method0.fits
RSS (Raw Stacked Spectra) corresponding to the same information stored in the
previous file. The shape of this image is NAXIS1=2048 (spectral axis) and
NAXIS2=1920 (spatial axis). Note that the \(1920 = 64 \times 30\), where 30
is the number of the IFU slices, and 64 is the number of pixels along the
NAXIS1 spatial direction of the white-ligth images.
Note that here the slices are vertically ordered in ascending order, from 1 to 30, starting from the bottom left corner of the image.
(venv_frida) $ numina-ximshow work/test_rss_2D_method0.fits \
--cbar_orientation vertical --z1z2 minmax --aspect equal
Image test_detector_2D_method0.fits
Simulation corresponding to the Hawaii detector version of the last image. Each
photon in the previous RSS image is transferred to the Hawaii detector making
use of the corresponding geometric distortions. The shape of this new image is
NAXIS1=2048 and NAXIS2=2048.
Note that in this case, the slices appear in the following order when moving vertically upwards in the image from the bottom left corner: 30, 1, 29, 2, 28, 3, 27, 4, 26, 5, 25, 6, 24, 7, 23, 8, 22, 9, 21, 10, 20, 11, 19, 12, 18, 13, 17, 14, 16, 15.
This simulated image also includes the following effects:
bias: the input bias level (assumed constant).
flatfield: variation in the pixel-to-pixel response. A predefined simulated flatfield image is assumed for the adopted grating.
readout noise: the value specified in the
--rnoiseparameter ofmegaradrp-ifu_simulatoris used as the standard deviation of the Gaussian distribution employed to generate the random values to be introduced in each pixel of the detector.
(venv_frida) $ numina-ximshow work/test_detector_2D_method0.fits \
--cbar_orientation vertical --z1z2 minmax --aspect equal
Image test_rss_2D_method1.fits
Reconstructed RSS image from the observed image on the Hawaii detector, taking into account the geometric distortions of the image. This tests the procedure that will be applied in the FRIDA pipeline based on real observations.
As expected, the shape of this image is NAXIS1=2048 (spectral axis) and
NAXIS2=1920.
(venv_frida) $ numina-ximshow work/test_rss_2D_method1.fits \
--cbar_orientation vertical --z1z2 minmax --aspect equal
It is possible to compare the two RSS images (before and after the simulation) using ds9. Note that the simulated RSS exhibit a background pattern corresponding to the bias level that, in addition, is not homogeneous. This reflects the fact that each
(venv_frida) $ ds9 \
-scale mode minmax \
-geometry 1000x1000 \
-wcs degrees \
-multiframe \
work/test_rss_2D_method0.fits \
work/test_rss_2D_method1.fits \
-lock slice image \
-lock frame image \
-zoom to fit \
-cmap viridis \
-match frame colorbar \
-colorbar lock yes \
-view multi yes
Image test_ifu_3D_method1.fits
Reconstructed 3D data cube built from the previous image. As expected for the
3D view of these data, NAXIS1=64, NAXIS2=60 and NAXIS3=2048.
This file simulates the result that will be obtained after reducing a single
pointing.
We can easily compare the while-light image obtained in the two simulated versions of the data cubes.
(venv_frida) $ numina-extract_2d_slice_from_3d_cube work/test_ifu_3D_method0.fits
(venv_frida) $ numina-extract_2d_slice_from_3d_cube work/test_ifu_3D_method1.fits
You can easily compare both images at each wavelength using ds9.
(venv_frida) $ ds9 \
-scale mode minmax \
-geometry 1000x1000 \
-wcs degrees \
-multiframe \
work/test_ifu_3D_method0.fits \
work/test_ifu_3D_method1.fits \
-lock slice image \
-lock frame image \
-zoom to fit \
-cmap viridis \
-match frame colorbar \
-colorbar lock yes \
-view multi yes
