corgidrp.fluxcal#

Attributes#

`calspec_names`
`calspec_url`

Functions#

`get_calspec_file`(star_name)	look up the calspec fits file name in the names dict and look for
`get_filter_name`(image)	return the name of the transmission curve csv file of used color filter
`read_filter_curve`(filter_filename)	read the transmission curve csv file of the color filters
`read_cal_spec`(calspec_file, filter_wavelength)	read the calspec flux density data interpolated on the wavelength grid of the transmission curve
`calculate_band_flux`(filter_curve, calspec_flux, ...)	calculate the average band flux of a calspec source in the filter band, see convention A in Gordon et al. (2022)
`calculate_effective_lambda`(filter_curve, calspec_flux, ...)	calculate the effective wavelength of a calspec source in the filter band, see convention A in Gordon et al. (2022)
`calculate_pivot_lambda`(filter_curve, filter_wavelength)	calculate the reference pivot wavelength of the filter band, see convention B in Gordon et al. (2022)
`calculate_flux_ref`(filter_wavelength, calspec_flux, ...)	calculate the flux at the reference wavelength of the filter band
`calculate_vega_mag`(source_flux, filter_file)	determine the apparent Vega magnitude of the source with known flux in CALSPEC units erg/(s * cm^2 *AA)
`compute_color_cor`(filter_curve, filter_wavelength, ...)	Compute the color correction factor K given the filter bandpass, reference spectrum (CALSPEC),
`calculate_band_irradiance`(filter_curve, calspec_flux, ...)	calculate the integrated band flux, irradiance of a calspec source in the filter band
`aper_phot`(image, encircled_radius[, frac_enc_energy, ...])	Returns the flux in photo-electrons of a point source, either by placing an aperture using a
`phot_by_gauss2d_fit`(image, fwhm[, fit_shape, ...])	Returns the flux in photo-electrons using a 2D Gaussian fit. Finds the star
`calibrate_fluxcal_aper`(dataset_or_image[, ...])	fills the FluxcalFactors calibration product values for one filter band,
`calibrate_pol_fluxcal_aper`(dataset_or_image[, ...])	Same overall process as calibrate_fluxcal_aper, adapted for polarimetric images
`measure_aper_flux_pol`(image[, image_center_x, ...])	Measure the individual flux from both polarized images in a polarimetric observation
`calibrate_fluxcal_gauss2d`(dataset_or_image[, ...])	fills the FluxcalFactors calibration product values for one filter band,

Module Contents#

corgidrp.fluxcal.calspec_names[source]#

corgidrp.fluxcal.calspec_url = 'https://archive.stsci.edu/hlsps/reference-atlases/cdbs/current_calspec/'[source]#

corgidrp.fluxcal.get_calspec_file(star_name)[source]#

look up the calspec fits file name in the names dict and look for the corresponding file in the .corgidrp/ calspec_data. If not available download the corresponding CALSPEC fits file and return the file path

Parameters:: star_name (str)
Returns:: file path str: fits file name
Return type:: str

corgidrp.fluxcal.get_filter_name(image)[source]#

return the name of the transmission curve csv file of used color filter

Parameters:: image (corgidrp.image) – image of the observed calibration star
Returns:: filepath of the selected filter curve
Return type:: str

corgidrp.fluxcal.read_filter_curve(filter_filename)[source]#

read the transmission curve csv file of the color filters

Parameters:: filter_filename (str) – file name of the transmission curve data
Returns:: wavelength in unit Angstroem transmission (np.array): transmission of the filter < 1
Return type:: lambda_nm (np.array)

corgidrp.fluxcal.read_cal_spec(calspec_file, filter_wavelength)[source]#

read the calspec flux density data interpolated on the wavelength grid of the transmission curve

Parameters:

calspec_file (str) – file path to the CALSPEC fits file
filter_wavelength (np.array) – wavelength grid of the transmission curve in unit Angstroem

