Module: work_unit#

class kbmod.work_unit.WorkUnit(im_stack, config, wcs=None, per_image_wcs=None, reprojected=False, reprojection_frame=None, per_image_indices=None, barycentric_distance=None, lazy=False, file_paths=None, obstimes=None, org_image_meta=None)[source]#

The work unit is a storage and I/O class for all of the data needed for a full run of KBMOD, including the: the search parameters, data files, and the data provenance metadata.

Parameters:

im_stackkbmod.search.ImageStack: The image data for the KBMOD run.
configkbmod.configuration.SearchConfiguration: The configuration for the KBMOD run.
wcsastropy.wcs.WCS, optional: A global WCS for all images in the WorkUnit. Only exists if all images have been projected to same pixel space.
per_image_wcslist, optional: A list with one WCS for each image in the WorkUnit. Used for when the images have not been standardized to the same pixel space. If provided this will overwrite the WCS values in org_image_meta
reprojectedbool, optional: Whether or not the WorkUnit image data has been reprojected.
reprojection_framestr, optional: Which coordinate frame the WorkUnit has been reprojected into, either “original” or “ebd” for a parallax corrected reprojection.
per_image_indiceslist of list, optional: A list of lists containing the indicies of constituent_images at each layer of the ImageStack. Used for finding corresponding original images when we stitch images together during reprojection.
barycentric_distancefloat, optional: The barycentric distance that was used when creating the per_image_ebd_wcs (in AU).
lazybool, optional: Whether or not to load the image data for the WorkUnit.
file_pathslist[str], optional: The paths for the shard files, only created if the WorkUnit is loaded in lazy mode.
obstimeslist[float]: The MJD obstimes of the midpoint of the images (in UTC).
org_image_metaastropy.table.Table, optional: A table of per-image data for the constituent images.

Attributes:

im_stackkbmod.search.ImageStack

The image data for the KBMOD run.

configkbmod.configuration.SearchConfiguration

The configuration for the KBMOD run.

n_constituentsint

The number of original images making up the data in this WorkUnit. This might be different from the number of images stored in memory if the WorkUnit has been reprojected.

org_img_metaastropy.table.Table

The meta data for each constituent image. Includes columns: * data_loc - the original location of the image * ebd_wcs - Used to reproject the images into EBD space. * geocentric_distance - The best fit geocentric distances used when creating

the per image EBD WCS.

original_wcs - The original per-image WCS of the image.

wcsastropy.wcs.WCS

A global WCS for all images in the WorkUnit. Only exists if all images have been projected to same pixel space.

barycentric_distancefloat

The barycentric distance that was used when creating the per_image_ebd_wcs (in AU).

reprojectedbool

Whether or not the WorkUnit image data has been reprojected.

per_image_indiceslist of list

A list of lists containing the indicies of constituent_images at each layer of the ImageStack. Used for finding corresponding original images when we stitch images together during reprojection.

lazybool

Whether or not to load the image data for the WorkUnit.

file_pathslist[str]

The paths for the shard files, only created if the WorkUnit is loaded in lazy mode.

obstimeslist[float]

The MJD obstimes of the midpoint of the images (in UTC).

Methods

`compute_ecliptic_angle`()	Return the ecliptic angle (in radians in pixel space) derived from the images and WCS.
`from_fits`(filename[, show_progress])	Create a WorkUnit from a single FITS file.
`from_sharded_fits`(filename, directory[, lazy])	Create a WorkUnit from multiple FITS files.
`get_all_obstimes`()	Return a list of the observation times in MJD.
`get_constituent_meta`(column)	Get the metadata values of a given column or a list of columns for all the constituent images.
`get_pixel_coordinates`(ra, dec[, times])	Get the pixel coordinates for pairs of (RA, dec) coordinates.
`get_unique_obstimes_and_indices`()	Returns the unique obstimes and the list of indices that they are associated with.
`get_wcs`(img_num)	Return the WCS for the a given image.
`image_positions_to_original_icrs`(...[, ...])	Method to transform image positions in EBD reprojected images into coordinates in the orignal ICRS frame of reference.
`load_images`()	Function for loading in ImageStack data when WorkUnit was created lazily.
`metadata_to_hdul`()	Creates the metadata fits headers.
`to_fits`(filename[, overwrite])	Write the WorkUnit to a single FITS file.
`to_sharded_fits`(filename, directory[, overwrite])	Write the WorkUnit to a multiple FITS files. Will create: - One "primary" file, containing the main WorkUnit metadata (see below) as well as the per_image_wcs information for the whole set. This will have the given filename. -One image fits file containing all of the image data for every LayeredImage in the ImageStack. This will have the image index infront of the given filename, e.g. "0_filename.fits".

