API for make_custom_mosaic

The task make_custom_mosaic serves as the primary interface for processing data from a multiple visits that span multiple skycells into a uniform set of images.

Frequently Asked Questions

• Why would a user want to run this code?

  • Standard multi-visit mosaic (MVM) processing only processes a single skycell per run. Datasets with images that span one or more skycell boundaries require multiple MVM processing runs and produce multiple overlapping product images that are segmented at skycell boundaries. This code simplifies this process. It creates seamless multi-visit mosaics for input datasets that span one or more skycell boundaries.

• What are the required and opitonal inputs? What do they do?

  • The only required to make_custom_mosaic.py is either the name of a text file containing a list of calibrated ACS or WFC _flc.fits or _flt.fits files process or a search search sting that will be used to find input files. Optional input arguments control the level of verbosity in the log statements that are displayed to the screen and written to log files, the formatting of output filenames, and the method used to align input images. These inputs are discussed in more detail in the USAGE section.

• When the code is run, what output products should be expected? Do they differ depending on the inputs?

  • As this script depends on hapmultisequencer to perform the actual image processing, users can expect the output products of make_custom_mosaics.py to be functionally identical to standard MVM products. As with standard MVM processing, the only variation in output images occurs when processing WFC3/IR data, which produces output imagery products at the standard platescale of 0.04 arcseconds per pixel, as well as at the native WFC3/IR detector platescale of 0.12 arcseconds per pixel.

make_custom_mosaic.py - Module to control the generation of user-defined multi-skycell mosaics. This script extends the capabilities of the HAP multi-visit mosaics (MVM) processing code (hapmultisequencer.py). Based on user input, this script will produce drizzle-combined mosaics that will be as large as necessary to incorporate all input images. Mosaic images can span multiple skycells, but NOT multiple projection cells. In the exceedingly rare case that a custom mosaic contains observations that fall on multiple adjacent projection cells, the bounds of the mosaic will be automatically clipped at the projection cell edge.

As this script is simply a wrapper around hapmultisequencer.py, the final output products are the exact same as what one would expect from a pipeline MVM run. For a complete details about all hapmultisequencer.py inputs and output products, please refer to the hapmultisequencer.py documentation.

hapmultisequencer.py was explicitly written to process data from only a single skycell. However, this script gives users the ability to create mosaics spanning multiple skycells. As such, all output products produced by hapmultisequencer.py normally include both the projection cell and skycell names in the all output products. To avoid any confusion that might arise during the creation of mosaics that span multiple skycells, all custom mosaic output product filenames will by default include projection cell name and the projection cell reference right ascension and declination instead of the skycell name. Users can also optionally specify an output product filename prefix of their choosing.

The output world cooordinate system (WCS) information is based on that of the projection cell in which the observations reside. If the input observations happen to fall in a region of the sky where more than one projection cells overlap, the WCS information of the output products will be based on the projection cell whose center is closest to the geometric center of the input observations.

For all detectors, output products will be generated with a plate scale of 0.04 arcseconds per pixel. The script produces an additional set up output products for WFC3/IR observations. This additional set of products is generated using the native detector platescale of 0.12 arcseconds per pixel. These files end in “_coarse_all_flt.fits”.

The output world coordinate system (WCS) information is based on that of the projection cell in which the observations reside. If the input observations happen to fall in a region of the sky where more than one projection cells overlap, the WCS information of the output products will be based on the projection cell whose center is closest to the geometric center of the input observations.

USAGE:

>>> python drizzlepac/make_custom_mosaic.py -[los] <search pattern enclosed in quotes>

or

>>> python drizzlepac/make_custom_mosaic.py -[los] <text file with list of input files>

• The ‘-l’ option allows the user to control the level of verboseness in the log statements displayed on the screen and written to the .log file. The level of verboseness from left to right, and includes all log statements with a log_level left of the specified level. Specifying “critical” will only record/display “critical” log statements, and specifying “error” will record/display both “error” and “critical” log statements, and so on.

• The ‘-o’ option allows the user to specify the text string that will be used as the filename prefix all files created by hapmultisequencer.py during the MVM custom mosaic generation process. If not explicitly specified, all output files will start with the following formatted text string: “hst-skycell-p<pppp>-ra<##>d<####>-dec<n|s><##>d<####>”, where p<pppp> is the projection cell ID, ra<##>d<####> are the whole-number and decimal portions of the right ascention, respectively, and dec<n|s><##>d<####> are the whole-number and decimal portions of the declination, respectively. Note that the “<n|s>” denotes if the declination is north (positive) or south (negative). Example: For skycell = 1974, ra = 201.9512, and dec = +26.0012, The filename prefix would be “skycell-p1974-ra201d9512-decn26d0012”.