Returns:

flux density in Jy interpolated on the wavelength grid of the transmission curve in CALSPEC units erg/(s * cm^2 * AA)

Return type:

np.array

corgidrp.fluxcal.calculate_band_flux(filter_curve, calspec_flux, filter_wavelength)[source]#

calculate the average band flux of a calspec source in the filter band, see convention A in Gordon et al. (2022) TBC if needed at all

Parameters:

filter_curve (np.array) – filter transmission curve over the filter_wavelength
calspec_flux (np.array) – converted flux in units of erg/(s*cm^2*AA) of the calspec source in the filter band
filter_wavelength (np.array) – wavelengths in units Angstroem in the filter band

Returns:

average band flux of the calspec star in unit erg/(s*cm^2*AA)

Return type:

float

corgidrp.fluxcal.calculate_effective_lambda(filter_curve, calspec_flux, filter_wavelength)[source]#

calculate the effective wavelength of a calspec source in the filter band, see convention A in Gordon et al. (2022) TBC if needed at all

Parameters:

filter_curve (np.array) – filter transmission curve over the filter_wavelength
calspec_flux (np.array) – converted flux in units of the calspec source in the filter band
filter_wavelength (np.array) – wavelengths in units nm in the filter band

Returns:

effective wavelength in unit Angstroem

Return type:

float

corgidrp.fluxcal.calculate_pivot_lambda(filter_curve, filter_wavelength)[source]#

calculate the reference pivot wavelength of the filter band, see convention B in Gordon et al. (2022)

Parameters:

filter_curve (np.array) – filter transmission curve over the filter_wavelength
filter_wavelength – wavelengths in unit Angstroem in the filter band

corgidrp.fluxcal.calculate_flux_ref(filter_wavelength, calspec_flux, wave_ref)[source]#

calculate the flux at the reference wavelength of the filter band

Parameters:

filter_wavelength (np.array) – wavelengths in unit Angstroem in the filter band
calspec_flux (np.array) – converted flux in units of the calspec source in the filter band
wave_ref (float) – reference wavelength in unit Angstroem

Returns:

flux at reference wavelength in unit erg/(s*cm^2*AA)

Return type:

float

corgidrp.fluxcal.calculate_vega_mag(source_flux, filter_file)[source]#

determine the apparent Vega magnitude of the source with known flux in CALSPEC units erg/(s * cm^2 *AA) in the used filter band.

Parameters:

source_flux (float) – source flux usually determined by applying the FluxcalFactor
filter_file (str) – name of the file with the transmission data of the corresponding color filter

Returns:

the apparent VEGA magnitude

Return type:

float

corgidrp.fluxcal.compute_color_cor(filter_curve, filter_wavelength, flux_ref, wave_ref, flux_source)[source]#

Compute the color correction factor K given the filter bandpass, reference spectrum (CALSPEC), and source spectrum model. To use this color correction, divide the flux density for a band by K. Such color corrections are needed to compute the correct flux density at the reference wavelength for a source with the flux_source spectral shape in the photometric convention that provides the flux density at a reference wavelength (convention B, see Gordon et al. 2022, The Astronomical Journal 163:267, for details). Thus the flux density value found by applying the calibration factor on the found detected electrons of an arbitrary source should be divided by K (for the appropriate filter and spectral shape) to produce the flux density at the reference wavelength of the filter. The color correction adjusts the calibration factor to align the reference spectral shape with the current source, which results in the correct flux density at the reference wavelength.

Args: filter_curve (np.array): transmission of the filter bandpass filter_wavelength (np.array): the wavelengths of the filter bandpass, flux_ref, and flux_source in unit Angstroem flux_ref (np.array): reference flux density F(lambda) as a function of wavelength wave_ref (float): reference wavelength in unit Angstroem flux_source (np.array): source flux density F(lambda) as a function of wavelength in CALSPEC unit erg/(s * cm^2 * AA)