get_num_images
print_stats

compute_ecliptic_angle()[source]#

Return the ecliptic angle (in radians in pixel space) derived from the images and WCS.

Returns:

ecliptic_anglefloat or None: The computed ecliptic_angle in radians in pixel space or None if data is missing.

classmethod from_fits(filename, show_progress=None)[source]#

Create a WorkUnit from a single FITS file.

The FITS file will have at least the following extensions:

PRIMARY extension
METADATA extension containing provenance
KBMOD_CONFIG extension containing search parameters

3. (+) any additional image extensions are named SCI_i, VAR_i, MSK_i and PSF_i for the science, variance, mask and PSF of each image respectively, where i runs from 0 to number of images in the WorkUnit.

Parameters:

filenamestr: The file to load.
show_progressbool or None, optional: If None use default settings, when a boolean forces the progress bar to be displayed or hidden.

Returns:

resultWorkUnit: The loaded WorkUnit.

classmethod from_sharded_fits(filename, directory, lazy=False)[source]#

Create a WorkUnit from multiple FITS files. Pointed towards the result of WorkUnit.to_sharded_fits.

The FITS files will have the following extensions:

Primary File:: 0 - Primary header with overall metadata 1 or “metadata” - The data provenance metadata 2 or “kbmod_config” - The search parameters
Individual Image File:: Image extensions for the science layer (“SCI_i”), variance layer (“VAR_i”), mask layer (“MSK_i”), and PSF (“PSF_i”) of each image.

Parameters:

filenamestr: The primary file to load.
directorystr: The directory where the sharded file is located.
lazybool: Whether or not to lazy load, i.e. whether to load all of the image data into the WorkUnit or just the metadata.

Returns:

resultWorkUnit: The loaded WorkUnit.

get_all_obstimes()[source]#

Return a list of the observation times in MJD.

