corgidrp.measure_companions#

Functions#

measure_companions(host_star_image, psf_sub_image, ...)

Measure companion properties in a coronagraphic image and return a table with companion position, flux ratio, and apparent magnitude.

parse_companions(ext_hdr)

Parse companion positions from an image extension header.

measure_counts(image, phot_method, initial_xy, **kwargs)

Measure the flux counts in an image using a specified photometry method.

get_photometry_kwargs(phot_method)

Retrieve default photometry keyword arguments based on the specified method.

simplified_psf_sub(psf_frame, ct_cal, guesssep, efficiency)

TO DO: add in core throughput efficiencies?

forward_model_psf(coronagraphic_dataset, ...[, ...])

Forward model the PSF for a companion by injecting a normalized PSF into each frame and performing KLIP subtraction.

update_companion_location_in_cropped_image(image, ...)

Update the companion location in an image header after cropping, based on new host coordinates.

extract_single_frame(image[, frame_index])

Extract a single frame from a multi-frame image, including associated error and DQ arrays.

plot_dataset(dataset, title_prefix[, cmap])

Plots frames from a dataset in a grid layout using ZScale normalization.

Module Contents#

corgidrp.measure_companions.measure_companions(host_star_image, psf_sub_image, ct_cal, fpam_fsam_cal, nd_cal=None, phot_method='aperture', photometry_kwargs=None, fluxcal_factor=None, host_star_in_calspec=True, thrp_corr='L4', coronagraphic_dataset=None, refstar_dataset=None, klip_fm_kwargs=None, verbose=True, kl_mode_idx=-1, cand_locs=None)[source]#

Measure companion properties in a coronagraphic image and return a table with companion position, flux ratio, and apparent magnitude.

Parameters:

  • host_star_image (corgidrp.data.Image) – Unocculted 2-D image of the host star (potentially corrected for ND transmission)

  • psf_sub_image (corgidrp.data.Image) – PSF-subtracted image with companions.

  • ct_cal (corgidrp.data.CoreThroughputCalibration) – Core throughput calibration data.

  • fpam_fsam_cal (corgidrp.data.FpamFsamCal) – Transformation calibration data.

  • nd_cal (corgidrp.data.NDFilterSweetSpotDataset) – ND calibration if host_star_image has not been corrected for ND. If None, no correction will be done.

  • phot_method (str) – Photometry method to use (‘aperture’ or ‘gauss2d’).

  • photometry_kwargs (dict) – Dictionary of keyword arguments for photometry.

  • fluxcal_factor (corgidrp.Data.FluxcalFactor) – Flux calibration factor object.

  • host_star_in_calspec (bool) – Flag indicating whether to use host star magnitude from calspec.

  • thrp_corr (str) – How to do the algorithm throughput estimation to measure the flux. Options are: 1) “L4”, which uses the algorithm throughput calculated from L3 -> L4 processing 2) “None”, which ignorees algorithm throughput 3) “KLIP-FM”, which forward models the PSF through KLIP (requires passing in coronagraphic_dataset and refstar_dataset, if RDI). [not implemented]

  • coronagraphic_dataset (corgidrp.data.Dataset) – Dataset containing coronagraphic images.

  • refstar_dataset (corgidrp.data.Dataset) – RDI reference star dataset for PSF subtraction

  • klip_fm_kwargs (dict) – keyword arguments to pass into forward_model_psf()

  • verbose (bool) – Flag to enable verbose output.

  • kl_mode_idx (int) – Index of the KL mode to use (must match the one used for PSF subtraction). Defaults to the last KL mode.

  • cand_locs (list of tuples, optional) – Locations of known off-axis sources to measure flux. Each tuple should be of the format (sep_pix, pa_degrees). If not, the function will look in the header for detections from l4_to_tda.find_source

Returns:

Table containing companion measurements.

Return type:

result_table (astropy.table.Table)

corgidrp.measure_companions.parse_companions(ext_hdr)[source]#

Parse companion positions from an image extension header.

Parameters:

ext_hdr (dict) – Dictionary representing the image extension header.

Returns:

List of dictionaries with keys ‘id’, ‘x’, and ‘y’ for each companion.

Return type:

companions (list)

corgidrp.measure_companions.measure_counts(image, phot_method, initial_xy, **kwargs)[source]#

Measure the flux counts in an image using a specified photometry method.

Parameters:

  • image (corgidrp.data.Image) – Input image for photometry.

  • phot_method (str) – Photometry method to use (‘aperture’ or ‘gauss2d’).

  • initial_xy (tuple or None) – Initial (x, y) guess for centroiding.

  • kwargs (dict) – Arbitrary keyword arguments passed directly to the photometry method (e.g., fluxcal.phot_by_gauss2d_fit or fluxcal.aper_phot).

Returns:

Measured flux in the image. flux_err (float): Estimated error in the measured flux.

Return type:

flux (float)

corgidrp.measure_companions.get_photometry_kwargs(phot_method)[source]#

Retrieve default photometry keyword arguments based on the specified method.

Parameters:

phot_method (str) – Photometry method to use (‘aperture’ or ‘gauss2d’).

Returns:

Dictionary of default photometry keyword arguments.

Return type:

options[phot_method] (dict)

corgidrp.measure_companions.simplified_psf_sub(psf_frame, ct_cal, guesssep, efficiency)[source]#

TO DO: add in core throughput efficiencies? Perform a simplified PSF subtraction by scaling the PSF frame using a provided efficiency.

Parameters:
Returns:

Scaled PSF-subtracted image. None (NoneType): Placeholder value.

Return type:

(corgidrp.data.Image)

corgidrp.measure_companions.forward_model_psf(coronagraphic_dataset, reference_star_dataset, ct_calibration, scaled_star_psf, guesssep, guesspa, outputdir='.', fileprefix='companion_fm', numbasis=[1, 2], mode='ADI', annuli=1, subsections=1, movement=1, inject_norm='sum', method='mcmc', stamp_size=30, fwhm_guess=3.0, nwalkers=10, nburn=5, nsteps=20, numthreads=1, star_center_err=0.05, platescale=21.8, platescale_err=0.02, pa_offset=0.0, pa_uncertainty=0.1, plot_results=False, kl_mode_idx=-1)[source]#

Forward model the PSF for a companion by injecting a normalized PSF into each frame and performing KLIP subtraction.

TODO: this is not fully implemented yet.

Parameters:

  • coronagraphic_dataset (corgidrp.data.Dataset) – Dataset containing coronagraphic images.

  • reference_star_dataset (corgidrp.data.Dataset) – Dataset containing reference star images.

  • ct_calibration (corgidrp.data.CoreThroughputCalibration) – Core throughput calibration data.

  • scaled_star_psf (corgidrp.data.Image) – PSF subtracted image at the location of the companion, scaled to the host star’s brightness.

  • guesssep (float) – Estimated separation of the companion.

  • guesspa (float) – Estimated position angle (in degrees) of the companion.

  • outputdir (str) – Directory path to save output files.

  • fileprefix (str) – File prefix for output files.

  • numbasis (list) – List of KLIP modes to retain.

  • mode (str) – PSF subtraction mode (e.g., “ADI”).

  • annuli (int) – Number of annuli to use for subtraction.

  • subsections (int) – Number of subsections for subtraction.

  • movement (int) – Movement parameter for subtraction.

  • inject_norm (str) – Normalization method for PSF injection.

  • method (str) – Fitting method (e.g., “mcmc”).

  • stamp_size (int) – Size of the stamp used in forward modeling.

  • fwhm_guess (float) – Initial guess for the FWHM of the PSF.

  • nwalkers (int) – Number of MCMC walkers.

  • nburn (int) – Number of burn-in steps for MCMC.

  • nsteps (int) – Number of MCMC steps.

  • numthreads (int) – Number of threads for computation.

  • star_center_err (float) – Error in the star center location.

  • platescale (float) – Plate scale (e.g., mas/pixel).

  • platescale_err (float) – Error in the plate scale.

  • pa_offset (float) – Position angle offset.

  • pa_uncertainty (float) – Uncertainty in the position angle.

  • plot_results (bool) – Flag to enable plotting of forward modeling results.

  • kl_mode_idx (int) – Index of the KL mode to use (must match the one used for PSF subtraction).

Returns:

KLIP throughput value extracted from the subtraction. ct_value (float): Core throughput value extracted from the subtraction. klip_image (corgidrp.data.Image): Final PSF-subtracted image after forward modeling.

Return type:

kl_value (float)

corgidrp.measure_companions.update_companion_location_in_cropped_image(image, comp_keyword, old_host, new_host)[source]#

Update the companion location in an image header after cropping, based on new host coordinates.

Parameters:

  • image (corgidrp.data.Image) – Image containing companion location in its header.

  • comp_keyword (str) – Header keyword that holds the companion location.

  • old_host (tuple) – Original (x, y) coordinates of the host star.

  • new_host (tuple) – New (x, y) coordinates of the host star in the cropped image.

Returns:

Image with updated companion location in the header.

Return type:

image (corgidrp.data.Image)

corgidrp.measure_companions.extract_single_frame(image, frame_index=0)[source]#

Extract a single frame from a multi-frame image, including associated error and DQ arrays.

Parameters:

  • image (corgidrp.data.Image) – Multi-frame image object.

  • frame_index (int) – Index of the frame to extract.

Returns:

Extracted single frame image with error and DQ information.

Return type:

new_image (corgidrp.data.Image)

corgidrp.measure_companions.plot_dataset(dataset, title_prefix, cmap='plasma')[source]#

Plots frames from a dataset in a grid layout using ZScale normalization.

Function accepts either:

  • A Dataset object with a ‘frames’ attribute,

  • A list or tuple of frame objects (each having a ‘data’ attribute), or

  • A single frame object.

Parameters:

  • dataset (Dataset, list, tuple, or object) – The input dataset or frame(s).

  • title_prefix (str) – Title prefix for each subplot.

  • cmap (str) – Colormap to use for the image display.