Returns:: color correction factor K
Return type:: float

corgidrp.fluxcal.calculate_band_irradiance(filter_curve, calspec_flux, filter_wavelength)[source]#

calculate the integrated band flux, irradiance of a calspec source in the filter band to determine the apparent magnitude

Parameters:

filter_curve (np.array) – filter transmission curve over the filter_wavelength
calspec_flux (np.array) – converted flux in units of erg/(s*cm^2*AA) of the calspec source in the filter band
filter_wavelength (np.array) – wavelengths in units Angstroem in the filter band

Returns:

band irradiance of the calspec star in unit erg/(s*cm^2)

Return type:

float

corgidrp.fluxcal.aper_phot(image, encircled_radius, frac_enc_energy=1.0, method='subpixel', subpixels=5, background_sub=False, r_in=5, r_out=10, centering_method='xy', centroid_roi_radius=5, centering_initial_guess=None)[source]#

Returns the flux in photo-electrons of a point source, either by placing an aperture using a: centroiding method, or by using WCS information.

Background subtraction can be done optionally using a user defined circular annulus.

Parameters:

image (corgidrp.data.Image) – combined source exposure image
encircled_radius (float) – pixel radius of the circular aperture to sum the flux
frac_enc_energy (float) – fraction of encircled energy inside the encircled_radius of the PSF, inverse aperture correction, 0…1
method (str) – {‘exact’, ‘center’, ‘subpixel’}, The method used to determine the overlap of the aperture on the pixel grid,
https (default is 'exact'. For detailed description see) – //photutils.readthedocs.io/en/stable/api/photutils.aperture.CircularAnnulus.html
subpixels (int) – For the ‘subpixel’ method, resample pixels by this factor in each dimension. That is, each pixel is divided into subpixels**2 subpixels. This keyword is ignored unless method=’subpixel’, default is 5
background_sub (boolean) – background can be determine from a circular annulus (default: False).
r_in (float) – inner radius of circular annulus in pixels, (default: 5)
r_out (float) – outer radius of circular annulus in pixels, (default: 10)
centering_method (str) – ‘xy’ for centroiding or ‘wcs’ for WCS-based centering.
centroid_roi_radius (int or float) – Half-size of the box around the peak, in pixels. Adjust based on desired λ/D.
centering_initial_guess (tuple) – (Optional) (x,y) initial guess to perform centroiding.

Returns:

(flux, flux_err) or (flux, flux_err, back) if background_sub is True.

Return type:

tuple

corgidrp.fluxcal.phot_by_gauss2d_fit(image, fwhm, fit_shape=None, background_sub=False, r_in=5, r_out=10, centering_method='xy', centroid_roi_radius=5, centering_initial_guess=None)[source]#

Returns the flux in photo-electrons using a 2D Gaussian fit. Finds the star: center either by placing an aperture using a centroiding method, or by using WCS information.

Allows optional background subtraction and selection of centering method.

Parameters:

image (corgidrp.data.Image) – the source image.
fwhm (float) – Estimated full-width at half maximum.
fit_shape (int or tuple, optional) – Fitting region shape. If a scalar, then it is assumed to be a square. If None, then the shape of the input ‘data’. It must be an odd value and should be much bigger than fwhm.
background_sub (bool) – If True, subtract background.
r_in (float) – Inner annulus radius.
r_out (float) – Outer annulus radius.
centering_method (str) – ‘xy’ or ‘wcs’ centering.
centroid_roi_radius (int or float) – Half-size of the box around the peak, in pixels. Adjust based on desired λ/D.
centering_initial_guess (tuple) – (Optional) (x,y) initial guess to perform centroiding.

Returns:

(flux, flux_err)

Return type:

tuple

corgidrp.fluxcal.calibrate_fluxcal_aper(dataset_or_image, calspec_file=None, flux_or_irr='flux', phot_kwargs=None)[source]#

