corgidrp.corethroughput#

Attributes#

here

Functions#

get_cfam([cfam_name, cfam_version])

Read CFAM filter wavelength in nm and transmission.

di_over_pil_transmission([cfam_name, cfam_version])

Derives the relative transmission between the pupil lens and the imaging

get_psf_pix(dataset[, roi_radius])

Estimate the PSF positions of a set of PSF images.

get_psf_ct(dataset[, unocc_psf_norm])

Estimate the core throughput of a set of PSF images.

estimate_psf_pix_and_ct(dataset_in[, roi_radius, ...])

1090881 - Given a core throughput dataset consisting of M clean frames

generate_psf_cube(dataset_in, psf_loc[, cfam_name, ...])

Function that derives a 3-d cube of PSF images from a core throughput dataset.

generate_ct_cal(dataset_in[, roi_radius, cfam_version])

Generate the elements needed to create a core throughput calibration file.

get_1d_ct(ct_cal, frame, seps[, method])

Fetches core throughput values at specific separations from the mask center.

create_ct_map(corDataset, fpamfsamcal, ct_cal[, ...])

Create a core throughput map: Given a core throughput calibration file and

Module Contents#

corgidrp.corethroughput.here = b'.'[source]#
corgidrp.corethroughput.get_cfam(cfam_name='1F', cfam_version=0)[source]#

Read CFAM filter wavelength in nm and transmission.

Parameters:

  • cfam_name (string) – Filter in CFAM. For instance, ‘1F’, ‘4A’, ‘3B’ or ‘2C’.

  • cfam_version (int) – version number of the filters (CFAM, pupil, imaging lens).

Returns:

CFAM filter wavelength in nm and transmission.

corgidrp.corethroughput.di_over_pil_transmission(cfam_name='1F', cfam_version=0)[source]#
Derives the relative transmission between the pupil lens and the imaging

lens: trans_imaging/trans_pupil.

Multiplying the counts of the pupil image by this factor translates them into equivalent counts of the direct imaging lens.

Parameters:

  • cfam_name (string) – Filter in CFAM. For instance, ‘1F’, ‘4A’, ‘3B’ or ‘2C’.

  • cfam_version (int) – version number of the filters (CFAM, pupil, imaging lens).

Returns:

Ratio trans_imaging/trans_pupil.

corgidrp.corethroughput.get_psf_pix(dataset, roi_radius=3)[source]#

Estimate the PSF positions of a set of PSF images.

Parameters:

  • dataset (corgidrp.data.Dataset) – a collection of off-axis PSFs.

  • roi_radius (int or float) – Half-size of the box around the peak, in pixels. Adjust based on desired λ/D.

Returns:

Array of pair of values with PSFs position in (fractional) EXCAM pixels with respect to the pixel (0,0) in the PSF images

corgidrp.corethroughput.get_psf_ct(dataset, unocc_psf_norm=1)[source]#

Estimate the core throughput of a set of PSF images.

Definition of core throughput: The numerator in CT (counts above 50% peak) is measured with pupil masks (Lyot stop, SPC pupil mask) in place, DMs at dark hole solution, but no FPM.  The denominator (total stellar flux) is measured without any masks in place and an infinite aperture.

NOTE: The FPM are kept in place while measuring the CT because near the region of 6 lam/D, the FPM effects are negligible and the CT data set allows one to quantify the effect of the FPM in other areas, near the IWA and OWA, respectively.

See Journal of Astronomical Telescopes, Instruments, and Systems, Vol. 9, Issue 4, 045002 (October 2023). https://doi.org/10.1117/1.JATIS.9.4.045002 and figures 9-13 for details.

Parameters:

  • dataset (corgidrp.data.Dataset) – a collection of off-axis PSFs.

  • unocc_psf_norm (float) – sum of the 2-d array corresponding to the unocculted psf. Default: off-axis PSF are normalized to the unocculted PSF already. That is, unocc_psf_norm equals 1.

Returns:

Array of core throughput values between 0 and 1.

corgidrp.corethroughput.estimate_psf_pix_and_ct(dataset_in, roi_radius=3, cfam_version=0)[source]#

1090881 - Given a core throughput dataset consisting of M clean frames (nominally 1024x1024) taken at different FSM positions, the CTC GSW shall estimate the pixel location and core throughput of each PSF.

NOTE: the list of M clean frames may be a subset of the frames collected during core throughput data collection, to allow for the removal of outliers.

Some of the images are pupil images of the unocculted source.

Parameters:

  • dataset_in (corgidrp.data.Dataset) – A core throughput dataset consisting of M clean frames (nominally 1024x1024) taken at different FSM positions. It includes some pupil images of the unocculted source. photoelectrons / second / pixel.

  • roi_radius (int or float) – Half-size of the box around the peak, in pixels. Adjust based on desired λ/D.

  • cfam_version (int) – version number of the filters (CFAM, pupil, imaging lens).

Returns:

Array with PSF’s pixel positions. Units: EXCAM pixels

referred to the (0,0) pixel.

psf_ct (array): Array with PSF’s core throughput values. Units:

dimensionless (Values must be within 0 and 1).

Return type:

psf_pix (array)

corgidrp.corethroughput.generate_psf_cube(dataset_in, psf_loc, cfam_name='1F', cfam_version=0)[source]#

Function that derives a 3-d cube of PSF images from a core throughput dataset.

# TODO: error data cubes will be added in a release after R3.0.2

