opticam.correctors ================== .. py:module:: opticam.correctors Classes ------- .. autoapisummary:: opticam.correctors.Corrector opticam.correctors.BiasCorrector opticam.correctors.DarkNoiseCorrector opticam.correctors.FlatFieldCorrector Module Contents --------------- .. py:class:: Corrector(out_directory = None, data_directory = None, instrument = OPTICAM_MX(), rebin_factor = 1, *args, **kwargs) Bases: :py:obj:`abc.ABC` Base class for correctors. .. py:attribute:: out_directory .. py:attribute:: instrument .. py:attribute:: passed_checks :value: False .. py:attribute:: rebin_factor :value: 1 .. py:attribute:: master_images :type: dict[str, numpy.typing.NDArray[numpy.float64]] .. py:attribute:: master_variances :type: dict[str, numpy.typing.NDArray[numpy.float64]] .. py:property:: master_image_path :type: pathlib.Path | None :abstractmethod: The path to the master calibration image. Returns ------- Path | None The path to the master calibration image. .. py:method:: correct(image, *args, **kwargs) :abstractmethod: Apply the required correction to an image. Parameters ---------- image : NDArray[np.float64] The image. Returns ------- tuple[NDArray[np.float64], float | NDArray[np.float64]] The corrected image and the variance of the correction term. The variance may be a `float` (e.g., if the dark noise is calculated from the exposure-integrated dark current) or an `NDArray`. .. py:method:: create_master_images(overwrite = False, *args, **kwargs) :abstractmethod: Create the master calibration image(s). Parameters ---------- bias_corrector : BiasCorrector | None, optional The bias corrector, by default `None` (no bias corrections). overwrite : bool, optional Whether to overwrite any existing master calibration images, by default `False`. .. py:method:: _read_master_image() Read the master images from the output directory. .. py:method:: run_checks(data_files_by_key, return_errors = False) :abstractmethod: Run a series of checks on the corrector to ensure that it is compatible with the data. Parameters ---------- data_files_by_key : dict[str, list[MEFSlice]] The science image files grouped by camera:filter keys. return_errors : bool, optional Whether to return the number of errors raised, by default `False`. Returns ------- None | int If `return_errors=True`, the number of errors raised is returned. .. py:method:: _save_master_image(overwrite) Save the master images and their corresponding variances to a compressed FITS cube. Parameters ---------- overwrite : bool Whether to overwrite an existing master images file. .. py:method:: _validate_data(files) :abstractmethod: Validate the input data. Parameters ---------- files : list[MEFSlice] The input files. Returns ------- dict[str, list[MEFSlice]] The file paths to the input data separated by filter. .. py:class:: BiasCorrector(out_directory = None, data_directory = None, instrument = OPTICAM_MX(), rebin_factor = 1, *args, **kwargs) Bases: :py:obj:`Corrector` Helper clsas for performing bias corrections. .. py:property:: master_image_path :type: pathlib.Path | None The path to the master calibration image. Returns ------- Path The path to the master calibration image. .. py:method:: correct(image, camera) Subtract the bias from an image. Parameters ---------- image : NDArray[np.float64] The image. camera : str The camera that took the image. Returns ------- tuple[NDArray[np.float64], NDArray[np.float64]] The corrected image and the variance of the master bias image. Raises ------ ValueError If no bias images were found with the given filter. .. py:method:: create_master_images(overwrite = False) Create master bias images for each filter. Parameters ---------- overwrite : bool, optional Whether to overwrite the existing master bias image, by default `False`. .. py:method:: run_checks(data_files_by_key, return_errors = False) Run a series of checks on the corrector to ensure that it is compatible with the data. In this case, check the binning of the science images matches those of the bias images (ignoring self.rebin_factor) and that there are no missing filters. Parameters ---------- data_files_by_key : dict[str, list[MEFSlice] The science image files grouped by camera:filter keys. return_errors : bool, optional Whether to return the number of errors raised, by default `False`. Returns ------- None | int If `return_errors=True`, the number of errors raised is returned. Otherwise, nothing is returned. .. py:method:: _validate_data(files) Ensure that the bias images in the specified directory are valid (i.e., all use the same binning and have exposure times of 0 s). Parameters ---------- files : list[MEFSlice] The bias image files. Returns ------- dict[str, list[MEFSlice]] A dictionary containing the bias image files for each camera. .. py:class:: DarkNoiseCorrector(out_directory = None, data_directory = None, instrument = OPTICAM_MX(), rebin_factor = 1, bias_corrector = None) Bases: :py:obj:`Corrector` Helper class for performing dark noise corrections. .. py:attribute:: bias_corrector :value: None .. py:property:: master_image_path :type: pathlib.Path | None The path to the master calibration image. Returns ------- Path The path to the master calibration image. .. py:method:: correct(image, camera = None, fltr = None, key = None, dark_flux = None) Subtract the dark noise from an image. Parameters ---------- image : NDArray[np.float64] The image. camera : str The camera that took the image. fltr : str The image filter. dark_flux : float | None, optional The exposure-integrated dark current, by default `None`. If the instrument provides a measure of the dark current in the image header, this obviates the need for master darks. Returns ------- NDArray[np.float64] | tuple[NDArray[np.float64], float] The corrected image and the variance of the master dark image. Raises ------ ValueError If no dark images were found with the given filter. .. py:method:: create_master_images(overwrite = False) Create master dark images for each available filter. Parameters ---------- overwrite : bool, optional Whether to overwrite any existing master dark image, by default `False`. .. py:method:: run_checks(data_files_by_key, return_errors = False) Run a series of checks on the corrector to ensure that it is compatible with the data. In this case, check the binning of the science images matches to those of the darks (neglecting self.rebin_factor), there are no missing filters, and the exposure times of the science images matches those of the darks. Parameters ---------- data_files_by_key : dict[str, list[MEFSlice] The science image files grouped by camera:filter keys. return_errors : bool, optional Whether to return the number of errors raised, by default `False`. Returns ------- None | int If `return_errors=True`, the number of errors raised is returned. Otherwise, nothing is returned. .. py:method:: _validate_data(files) Ensure that the dark images in the specified directory are valid (i.e., all use the same binning). Parameters ---------- file_paths : list[MEFSlice] The dark image files Returns ------- dict[str, list[Path]] A dictionary containing the dark image files for each filter. .. py:class:: FlatFieldCorrector(out_directory = None, data_directory = None, instrument = OPTICAM_MX(), rebin_factor = 1, bias_corrector = None, dark_corrector = None) Bases: :py:obj:`Corrector` Helper class for performing flat-field corrections. .. py:attribute:: bias_corrector :value: None .. py:attribute:: dark_corrector :value: None .. py:property:: master_image_path :type: pathlib.Path | None The path to the master flat. Returns ------- Path The path to the master flat. .. py:method:: correct(image, camera = None, fltr = None, key = None) Correct an image for flat-fielding. Parameters ---------- image : NDArray[np.float64] The image. camera : str The camera that took the image. fltr : str The image filter. Returns ------- tuple[NDArray[np.float64], NDArray[np.float64]] The corrected image and the variance of the master flat-field image scaled by the square of the calibrated image. .. py:method:: create_master_images(overwrite = False) Create master flat-field images for each filter. Parameters ---------- bias_corrector : BiasCorrector | None, optional The bias corrector. overwrite : bool, optional Whether to overwrite the existing master flat-field image, by default `False`. .. py:method:: run_checks(data_files_by_key, return_errors = False) Run a series of checks on the corrector to ensure that it is compatible with the data. In this case, check the binning of the science images can be matched to those of the flats (accounting for self.rebin_factor), and that the there are no missing filters. Parameters ---------- data_files_by_key : dict[str, list[MEFSlice]] The science images grouped by camera:filter keys. return_errors : bool, optional Whether to return the number of errors raised, by default `False`. Returns ------- None | int If `return_errors=True`, the number of errors raised is returned. Otherwise, nothing is returned. .. py:method:: _validate_data(files) Ensure that the flat-field images in the specified directory are valid (i.e., all use the same binning). Parameters ---------- file_paths : list[MEFSlice] The flat-field image files. Returns ------- dict[str, list[MEFSlice]] A dictionary containing the paths to the flat-field image files grouped by each filter. .. py:method:: _dark_corrector_is_valid() Check that the dark images have the same exposure time as the flat-field images. Returns ------- tuple[bool, float, float] If the exposure times are equal, returns `True, 0., 0.,`. Otherwise, returns `False, flat_exposure_time, dark_exposure_time`.