corgidrp.l4_to_tda#
Functions#
|
Determine the apparent Vega magnitude by comparing CALSPEC SEDs. |
|
determine the color correction factor of the observed source |
|
Flux calibrate 1-D spectroscopy spectra stored in the L4 SPEC extension. |
|
applies the slit transmission and the algorithm throughput correction (if available) |
|
Apply a core-throughput correction to a single L4 spectroscopy frame. |
|
Combine multiple 1-D spectra in a Dataset into a single spectrum. |
|
Compute the flux ratio of a single companion image relative to a single |
|
Convert the data from photoelectron unit to flux unit erg/(s * cm^2 * AA). |
|
Uses the PSF-subtracted frame and its algorithm throughput vs separation to |
|
Calculates the total number of photoelectrons/s of a point source and convert them to the flux in erg/(s * cm^2 * AA). |
|
Updates the data level to TDA (Technical Demo Analysis). Only works on L4 data. |
|
Detects sources in an image based on a specified SNR threshold and save their approximate pixel locations and SNRs into the header. |
|
Calculate the photometric zero point for a given star image. |
|
Compute polarization intensity, fractional polarization, and EVPA from Stokes maps. |
|
Compute Q_phi and U_phi from Stokes Q and U, returning an Image with shape [6, n, m]: |
Module Contents#
- corgidrp.l4_to_tda.determine_app_mag(input_data, source_star, scale_factor=1.0)[source]#
Determine the apparent Vega magnitude by comparing CALSPEC SEDs.
This function integrates the CALSPEC spectrum given by source_star through the filter bandpass of the input image(s), integrates the Vega CALSPEC spectrum through the same bandpass, and writes APP_MAG = -2.5 log10(source_irr / vega_irr) into the header. The dataset is only inspected to ensure all frames share the same filter and target. This function does not use the measured photometry/flux in input_data. To convert a measured flux into a Vega magnitude, use fluxcal.calculate_vega_mag or determine_flux.
- Parameters:
input_data (corgidrp.data.Dataset or corgidrp.data.Image) – A dataset of Images (L2b-level) or a single Image. Must be all of the same source with same filter.
source_star (str) – either the fits file path of the flux model of the observed source in CALSPEC units erg/(s * cm^2 * AA) and format or the (SIMBAD) name of a CALSPEC star
scale_factor (float) – factor applied to the flux of the calspec standard source, so that you can apply it if you have a different source with similar spectral type, but no calspec standard. Defaults to 1.
- Returns:
- A version of the input with an updated header including the apparent
magnitude.
- Return type:
mag_data (corgidrp.data.Dataset)
- corgidrp.l4_to_tda.determine_color_cor(input_dataset, ref_star, source_star)[source]#
determine the color correction factor of the observed source at the reference wavelength of the used filter band and put it into the header. We assume that each frame in the dataset was observed with the same color filter.
- Parameters:
input_dataset (corgidrp.data.Dataset) – a dataset of Images (L2b-level)
ref_star (str) – either the fits file path of the known reference flux (usually CALSPEC), or the (SIMBAD) name of a CALSPEC star
source_star (str) – either the fits file path of the flux model of the observed source in CALSPEC units erg/(s * cm^2 * AA) and format or the (SIMBAD) name of a CALSPEC star
- Returns:
- a version of the input dataset with updated header including
the reference wavelength and the color correction factor
- Return type:
- corgidrp.l4_to_tda.convert_spec_to_flux(input_dataset, fluxcal)[source]#
Flux calibrate 1-D spectroscopy spectra stored in the L4 SPEC extension. The function propagates calibration uncertainties. It applies the spectral flux calibration, if not available it can apply the fluxcal factor and color correction. Requires the input dataset to have already been core-throughput (ie SPEC header contains CTCOR=True) and slit transmission corrected (ie SPEC header contains SLITCOR=True).
- Parameters:
input_dataset (corgidrp.data.Dataset) – L4 dataset containing SPEC, SPEC_ERR, SPEC_DQ, SPEC_WAVE, and SPEC_WAVE_ERR extensions.
fluxcal (corgidrp.data.SpecFluxCal or corgidrp.data.FluxcalFactor) – wavelength dependent flux calibration or absolute flux calibration product used to convert the spectrum to absolute flux units erg/(s*cm^2*Å).
- Returns:
copy of the input dataset with the SPEC/SPEC_ERR data converted to erg/(s*cm^2*Å) and headers/history updated.
- Return type:
- corgidrp.l4_to_tda.apply_slit_transmission(input_dataset, slit_transmission)[source]#
applies the slit transmission and the algorithm throughput correction (if available) to a spectrometer input dataset of a corresponding slit observation.
- Parameters:
input_dataset (corgidrp.data.Dataset) – L4 dataset containing SPEC, SPEC_ERR, SPEC_DQ, SPEC_WAVE, and SPEC_WAVE_ERR extensions.
slit_transmission (corgidrp.data.SlitTransmission) – slit throughput calibration product, contains the (slit_map, slit_x, slit_y) tuple of a corresponding slit.
- Returns:
- copy of the input dataset with the
SPEC/SPEC_ERR data corrected by slit transmission and headers/history updated.
- Return type:
- corgidrp.l4_to_tda.apply_core_throughput_correction(frame, core_throughput_cal, fpam_fsam_cal, logr=False)[source]#
Apply a core-throughput correction to a single L4 spectroscopy frame.
- Parameters:
frame (corgidrp.data.Image) – L4 spectroscopy frame containing SPEC/SPEC_ERR HDUs.
core_throughput_cal (corgidrp.data.CoreThroughputCalibration) – calibration product providing InterpolateCT().
fpam_fsam_cal (corgidrp.data.FpamFsamCal) – calibration relating FPAM/FSAM motions to EXCAM coordinates.
logr (bool) – passed through to InterpolateCT (logarithmic radii interpolation).
- Returns:
- (ct_value, corrected_frame) where:
ct_value (float): core-throughput factor applied to the frame.
corrected_frame (corgidrp.data.Image): the corrected frame (same object as input, modified in place).
- Return type:
tuple
- corgidrp.l4_to_tda.combine_spectra(input_dataset)[source]#
Combine multiple 1-D spectra in a Dataset into a single spectrum.
This function takes a Dataset of images that each contain SPEC, SPEC_ERR and SPEC_WAVE extensions, interpolates all spectra onto a common wavelength grid, and combines them using inverse-variance weighting (1/σ^2).
- Parameters:
input_dataset (corgidrp.data.Dataset) – Dataset of Images with 1-D spectra and SPEC/SPEC_ERR/SPEC_WAVE extensions.
- Returns:
- (combined_spec, wavelength, combined_err, rotations) where:
combined_spec (ndarray): weighted spectrum on the reference grid
wavelength (ndarray): reference wavelength grid
combined_err (ndarray): 1σ uncertainty of the combined spectrum
rotations (list): list of PA_APER angles
- Return type:
tuple
- corgidrp.l4_to_tda.compute_spec_flux_ratio(host_image, companion_image)[source]#
Compute the flux ratio of a single companion image relative to a single host image. Input should already be flux calibrated and slit transmission corrected.
- Parameters:
host_image (corgidrp.data.Image) – L4 image containing the host spectrum (can be a combined/
spectrum). (a combined/ weighted)
companion_image (corgidrp.data.Image) – L4 image containing the companion spectrum (can be
spectrum).
- Returns:
- (flux_ratio, wavelength, metadata) where:
flux_ratio (numpy.ndarray): companion/host spectrum R(λ).
wavelength (numpy.ndarray): wavelength array in nm.
- metadata (dict): contains:
’rotation’: host PA_APER angle
’companion_rotation’: companion PA_APER angle
’ratio_err’: 1σ uncertainty on the flux ratio R(λ).
- Return type:
tuple
- corgidrp.l4_to_tda.convert_to_flux(input_dataset, fluxcal_factor)[source]#
Convert the data from photoelectron unit to flux unit erg/(s * cm^2 * AA).
- Parameters:
input_dataset (corgidrp.data.Dataset) – a dataset of Images
fluxcal_factor (corgidrp.data.FluxcalFactor) – flux calibration file
- Returns:
a version of the input dataset with the data in flux units
- Return type:
- corgidrp.l4_to_tda.compute_flux_ratio_noise(input_dataset, NDcalibration, unocculted_star_dataset, unocculted_star_loc=None, requested_separations=None, halfwidth=None, nsigma=1, small_sample_correction=False)[source]#
Uses the PSF-subtracted frame and its algorithm throughput vs separation to produce a calibrated n-sigma flux ratio noise curve, also accounting for the throughput of the coronagraph. It calculates flux ratio noise curve value for each radial separation from the subtracted star location, interpolating KLIP and core throughput values at these input separations. It uses a dataset of unocculted stars and ND transmission to determine the integrated flux of the Gaussian-fit star (where each frame in the dataset is assumed to correspond to the frames in the input_dataset), and an estimate of planet flux per frame of input_dataset is made by calculating the integrated flux of a Gaussian with amplitude equal to the annular noise and FWHM equal to that used for KLIP algorithm througput for each radial separation.
- Parameters:
input_dataset (corgidrp.data.Dataset) – a dataset of PSF-subtracted Images
NDcalibration (corgidrp.data.NDFilterSweetSpotDataset) – ND filter calibration
unocculted_star_dataset (corgidrp.data.Dataset) – a dataset of unocculted star Images corresponding to the Images in input_dataset. Should have the same number of frames as input_dataset (1-to-1 correspondence).
unocculted_star_loc (2-D float array, optional) – array of coordinates of the unocculted stars according to the order given in the unocculted_star_dataset. The first row of the array is for row position, and the second row is for column position. If None, the peak pixel location is used for each frame. Defaults to None.
requested_separations (float array, optional) – separations at which to compute the flux ratio noise curve. If None, the separations used for the core throughput are used (e.g., no interpolation needed). Defaults to None.
halfwidth (float, optional) – halfwidth of the annulus to use for noise calculation. If None, half of the minimum spacing between separation distances (if it isn’t uniform spacing) is used. Defaults to None.
nsigma (float, optional) – Sigma multiplier for the noise curve. E.g. nsigma=5 produces a 5-sigma contrast curve. Defaults to 1.
small_sample_correction (bool, optional) – If True, apply the small sample statistics correction from Mawet et al. (2014) using the Student’s t-distribution. Defaults to False.
- Returns:
- input dataset with an additional extension header ‘FRN_CRV’ for every frame, containing the
calibrated flux ratio noise curve as a function of radial separation. The data in that extension for a given frame is a (2+M)xN array, where: –the first row contains the separation radii in pixels –the second row containts the separation radii in milli-arcseconds (mas) –and the M rows contain the corresponding flux ratio noise curve values for the M KL mode truncations (maintaining the KL index ordering). TODO: Add uncertainty to flux ratio noise curve based on uncertainties in core throughput and algorithm throughput if those are implemented in the future.
- Return type:
- corgidrp.l4_to_tda.determine_flux(input_dataset, fluxcal_factor, photo='aperture', phot_kwargs=None)[source]#
Calculates the total number of photoelectrons/s of a point source and convert them to the flux in erg/(s * cm^2 * AA). Write the flux and corresponding error in the header. Convert the flux to Vega magnitude and write it in the header. We assume that the source is the brightest point source in the field close to the center.
- Parameters:
input_dataset (corgidrp.data.Dataset) – a dataset of Images with the source
fluxcal_factor (corgidrp.data.FluxcalFactor) – flux calibration file
photo (String) – do either aperture photometry (“aperture”) or 2DGaussian fit of the point source (“2dgauss”)
phot_kwargs (dict) – parameters of the photometry method, for details see fluxcal.aper_phot and fluxcal.phot_by_gauss_2dfit
- Returns:
a version of the input dataset with the data in flux units
- Return type:
- corgidrp.l4_to_tda.update_to_tda(input_dataset)[source]#
Updates the data level to TDA (Technical Demo Analysis). Only works on L4 data.
Currently only checks that data is at the L4 level
- Parameters:
input_dataset (corgidrp.data.Dataset) – a dataset of Images (L4-level)
- Returns:
same dataset now at TDA-level
- Return type:
- corgidrp.l4_to_tda.find_source(input_image, psf=None, fwhm=2.8, nsigma_threshold=5.0, image_without_planet=None)[source]#
Detects sources in an image based on a specified SNR threshold and save their approximate pixel locations and SNRs into the header.
- Parameters:
input_image (corgidrp.data.Image) – The input image to search for sources (L4-level).
psf (ndarray, optional) – The PSF used for detection. If None, a Gaussian approximation is created.
fwhm (float, optional) – Full-width at half-maximum of the PSF in pixels.
nsigma_threshold (float, optional) – The SNR threshold for source detection.
image_without_planet (ndarray, optional) – An image without any sources (~noise map) to make snmap more accurate.
- Returns:
A copy of the input image with the detected sources and their SNRs saved in the header.
- Return type:
- corgidrp.l4_to_tda.calculate_zero_point(image, star_name, encircled_radius, phot_kwargs=None)[source]#
Calculate the photometric zero point for a given star image.
Computes the zero point by comparing the measured photon flux from the image with the apparent magnitude determined for the star relative to Vega. If no photometry keyword arguments are provided, default values are used for the aperture photometry parameters.
- Parameters:
image (corgidrp.data.Image) – An image containing the star.
star_name (str) – The name of the star, used to determine its apparent magnitude.
encircled_radius (float) – The radius within which to sum the counts for aperture photometry.
phot_kwargs (dict, optional) – A dictionary of keyword arguments for photometry, including parameters like ‘frac_enc_energy’, ‘method’, ‘subpixels’, ‘background_sub’, ‘r_in’, ‘r_out’, ‘centering_method’, and ‘centroid_roi_radius’. Defaults to a predefined set of parameters if None.
- Returns:
The computed zero point based on the apparent magnitude and the measured counts sum.
- Return type:
zp (float)
- corgidrp.l4_to_tda.calc_pol_p_and_pa_image(input_Image)[source]#
Compute polarization intensity, fractional polarization, and EVPA from Stokes maps.
- Parameters:
input_Image (Image) – Object containing Stokes maps and uncertainties.
- Returns:
- Image object containing
data: stacked [P, p, evpa] (shape: 3 x H x W)
ext_hdr: Header with updated HISTORY
err, dq: arrays reflecting Perr, perr and evpa_err
- Return type:
- Raises:
AttributeError – If input_Image is missing data or err attributes.
ValueError – If Stokes maps I, Q, U have inconsistent shapes or insufficient slices.
- corgidrp.l4_to_tda.compute_QphiUphi(image, x_center=None, y_center=None)[source]#
Compute Q_phi and U_phi from Stokes Q and U, returning an Image with shape [6, n, m]: [I, Q, U, V, Q_phi, U_phi].
- Parameters:
image – Image Input image whose data is shaped [4, n, m] as [I, Q, U, V]. If the extension header contains ‘STARLOCX’ and ‘STARLOCY’, these are used as the stellar center.
x_center – float or None Optional override for the x-coordinate of the center. Used only when the header does not provide ‘STARLOCX’. If both header and this argument are missing, the image center ( (m-1)/2 ) is used.
y_center – float or None Optional override for the y-coordinate of the center. Used only when the header does not provide ‘STARLOCY’. If both header and this argument are missing, the image center ( (n-1)/2 ) is used.
- Returns:
- A copy of the input image with data expanded to [6, n, m] as
[I, Q, U, V, Q_phi, U_phi]. The err array is expanded to match and the uncertainties for Q_phi/U_phi are propagated from Q and U (assuming no covariance). The dq planes are expanded to match; if I/Q/U/V have identical dq, that mask is copied to both Q_phi and U_phi, otherwise Q_phi inherits Q’s dq and U_phi inherits U’s dq.
- Return type: