API for MVM Utilities

The hapcut_utils.py module is part of the drizzlepac package and contains utilities which are intended to be used with Multi-visit Mosaic (MVM) data and to be imported into other Python programs or a Python session for interactive data analysis.

haputils.hapcut_utils

The module is a high-level interface to astrocut for use with HAP SVM and MVM files.

drizzlepac.haputils.hapcut_utils.mvm_id_filenames(sky_coord, cutout_size, log_level=20)

This function retrieves a table of MVM drizzled image filenames with additional information from the archive. The user can then further cull the table to use as input to obtain a list of files from the archive. This function will return filter-level products. At this time, both ACS and WFC3 are searched by default.

Parameters:

sky_coordstr or astropy.coordinates.SkyCoord object

The position around which to cutout. It may be specified as a string (“ra dec” in degrees) or as the appropriate astropy.coordinates.SkyCoord object.

cutout_sizeint, array-like, astropy.units.Quantity

The size of the cutout array. If cutout_size is a scalar number or a scalar astropy.units.Quantity, then a square cutout of cutout_size will be created. If cutout_size has two elements, they should be in (ny, nx) order. Scalar numbers in cutout_size are assumed to be in units of arcseconds. astropy.units.Quantity objects must be in angular units.

log_levelint, optional

The desired level of verbosity in the log statements displayed on the screen and written to the .log file. Default value is 20, or ‘info’.

Returns:

final_tableastropy.table.Table object

This utility also writes an output ECSV file version of the in-memory filtered data product table,

final_table. The output filename is in the form:

mvm_query-ra<###>d<####>-dec<n|s><##>d<####>_<radius>_cutout.ecsv

(e.g., mvm_query-ra84d8208-decs69d8516_354_cutout.ecsv, where radius has been computed from the

cutout dimensions.

drizzlepac.haputils.hapcut_utils.mvm_retrieve_files(products, archive=False, clobber=False, log_level=20)

This function retrieves specified files from the archive - unless the file is found to be locally resident on disk. Upon completion, The function returns a list of filenames available on disk.

Parameters:

productsastropy.table.Table object

A Table of products as returned by the mvm_id_filenames function.

archiveBoolean, optional

Retain copies of the downloaded files in the astroquery created sub-directories? Default is “False”.

clobberBoolean, optional

Download and Overwrite existing files? Default is “False”.

log_levelint, optional

The desired level of verbosity in the log statements displayed on the screen and written to the .log file. Default value is 20, or ‘info’.

Returns:

local_fileslist

List of filenames

Note: Code here cribbed from retrieve_obsevation in astroquery_utils module.

drizzlepac.haputils.hapcut_utils.make_the_cut(input_files, sky_coord, cutout_size, output_dir='.', log_level=20, verbose=False)

This function makes the actual cut in the input MVM drizzled filter- and exposure-level FITS files. As such it is a high-level interface for the astrocut.cutouts.fits_cut functionality.

Parameters:

input_fileslist

List of fits image filenames from which to create cutouts.

sky_coordstr or astropy.coordinates.SkyCoord object

The position around which to cutout. It may be specified as a string (“ra dec” in degrees) or as the appropriate astropy.coordinates.SkyCoord object.

cutout_sizeint, array-like, astropy.units.Quantity

The size of the cutout array. If cutout_size is a scalar number or a scalar astropy.units.Quantity, then a square cutout of cutout_size will be created. If cutout_size has two elements, they should be in (ny, nx) order. Scalar numbers in cutout_size are assumed to be in units of arcseconds. astropy.units.Quantity objects must be in angular units.

output_dirstr

Default value ‘.’. The directory where the cutout file(s) will be saved.

log_levelint, optional

The desired level of verbosity in the log statements displayed on the screen and written to the .log file. Default value is 20, or ‘info’.

verbosebool

Default False. If True, additional intermediate information is printed for the underlying spacetelescope.astrocut utilities.

Returns:

responselist

Returns a list of all the output filenames.

Note: For each input file designated for a cutout, there will be a corresponding output file.

Since both the SCI and WHT extensions of the input files are actually cut, individual fits files will contain two image extensions, a SCI followed by the WHT.

While the standard pipeline processing does not produce an MVM exposure-level drizzled product, it is possible for a user to turn on this capability in the pipeline while performing custom processing. As such this routine will perform cutouts of the exposure-level drizzled files.

Each filter-level output filename will be of the form:

hst_cutout_skycell-p<pppp>-ra<##>d<####>-dec<n|s><##>d<####>_instrument_detector_filter[_platescale].fits

Each exposure-level filename will be of the form:

hst_cutout_skycell-p<pppp>-ra<##>d<####>-dec<n|s><##>d<####>_instrument_detector_filter[_platescale]-ipppssoo.fits

where platescale has the value of “coarse” representing 0.12”/pixel for WFC3/IR, or there is no platescale value present which is the default and represents a “fine” platescale of 0.04”/pixel.

drizzlepac.haputils.hapcut_utils.mvm_combine(cutout_files, output_dir='.', log_level=20)

This function combines multiple MVM skycell cutout images from the same detector/filter combination to create a single view of the requested data. All of the functions in this module are designed to work in conjunction with one another, so the cutout images should be on the user’s local disk. This task is a high-level wrapper for the astrocut.cutout_processing.combine functionality.

Specifically, this routine will combine filter-level cutouts from multiple skycells, all sharing the same detector and filter. This routine will also combine exposure-level cutouts from multiple skycells, all sharing the same detector, filter, and ipppssoo. Images which do not share a detector and filter with any other image will be ignored. Individual exposures from a single skycell will also be ignored.

Parameters:

cutout_fileslist

List of fits image cutout filenames where the cutouts are presumed to have been created with make_the_cut.

output_dirstr

Default value ‘.’ - The directory where the output combined files will be saved.

log_levelint, optional

The desired level of verbosity in the log statements displayed on the screen and written to the .log file. Default value is 20, or ‘info’.