# 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. ```{include} scene00/last_command.txt ``` ```{include} scene00/terminal_output.md ``` 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)= ## The scene file of the initial example In this specific example, we are using the file {download}`scene00.yaml `. ```{literalinclude} scene00/scene00.yaml :language: yaml ``` 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 key ``type: 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 using `type: 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. If `True`, 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. If `True`, 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 sense `render: True`). But in more complicated cases, it is useful to be able to set this key to `False` when 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`. ```{list-table} Files generated by the simulator :header-rows: 1 :class: wrap-table * - 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_detector` parameter. 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`. ```{code-block} console (venv_frida) $ numina-ximshow work/test_ifu_white2D_method0_os10.fits \ --cbar_orientation vertical --z1z2 minmax --aspect equal ``` ```{image} scene00/test_ifu_white2D_method0_os10.png :width: 100% :alt: image test_ifu_white2D_method0_os10.fits ``` ### 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$. ```{code-block} console (venv_frida) $ numina-ximshow work/test_ifu_white2D_method0_os1.fits \ --cbar_orientation vertical --z1z2 minmax --aspect equal ``` ```{image} scene00/test_ifu_white2D_method0_os1.png :width: 100% :alt: image test_ifu_white2D_method0_os1.fits ``` We can easily compare the last two exposures with **ds9** by matching their WCS information (note the use of `-match frame wcs`). ```{code-block} console (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} scene00/comparison_white2D_os1_os10.png :width: 100% :alt: image comparison_white2D_os1_os10.png ``` ### Image test_ifu_3D_method0.fits 3D data cube of the simulated photons. In this case `NAXIS1=64`, `NAXIS2=60` and `NAXIS3=2048`. ```{code-block} console (venv_frida) $ fitsheader test_ifu_3D_method0.fits ``` ```{include} scene00/header_test_ifu_3D_method0.txt ``` It is possible to have a look to this image using QFitsView ```{code-block} console (venv_frida) $ qfitsview test_ifu_3D_method0.fits ``` ```{image} scene00/test_ifu_3D_method0_plot1.png :width: 100% :alt: image test_ifu_3D_method0.fits, plot 1 ``` ```{image} scene00/test_ifu_3D_method0_plot2.png :width: 100% :alt: image test_ifu_3D_method0.fits, plot 2 ``` ### 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. ```{code-block} console (venv_frida) $ numina-ximshow work/test_rss_2D_method0.fits \ --cbar_orientation vertical --z1z2 minmax --aspect equal ``` ```{image} scene00/test_rss_2D_method0.png :width: 100% :alt: image test_rss_2D_method0.fits ``` ### 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 ``--rnoise`` parameter of ``megaradrp-ifu_simulator`` is used as the standard deviation of the Gaussian distribution employed to generate the random values to be introduced in each pixel of the detector. ```{code-block} console (venv_frida) $ numina-ximshow work/test_detector_2D_method0.fits \ --cbar_orientation vertical --z1z2 minmax --aspect equal ``` ```{image} scene00/test_detector_2D_method0.png :width: 100% :alt: image test_detector_2D_method0.fits ``` ### 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`. ```{code-block} console (venv_frida) $ numina-ximshow work/test_rss_2D_method1.fits \ --cbar_orientation vertical --z1z2 minmax --aspect equal ``` ```{image} scene00/test_rss_2D_method1.png :width: 100% :alt: image test_rss_2D_method1.fits ``` 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 ```{code-block} console (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} scene00/comparison_rss_2D_method0_method1.png :width: 100% :alt: image comparison_rss_2D_method0_method1.png ``` ### 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. ```{code-block} console (venv_frida) $ numina-extract_2d_slice_from_3d_cube work/test_ifu_3D_method0.fits ``` ```{code-block} console (venv_frida) $ numina-extract_2d_slice_from_3d_cube work/test_ifu_3D_method1.fits ``` ```{image} scene00/projected_3D_method0.png :width: 49% ``` ```{image} scene00/projected_3D_method1.png :width: 49% ``` You can easily compare both images at each wavelength using **ds9**. ```{code-block} console (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 ``` ```{image} scene00/comparison_ifu_3D_method0_method1.png :width: 100% :alt: image comparison_ifu_3D_method0_method1.png ```