Parameters:

  • dataset_in (corgidrp.data.Dataset) – A core throughput dataset consisting of M clean frames (nominally 1024x1024) taken at different FSM positions. It includes some pupil images of the unocculted source.

  • psf_loc (array) – Array of pair of values with PSFs position in (fractional) EXCAM pixels with respect to the pixel (0,0) in the PSF images.

  • cfam_name (string) – Filter in CFAM. For instance, ‘1F’, ‘4A’, ‘3B’ or ‘2C’.

  • cfam_version (int) – version number of the filters (CFAM, pupil, imaging lens).

Returns:

3-d PSF cube of PSF images from a core throughput dataset, including their data quality, and corresponding headers as HDU units.

corgidrp.corethroughput.generate_ct_cal(dataset_in, roi_radius=3, cfam_version=0)[source]#

Generate the elements needed to create a core throughput calibration file.

A CoreThroughput calibration file has two main data arrays:

3-d cube of PSF images, e.g, a N1xN1xN array where N1= +/- 3l/D about

PSF’s centroid in EXCAM pixels. The N PSF images are the ones in the CT dataset.

N sets of (x, y, CT measurements). The (x, y) are pixel coordinates of the

PSF images in the CT dataset wrt EXCAM (0,0) pixel during core throughput observation.

Parameters:

  • dataset_in (corgidrp.data.Dataset) – A core throughput dataset consisting of M clean frames (nominally 1024x1024) taken at different FSM positions. It includes some pupil images of the unocculted source.

  • roi_radius (int or float) – Half-size of the box around the peak, in pixels. Adjust based on desired λ/D.

  • cfam_version (int) – version number of the filters (CFAM, pupil, imaging lens).

Returns:

PSF cube, data quality cube, HDU list with the CT array measurements, including the PSF locations, FPAM/FSAM positions, and corrresponding headers.

corgidrp.corethroughput.get_1d_ct(ct_cal, frame, seps, method='nearest')[source]#

Fetches core throughput values at specific separations from the mask center. Currently only the ‘nearest’ method is configured.

Parameters:

  • ct_cal (corgidrp.data.CoreThroughputCalibration) – the core throughput calibration object.

  • frame (corgidrp.data.Image) – data frame containing mask location and detector 0,0 coordinate in the header

  • seps (np.array of float) – separations (pixels from the mask center) at which to sample the CT curve.

  • method (str, optional) – Method of calculating CT at a given separation. Defaults to ‘nearest’. ‘nearest’: grabs the core throughput measured at a location nearest to the desired separation and assumes CT is radially symmetric.

Returns:

Array of shape (2,len(seps)), where the first row is the list of separations

sampled, and the second row is the ct value for each separation.

Return type:

np.array

corgidrp.corethroughput.create_ct_map(corDataset, fpamfsamcal, ct_cal, x_range=[-23, 23], y_range=[-23, 23], n_gridx=47, n_gridy=47, target_pix=None, logr=False, filepath=None, save=False)[source]#

Create a core throughput map: Given a core throughput calibration file and a coronagraphic dataset, derive 3-D list (x,y,ct) where (x,y) are some target locations on EXCAM relative to the FPM’s center and with valid values of the throughput.

The core throughmap may be saved, optionally, as a CSV file.

The creation of the core throughput map relies on InterpolateCT(), a

method of the CoreThroughputCalibration class in data.py. Valid core throughput values are within the minimum and maxium radial distance from the FPM’s center in the core throughput dataset used to generate the core throughput calibration file. Its options are inluded in the call of this method too.

If an external list of locations is not provided, a default grid of points is condidered.

Parameters:

  • corDataset (corgidrp.data.Dataset) – a dataset containing some coronagraphic observations.

  • fpamfsamcal (corgidrp.data.FpamFsamCal) – an instance of the FpamFsamCal class. That is, a FpamFsamCal calibration.

  • ct_cal (corgidrp.data.CoreThroughputCalibration) – an instance of the CoreThroughputCalibration class. That is, a core throughput calibration file.

  • x_range (array) – Two values [xmin, xmax] specifying the range of pixels to be considered. Units are EXCAM pixels measured with respect the center of the FPM. Notice that [-23,23] is approx. +/-10 l/D in band 1.

  • y_range (array) – Two values [ymin, ymax] specifying the range of pixels to be considered. Units are EXCAM pixels measured with respect the center of the FPM. Notice that [-23,23] is approx. +/-10 l/D in band 1.

  • n_gridx (int) (optional) – Number of x gridpoints.

  • n_gridy (int) (optional) – Number of y gridpoints.

  • target_pix (array) (optional) – a user-defined Mx2 array containing the pixel positions for M target pixels where the core throughput will be derived by interpolation. The target pixels are measured with respect the center of the focal plane mask in (fractional) EXCAM pixels. Default is None. In this case, a rectangular grid of pixel positions is used. Using matplotlib.pyplot, target_pix[0] is the horizontal axis (x), and target_pix[1] is the vertical axis (y).

  • logr (bool) (optional) – If True, radii are mapped into their logarithmic values before constructing the interpolant.

  • filepath (string) (optional) – String with the path and filename of the file that will store the core throughput map as a CSV file.

  • save (bool) (optionla) – Whether the core throughput map will be stored or not.

Returns:

A core throughput map with (x,y,ct) where x and y are locations on EXCAM relative to the FPM’s center with valid interpolated values of the core throughput.