• When turned on, the ‘-s’ option allows users to skip alignment of all input images to known Gaia/HSC sources in the input image footprint and instead use the existing input image alignment solution.

Python USAGE:

>>> python
>>> from drizzlepac import make_custom_mosaic
>>> make_custom_mosaic.perform(<list file or search pattern>, log_level='info', output_file_prefix=None, skip_gaia_alignment=False)

drizzlepac.make_custom_mosaic.calc_skycell_dist(x, y, x_ref, y_ref)

Calculate distance from one skyframe to another

Parameters:

xint

skyframe x index

yint

skyframe y index

x_refint

reference x index

y_refint

reference y index

Returns:

distfloat

distance from (x, y) to (x_ref, y_ref)

drizzlepac.make_custom_mosaic.compute_mosaic_limits(proj_cell_dict)

Compute min and max limits of the rectangle that encloses the mosaic observations

Parameters:

proj_cell_dictdictionary

Dictionary containing projection cell information

Returns:

mosaic_limitslist

4-element list containing the mosaic bounding rectangle X min and max and Y min and max values

drizzlepac.make_custom_mosaic.create_input_image_list(user_input)

Create list of input images based in user input from command-line

Parameters:

user_inputstr

Search pattern to be used to identify images to process or the name of a text file containing a list of images to process

Returns:

img_listlist

list of images to process

drizzlepac.make_custom_mosaic.create_poller_file(img_list, proj_cell_dict)

Subroutine that executes make_poller_files.generate_poller_file() to generate custom MVM poller file for execution of hapmultisequencer.run_mvm_processing().

Parameters:

img_listlist

list of images to process

proj_cell_dictdict

Dictionary containing projection cell information

Returns:

poller_filenamestr

Name of the newly created poller_filename

drizzlepac.make_custom_mosaic.determine_projection_cell(img_list)

Determine which projection cell should be used as the basis for the WCS of the output mosaic product(s) based on which projection cell center is closest to the center of the observations.

Parameters:

img_listlist

A list of images to process

Returns:

best_pc_dictdict

Dictionary of SkyCell objects for the input observations. These SkyCell objects contain projection cell information from the projection cell whose center is closest to the geometric center of the input observations.

drizzlepac.make_custom_mosaic.main()

Command-line interface

Parameters:

None

Returns:

return_valueint

return value from the run. 0 for successful run, something else otherwise.

drizzlepac.make_custom_mosaic.perform(input_image_source, log_level='info', output_file_prefix=None, skip_gaia_alignment=False)

Main calling subroutine

Parameters:

input_image_sourcestr

Search pattern to be used to identify images to process or the name of a text file containing a list of images to process.

log_levelstr, optional

The desired level of verboseness in the log statements displayed on the screen and written to the .log file. The level of verboseness from left to right, and includes all log statements with a log_level left of the specified level. Specifying “critical” will only record/display “critical” log statements, and specifying “error” will record/display both “error” and “critical” log statements, and so on. Unless explicitly set, the default value is ‘info’.

output_file_prefixstr, optional

‘Text string that will be used as the filename prefix all files created by hapmultisequencer.py during the MVM custom mosaic generation process. If not explicitly specified, all output files will start with the following formatted text string: “hst-skycell-p<pppp>-ra<##>d<####>-dec<n|s><##>d<####>”, where p<pppp> is the projection cell ID, ra<##>d<####> are the whole-number and decimal portions of the right ascention, respectively, and dec<n|s><##>d<####> are the whole-number and decimal portions of the declination, respectively. Note that the “<n|s>” denotes if the declination is north (positive) or south (negative). Example: For skycell = 1974, ra = 201.9512, and dec = +26.0012, The filename prefix would be “skycell-p1974-ra201d9512-decn26d0012”.

skip_gaia_alignmentbool, optional

Skip alignment of all input images to known Gaia/HSC sources in the input image footprint? If set to ‘True’, The existing input image alignment solution will be used instead. The default is False.

Returns:

return_valueint

A simple status value. ‘0’ for a successful run or ‘1’ for a failed run.