fills the FluxcalFactors calibration product values for one filter band, calculates the flux calibration factors by aperture photometry. The band flux values are divided by the found photoelectrons/s. Propagates also errors to flux calibration factor calfile. Background subtraction can be done optionally using a user defined circular annulus.

The photometry parameters are controlled via the phot_kwargs dictionary. Defaults are provided below if these parameters are not defined. Accepted keywords:

‘encircled_radius’ (float): The radius of the circular aperture used for photometry. ‘frac_enc_energy’ (float): The fraction of the total flux expected to be enclosed

within the aperture. Must be in the range (0, 1].

‘method’ (str): The photometry method to use. For example, ‘subpixel’ indicates subpixel
sampling for the aperture.

‘subpixels’ (int): The number of subpixels per pixel to use in the photometry calculation
or improved resolution.

‘background_sub’ (bool): Flag indicating whether to subtract background using an annulus. ‘r_in’ (float): The inner radius of the annulus used for background estimation. ‘r_out’ (float): The outer radius of the annulus used for background estimation. ‘centering_method’ (str): The method for determining the star’s center. Options include

‘xy’ for centroiding or ‘wcs’ for WCS-based centering.

‘centroid_roi_radius’ (int or float): Half-size of the box around the peak,
in pixels. Adjust based on desired λ/D.

‘centering_initial_guess’ (tuple): (Optional) (x,y) initial guess to perform centroiding.

Parameters:

dataset_or_image (corgidrp.data.Dataset or corgidrp.data.Image) – Image(s) to compute the calibration factor. Should already be normalized for exposure time.
calspec_file (str, optional) – file path to the calspec fits file of the observed star
flux_or_irr (str, optional) – Whether flux (‘flux’) or in-band irradiance (‘irr) should be used.
phot_kwargs (dict, optional) – A dictionary of keyword arguments controlling the aperture photometry function.

Returns:

A calibration object containing the computed: flux calibration factor in (TO DO: what units should this be in)

Return type:

FluxcalFactor (corgidrp.data.FluxcalFactor)

corgidrp.fluxcal.calibrate_pol_fluxcal_aper(dataset_or_image, image_center_x=512, image_center_y=512, separation_diameter_arcsec=7.5, alignment_angle=None, calspec_file=None, flux_or_irr='flux', phot_kwargs=None)[source]#

Same overall process as calibrate_fluxcal_aper, adapted for polarimetric images from WP1 or WP2 with two apertures instead of one.

The photometry parameters are controlled via the phot_kwargs dictionary. Defaults are provided below if these parameters are not defined. Accepted keywords:

‘encircled_radius’ (float): The radius of the circular aperture used for photometry. ‘frac_enc_energy’ (float): The fraction of the total flux expected to be enclosed

within the aperture. Must be in the range (0, 1].

‘method’ (str): The photometry method to use. For example, ‘subpixel’ indicates subpixel
sampling for the aperture.

‘subpixels’ (int): The number of subpixels per pixel to use in the photometry calculation
or improved resolution.

‘background_sub’ (bool): Flag indicating whether to subtract background using an annulus. ‘r_in’ (float): The inner radius of the annulus used for background estimation. ‘r_out’ (float): The outer radius of the annulus used for background estimation. ‘centroid_roi_radius’ (int or float): Half-size of the box around the peak,

in pixels. Adjust based on desired λ/D.

Parameters:

