opticam.photometers =================== .. py:module:: opticam.photometers Classes ------- .. autoapisummary:: opticam.photometers.BasePhotometer opticam.photometers.AperturePhotometer opticam.photometers.OptimalPhotometer Functions --------- .. autoapisummary:: opticam.photometers.get_optimal_weights opticam.photometers.get_optimal_flux_and_error opticam.photometers.get_growth_curve Module Contents --------------- .. py:class:: BasePhotometer(forced = False, source_matching_tolerance = 5.0, local_background_estimator = None) Bases: :py:obj:`abc.ABC` Base class for performing photometry on OPTICAM catalogues. .. py:attribute:: forced :value: False .. py:attribute:: source_matching_tolerance :value: 5.0 .. py:attribute:: local_background_estimator :value: None .. py:method:: compute(image, bias_var, dark_var, flat_var, background_rms, cat_coords, image_coords, psf_params, read_noise) :abstractmethod: Compute the fluxes of the catalogued sources from the given image. Parameters ---------- image : NDArray The image. If `self.local_background_estimator` is undefined, this image will be background subtracted. bias_var : float | NDArray The bias correction variance term. dark_var : float | NDArray The dark noise correction variance term. flat_var : float | NDArray The flat-field correction variance term. background_rms : NDArray | None The background RMS. May be `None` if `self.local_background_estimator` is defined. cat_coords : NDArray The source coordinates in the catalogue. image_coords : NDArray | None The source coordinates in the image. If `match_sources` is True, this will be used to match sources in the image to sources in the catalogue. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). read_noise : float The detector's read noise. Returns ------- Dict[str, List] The photometry results. .. py:method:: get_position(cat_coords, image_coords, source_index, psf_params) Get the position of a source in an image. Parameters ---------- cat_coords : NDArray The source coordinates in the catalogue. image_coords : NDArray | None The source coordinates in the image. source_index : int The source index. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- NDArray The source coordinates. .. py:method:: get_closest_source(cat_coords, image_coords, source_index, psf_params) Given a source, find the closest source in the catalogue. Parameters ---------- cat_coords : NDArray The source coordinates in the catalogue. image_coords : NDArray | None The source coordinates in the image. source_index : int The source index. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- NDArray | None The coordinates of the closest source. .. py:method:: define_results_dict() Define a results dictionary for the photometer depending on whether `local_background_estimator` is defined. Returns ------- Dict[str, List] The results dictionary with keys 'flux', 'flux_err'. If `local_background_estimator` is defined, the dictionary will also contain 'bkg' and 'bkg_err'. .. py:method:: pad_results_dict(results) Pad the results dictionary with None values for flux and flux error, and background and background error if `local_background_estimator' is defined. This is used when a source cannot be matched or its position is invalid. Parameters ---------- results : Dict[str, List] The results dictionary to pad. Returns ------- Dict[str, List] The padded results dictionary. .. py:method:: populate_results_dict(results, phot_function, image, bias_var, dark_var, flat_var, background_rms, position, psf_params, read_noise) Populate the results dictionary with the computed flux, flux error, and background (if applicable) using the provided photometry function. Parameters ---------- results : Dict[str, List] The results dictionary to populate. phot_function : Callable The photometry function to use for computing the flux and flux error. This function should take the image, image error, position, and PSF parameters as arguments and return the flux and flux error, and optionally the background and background error if `local_background_estimator` is defined. image : NDArray The image. bias_var : float | NDArray The bias correction variance term. dark_var : float | NDArray The dark noise correction variance term. flat_var : float | NDArray The flat-field correction variance term. background_rms : NDArray | None The background RMS. May be `None` if `self.local_background_estimator` is defined. position : NDArray The position of the source in the image. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). read_noise : float The detector's read noise. Returns ------- Dict[str, List] The updated results dictionary with the computed flux, flux error, and background (if applicable). .. py:method:: get_label() Get the label of the photometer for labelling output. Returns ------- str The label. .. py:class:: AperturePhotometer(semimajor_axis = None, semiminor_axis = None, orientation = None, forced = False, source_matching_tolerance = 5.0, local_background_estimator = None) Bases: :py:obj:`BasePhotometer` A photometer for performing aperture photometry. .. py:attribute:: semimajor_axis :value: None .. py:attribute:: semiminor_axis :value: None .. py:attribute:: orientation :value: None .. py:method:: compute(image, bias_var, dark_var, flat_var, background_rms, cat_coords, image_coords, psf_params, read_noise) Compute the fluxes of the catalogued sources from the given image. Parameters ---------- image : NDArray The image. If `self.local_background_estimator` is undefined, this image will be background subtracted. bias_var : float | NDArray The bias correction variance term. dark_var : float | NDArray The dark noise correction variance term. flat_var : float | NDArray The flat-field correction variance term scaled by the square of the calibrated image. background_rms : NDArray | None The background RMS. May be `None` if `self.local_background_estimator` is defined. cat_coords : NDArray The source coordinates in the catalogue. image_coords : NDArray | None The source coordinates in the image. If `match_sources` is True, this will be used to match sources in the image to sources in the catalogue. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). read_noise : float The detector's read noise. Returns ------- Dict[str, List] The photometry results. .. py:method:: compute_aperture_flux(image, bias_var, dark_var, flat_var, background_rms, position, psf_params, read_noise) Compute the aperture flux of a source in the image. Parameters ---------- image : NDArray The image. bias_var : float | NDArray The bias correction variance term. dark_var : float | NDArray The dark noise correction variance term. flat_var : float | NDArray The flat-field correction variance term scaled by the square of the calibrated image. background_rms : NDArray | None The background RMS. May be `None` if `self.local_background_estimator` is defined. position : NDArray The position of the source. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). read_noise : float The instrument's read noise. Returns ------- Tuple[float, float] | Tuple[float, float, float, float, float] The flux and its error. If `local_background_estimator` is defined, the local background and its error are also returned. .. py:method:: get_aperture(position, psf_params) .. py:method:: get_aperture_area(psf_params) Get the area of the aperture. Parameters ---------- psf_params : Dict[str, float], The PSF parameters. Returns ------- float The area of the aperture. .. py:class:: OptimalPhotometer(forced = False, source_matching_tolerance = 5.0, local_background_estimator = None) Bases: :py:obj:`BasePhotometer` A photometer that implements the optimal photometry method described in Naylor 1998, MNRAS, 296, 339-346. .. py:method:: compute(image, bias_var, dark_var, flat_var, background_rms, cat_coords, image_coords, psf_params, read_noise) Compute the fluxes of the catalogued sources from the given image. Parameters ---------- image : NDArray The image. If `self.local_background_estimator` is undefined, this image will be background subtracted. bias_var : float | NDArray The bias correction variance term. dark_var : float | NDArray The dark noise correction variance term. flat_var : float | NDArray The flat-field correction variance term scaled by the square of the calibrated image. background_rms : NDArray | None The background RMS. May be `None` if `self.local_background_estimator` is defined. cat_coords : NDArray The source coordinates in the catalogue. image_coords : NDArray | None The source coordinates in the image. If `match_sources` is True, this will be used to match sources in the image to sources in the catalogue. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). read_noise : float The detector's read noise. Returns ------- Dict[str, List] The photometry results. .. py:method:: compute_optimal_flux(image, bias_var, dark_var, flat_var, background_rms, position, psf_params, read_noise) Compute the optimal flux of a source in the image as described in Naylor 1998, MNRAS, 296, 339-346. Parameters ---------- image : NDArray The image. bias_var : float | NDArray The bias correction variance term. dark_var : float | NDArray The dark noise correction variance term. flat_var : float | NDArray The flat-field correction variance term scaled by the square of the calibrated image. background_rms : NDArray | None The background RMS. May be `None` if `self.local_background_estimator` is defined. position : NDArray The position of the source in the image, given as (y, x) coordinates. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). read_noise : float The instrument's read noise. Returns ------- Tuple[float, float] | Tuple[float, float, float, float] The flux and flux error. If `local_background_estimator` is defined, the background and its error are also returned. .. py:function:: get_optimal_weights(var, position, psf_major, psf_minor, psf_orientation) Compute the optimal weight for each pixel in an image. Parameters ---------- var : NDArray[np.float64] The variance image. position : NDArray[np.float64] The position of the source. psf_major : float The semi-major axis of the PSF. psf_minor : float The semi-minor axis of the PSF. psf_orientation : float The orientation of the PSF in degrees. Returns ------- Tuple[NDArray[np.float64], float] The weights and the normalisation constant. .. py:function:: get_optimal_flux_and_error(image, bias_var, dark_var, flat_var, background_rms, read_noise, position, psf_params) Compute the optimal flux and its error. Parameters ---------- image : NDArray[np.float64] The background-subtracted image. bias_var : float | NDArray The bias correction variance term. dark_var : float | NDArray The dark noise correction variance term. flat_var : float | NDArray The flat-field correction variance term scaled by the square of the calibrated image. background_rms : float | NDArray[np.float64] The background RMS. May be a scalar value or an `NDArray` with the same shape as `image`. read_noise : float The instrument's read noise. position : NDArray[np.float64] The source position [x, y]. psf_params : Dict[str, float] The PSF parameters. Returns ------- Tuple[float, float] The flux and its corresponding error. .. py:function:: get_growth_curve(image, x_centroid, y_centroid, r_max) Compute the growth curve for a point in an image. Parameters ---------- image : NDArray The image. x_centroid : float The x centroid of the point. y_centroid : float The y centroid of the point. r_max : int The maximum radius in pixels. Returns ------- Tuple[NDArray, NDArray] _description_