Data reduction
Warning
Since February 2026, a new, more simplified data reduction procedure has been implemented. These changes were introduced in megaradrp version 0.20.0.
In particular:
the auxiliary file
control.yamlis no longer necessarythe calibration tree is automatically built using
megaradrp-inittree, as explained belowthe auxiliary calibration file
extinction_LP.txtis now part of the calibration tree and no longer needs to be stored in thedatasubdirectory; the requirementreference_extinction: extinction_LP.txtshould no longer appear in the observation result file (unless the user needs to use a different extinction table, in which case the requirement can be set and the corresponding file should be placed in thedatasubdirectory)
Concerning the label used to identify the calibration path, for observations
carried out before February 2026 this label is the original
ca3558e3-e50d-4bbc-86bd-da50a0998a48 sequence, whereas for images
obtained after February 2026 the label to store the calibrations is
9f3fecbf-376c-47ae-a188-313b7d829104.
Getting Started
The first step to start the data reduction is to activate your environment (see details in section DRP installation).
The next step is to download the data employed in this cookbook: megara-cookbook-v3.tar.gz
If you find any trouble trying to download the previous file, try with the following command line:
(megara) $ curl -O https://guaix.fis.ucm.es/data/megaradrp/megara-cookbook-v3.tar.gz
It is advisable to decompress the previous file in a pristine directory where you can comfortably start the reduction of the data:
(megara) $ tar zxvf megara-cookbook-v3.tar.gz
(megara) $ cd megara-cookbook-v3
(megara) $ ls
(megara) $ tree M15_LCB_HR-R
Note that the tree command shown above might not be available in certain
unix distributions (you can use ls instead).
Data organization
Before starting the reduction procedure, it is important to initialize the
calibration tree. Since February 2026, this procedure has been simplified
through the introduction of a new script, megaradrp-inittree.
This process is illustrated below using the M15 data set as an example.
(megara) $ cd M15_LCB_HR-R
(megara) $ megaradrp-inittree
After executing the last script, a new subdirectory calibrations should
appear, along with an auxiliary hidden file .numina.cfg (the contents of
which can be ignored).
(megara) $ tree calibrations -L 2
The execution of megaradrp-inittree automatically downloads basic
calibration files stored at Zenodo.
In particular, the files correspond to the instrument status during two
different epochs:
ca3558e3-e50d-4bbc-86bd-da50a0998a48: for images obtained before January 20269f3fecbf-376c-47ae-a188-313b7d829104: for images obtained after January 2026
Warning
Since this cookbook uses data obtained before January 2026, the subdirectory
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48 serves as the
root destination path for the various reduced images that will be generated
during the reduction procedure. If you are reducing data obtained after
January 2026, simply replace
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48 with
calibrations/MEGARA/9f3fecbf-376c-47ae-a188-313b7d829104.
For instance, the calibration products generated during the reduction of the cookbook data, such as the MasterBias, MasterFiberFlat, MasterSensitivity, etc., will be hosted within this calibration tree. Thus, once the files for these calibrations are generated, they should be copied under this calibration tree according structure below.
(megara) $ tree -L 2 calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48
Different files can be stored at the same directory, but the DRP is
going to use the first file it encounters in alphabetical order. The
user can name the desired file with prefix 00_ (e.g.
00_master_traces.json) to be sure this is the file to be used by the
DRP. Note that the sorting of files named 00_ and 000_ might
be different for the operative system and for the MEGARA DRP, so avoid
making abusive use of these prefixes.
Your raw data should always be included in a subdirectory named data/
within each working target directory (M15, M71, etc.). Images could be stored
gzipped but then the observation-result files should list the images with the
.gz extension. The different observation-result files (*.yaml) used during
the data reduction process should be also located within each target directory
as they will be different for each target. In this example, the
observation-result files in YAML format are named with a first number related
in which order they are run.
(megara) $ cd M15_LCB_HR-R
(megara) $ ls
Running a recipe
The MEGARA DRP is run through a command line interface provided by numina.
Note
Remember that the numina script is the interface with GTC pipelines.
In order to execute megaradrp recipes you should type something like:
(megara) $ numina run <observation_result_file.yaml>
where <observation_result_file.yaml> is an observation result file in
YAML format.
YAML is a human-readable data serialization language (for details see YAML Syntax)
The run mode of numina requires:
An observation-result file in YAML format.
The raw images obtained as part of the user’s observing block.
The calibrations required by the recipe.
The observation-result files are created by the
user. This is an example of the observation result file to compute the
fibers traces 1_TraceMap.yaml under the subdirectory M15_LCB-HR-R:
The id: is an identifier of the observing block. The DRP will
create two directories with the products of the recipe (obsid<id>_work/ and
obsid<id>_results/) using the id identifier as an arbitray label to
identify
the corresponding processing block. The mode: is the name of the
instrument observing mode as returned by numina show-modes. In
frames: a list of the names of the images obtained as part of the
observation should be included.
Using the same YAML file the user can process sequentially different sets of
files with the same recipe. For that purpose, the enabled: parameter can be
set to True (or False) to process (or not) a specific block of files. In
this case, do not forget the separation line --- between blocks (otherwise
the pipeline will not recognize where one block ends and the next one begins).
This separation line must not appear after the last block.
Note that the user can add comments to these YAML files by adding lines
preceded with a hash sign (#).
An example of an observation-result file with two blocks is the following:
(megara) $ more 1_TraceMap.yaml
In the directory of our target M15 we have already defined several
observation-result files (*.yaml):
(megara) $ pwd
(megara) $ ls
If we want to run the recipe MegaraTraceMap using the observing-result file
1_TraceMap.yaml we should execute:
(megara) $ numina run 1_TraceMap.yaml
When disk space is an issue, it is possible to execute numina indicating
that links (instead of actual copies of the original raw files) must be placed
in the obsid<id>_work/ subdirectory. This behaviour is set using the
parameter --link-files:
(megara) $ numina run 1_TraceMap.yaml --link-files
Note: in recent versions of numina this is no longer necessary since the
default behavior assumes --link-files.
Other useful numina commands include:
Data reduction process
In the following sections the different steps to produce the target wavelength and flux calibrated row-stacked spectra (RSS) are detailed. The examples are illustrated making use of the cookbook data available for the target M15:
(megara) $ pwd
You can easily examine the header of the FITS images using the astropy utility
fitsheader:
(megara) $ fitsheader \
-k VPH -k INSMODE -k OBJECT -k SPECLAMP -k EXPTIME -k DATE-OBS \
-f -e 0 data/0001*.fits
The data available include bias exposures (the VPH is not relevant here), halogen exposures (for tracing and flatfielding), ThNe arc exposures (for wavelength calibration), and target exposures.
Bias image
Before the Analog-to-Digital conversion is performed a pedestal (electronic) level is added to all images obtained with the MEGARA CCD. This is a standard procedure in CCD imaging and spectroscopy applications for Astronomy and is intended to minimize the ADC errors produced when very low analog values are converted to DUs. To calibrate this pedestal level of the detectors, bias images are taking with null integration time. We note the user that in the case of the MEGARA CCD (a 4k x 4k pixels CCD231-84 E2V chip), since the detector is always read using two diagonally-opposed amplifiers (to speed up the reading process while minimizing electronic cross-talk), the bias is slightly different in the upper and bottom halves of the image. Note that the Readout Noise (RoN) should be around 2 e– in all cases.
This recipe processes a set of bias images obtained in Bias Image instrument mode. Images are corrected from overscan and trimmed to the physical size of the detector. Then, they are corrected from Bad-pixels Mask, if the BPM is available and finally, images are stacked using the median.
The content of the file 0_Bias.yaml for the M15 data is the following:
1id: 0_Bias
2mode: MegaraBiasImage
3instrument: MEGARA
4frames:
5 - 0001310880-20170827-MEGARA-MegaraBiasImage.fits
6 - 0001310881-20170827-MEGARA-MegaraBiasImage.fits
7 - 0001310882-20170827-MEGARA-MegaraBiasImage.fits
8 - 0001310883-20170827-MEGARA-MegaraBiasImage.fits
9 - 0001310884-20170827-MEGARA-MegaraBiasImage.fits
10 - 0001310885-20170827-MEGARA-MegaraBiasImage.fits
11 - 0001310886-20170827-MEGARA-MegaraBiasImage.fits
12 - 0001310887-20170827-MEGARA-MegaraBiasImage.fits
13 - 0001310888-20170827-MEGARA-MegaraBiasImage.fits
The recipe is run as follows,
(megara) $ numina run 0_Bias.yaml
and the products are stored in the directory obsid0_Bias_results/,
including the master_bias.fits file (see Figure 4).
(megara) $ ls obsid0_Bias_work/
(megara) $ ls obsid0_Bias_results/
Note that the data files in the obsid0_Bias_work subdirectory are shown
with a suffix @, indicating that these files are actually links the the
original files (stored under the data subdirectory).
Figure 4: Example of a MEGARA master bias as created by the MegaraBiasImage recipe. Note that this image was obtained with the MEGARA DRP ver. 0.9. Later versions fit a spline to the overscan regions of both amplifiers (instead of adopting a constant value) so the resulting image is typically flatter than the example shown here.
The user needs to copy the file master_bias.fits to the calibration tree at
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/MasterBias/:
(megara) $ cp obsid0_Bias_results/master_bias.fits \
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/MasterBias/
Warning
Remember: for data obtained after February 2026 you should use
(megara) $ cp obsid0_Bias_results/master_bias.fits \
calibrations/MEGARA/9f3fecbf-376c-47ae-a188-313b7d829104/MasterBias/
Dark image
The potential wells in CCD detectors spontaneously generate electron-ion pairs at a rate that is a function of temperature. For very long exposures this translates into a current that is associated with no light source and that is commonly referred to as dark current. Different tests during AIV activities have shown MEGARA detector´s dark current has very low values < 2 e-/h/pixel, therefore in our data reduction dark images are neither needed nor used.
Bad-pixels Mask
Although science-grade CCD detectors show very few bad pixels / bad columns
there will be a number of pixels (among the ~17 Million pixels in the MEGARA
CCD) whose response could not be corrected by means of using calibration images
such as dark frames or flat-field images. These pixels, commonly called either
dead or hot pixels, should be identified and masked so their expected signal
could be derived using dithered images or, alternatively, locally interpolated.
The user is provided with a Bad-Pixels Mask (BPM) named master_bpm.fits.gz
and located at
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/MasterBPM/ that
was generated as part of the AIV activities by processing a set of defocused
continuum flat images. Currently, MEGARA presents only one (partial) bad
column of 120 pixels in length.
Slit Flat correction
In the case of fiber-fed spectrographs the correction for the detector pixel-to-pixel variation of the sensibility is usually carried out using data from laboratory, where the change in efficiency of the detector at different wavelengths is computed and then used to correct for this effect for each specific instrument configuration (VPH setup in the case of MEGARA).
The quality of present-day CCDs leads to a rather small impact of these pixel-to-pixel variations in sensitivity on either the flux calibration and the cosmetics of the scientific images, especially considering that not one but a number of pixels along the spatial direction are extracted for each fiber and at each wavelength. In the case of MEGARA, the pseudo-slit has been offset from its optical focus position to ensure that the gaps between fibers are also illuminated when a continuum (halogen) lamp at the ICM is used. The results of the analysis of the pixel-to-pixel variations in sensitivity show that this correction is actually not needed although this recipe is implemented in the MEGARA DRP.
Tracing fibers
Trace map
The next processing step combine a series of fiber-flats to generate a master trace map. The fiber-flats are obtained by illuminating the instrument focal plane with a continuum (halogen) lamp that is part of the GTC Instrument Calibration Module (ICM).
This step produces the tracing information required to extract the flux
of the fibers. The result is stored in a file named
master_traces.json.
An example of the observation result file 1_TraceMap.yaml to trace the
fibers is the following:
Then the recipe is run by doing:
(megara) $ numina run 1_TraceMap.yaml
Images listed in the observation-result file are trimmed and corrected
from overscan, bad-pixel mask (if master_bpm.fits is present in the
calibration tree), bias and
dark current (if master_dark.fits is present). Images thus corrected are
then median stacked. The result of the combination is saved as an
intermediate result that is named reduced_image.fits. This
combined image is also returned in the field reduced_image of the
recipe result and will be used for doing some quality control on the
tracing of the fibers.
The fibers are then grouped in packs of different numbers of fibers. To
match the traces in the image with the corresponding fibers, the DRP
uses the information provided by the instrument configuration to know
how fibers are packed and where the different groups of fibers appear in
the detector. Using the column reference 2000, peaks are detected (using
an average of 7 columns) and matched to the layout of fibers. Fibers
without a matching peak are counted and their ids stored in the final
master_traces.json file. Once the peaks in the reference column are
found, each one is traced until the border of the image is reached. The
trace may be lost before reaching the border. In all cases, the
beginning and the end of the trace are stored.
The Y position of the trace is fitted to a polynomial of degree
polynomial_degree set to 5 by default. The coefficients of the
polynomial are stored in the final master_traces.json file.
(megara) $ ls obsid1_TraceMap_HR-R_work/
(megara) $ ls obsid1_TraceMap_HR-R_results
The position of the fibers traces at the detector are shifted depending on the ambient temperature. It is recommended to have continuum halogen exposures near in time to the observation of the scientific target. If this is not the case, the traces can be shifted easily when processing the target (see below).
The traces generated by this task can be visualized both on the raw or the processed images and can be also shifted to consider possible offsets between these traces and the position in the fibers in other images (twilight flats, standard star or scientific target observations, etc.). The visualization of the traces and an underlying reduced image can be done by executing:
(megara) $ megaradrp-overplot_traces \
obsid1_TraceMap_HR-R_results/reduced_image.fits \
obsid1_TraceMap_HR-R_results/master_traces.json
It is also possible to overplot the traces in the original raw data, making
using of the additional parameter --rawimage:
(megara) $ megaradrp-overplot_traces --rawimage \
data/0001312246-20170831-MEGARA-MegaraSuccess.fits \
obsid1_TraceMap_HR-R_results/master_traces.json
Another way to check the tracing is by overplotting the ds9 region files
created by the DRP for the traces on top of this reduced_image.fits by
doing (syntax might vary):
(megara) $ ds9 obsid1_TraceMap_HR-R_results/reduced_image.fits \
-regions load obsid1_TraceMap_HR-R_work/ds9.reg
The same syntax can be used to check the offset between these traces and the position of the fibers in other images (arc-lamp, twilight, standard star and object images).
Finally, the user needs to copy this master_traces.json to the
corresponding place at the calibration tree. In this case, this trace map
corresponds to the VPH HR-R (LCB mode):
(megara) $ cp obsid1_TraceMap_HR-R_results/master_traces.json \
calibratons/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/TraceMap/LCB/HR-R/
Warning
Remember: for data obtained after February 2026 you should use
(megara) $ cp obsid1_TraceMap_HR-R_results/master_traces.fits \
calibrations/MEGARA/9f3fecbf-376c-47ae-a188-313b7d829104/TraceMap/LCB/HR-R/
It is possible to force the generation of plots with the individual fits to
each fiber using the requirement debug_plot. For example,
requirements:
debug_plot: 1
By activating these additional plots, the files trace-xy-???.png
(y-coordinate vs. x-coordinate used to fit the trace of each fiber) and
trace-xz-???.png (flux vs. x-coordinate) will be stored in the work
subdirectory.
Warning
When trying to find the traces corresponding to the VPH LR-U, the fits sometimes yield unexpected results. One solution is to restrict the fitting range in the horizontal direction, decrease the polynomial degree, and extrapolate the fit. This can be accomplished by adjusting the corresponding arguments. A working example is the following:
requirements:
polynomial_degree: 2
xmin_fit: 1
xmax_fit: 3000
extrapolate_traces: True
Model map
This recipe processes a set of continuum flat images obtained in Trace Map or Fiber Flat modes and returns the fiber profile information required to perform advanced fiber extraction in other recipes.
The set of files listed in the observation-result file 2_ModelMap.yaml
is the same one used for the Trace Map.
Then the recipe is run by doing:
(megara) $ numina run 2_ModelMap.yaml
This processing step might take several minutes (from 10-40 min.) depending on the hardware used. When a model map is used the running times of the subsequent processing steps also increase by 2-5 minutes.
The images are processed as in the Trace Map recipe. In this case, the
approximate central position of the fibers is obtained from the
previously computed master_traces.json. Then, for every 100 columns of
the reduced image, a vertical cut in the image is fitted to a sum of
fiber profiles, being the profile a gaussian convolved with a square.
After the columns are fitted, the profiles (central position and sigma)
are interpolated to all columns using splines (see Figure 5). The
coefficients of the resulting splines are stored in the final
master_model.json file.
Figure 5: Mean position (left) and sigma (right) in pixels for fiber
#310 along the spectral axis shown as blue points. The red line shows
the spline fit. Plots for all the fibers are stored in the
obsid2_ModelMap_HR-R_work/ subdirectory.
The recipe also returns the RSS obtained by applying this advanced extraction to reduced_image. As an intermediate result, the recipe produces DS9 region files with the position of the center of the profiles, that can be used with raw and reduced images (see Figure 6).
Figure 6: MEGARA LCB HR-R continuum halogen exposure (left) and a region
of the raw image (right) with the ds9_raw.reg tracing the fibers’ path
shown on top.
(megara) $ ls obsid2_ModelMap_HR-R_work/
(megara) $ ls obsid2_ModelMap_HR-R_results/
The user needs to copy this master_model.json to the corresponding
place at the calibration tree.
(megara) $ cp obsid2_ModelMap_HR-R_results/master_model.json \
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/ModelMap/LCB/HR-R
Warning
Remember: for data obtained after February 2026 you should use
(megara) $ cp obsid2_ModelMap_HR-R_results/master_model.json \
calibrations/MEGARA/9f3fecbf-376c-47ae-a188-313b7d829104/ModelMap/LCB/HR-R/
Wavelength Calibration
In this processing step the wavelength solution for each fiber is created using recipe MegaraArcCalibration. To create the dispersion solution the recipe needs raw arc-lamp frames as input (see Figure 7). Note that although the term used is “arc-lamps” these are ThAr and ThNe Hollow-Cathode Lamps (HCL).
Figure 7: MEGARA LCB ThNe arc-lamp exposure obtained with the HR-R VPH.
The user needs to check if the traces already computed in the previous step are appropriate to do the extraction in the arc-lamp exposures. If the continuum halogen used to generate the traces and the arc-lamp images were obtained near in time there no offset should be applied to the traces. By taking the images close in time user ensures that temperature remains constant so no offset is present. The offsets are estimated to be ~1 pixel per ºC/K of change in temperature. No offset in the spectral direction has been reported.
The user can check this and evaluate the actual offset
by plotting the ds9_raw.reg regions file on top of the arc-lamp raw
image using DS9. If the traces (regions in ds9_raw.reg) are above the
fiber as seen in the raw image, then the offset is a negative number and
it is measured in pixels, while if the traces are below then the offset
is a positive number. This offset is given in the requirements
section in the observation-result file using the extraction_offset
parameter.
In this case, the observation-result file is called 3_WaveCalib.yaml.
In the example below, three frames for arc lamp exposures are included
and the offset for the extraction is set to 0 pixels:
Then the recipe is run by doing:
(megara) $ numina run 3_WaveCalib.yaml
Images provided in 3_WaveCalib.yaml are trimmed and corrected from
overscan, bad-pixel mask (if master_bpm.fits is present in the calibration
tree), bias and dark current (if master_dark.fits is present). The
corrected images are then stacked using a median. The result of the combination
of these images is saved as an intermediate result, named
reduced_image.fits. The apertures in the 2D image are extracted, using the
information in master_traces.json (or in the model_map.json if this
file is present at the calibration tree) and the extraction_offset
parameter set in the 3_WaveCalib.yaml. The result of the extraction is
saved as an intermediate result named reduced_rss.fits. The matched lines,
the quality of the match and other relevant information such as the
coefficients of the polynomial are stored in the final master_wlcalib.json
for each fiber.
Finally, the recipe returns different products. At the
obsid3_WaveCalib_HR-R_work/ directory the files wavecal_iter1.pdf (for
the initial wavelength calibration) and wavecal_iter2.pdf (for the final
iteration) contain a graphical representation for the wavelength calibration
for each fiber. For example, in wavecal_iter2.pdf the total number of
lines used for the refined wavelength calibration and the root mean square for
each fit is plotted depending on the fiber number. In the same PDF file, the
linear approximation for CRVAL1 and CDELT1 is plotted and also a graph for each
coefficient (typically of 5th degree) of the polynomial fit used for
the refined wavelength calibration is shown (see Figure 8).
After the previous procedure, a refinement of the wavelength calibration is
performed by fitting a polynomial to the variation of each coefficient of the
wavelength calibration polynomial against the fiber number. Fibers whose
wavelength calibration polynomial does not fit the expected smooth variation of
the coefficients are automatically detected. In such cases, an interpolated
polynomial is used, which provides very good results. The results of this
refinment are graphically stored in the file wavecal_refine_iter1.pdf.
Figure 8: Some of the plots included in the wavecalib_iter2.pdf file
generated with the MegaraArcCalibration recipe.
Should the user set the store_pdf_with_refined_fits parameter to
store_pdf_with_refined_fits: 1 at the 3_WaveCalib.yaml, the recipe will
create the subdirectory obsid3_WaveCalib_HR-R_work/refined_wavecal/ where a
collection of PDF files (one for each fiber) is created with graphical
information about the refined wavelength calibration (see Figure 9).
Figure 9: Example of the refined wavelength calibration result for
fiber #310. This kind of file (310.pdf at refined_wavecalib/ in this
case) is generated when the parameter store_pdf_with_refined_fits is
set to 1. This requirement should be set to 0 for a faster execution of
this recipe.
(megara) $ ls obsid3_WaveCalib_HR-R_work/
(megara) $ ls obsid3_WaveCalib_HR-R_results/
The user needs to copy the master_wlcalib.json at the obsid_result/
directory to the corresponding place at the calibration tree:
(megara) $ cp obsid3_WaveCalib_HR-R_results/master_wlcalib.json \
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/WavelengthCalibration/LCB/HR-R/
Warning
Remember: for data obtained after February 2026 you should use
(megara) $ cp obsid3_WaveCalib_HR-R_results/master_wlcalib.json \
calibrations/MEGARA/9f3fecbf-376c-47ae-a188-313b7d829104/WavelengthCalibration/LCB/HR-R/
To quickly check the wavelength calibration, it is possible to apply the newly
calculated calibration to the arc image itself. To do this, we can reduce the
arc exposures as if they were scientific exposures. We carry out this task
using the MegaraLcbAcquisition recipe. In this example, we execute this
task using the file 3_WaveCalib_check.yaml.
1id: 3_WaveCalib_check_HR-R
2mode: MegaraLcbAcquisition
3instrument: MEGARA
4frames:
5 - 0001312249-20170831-MEGARA-MegaraSuccess.fits
6 - 0001312250-20170831-MEGARA-MegaraSuccess.fits
7 - 0001312251-20170831-MEGARA-MegaraSuccess.fits
8requirements:
9 extraction_offset: [0.0]
10 master_fiberflat: master_fiberflat_ones.fits
Note that the images to be reduced correspond to the 3 individual arc
exposures. Among the requirements, we are using master_fiberflat:
master_fiberflat_ones.fits, a special FITS file located in the data
subdirectory that contains a fictitious flatfield image where all values are
set to 1.0. For the wavelength calibration check, we do not need to use a
correct master fiberflat image.
Warning
If this file is not present if your data directory, you can easily download it from master_fiberflat_ones.fits.gz, or execute
(megara) $ curl -O https://guaix.fis.ucm.es/data/megaradrp/master_fiberflat_ones.fits.gz
Don’t forger to move this file to the data subdirectory and uncompress it
(megara) $ cd data
(megara) $ mv ~/Downloads/master_fiberflat_ones.fits.gz .
(megara) $ gunzip master_fiberflat_ones.fits.gz
(megara) $ cd ..
Then the recipe is run by doing:
(megara) $ numina run 3_WaveCalib_check.yaml
The image to be examined is
obsid3_WaveCalib_check_HR-R_results/reduced_rss.fits. In this image, all
the arc line must appear as perfectly vertical lines.
(megara) $ numina-ximshow obsid3_WaveCalib_check_HR-R_results/reduced_rss.fits \
--z1z2 100,1000
Flat-field correction
Each optical fiber in MEGARA behaves like a different optical system, and therefore, its optical transmission is different and individual, with different wavelength dependence.
The recipe MegaraFiberFlatImage computes the master_fiberflat.fits
to correct for the global variations in transmission in between fibers
and as a function of wavelength in MEGARA. A fiber-flat image should be
used to perform this correction. These images are obtained by means of
illuminating the instrument focal plane with a flat spectral source
(typically a halogen lamp) that is installed as part of the GTC
Instrument Calibration Module (ICM).
In this case, we called the observation result file 4_FiberFlat.yaml,
where a total of three continuum halogen exposures are included:
If the inputs frames are the same used to trace the fiber spectra on the
detector for the same specific spectral setup, the extraction_offset
parameter should be set to 0 pixels. If that is note the case the offset should
be evaluated and computed as detailed in Section Wavelength Calibration.
Then the recipe is run by doing:
(megara) $ numina run 4_FiberFlat.yaml
All images listed in the observation-result file are trimmed and corrected from
overscan, bad pixel mask (if master_bpm.fits is present in the calibration
tree), bias and dark current (if master_dark.fits is present) and corrected
from pixel-to-pixel flat if master_slitflat.fits is provided. The corrected
images are then stacked using a median. The result of the combination is saved
as an intermediate result, named reduced_image.fits.
The apertures in the 2D image are extracted, using the information in
master_traces.json (or in the model_map.json if this file is present
at the calibration tree) and the extraction_offset parameter set in
the 4_FiberFlat.yaml, and then it is resampled according to the
wavelength calibration in master_wlcalib.json. The resulting RSS is
saved as an itnermediate result named reduced_rss.fits. To normalize
the master_fiberflat, each fiber is divided by the best-fitting spline
to the average of all valid fibers (see Figure 10). The RSS image
master_fiberflat.fits is returned as a recipe result (see Figure
11).
Figure 10: Example of the collapsed_smooth.png file generated as part
of the MegaraFiberFlatImage recipe, which is located at the
obsid4_FiberFlat_HR-R_work/ directory. The green line is a spline fit to
the average of all valid fibers, which is then used to normalize the extracted
spectral in order to generate the normalized master_fiberflat image.
Figure 11: Example of the master_fiberflat.fits file
generated for MEGARA LCB HR-R mode.
(megara) $ ls obsid4_FiberFlat_HR-R_work/
(megara) $ ls obsid4_FiberFlat_HR-R_results/
The user needs to copy the master_fiberflat.fits
to the corresponding place at the calibration tree:
(megara) $ cp obsid4_FiberFlat_HR-R_results/master_fiberflat.fits \
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/MasterFiberFlat/LCB/HR-R/
Warning
Remember: for data obtained after February 2026 you should use
(megara) $ cp obsid4_FiberFlat_HR-R_results/master_fiberflat.fits \
calibrations/MEGARA/9f3fecbf-376c-47ae-a188-313b7d829104/MasterFiberFlat/LCB/HR-R/
Illumination correction
Blank twilight-sky exposures are to be used to calibrate the global change in response introduced by the fiber flat. This is called the illumination correction and it is due to the fact that the GTC ICM does not produce a perfectly uniform illumination of the field and that the fraction and shape of the pupil that is seen by the MEGARA fibers during the observation of a specific target does not coincide with that seen during the acquisition of the fiber-flat images with the ICM.
The twilight sky exposure can safely assume to homogeneously illuminate the entire MEGARA field of view (3.5 arcmin x 3.5 arcmin for MOS mode and 12.5 x 11.3 sq. arcsec for LCB mode). However, since the telescope pupil is not circular and the alignment of the image of the pupil on top fibers by the microlenses is not identical for all fibers, in order to do this correction properly, the Rotator Angle of the FC-F rotator (ROTANG keyword in the raw image) and the Elevation of the telescope (ELEVAT keyword), and ideally also the temperature, should have the same values as the ones for the scientific observation. Furthermore, in case of MOS observing mode, the twilight sky exposures should be done with the robotic positioners placed at the same positions as for the targets’ configuration.
The recipe MegaraTwilightFlatImage process a set of continuum blank
twilight sky images and returns the master twilight flat product. In
this case, we named observation result file as 5_TwilightFlat.yaml, where
three frames for continuum blank twilight sky exposures being listed in
the file:
1id: 5_TwilightFlat_HR-R
2mode: MegaraTwilightFlatImage
3instrument: MEGARA
4frames:
5 - 0001251794-20170626-MEGARA-MegaraLCBImage.fits
6 - 0001251795-20170626-MEGARA-MegaraLCBImage.fits
7 - 0001251796-20170626-MEGARA-MegaraLCBImage.fits
8requirements:
9 extraction_offset: [+2.5]
10 normalize_region: [1550, 1700]
The extraction_offset parameter can be computed as
detailed in section Wavelength Calibration (see Figure 12).
Figure 12: Example of a region in the raw blank twilight sky image
(LCB, HR-R) with the computed traces (ds9_raw.reg file) on top. In this
case a extraction_offset of +2.5 pixels was needed.
Then the recipe is run by doing:
(megara) $ numina run 5_TwilightFlat.yaml
Images provided in the observation-result file are trimmed and corrected
from overscan, bad pixel mask (if master_bpm is present), bias and
dark current (if master_dark is present) and corrected from
pixel-to-pixel flat if master_slitflat is provided. The corrected
images are then stacked using a median. The result of the combination is
saved as an intermediate result, named reduced_image.fits.
The apertures in the 2D image are extracted, using the information in
master_traces.json (or in the model_map.json if this file is present
at the calibration tree) and the extraction_offset parameter set in
the 5_TwilightFlat.yaml, and then it is resampled according to the
wavelength calibration in master_wlcalib.json. Then, the result is
divided by the master_fiberflat. The resulting RSS is saved as an
intermediate result named reduced_rss.fits. To normalize the
master_twilightflat (see Figure 13), each fiber is divided by
the average of the column range given in normalize_region
parameter in 5_TwilightFlat.yaml. In those cases where the observation of
an object includes a bright sky line, this normalize_region
parameter can be used to obtain a twilight flat image from these science
observations, especially if twilight frames of the same ROTANG, ELEVAT
and temperature values are not available. In that case, the user can
also make use of the parameter continuum_region to previously
subtract the sky continuum under the bright sky line of interest. Note
that the pixels used in the normalize_region and the
continuum_region requirements correspond to those of the x-axis
of the reduced_rss.fits image.
Figure 13: Example of the master_twilightflat.fits file generated for MEGARA LCB HR-R mode.
(megara) $ ls obsid5_TwilightFlat_HR-R_work/
(megara) $ ls obsid5_TwilightFlat_HR-R_results/
The user needs to copy the master_twilightflat.fits at the
obsid5_TwilightFlat_HR-R_results/ directory to the corresponding place at
the calibration tree:
(megara) $ cp obsid5_TwilightFlat_HR-R_results/master_twilightflat.fits \
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/MasterTwilightFlat/LCB/HR-R/
Warning
Remember: for data obtained after February 2026 you should use
(megara) $ cp obsid5_TwilightFlat_HR-R_results/master_twilightflat.fits \
calibrations/MEGARA/9f3fecbf-376c-47ae-a188-313b7d829104/MasterTwilightFlat/LCB/HR-R/
Flux calibration
The flux calibration is performed by observing one or several spectrophotometric stars with the same instrument configuration that for the scientific observations. Depending on the number of standard stars observed and on the weather conditions (mainly transparency) two different types of calibration could be achieved:
Absolute-flux calibration: The weather conditions during the night should be photometric and a number of spectrophotometric standard stars at different airmasses should be observed. This allows to fully correct from DUs per CCD pixel to energy surface density (typically in AB magnitudes, Jankys or erg s-1 cm-2 Å-1) incident at the top of the atmosphere. If only one single standard star is observed (ideally at the airmass of the science object) this correction allows deriving the energy surface density hitting the telescope primary mirror exclusively, unless an atmospheric extinction curve for the observatory and that particular night is assumed (in which case the airmass could be different). In order to properly flux-calibrate scientific observations at all airmasses several stars should be observed during the night.
Relative-flux calibration: If the weather conditions are not photometric this correction only allows normalizing the DUs per CCD pixel along the spectral direction so the conversion to incident energy at the top of the atmosphere is the same at all wavelengths. In order for this calibration to be valid one must assume that the effect of the atmosphere (including atmospheric cirrus and possibly thick clouds) on the wavelength dependence of this correction is that given by the adopted atmospheric extinction curve, even if the absolute flux level is not.
In the following, the different steps to do an absolute flux calibration are described. A photometric night and one spectrophotometric standard star observation with the same airmass as the scientific observation are assumed.
The entire flux of the spectrophotometric standard star needs to be recovered, so the LCB IFU bundle must be used. The recipe MegaraLcbAcquisition is used to process and extract the spectra in the standard star observation and determine the position of the centroid of the target in the LCB field of view, around which the total flux of the star will be later recovered.
In this case, the observation-result file for determining the star
centroid is 6_LcbAdquisition.yaml, where three frames for
spectrophotometric standard star exposures are here listed:
The extraction_offset parameter can be computed as detailed in section
Wavelength Calibration.
Then the recipe is run by doing:
(megara) $ numina run 6_LcbAdquisition.yaml
Images provided in observation-result file are trimmed and corrected from
overscan, bad pixel mask (if master_bpm.fits is present in the calibration
tree), bias and dark current (if master_dark.fits is present) and corrected
from pixel-to-pixel flat if master_slitflat.fits is provided. The corrected
images are then stacked using a median. The result of the combination is saved
as an intermediate result, named reduced_image.fits.
The apertures in the 2D image are extracted, using the information in
master_traces.json (or in the model_map.json if this file is present
at the calibration tree) and the extraction_offset parameter set in
the 6_LcbAdquisition.yaml, and then it is resampled according to the
wavelength calibration in master_wlcalib.json. Then it is divided by
the master_fiberflat.fits. The resulting RSS is saved as an intermediate
result named reduced_rss.fits.
The sky is subtracted by combining the 56 fibers dedicated for this
purpose in the LCB mode. The RSS with sky subtracted is saved in a file
named final_rss.fits as a result of the recipe. Then, the centroids
around both the center of the field and the brighest spaxel are computed
using up the signal from the 3 rings of fibers (37 fibers in total)
around these two spaxels. The offsets needed to center the object
(considered to be either the centroid around the central spaxel or, more
likely, around the brightest spaxel) in the center of the LCB field are
then returned both in mm and arcsec. This information is saved in the
processing.log file at the obsid6_LcbImage_HR-R_result/ directory.
(megara) $ ls obsid6_LcbImage_HR-R_work/
(megara) $ ls obsid6_LcbImage_HR-R_results/
(megara) $ more obsid6_LcbImage_HR-R_results/processing.log
In this example, the brighest spaxel is located at [0.38366336928735895,
0.0] mm relative to the center of the field, which is, by definition
located at [0.0, 0.0] mm. The position of the centroid obtained from
the 37 fibers around this spaxels is [0.29712138659120624,
0.04342557311038363] mm. Note: these numbers depend on whether you are
using the trace map master_traces.json or the model map
master_model.json (see section Tracing fibers).
This centroid offset (in mm) is needed to recover all the flux from the standard star and to derive the instrument sensitivity curve for a particular setup using the MegaraLcbStdStar recipe.
In this case, the observation-result file was named
7_StandardStar.yaml and includes spectrophotometric standard star
individual exposures:
The extraction_offset parameter can be computed as detailed in section
Wavelength Calibration (this parameter is the same as in
6_LcbAdquisition.yaml for the same spectrophotometric standard star). The
parameter reference_spectrum includes a text file where the flux-calibrated
spectrum in AB magnitudes is provided. (the format of these files is the same
as for those found in the ESO spectrophotometric standard stars database
located at this ESO web page). The
reference_extinction parameter points to the text file with the information
to apply the atmospheric extinction correction. (for processing standard-star
observations this parameter must be defined in the
7_StandardStar.yaml file or the recipe would fail; in the case of the
MegaraLcbImage or MegarMosImage recipes this would only imply that the
processed data would not be corrected for atmospheric extinction).
By default, the DRP searches for these data files in the
data/ directory. The position parameter is the position of the
reference object, i.e. the offset in mm at the CCD detector computed with the
recipe MegaraLcbAcquisition, written in the same format and units. Finally,
the sigma_resolution parameter is the sigma of the Gaussian filter that
would be used to degrade the resolution of the MEGARA input star spectrum.
Given the high spectral resolution and low reciprocal dispersion of the MEGARA
spectra this parameter is critical to remove artifacts associated to bright
absorption lines present in the standard star spectrum, especially when the
tabulated spectra have reciprocal dispersions that can be as high as 50
Å/pixel. The parameter ignored_sky_bundles contains the fiber bundle ids to
be ignored when the sky spectrum is computed (see more details in section
LCB IFU/MOS scientific observation below).
Then the recipe is run by doing:
(megara) $ numina run 7_StandardStar.yaml
Images provided in the observation-result file are trimmed and corrected from
overscan, bad pixel mask (if master_bpm.fits is present in the calibration
tree), bias and dark current (if master_dark.fits is present) and corrected
from pixel-to-pixel flat if master_slitflat.fits is provided. The corrected
images are then stacked using a median. The result of the combination is saved
as an intermediate result, named reduced_image.fits.
The apertures in the 2D image are extracted, using the information in
master_traces.json (or in the model_map.json if this file is present
at the calibration tree) and the extraction_offset parameter set in
the 7_StandardStar.yaml, and then it is resampled according to the
wavelength calibration in master_wlcalib.json. Then, the result is
divided by the master_fiberflat.fits. The resulting RSS is saved as an
intermediate result named reduced_rss.fits.
The sky is subtracted by combining the 56 fibers dedicated for this purpose in
the LCB mode. The RSS with the sky already subtracted is saved in a file named
final_rss.fits as a result of the recipe. The flux of the star is computed
by summing the signal in 37 fibers around the spaxel closest to the offset
given in the position parameter so, finally, the star_spectrum.fits is
returned. This star spectrum is degraded with a Gaussian filter, corrected by
atmospheric extinction and compared with the reference spectrum to return the
master_sensitivity.fits, which is finally stored at the
obsid7_StandardStar_HR-R_result/ directory.
(megara) $ ls obsid7_StandardStar_HR-R_work/
(megara) $ ls obsid7_StandardStar_HR-R_results/
The user can visualize the master_sensitivity.fits curve (see Figure
14) running the python script megaratools-plot_spectrum that can
be found in the DRP distribution located at
https://github.com/guaix-ucm/megara-tools (see section MEGARA Tools).
(megara) $ megaratools-plot_spectrum -s obsid7_StandardStar_HR-R_results/master_sensitivity.fits
Figure 14: Example of sensitivity curve for MEGARA HR-R VPH. The spectral ranges defined by keywords WAVLIMM1-2 and WAVELIMF1-2 are shown as cyan and dashed brown lines, respectively (see text for details).
The user needs to copy the file master_sensitivity.fits to the calibration
tree:
(megara) $ cp obsid7_StandardStar_HR-R_results/master_sensitivity.fits \
calibrations/MEGARA/ca3558e3-e50d-4bbc-86bd-da50a0998a48/MasterSensitivity/LCB/HR-R/
Warning
Remember: for data obtained after February 2026 you should use
(megara) $ cp obsid7_StandardStar_HR-R_results/master_sensitivity.fits \
calibrations/MEGARA/9f3fecbf-376c-47ae-a188-313b7d829104/MasterSensitivity/LCB/HR-R/
It is worth noting that the master_sensitivity.fits file includes on
its header the information on the spectral ranges that are valid in
terms of spectral coverage both in pixels and wavelength for all, ranges
covered in at least one fiber (PIXLIMR1-2 and WAVLIMR1-2), all fibers
(PIXLIMM1-2 and WAVLIMM1-2) and with a proper flux calibration
(PIXLIMF1-2 and WAVLIMF1-2) (see Table 2). The latter range is
limited by the degree of smoothing applied to the sensitivity curve. The
WAVLIMM1-2 and WAVELIMF1-2 ranges are shown in Figure 14 using cyan
and dashed brown lines, respectively.
Keyword |
Meaning |
Keyword |
Meaning |
|---|---|---|---|
(keywords in pixels) |
(keywords in Ångstroms) |
||
PIXLIMR1 |
Start of region with at least one fiber |
WAVLIMR1 |
Start of region with at least one fiber |
PIXLIMR2 |
End of region with at least one fiber |
WAVLIMR2 |
End of region with at least one fiber |
PIXLIMM1 |
Start of region with all fibers |
WAVLIMM1 |
Start of region with all fibers |
PIXLIMM2 |
End of region with all fibers |
WAVLIMM2 |
End of region with all fibers |
PIXLIMF1 |
Start of valid flux calibration |
WAVLIMF1 |
Start of valid flux calibration |
PIXLIMF2 |
End of valid flux calibration |
WAVLIMF2 |
End of valid flux calibration |
Table 2: Keywords included in the master_sensitivity.fits file
regarding the wavelength coverage of at least one fiber (PIXLIMR1-2 and
WAVLIMR1-2), all fibers (PIXLIMM1-2 and WAVLIMM1-2) and with proper flux
calibration in all fibers (PIXLIMF1-2 and WAVLIMF1-2).
LCB IFU/MOS scientific observation
Once all the calibrations files are derived and copied at the corresponding calibration directories, the user can reduce the corresponding scientific observations with recipes MegaraLcbImage or MegarMosImage depending on the observing mode (the LCB IFU or the MOS).
In this case, the observation-result files are named 8_LcbImage.yaml for
the LCB and 8_MosImage.yaml for the MOS mode, and include a list of all the
frames obtained for the target. The extraction_offset parameter can be
computed as detailed in section Wavelength Calibration. The
reference_extinction parameter can be provided here if it is not at the
default calibration directory. The parameter ignored_sky_bundles contains
the sky bundle ids to be ignored when the sky spectrum is computed (see sample
.yaml file below). In the case of LCB observing mode, the dedicated sky-bundles
have, by default, all ids in the range 93-100. These bundles (sorted in blocks
of seven consecutive fibers) correspond to the individual fiber ids and
position on the sky (for instrument PA set to zero, i.e. NE) listed in Table
below.
Sky-bundle id |
Sky-fibers ids in each bundle |
On-sky orientation for IPA=0º |
Distance to the LCB center |
|---|---|---|---|
93 |
22, 23, 24, 25, 26, 27, 28 |
NE |
2.5 arcmin |
94 |
57, 58, 59, 60, 61, 62, 63 |
E |
1.75 arcmin |
95 |
134, 135, 136, 137, 138, 139, 140 |
N |
1.75 arcmin |
96 |
267, 268, 269, 270, 271, 272, 273 |
SE |
2.5 arcmin |
97 |
351, 352, 353, 354, 355, 356, 357 |
NW |
2.5 arcmin |
98 |
484, 485, 486, 487, 488, 489, 490 |
S |
1.75 arcmin |
99 |
561, 562, 563, 564, 565, 566 |
W |
1.75 arcmin |
100 |
567, 596, 597, 598, 599, 600, 601, 602 |
SW |
2.5 arcmin |
Table 3: Sky bundles: The first column identifies the sky-bundle id, while the second column indicates which fibers (listed by fiber id) are included in each sky bundle. The orientation (for an instrument Position Angle of 0º; i.e. NE) and distance to the LCB center of each bundle is included in the third and fourth columns, respectively.
In case MOS observing mode, sky-bundles should have been previously selected by the user for that purpose when preparing the observation with FMAT tool. If no sky-bundles are identified the DRP will not perform any sky subtraction to the target data.
The content of the 8_LcbImage.yaml file would be the following:
1id: 8_LcbImage_HR-R_M15
2mode: MegaraLcbImage
3instrument: MEGARA
4frames:
5 - 0001309955-20170822-MEGARA-MegaraLcbAcquisition.fits
6 - 0001309956-20170822-MEGARA-MegaraLcbAcquisition.fits
7 - 0001309957-20170822-MEGARA-MegaraLcbAcquisition.fits
8requirements:
9 extraction_offset: [+6.5]
10 ignored_sky_bundles: [93,95,98]
Then the recipe is run by doing:
(megara) $ numina run 8_LcbImage.yaml
Images provided in the observation-result file are trimmed and corrected
from overscan, bad pixel mask (if master_bpm.fits is present in the
calibration tree), bias and
dark current (if master_dark.fits is present) and corrected from
pixel-to-pixel flat if master_slitflat.fits is provided. The corrected
images are then stacked using a median. The result of the combination is
saved as an intermediate result, named reduced_image.fits.
The apertures in the 2D image are extracted, using the information in
master_traces.json (or in the model_map.json if this file is present
at the calibration tree) and the extraction_offset parameter set in
the 8_LcbImage.yaml. These are then resampled according to the
wavelength calibration in master_wlcalib.json. Then, the result is
divided by the master_fiberflat.fits. The resulting RSS is saved as an
intermediate result named reduced_rss.fits.
The sky is subtracted by combining the 56 fibers (except the fibers
listed in the ignored_sky_bundles parameter) dedicated for this
purpose in the LCB mode. In case MOS observing mode, the sky is
subtracted combining the signal of the fiber bundles (SKY bundles)
selected by the user when preparing the MOS observation. The RSS with
sky subtracted is saved in a file named final_rss.fits as a result
of the recipe.
If a master_sensitivity.fits is provided (optional), RSS products will be
flux calibrated. If reference_extinction is provided (optional),
final_rss.fits and reduced_rss.fits will be extinction corrected.
Notice that sky_rss.fits is not corrected for extinction.
(megara) $ ls obsid8_LcbImage_HR-R_M15_work/
(megara) $ ls obsid8_LcbImage_HR-R_M15_results/
Figure 15: Example of the final_rss.fits (sky subtracted, wavelength
and flux calibrated) file for object M15 in the HR-R setup and the LCB
observing mode.
The following is an example of the products for M71 MOS observing mode data reduction:
(megara) $ ls obsid8_MosImage_LR-R_M71_work/
(megara) $ ls obsid8_MosImage_LR-R_M71_results/
Figure 16: Example of the final_rss.fits (sky subtracted,
wavelength and flux calibrated) file for object M71 with the LR-R setup
and the MOS observing mode.
The user has also the option of running these recipes without performing any flux calibration. In order to do that one can simply add the following lines (shown highlighted below) in the corresponding YAML file:
1id: 8_LcbImage_HR-R_M15
2mode: MegaraLcbImage
3instrument: MEGARA
4frames:
5 - 0001309955-20170822-MEGARA-MegaraLcbAcquisition.fits
6 - 0001309956-20170822-MEGARA-MegaraLcbAcquisition.fits
7 - 0001309957-20170822-MEGARA-MegaraLcbAcquisition.fits
8requirements:
9 extraction_offset: [+6.5]
10 reference_extinction: null
11 master_sensitivity: null
12 ignored_sky_bundles: [93,95,98]