dataset_or_image (corgidrp.data.Dataset or corgidrp.data.Image) – Image(s) to compute the calibration factor. Should already be normalized for exposure time. Images must be from polarimetric observations taken with WP1 or WP2 in the DPAM.
image_center_x (int) – X pixel coordinate of where the two wollaston spots are centered around
image_center_y (int) – Y pixel coordinate of where the two wollaston spots are centered around
separation_diameter_arcsec (optional, float) – Distance between the centers of the two polarized images on the detector in arcsec, default for Roman CGI is 7.5”
alignment_angle (optional, float) – the angle in degrees of how the two polarized images are aligned with respect to the horizontal, defaults to 0 for WP1 and 45 for WP2
calspec_file (str, optional) – file path to the calspec fits file of the observed star
flux_or_irr (str, optional) – Whether flux (‘flux’) or in-band irradiance (‘irr) should be used.
phot_kwargs (dict, optional) – A dictionary of keyword arguments controlling the aperture photometry function.

Returns:

A calibration object containing the computed: flux calibration factor in (TO DO: what units should this be in)

Return type:

FluxcalFactor (corgidrp.data.FluxcalFactor)

corgidrp.fluxcal.measure_aper_flux_pol(image, image_center_x=512, image_center_y=512, separation_diameter_arcsec=7.5, alignment_angle=None, phot_kwargs=None, pixel_scale=0.0218)[source]#

Measure the individual flux from both polarized images in a polarimetric observation using aperture photometry.

Parameters:

image (corgidrp.data.Image) – the source image.
image_center_x (int) – X pixel coordinate of where the two wollaston spots are centered around
image_center_y (int) – Y pixel coordinate of where the two wollaston spots are centered around
separation_diameter_arcsec (optional, float) – Distance between the centers of the two polarized images on the detector in arcsec, default for Roman CGI is 7.5”
alignment_angle (optional, float) – the angle in degrees of how the two polarized images are aligned with respect to the horizontal, defaults to 0 for WP1 and 45 for WP2
phot_kwargs (dict, optional) – A dictionary of keyword arguments controlling the aperture photometry function. See calibrate_pol_fluxcal_aper for accepted keywords.
pixel_scale (float) – pixel scale in arcsec/pixel, default for Roman CGI is 0.0218”/pix

Returns:

(result_beam_1, result_beam_2) where each result is either (flux, flux_err) or (flux, flux_err, back)

Return type:

tuple

corgidrp.fluxcal.calibrate_fluxcal_gauss2d(dataset_or_image, calspec_file=None, flux_or_irr='flux', phot_kwargs=None)[source]#

fills the FluxcalFactors calibration product values for one filter band, calculates the flux calibration factors by fitting a 2D Gaussian. The band flux values are divided by the found photoelectrons/s. Propagates also errors to flux calibration factor calfile. Background subtraction can be done optionally using a user defined circular annulus.

All photometry settings are provided via the phot_kwargs dictionary. Defaults are provided below if these parameters are not defined. Accepted keywords:

‘fwhm’ (float): The expected full width at half maximum. ‘fit_shape’ (int or tuple): Fitting region shape. ‘background_sub’ (bool): Flag indicating whether to subtract background using an annulus. ‘r_in’ (float): The inner radius of the annulus used for background estimation. ‘r_out’ (float): The outer radius of the annulus used for background estimation. ‘centering_method’ (str): The method for determining the star’s center. Options include

‘xy’ for centroiding or ‘wcs’ for WCS-based centering.

‘centroid_roi_radius’ (int or float): Half-size of the box around the peak,
in pixels. Adjust based on desired λ/D.

‘centering_initial_guess’ (tuple): (Optional) (x,y) initial guess to perform centroiding.

Parameters:

dataset_or_image (corgidrp.data.Dataset or corgidrp.data.Image) – Image(s) to compute the calibration factor. Should already be normalized for exposure time.
calspec_file (str, optional) – file path to the calspec fits file of the observed star
flux_or_irr (str, optional) – Whether flux (‘flux’) or in-band irradiance (‘irr) should be used.
phot_kwargs (dict, optional) – A dictionary of keyword arguments controlling the Gaussian photometry function.

Returns:

A calibration object containing the computed: flux calibration factor in (TO DO: what units should this be in)

Return type:

FluxcalFactor (corgidrp.data.FluxcalFactor)