corgidrp.combine#

Module to support frame combination

Functions#

combine_images(data_subset, err_subset, dq_subset, ...)

Combines several images together

combine_subexposures(input_dataset[, ...])

Combines a sequence of exposures assuming a constant nubmer of frames per group.

combine_frames_per_visit(input_dataset[, collapse, ...])

Combines frames in the input dataset by calling combine_subexposures on each

derotate_arr(data_arr, northang_deg, xcen, ycen[, ...])

Derotates an array based on the provided NORTHANG angle, about the provided

prop_err_dq(sci_dataset, ref_dataset, mode[, ...])

Applies logic to propagate the dq arrays and error arrays

Module Contents#

corgidrp.combine.combine_images(data_subset, err_subset, dq_subset, collapse, num_frames_scaling, other_hdus=None)[source]#

Combines several images together

Parameters:

  • data_subset (np.array) – 3-D array of N 2-D images

  • err_subset (np.array) – 4-D array of N 3-D error maps

  • dq_subset (np.array) – 3-D array of N 2-D DQ maps

  • collapse (str) – “mean” or “median”.

  • num_frames_scaling (bool) – Multiply by number of frames in sequence in order to ~conserve photons

  • other_hdus (list of HDULists, optional) – list of other HDULists to be combined in the same way

Returns:

combined images

np.array: 2-D array of combined images np.array: 3-D array of combined error map np.array: 2-D array of combined DQ maps list of np.array: list of the combined data of other HUDs

Return type:

tuple

corgidrp.combine.combine_subexposures(input_dataset, num_frames_per_group=None, collapse='mean', num_frames_scaling=True, combine_other_hdus=False)[source]#

Combines a sequence of exposures assuming a constant nubmer of frames per group. The length of the dataset must be divisible by the number of frames per group.

The combination is done with either the mean or median, but the collapsed image can be scaled in order to ~conserve the total number of photons in the input dataset (this essentially turns a median into a sum)

Parameters:

  • input_dataset (corgidrp.data.Dataset) – input data.

  • num_frames_per_group (int) – number of subexposures per group. If None, combines all images together

  • collapse (str) – “mean” or “median”. (default: mean)

  • num_frames_scaling (bool) – Multiply by number of frames in sequence in order to ~conserve photons (default: True)

  • combine_other_hdus (bool) – Whether to combine other HDUs in the same way as the main data, err, DQ. Otherwise, uses the HDUs from the first frame in a subset (default: False)

Returns:

dataset after combination of every “num_frames_per_group” frames together

Return type:

corgidrp.data.Dataset

corgidrp.combine.combine_frames_per_visit(input_dataset, collapse='mean', num_frames_per_group=None, num_frames_scaling=False, combine_other_hdus=False, max_combined=100, pri_split_keywords=['VISITID'], ext_split_keywords=['DPAMNAME'])[source]#

Combines frames in the input dataset by calling combine_subexposures on each unique split of VISITID and polarization state (DPAMNAME). The combination is done with either the mean or median, but the collapsed image can be scaled in order to ~conserve the total number of photons in the input dataset (this essentially turns a median into a sum).

Parameters:

  • input_dataset (corgidrp.data.Dataset) – a dataset of Images (L3-level)

  • collapse (str) – “mean” or “median”. (default: mean)

  • num_frames_per_group (int or None) – number of consecutive frames to combine within each VISITID/DPAMNAME split subset. If None, combine all frames in each subset into one output frame. If the requested grouping would create more than max_combined output frames in a split subset, it is overridden with the smallest group size that keeps the per-subset output count at or below max_combined; trailing remainder frames are left out. (default: None)

  • num_frames_scaling (bool) – Multiply by number of frames in sequence in order to ~conserve photons (default: False)

  • combine_other_hdus (bool) – Whether to combine other HDUs in the same way as the main data, err, DQ. Otherwise, uses the HDUs from the first frame in a subset (default: False)

  • max_combined (int) – maximum number of output frames allowed per split subset before num_frames_per_group is automatically increased. (default: 100)

  • pri_split_keywords (list of str) – Additional primary header keywords to use for splitting the dataset into subsets. The default split keyword [‘VISITID’] is always included, and input values are appended. (default: [‘VISITID’])

  • ext_split_keywords (list of str) – Additional extension header keywords to use for splitting the dataset into subsets. The default split keyword [‘DPAMNAME’] is always included, and input values are appended. (default: [‘DPAMNAME’])

Returns:

dataset of combined frames. If num_frames_per_group is None, there is one output frame per split subset, so len(output_dataset) equals the number of unique VISITID groups or unique (VISITID, DPAMNAME) groups when DPAMNAME is present for all frames. If num_frames_per_group is set, each split subset is further combined in sequential groups of num_frames_per_group. If a requested grouping would create more than max_combined output frames in a split subset, the grouping is increased so that the output count stays at or below max_combined and trailing remainder frames are left out. Each output frame keeps the same internal data cube shape as an input frame; only the dataset/frame axis is collapsed.

Return type:

corgidrp.data.Dataset

corgidrp.combine.derotate_arr(data_arr, northang_deg, xcen, ycen, new_center=None, astr_hdr=None, is_dq=False, dq_round_threshold=0.05)[source]#

Derotates an array based on the provided NORTHANG angle, about the provided center. Treats DQ arrays specially, converting to float to do the rotation, and converting back to np.int64 afterwards. DQ output becomes only zeros and ones, so detailed DQ flag information is not preserved.

Parameters:

  • data_arr (np.array) – an array with 2-4 dimensions

  • northang_deg (float) – angle (measured counter-clockwise) of the detector y axis from celestial north (degrees). Calculated from the northangle of the astrometric cal frame and the PA_APER offset between the astrom cal frame and the science frame.

  • xcen (float) – x-coordinate of center about which to rotate

  • ycen (float) – y-coordinate of center about which to rotate

  • new_center (tuple, optional) – tuple of x- and y- coordinate of the new center to shift to.

  • astr_hdr (astropy.fits.Header, optional) – WCS header which will be updated. Defaults to None.

  • is_dq (bool, optional) – Flag to determine if this is a DQ array. Defaults to False.

  • dq_round_threshold (float, optional) – value between 0-1 which determines the threshold for spreading dq values to neighboring pixels after derotation.

Returns:

The derotated array.

Return type:

np.array

corgidrp.combine.prop_err_dq(sci_dataset, ref_dataset, mode, dq_thresh=1, new_center=None)[source]#

Applies logic to propagate the dq arrays and error arrays in a dataset through PSF subtraction.

Parameters:

  • sci_dataset (corgidrp.data.Dataset) – The input science dataset.

  • ref_dataset (corgidrp.data.Dataset) – The input reference dataset (or None if ADI only).

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

  • dq_thresh (int) – Minimum dq flag value to be considered a bad pixel. Defaults to 1.

  • new_center (tuple) – New center (xy) to align all frames. Defaults to pixel closest to array center.

Returns:

the dq array and err array which should apply to the PSF subtraction output dataset.

Return type:

tuple of np.array