Configuration file¶
The configuration file with the input parameters for IRDAP is shown below:
[Basic pre-processing options]
sigma_filtering = True
object_collapse_ndit = False
object_centering_method = automatic
skip_preprocessing = False
frames_to_remove = []
[Basic post-processing options]
annulus_star = automatic
annulus_background = large annulus
normalized_polarization_images = False
[Advanced pre-processing options]
# Generally do not need to be changed
center_subtract_object = True
center_param_centering = (12, None, 30000)
object_center_coordinates = automatic
object_param_centering = (60, None, 30000)
flux_centering_method = gaussian
flux_center_coordinates = (478, 522, 1504, 512)
flux_param_centering = (60, None, 30000)
flux_annulus_background = large annulus
[Advanced post-processing options]
# Generally do not need to be changed
double_difference_type = conventional
single_posang_north_up = True
The input parameters are divided into four groups:
- Basic pre-processing options
- Basic post-processing options
- Advanced pre-processing options
- Advanced post-processing options
Below we discuss for each parameter of the configuration file what it does and what the valid input options are.
Important
While the user will quite frequently have to adapt the basic options, the advanced options generally do not need to be changed.
Basic pre-processing options¶
-
sigma_filtering:
True
,False
(default =True
)If
True
, use sigma-filtering to remove bad pixels that are still in the OBJECT-, CENTER- and FLUX-frames after applying the master bad pixel map. After the sigma-filtering the frames should have no bad pixels. IfFalse
, only use the master bad pixel map to speed up the reduction. The latter is not recommended for a final reduction however, because a signficant number of bad pixels will remain in the frames.
-
object_collapse_ndit:
True
,False
(default =False
)If
True
, compute the mean over the (NDIT) frames of the OBJECT-files before sky (or background) subtraction, flat-fielding, bad pixel removal and centering to speed up the pre-processing. IfFalse
, perform the above steps for each frame and then compute the mean over the frames. The latter will result in the most accurate reduction and is recommended for a final reduction.
-
object_centering_method:
automatic
,center frames
,gaussian
,cross-correlation
,manual
(default =automatic
)Method to center the OBJECT-frames. If
center frames
, center the OBJECT-frames with the center coordinates determined from the CENTER-frames. Ifgaussian
, center the OBJECT-frames by fitting a 2D Gaussian to each frame. Ifcross-correlation
, perform the centering by fitting a 2D Gaussian to the first frame and then using cross-correlation to align (register) the other frames onto the centered first frame. Generallygaussian
yields more accurate results thancross-correlation
. Forgaussian
andcross-correlation
the determined center coordinates are plotted for each image. Ifmanual
, use fixed coordinates as defined with object_center_coordinates to center the OBJECT-frames. Ifautomatic
, center the OBJECT-frames using the CENTER-files if they exist, and fit a 2D Gaussian to each OBJECT-frame if there are no CENTER-files.In case the centering is not accurate, the advanced parameters center_subtract_object, center_param_centering, object_center_coordinates and object_param_centering can be adapted.
-
skip_preprocessing:
True
,False
(default =False
)If
True
, skip the pre-processing and only perform the post-processing of the data. This way time can be saved when tweaking the input parameters of the post-processing. Skipping the pre-processing is only possible if the data has been pre-processed before. IfFalse
, do not skip the pre-processing.
-
frames_to_remove:
list (default =
[]
)List of integers and length-2-tuples of integers indicating which files and frames not to use for the data reduction. This parameter allows the user to remove frames of bad quality and to exclude complete files from the reduction without (re)moving them from the raw subdirectory. A complete file can be removed by specifying its integer index, while a frame of a specific file can be removed by specifying a tuple
(file_index, frame_index)
. For example[2, 4, (5, 3)]
will exclude files 2 and 4 from the reduction and will remove frame 3 of file 5. If no files or frames should be removed, use an empty list[]
. The files are sorted in chronological order from oldest to newest. The file indices of each file are shown in the header overview that is created when you run IRDAP.Attention
The indices of the files and frames are 1-based, i.e. the first file or frame has index 1.
Hint
To check for frames of bad quality or frames that are not centered correctly, the user can examine the sub-images of the (pre-)processed OBJECT- and FLUX-frames that IRDAP writes to the
preprocessed
andcalibration/flux
subdirectories. Because the file and frame indices are displayed next to the sub-images, the bad frames can straightforwardly be removed by inserting the corresponding indices in the list of frames_to_remove.
Basic post-processing options¶
-
annulus_star:
automatic
,ao residuals
,star aperture
, list, tuple (default =automatic
)Annulus used to measure the polarization of the central star (or any other source in the field of view) from the Q-, I_Q-, U-, and I_U-images. This measured polarization signal is subtracted from the polarization images written to the subdirectory
reduced_star_pol_subtr
. For the most accurate results the annulus should only contain signal from the star, and no signal from for example a circumstellar disk. The measured polarization signal is affected by the subtraction of the background in the images (see annulus_background).If
ao residuals
, the annulus will be centered on the central star and be located over the AO residuals. The inner radius and width of the annulus will automatically be adapted to the filter used. Ifstar aperture
, the star polarization will be determined from a small aperture with a radius of 11 pixels located at the position of the central star. Ifautomatic
, an annulus over the AO residuals (as forao residuals
) will be used in case of coronagraphic data, and a small aperture at the position of the central star (as forstar aperture
) in case of non-coronagraphic data.Generally the user would do a first data reduction using
automatic
. If after this first reduction it appears that more control over the exact shape of the annulus is required, the user can define the annulus with a tuple of 6 parameters:- coord_center_x: x-coordinate of center (pixels)
- coord_center_y: y-coordinate of center (pixels)
- inner_radius: Inner radius (pixels)
- width: Width (pixels)
- start_angle: Start angle of annulus sector (deg)
- end_angle: End angle of annulus sector (deg)
For example
(512.5, 512.5, 60, 35, 0, 360)
will create an annulus that is centered on the central star and is located over the AO residuals in H-band.Attention
IRDAP uses the same 1-based indexed coordinates as DS9. Therefore coordinates read from DS9 can be used for the configuration file without applying any conversion.
IRDAP centers the frames at the coordinates (x, y) = (512.5, 512.5). Therefore a centered annulus will have coord_center_x and coord_center_y equal to 512.5.
Attention
start_angle and end_angle are defined with respect to the orientation of the final images with 0 deg oriented up and positive angles rotating counterclockwise. Therefore an angle of 0 deg points to the North, except when single_posang_north_up is set to
False
for observations taken in field-tracking mode with a single derotator position angle.If even more control over the shape of the annulus is required, the user can define a list of length-6-tuples. This is for instance useful to exclude signal of a circumstellar disk from the annulus.
[(512.5, 512.5, 60, 35, 15, 165), (512.5, 512.5, 60, 35, 195, 345)]
will for example create an annulus with a gap at the top and bottom each spanning 30 deg.
-
annulus_background:
large annulus
, list, tuple (default =large annulus
)Annulus used to measure and remove the background in the Q-, I_Q-, U-, and I_U-images. This background subtraction also affects the computation of the polarization of the central star (see annulus_star). For the most accurate results the annulus should not contain any signal from the star or any other source in the field of view.
If
large annulus
, the annulus will be centered on the central star and be located far away from the star with an inner radius of 360 pixels and a width of 60 pixels. In case more control over the exact shape of the annulus is required, the user can define the annulus with a (list of) length-6-tuple(s) in the same way as for annulus_star.
-
normalized_polarization_images:
True
,False
(default =False
)If
True
, create final images of degree of linear polarization, normalized Stokes q and u (see van Holstein et al. 2019) and degree and angle of linear polarization computed from q and u:- DoLP = sqrt(Q^2 + U^2) / (0.5 * (I_Q + I_U))
- q = Q / I_Q
- u = U / I_U
- AoLP_norm = 0.5 * arctan(u / q)
- DoLP_norm = sqrt(q^2 + u^2)
These additional final images are only valid if all flux in the images originates from the source of interest. This is generally the case for observations of for example solar system objects or galaxies. The images are generally not valid for observations of circumstellar disks or companions because in that case a large part of the flux in the total intensity images originates from the central star.
DoLP_norm and AoLP_norm are potentially more accurate than DoLP (above) and AoLP = 0.5 * arctan(U / Q) (as always created), especially when there are significant variations in seeing and sky transparency among the measurements. If
False
, do not create these images.
Advanced pre-processing options¶
-
center_subtract_object:
True
,False
(default =True
)If
True
, subtract the OBJECT-file(s) taken closest in time from the CENTER-file(s) before determining the center coordinates from the satellite spots. This results in a more accurate determination of the center coordinates because the background and any other sources in the field of view are suppressed. When the difference between the image orientations of the CENTER- and OBJECT-frames is large (i.e. difference in derotator position angle for field-tracking and difference in parallactic angle for pupil-tracking), the OBJECT-frame will be rotated around the initial guess of the centers as defined by object_center_coordinates before subtracting it from the CENTER-frame. IfFalse
, do not subtract the OBJECT-file(s). Parameter is ignored if no CENTER-files are used for the centering (see object_centering_method).
-
center_param_centering:
tuple (default =
(12, None, 30000)
)Tuple of 3 parameters pertaining to the fitting of the satellite spots of the the CENTER-frames with 2D Gaussians to determine the center coordinates. In case the center coordinates are not accurately determined, the 3 parameters can be adapted in addition to object_center_coordinates:
- crop_radius: Half the length of the sides of the square cropped sub-images that should each contain a satellite spot and are used to fit the 2D Gaussians to (pixels). Must be integer. object_center_coordinates gives the initial guess of the center coordinates to place the sub-images approximately at the locations of the satellite spots. If
None
, the complete frame is used for the fitting and object_center_coordinates is ignored. - sigfactor: All sub-image pixels with values smaller than sigfactor*standard deviation are replaced by random Gaussian noise to mask them for fitting the 2D Gaussian. This can be useful when there is a lot of noise in the background. If
None
, no pixels are replaced by Gaussian noise. - saturation_level: All pixels within the smallest circle encompassing the pixels with a value equal to or higher than saturation_level are ignored when fitting the 2D Gaussian. Ignoring the saturated pixels improves the accuracy of the fit. We use a circle because strongly saturated pixels in the peak of the PSF often have values lower than saturation_level. If
None
, no pixels are ignored.
center_param_centering is ignored if no CENTER-files are used for the centering (see object_centering_method).
- crop_radius: Half the length of the sides of the square cropped sub-images that should each contain a satellite spot and are used to fit the 2D Gaussians to (pixels). Must be integer. object_center_coordinates gives the initial guess of the center coordinates to place the sub-images approximately at the locations of the satellite spots. If
-
object_center_coordinates:
automatic
, tuple (default =automatic
)Tuple of 4 floats with (initial guess of) center coordinates of OBJECT-frames:
- x_left: x-coordinate of center of left frame half (pixels)
- y_left: y-coordinate of center of left frame half (pixels)
- x_right: x-coordinate of center of right frame half (pixels)
- y_right: y-coordinate of center of right frame half (pixels)
If
automatic
, object_center_coordinates is set to(478, 535, 1504, 524)
when the coronagraph N_ALC_Ks is used and to(478, 522, 1504, 512)
otherwise.Attention
IRDAP uses the same 1-based indexed coordinates as DS9. Therefore coordinates read from DS9 can be used for the configuration file without applying any conversion.
The center coordinates are defined in the complete frame, i.e. with both detector halves. Therefore x_right has a value larger than 1024 pixels.
The center coordinates of object_center_coordinates are used at various steps of the pre-processing:
- During the processing of the CENTER-files, they give the coordinates to rotate the OBJECT-frame around before subtracting it from the CENTER-frame (see center_subtract_object).
- When determining the center coordinates from the CENTER-frames, they give the initial guess of the center coordinates to place the sub-images approximately on the location of the satellite spots (see center_param_centering).
- They give the initial guess of the center coordinates when centering the OBJECT-frames by fitting 2D Gaussians or using cross-correlation (see object_centering_method and object_param_centering).
- In case object_centering_method is
manual
, they are the actual center coordinates used to center the OBJECT-frames.
-
object_param_centering:
tuple (default =
(60, None, 30000)
)Tuple of 3 parameters pertaining to the centering of the OBJECT-frames by fitting a 2D Gaussian to each frame or using cross-correlation. In case the centering is not performed accurately, the 3 parameters can be adapted in addition to object_center_coordinates (especially useful for non-coronagraphic data of multiple stars):
- crop_radius: Half the length of the sides of the square cropped sub-images used to fit the 2D Gaussians to and used for cross-correlating the images (pixels). Must be integer. The sub-image is centered on the coordinates as provided by object_center_coordinates. If
None
, the complete frame is used and object_center_coordinates is ignored. - sigfactor: see center_param_centering.
- saturation_level: see center_param_centering.
object_param_centering is only used when object_centering_method is
gaussian
orcross-correlation
.- crop_radius: Half the length of the sides of the square cropped sub-images used to fit the 2D Gaussians to and used for cross-correlating the images (pixels). Must be integer. The sub-image is centered on the coordinates as provided by object_center_coordinates. If
-
flux_centering_method:
gaussian
,manual
(default =gaussian
)Method to center the FLUX-frames. If
gaussian
, fit a 2D Gaussian to each frame. The determined center coordinates are plotted for each image. Ifmanual
, use fixed coordinates as defined with flux_center_coordinates. In case the centering is not accurate, the parameters flux_center_coordinates and flux_param_centering can be adapted.
-
flux_center_coordinates:
tuple (default =
(478, 522, 1504, 512)
)(Initial guess of) center coordinates of FLUX-frames, defined in the same way as object_center_coordinates. The center coordinates are the initial guess when centering the FLUX-frames by fitting 2D Gaussians (see flux_centering_method and flux_param_centering). In addition, in case flux_centering_method is
manual
, the center coordinates are the actual center coordinates used to center the FLUX-frames.
-
flux_param_centering:
tuple (default =
(60, None, 30000)
)Tuple of 3 parameters pertaining to the centering of the FLUX-frames by fitting a 2D Gaussian to each frame. In case the centering is not performed accurately, the 3 parameters can be adapted in addition to flux_center_coordinates (especially useful in case of multiple stars):
- crop_radius: Half the length of the sides of the square cropped sub-images used to fit the 2D Gaussians to (pixels). Must be integer. The sub-image is centered on the coordinates as provided by flux_center_coordinates. If
None
, the complete frame is used and flux_center_coordinates is ignored. - sigfactor: see center_param_centering.
- saturation_level: see center_param_centering.
flux_param_centering is only used when flux_centering_method is
gaussian
.- crop_radius: Half the length of the sides of the square cropped sub-images used to fit the 2D Gaussians to (pixels). Must be integer. The sub-image is centered on the coordinates as provided by flux_center_coordinates. If
-
flux_annulus_background:
large annulus
, list, tuple (default =large annulus
)Annulus used to remove the background in the FLUX-frames. For the most accurate results the annulus should not contain any signal from the star or any other source in the field of view. If
large annulus
, the annulus will be centered on the central star and be located far away from the star with an inner radius of 320 pixels and a width of 60 pixels. In case more control over the exact shape of the annulus is required, the user can define the annulus with a (list of) length-6-tuple(s) in the same way as for annulus_star.
Advanced post-processing options¶
-
double_difference_type:
conventional
,normalized
(default =conventional
)Type of double difference to be computed. In almost all cases one would use
conventional
. When there are large variations in atmospheric seeing and sky transparency among the measurements, usingnormalized
can suppress spurious polarization signals and improve the quality of the final images (see van Holstein et al. 2019).
-
single_posang_north_up:
True
,False
(default =True
)For observations taken in field-tracking mode with a single derotator position angle (header keyword
INS4.DROT2.POSANG
either 0 or with a fixed offset), the final images are rotated with North up ifTrue
, and kept in the orientation of the raw frames ifFalse
. In the latter case, the images are more accurate as they suffer less from interpolation errors caused by image rotation. This is useful when for example extracting the polarized surface brightness distribution of a circumstellar disk. Parameter is ignored for field-tracking observations with more than one derotator position angle or observations taken in pupil-tracking mode. In these cases the final images produced are always oriented with North up.