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)

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_stackImageStackPy

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 image stack. 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_stackImageStackPy

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. Columns are all optional and can include: * data_loc - the original location of the image data. * 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.

• visit - The visit number of the image (if known).

• filter - The filter used for 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 image stack. 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

clear_metadata()	Clear all WorkUnit metadata.
compute_ecliptic_angle()	Return the ecliptic angle (in radians in pixel space) derived from the images and WCS.
disorder_obstimes()	Reorders the timestamps in the WorkUnit to be random.
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 ImageStackPy 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[, ...])	Write the WorkUnit to a multiple FITS files.
write_config([overwrite])	Create the provenance directory and writes the SearchConfiguration out to disk.

get_num_images
print_stats

clear_metadata()

Clear all WorkUnit metadata.

compute_ecliptic_angle()

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.

disorder_obstimes()

Reorders the timestamps in the WorkUnit to be random. Random offsets are chosen for each unique obstime and added to the original obstime. The maximum offset is the number of images/times in the image stack or the difference between the maximum and minimum obstime.

The offsets are applied such that images will have a shared obstime if they did so before this method was called. The WorkUnit’s image stack is then sorted in ascending order of the updated obstimes.

This is useful for testing and ML training purposes where we might want to perform a search on a WorkUnit that would produce unlikely KBMOD results.

classmethod from_fits(filename, show_progress=None)

Create a WorkUnit from a single FITS file.

The FITS file will have at least the following extensions:

0. PRIMARY extension

1. METADATA extension containing provenance

2. 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)

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()

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 ImageStackPy.

Returns:

obs_timeslist

The list of 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.

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)

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()

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)

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)

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

Parameters:

image_indicesnumpy.array

The ImageStackPy 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()

Function for loading in ImageStackPy data when WorkUnit was created lazily.

metadata_to_hdul()

Creates the metadata fits headers.

Returns:

hdulastropy.io.fits.HDUList

The HDU List.

to_fits(filename, overwrite=False, compression_type='RICE_1', quantize_level=-0.01)

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.

compression_typestr

The compression type to use for the image layers (sci and var). Must be one of “NOCOMPRESS”, “RICE_1”, “GZIP_1”, “GZIP_2”, or “HCOMPRESS_1”. Default: “RICE_1”

quantize_levelfloat

The level at which to quantize the floats before compression. See https://docs.astropy.org/en/stable/io/fits/api/images.html for details. Default: -0.01

to_sharded_fits(filename, directory, overwrite=False, compression_type='RICE_1', quantize_level=-0.01)

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 time step in the image stack. 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.

compression_typestr

The compression type to use for the image layers (sci and var). Must be one of “NOCOMPRESS”, “RICE_1”, “GZIP_1”, “GZIP_2”, or “HCOMPRESS_1”. Default: “RICE_1”

quantize_levelfloat

The level at which to quantize the floats before compression. See https://docs.astropy.org/en/stable/io/fits/api/images.html for details. Default: -0.01

write_config(overwrite=False)

Create the provenance directory and writes the SearchConfiguration out to disk.

kbmod.work_unit.add_image_data_to_hdul(hdul, idx, sci, var, mask, obstime, psf_kernel=None, wcs=None, compression_type='RICE_1', quantize_level=-0.01)

Add the image data for a single time step to a fits file’s HDUL as individual layers for science, variance, etc. Masked pixels in the science and variance layers are added to the masked bits.

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.

compression_typestr

The compression type to use for the image layers (sci and var). Must be one of “NOCOMPRESS”, “RICE_1”, “GZIP_1”, “GZIP_2”, or “HCOMPRESS_1”. Default: “RICE_1”

quantize_levelfloat

The level at which to quantize the floats before compression. See https://docs.astropy.org/en/stable/io/fits/api/images.html for details. Default: -0.01

kbmod.work_unit.create_image_metadata(n_images, data=None)

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)

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)

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)

Function for loading a LayeredImagePy from a WorkUnit shard.

Parameters:

file_pathstr

The location of the shard file.

Returns:

imgLayeredImagePy

The materialized LayeredImagePy.

kbmod.work_unit.read_image_data_from_hdul(hdul, idx)

Read the image data for a single time step to a fits file’s HDUL. The mask is auto-applied to the science and variance layers.

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.