opticam.correctors

Classes

`Corrector`	Base class for correctors.
`BiasCorrector`	Helper clsas for performing bias corrections.
`DarkNoiseCorrector`	Helper class for performing dark noise corrections.
`FlatFieldCorrector`	Helper class for performing flat-field corrections.

Module Contents

class opticam.correctors.Corrector(out_directory=None, data_directory=None, instrument=OPTICAM_MX(), rebin_factor=1, *args, **kwargs)

Bases: abc.ABC

Base class for correctors.

Parameters:

out_directory (pathlib.Path | str | None)
data_directory (pathlib.Path | str | None)
instrument (opticam.instruments.Instrument)
rebin_factor (int)

out_directory

instrument

passed_checks = False

rebin_factor = 1

master_images: dict[str, numpy.typing.NDArray[numpy.float64]]

master_variances: dict[str, numpy.typing.NDArray[numpy.float64]]

property master_image_path: pathlib.Path | None

Abstractmethod:
Return type:: pathlib.Path | None

The path to the master calibration image.

Returns

Path | None: The path to the master calibration image.

abstractmethod correct(image, *args, **kwargs)

Apply the required correction to an image.

Parameters

imageNDArray[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.

Parameters:: image (numpy.typing.NDArray[numpy.float64])
Return type:: tuple[numpy.typing.NDArray[numpy.float64], float | numpy.typing.NDArray[numpy.float64]]

abstractmethod create_master_images(overwrite=False, *args, **kwargs)

Create the master calibration image(s).

Parameters

bias_correctorBiasCorrector | None, optional: The bias corrector, by default None (no bias corrections).
overwritebool, optional: Whether to overwrite any existing master calibration images, by default False.

Parameters:: overwrite (bool)
Return type:: None

_read_master_image()

Read the master images from the output directory.

Return type:: None

abstractmethod 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.

Parameters

data_files_by_keydict[str, list[MEFSlice]]: The science image files grouped by camera:filter keys.
return_errorsbool, 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.

Parameters:

data_files_by_key (dict[str, list[opticam.mef_slice.MEFSlice]])
return_errors (bool)

Return type:

None | int

_save_master_image(overwrite)

Save the master images and their corresponding variances to a compressed FITS cube.

Parameters

overwritebool: Whether to overwrite an existing master images file.

Parameters:: overwrite (bool)
Return type:: None

abstractmethod _validate_data(files)

Validate the input data.

Parameters

fileslist[MEFSlice]: The input files.

Returns

dict[str, list[MEFSlice]]: The file paths to the input data separated by filter.

Parameters:: files (list[opticam.mef_slice.MEFSlice])
Return type:: dict[str, list[opticam.mef_slice.MEFSlice]]

class opticam.correctors.BiasCorrector(out_directory=None, data_directory=None, instrument=OPTICAM_MX(), rebin_factor=1, *args, **kwargs)

Bases: Corrector

Helper clsas for performing bias corrections.

Parameters:

out_directory (pathlib.Path | str | None)
data_directory (pathlib.Path | str | None)
instrument (opticam.instruments.Instrument)
rebin_factor (int)

property master_image_path: pathlib.Path | None

The path to the master calibration image.

Returns

Path: The path to the master calibration image.

Return type:: pathlib.Path | None

correct(image, camera)

Subtract the bias from an image.

Parameters

imageNDArray[np.float64]: The image.
camerastr: 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.

Parameters:

image (numpy.typing.NDArray[numpy.float64])
camera (str)

Return type:

tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

create_master_images(overwrite=False)

Create master bias images for each filter.

Parameters

overwritebool, optional: Whether to overwrite the existing master bias image, by default False.

Parameters:: overwrite (bool)
Return type:: None

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_keydict[str, list[MEFSlice]: The science image files grouped by camera:filter keys.
return_errorsbool, 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.

Parameters:

data_files_by_key (dict[str, list[opticam.mef_slice.MEFSlice]])
return_errors (bool)

Return type:

None | int

_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

fileslist[MEFSlice]: The bias image files.

Returns

dict[str, list[MEFSlice]]: A dictionary containing the bias image files for each camera.

Parameters:: files (list[opticam.mef_slice.MEFSlice])
Return type:: dict[str, list[opticam.mef_slice.MEFSlice]]

class opticam.correctors.DarkNoiseCorrector(out_directory=None, data_directory=None, instrument=OPTICAM_MX(), rebin_factor=1, bias_corrector=None)

Bases: Corrector

Helper class for performing dark noise corrections.

Parameters:

out_directory (pathlib.Path | str | None)
data_directory (pathlib.Path | str | None)
instrument (opticam.instruments.Instrument)
rebin_factor (int)
bias_corrector (BiasCorrector | None)

bias_corrector = None

property master_image_path: pathlib.Path | None

The path to the master calibration image.

Returns

Path: The path to the master calibration image.

Return type:: pathlib.Path | None

correct(image, camera=None, fltr=None, key=None, dark_flux=None)

Subtract the dark noise from an image.

Parameters

imageNDArray[np.float64]: The image.
camerastr: The camera that took the image.
fltrstr: The image filter.
dark_fluxfloat | 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.

Parameters:

image (numpy.typing.NDArray[numpy.float64])
camera (str | None)
fltr (str | None)
key (str | None)
dark_flux (float | None)

Return type:

tuple[numpy.typing.NDArray[numpy.float64], float | numpy.typing.NDArray[numpy.float64]]

create_master_images(overwrite=False)

Create master dark images for each available filter.

Parameters

overwritebool, optional: Whether to overwrite any existing master dark image, by default False.

Parameters:: overwrite (bool)
Return type:: None

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_keydict[str, list[MEFSlice]: The science image files grouped by camera:filter keys.
return_errorsbool, 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.

Parameters:

data_files_by_key (dict[str, list[opticam.mef_slice.MEFSlice]])
return_errors (bool)

Return type:

None | int

_validate_data(files)

Ensure that the dark images in the specified directory are valid (i.e., all use the same binning).

Parameters

file_pathslist[MEFSlice]: The dark image files

Returns

dict[str, list[Path]]: A dictionary containing the dark image files for each filter.

Parameters:: files (list[opticam.mef_slice.MEFSlice])
Return type:: dict[str, list[opticam.mef_slice.MEFSlice]]

class opticam.correctors.FlatFieldCorrector(out_directory=None, data_directory=None, instrument=OPTICAM_MX(), rebin_factor=1, bias_corrector=None, dark_corrector=None)

Bases: Corrector

Helper class for performing flat-field corrections.

Parameters:

out_directory (pathlib.Path | str | None)
data_directory (pathlib.Path | str | None)
instrument (opticam.instruments.Instrument)
rebin_factor (int)
bias_corrector (BiasCorrector | None)
dark_corrector (DarkNoiseCorrector | None)

bias_corrector = None

dark_corrector = None

property master_image_path: pathlib.Path | None

The path to the master flat.

Returns

Path: The path to the master flat.

Return type:: pathlib.Path | None

correct(image, camera=None, fltr=None, key=None)

Correct an image for flat-fielding.

Parameters

imageNDArray[np.float64]: The image.
camerastr: The camera that took the image.
fltrstr: 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.

Parameters:

image (numpy.typing.NDArray[numpy.float64])
camera (str | None)
fltr (str | None)
key (str | None)

Return type:

tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

create_master_images(overwrite=False)

Create master flat-field images for each filter.

Parameters

bias_correctorBiasCorrector | None, optional: The bias corrector.
overwritebool, optional: Whether to overwrite the existing master flat-field image, by default False.

Parameters:: overwrite (bool)
Return type:: None

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_keydict[str, list[MEFSlice]]: The science images grouped by camera:filter keys.
return_errorsbool, 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.

Parameters:

data_files_by_key (dict[str, list[opticam.mef_slice.MEFSlice]])
return_errors (bool)

Return type:

None | int

_validate_data(files)

Ensure that the flat-field images in the specified directory are valid (i.e., all use the same binning).

Parameters

file_pathslist[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.

Parameters:: files (list[opticam.mef_slice.MEFSlice])
Return type:: dict[str, list[opticam.mef_slice.MEFSlice]]

_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.

Return type:: tuple[bool, float, float]