If the WorkUnit was lazily loaded, then the obstimes have already been preloaded. Otherwise, grab them from the `ImageStack.

Returns:

obs_timeslist: The list of observation times in MJD.

get_constituent_meta(column)[source]#

Get the metadata values of a given column or a list of columns for all the constituent images.

Parameters:

columnstr, or Iterable: The column name(s) to fetch.

Returns:

datalist or dict: If a single string column name is provided, the function returns the values in a list. Otherwise it returns a dictionary, mapping each column name to its values.

get_pixel_coordinates(ra, dec, times=None)[source]#

Get the pixel coordinates for pairs of (RA, dec) coordinates. Uses the global WCS if one exists. Otherwise uses the per-image WCS. If times is provided, uses those values to choose the per-image WCS.

Parameters:

ranumpy.ndarray: The right ascension coordinates (in degrees.
decnumpy.ndarray: The declination coordinates in degrees.
timesnumpy.ndarray or None, optional: The times to match in MJD.

Returns:

x_pos, y_pos: numpy.ndarray: Arrays of the X and Y pixel positions respectively.

get_unique_obstimes_and_indices()[source]#

Returns the unique obstimes and the list of indices that they are associated with.

Returns:

unique_obstimeslist: The list of unique observation times in MJD.
unique_indiceslist: The list of the indices corresponding to each observation time.

get_wcs(img_num)[source]#

Return the WCS for the a given image. Alway prioritizes a global WCS if one exits.

Parameters:

img_numint: The number of the image.

Returns:

wcsastropy.wcs.WCS: The image’s WCS if one exists. Otherwise None.

image_positions_to_original_icrs(image_indices, positions, input_format='xy', output_format='xy', filter_in_frame=True)[source]#

Method to transform image positions in EBD reprojected images into coordinates in the orignal ICRS frame of reference.

Parameters:

image_indicesnumpy.array: The ImageStack indices to transform coordinates.
positionslist of `astropy.coordinates.SkyCoord`s or `tuple`s: The positions to be transformed.
input_formatstr: The input format for the positions. Either ‘xy’ or ‘radec’. If ‘xy’ is given, positions must be in the format of a tuple with two float or integer values, like (x, y). If ‘radec’ is given, positions must be in the format of a astropy.coordinates.SkyCoord.
output_formatstr: The output format for the positions. Either ‘xy’ or ‘radec’. If ‘xy’ is given, positions will be returned in the format of a tuple with two int`s, like (x, y). If ‘radec’ is given, positions will be returned in the format of a `astropy.coordinates.SkyCoord.
filter_in_framebool: Whether or not to filter the output based on whether they fit within the original constituent_image frame. If True, only results that fall within the bounds of the original WCS will be returned.

Returns:

positionslist of `astropy.coordinates.SkyCoord`s or `tuple`s: The transformed positions. If filter_in_frame is true, each element of the result list will also be a tuple with the URI string of the constituent image matched to the position.

load_images()[source]#: Function for loading in ImageStack data when WorkUnit was created lazily.

metadata_to_hdul()[source]#

Creates the metadata fits headers.

Returns:

hdulastropy.io.fits.HDUList: The HDU List.

to_fits(filename, overwrite=False)[source]#

Write the WorkUnit to a single FITS file.

Uses the following extensions:: 0 - Primary header with overall metadata 1 or “metadata” - The data provenance metadata 2 or “kbmod_config” - The search parameters 3+ - Image extensions for the science layer (“SCI_i”),

variance layer (“VAR_i”), mask layer (“MSK_i”), and PSF (“PSF_i”) of each image.

Parameters:

filenamestr: The file to which to write the data.
overwritebool: Indicates whether to overwrite an existing file.

to_sharded_fits(filename, directory, overwrite=False)[source]#

Write the WorkUnit to a multiple FITS files. Will create:

One “primary” file, containing the main WorkUnit metadata

(see below) as well as the per_image_wcs information for the whole set. This will have the given filename. -One image fits file containing all of the image data for every LayeredImage in the ImageStack. This will have the image index infront of the given filename, e.g. “0_filename.fits”.

Primary File:: 0 - Primary header with overall metadata 1 or “metadata” - The data provenance metadata 2 or “kbmod_config” - The search parameters
Individual Image File:: Image extensions for the science layer (“SCI_i”), variance layer (“VAR_i”), mask layer (“MSK_i”), and PSF (“PSF_i”) of each image.

Parameters:

filenamestr: The base filename to which to write the data.
directory: `str`: The directory to place all of the FITS files. Recommended that you have one directory per sharded file to avoid confusion.
overwritebool: Indicates whether to overwrite an existing file.

kbmod.work_unit.add_image_data_to_hdul(hdul, idx, sci, var, mask, obstime, psf_kernel=None, wcs=None)[source]#

Add the image data for a single time step to a fits file’s HDUL as individual layers for science, variance, etc.

Parameters:

hdulHDUList: The HDUList for the fits file.
idxint: The time step number (index of the layer).
scinp.ndarray: The pixels of the science image.
varnp.ndarray: The pixels of the variance image.
masknp.ndarray: The pixels of the mask image.
obstimefloat: The observation time of the image in UTC MJD.
psf_kernelnp.ndarray, optional: The kernel values of the PSF.
wcsastropy.wcs.WCS, optional: An optional WCS to include in the header.

kbmod.work_unit.create_image_metadata(n_images, data=None)[source]#

Create an empty img_meta table, filling in default values for any unspecified columns.

Parameters:

n_imagesint: The number of images to include.
dataastropy.table.Table: An existing table from which to fill in some of the data.

Returns:

img_metaastropy.table.Table: The empty table of org_img_meta.

kbmod.work_unit.hdu_to_image_metadata_table(hdu)[source]#

Load a HDU layer with custom encodings for some columns (such as WCS) to an astropy table.

Parameters:

hduastropy.io.fits.TableHDU: The HDUList for the fits file.

Returns:

dataastropy.table.Table: The table of loaded data.

kbmod.work_unit.image_metadata_table_to_hdu(data, layer_name=None)[source]#

Create a HDU layer from an astropy table with custom encodings for some columns (such as WCS).

Parameters:

dataastropy.table.Table: The table of the data to save.
layer_namestr, optional: The name of the layer in which to save the table.

kbmod.work_unit.load_layered_image_from_shard(file_path)[source]#

Function for loading a LayeredImage from a WorkUnit shard.

Parameters:

file_pathstr: The location of the shard file.

Returns:

imgLayeredImage: The materialized LayeredImage.

kbmod.work_unit.read_image_data_from_hdul(hdul, idx)[source]#

Read the image data for a single time step to a fits file’s HDUL.

Parameters:

hdulHDUList: The HDUList for the fits file.
idxint: The time step number (index of the layer).

Returns:

scinp.ndarray: The pixels of the science image.
varnp.ndarray: The pixels of the variance image.
masknp.ndarray: The pixels of the mask image.
obstimefloat: The observation time of the image in UTC MJD.
psf_kernelnp.ndarray: The kernel values of the PSF.
wcsastropy.wcs.WCS: An optional WCS to include in the header. May be None if no WCS is found.