Enhanced Pipeline Products code API

This script is a modernized implementation of tweakreg.

drizzlepac.alignimages.perform_align(input_list, **kwargs)

Main calling function.

Parameters:

input_list : list

List of one or more IPPSSOOTs (rootnames) to align.

archive : Boolean

Retain copies of the downloaded files in the astroquery created sub-directories?

clobber : Boolean

Download and overwrite existing local copies of input files?

debug : Boolean

Attempt to use saved sourcelists stored in pickle files if they exist, or if they do not exist, save sourcelists in pickle files for reuse so that step 4 can be skipped for faster subsequent debug/development runs??

update_hdr_wcs : Boolean

Write newly computed WCS information to image image headers?

runfile : string

log file name

print_fit_parameters : Boolean

Specify whether or not to print out FIT results for each chip.

print_git_info : Boolean

Display git repository information?

output : Boolean

Should utils.astrometric_utils.create_astrometric_catalog() generate file ‘ref_cat.ecsv’ and should generate_source_catalogs() generate the .reg region files for every chip of every input image and should generate_astrometric_catalog() generate file ‘refcatalog.cat’?

num_sources : int, optional

Maximum number of brightest sources per chip which will be used for cross-matching and fitting. If set to None, all sources will be used.

drizzlepac.alignimages.generate_source_catalogs(imglist, **pars)

Generates a dictionary of source catalogs keyed by image name.

Parameters:

imglist : list

List of one or more calibrated fits images that will be used for source detection.

Returns:

sourcecatalogdict : dictionary

a dictionary (keyed by image name) of two-element dictionaries which contain the following:

• a dictionary of the detector-specific processing parameters
• an astropy table of position and photometry information of all detected sources

Utilities to support creation of astrometrically accurate reference catalogs

The function, create_astrometric_catalog, allows the user to query an astrometric catalog online to generate a catalog of astrometric sources that should fall within the field-of-view of all the input images.

This module relies on the definition of an environment variable to specify the URL of the astrometric catalog to use for generating this reference catalog.

ASTROMETRIC_CATALOG_URL  -- URL of web service that can be queried to
                            obtain listing of astrometric sources,
                            sky coordinates, and magnitudes.

drizzlepac.hlautils.astrometric_utils.create_astrometric_catalog(inputs, catalog='GAIADR2', output='ref_cat.ecsv', gaia_only=False, table_format='ascii.ecsv', existing_wcs=None)

Create an astrometric catalog that covers the inputs’ field-of-view.

Parameters:

input : str, list

Filenames of images to be aligned to astrometric catalog

catalog : str, optional

Name of catalog to extract astrometric positions for sources in the input images’ field-of-view. Default: GAIADR2. Options available are documented on the catalog web page.

output : str, optional

Filename to give to the astrometric catalog read in from the master catalog web service. If None, no file will be written out.

gaia_only : bool, optional

Specify whether or not to only use sources from GAIA in output catalog

existing_wcs : HSTWCS

existing WCS object specified by the user

Returns:

ref_table : Table

Astropy Table object of the catalog

Notes

This function will point to astrometric catalog web service defined through the use of the ASTROMETRIC_CATALOG_URL environment variable.

drizzlepac.hlautils.astrometric_utils.get_catalog(ra, dec, sr=0.1, catalog='GSC241')

Extract catalog from VO web service.

Parameters:

ra : float

Right Ascension (RA) of center of field-of-view (in decimal degrees)

dec : float

Declination (Dec) of center of field-of-view (in decimal degrees)

sr : float, optional

Search radius (in decimal degrees) from field-of-view center to use for sources from catalog. Default: 0.1 degrees

catalog : str, optional

Name of catalog to query, as defined by web-service. Default: ‘GSC241’

Returns:

csv : CSV object

CSV object of returned sources with all columns as provided by catalog

drizzlepac.hlautils.astrometric_utils.find_gsc_offset(image, input_catalog='GSC1', output_catalog='GAIA')

Find the GSC to GAIA offset based on guide star coordinates

Parameters:

image : str

Filename of image to be processed.

Returns:

delta_ra, delta_dec : tuple of floats

Offset in decimal degrees of image based on correction to guide star coordinates relative to GAIA.

drizzlepac.hlautils.astrometric_utils.extract_sources(img, dqmask=None, fwhm=3.0, threshold=None, source_box=7, classify=True, centering_mode='starfind', nlargest=None, outroot=None, plot=False, vmax=None, deblend=False)

Use photutils to find sources in image based on segmentation.

Parameters:

img : ndarray

Numpy array of the science extension from the observations FITS file.

dqmask : ndarray

Bitmask which identifies whether a pixel should be used (1) in source identification or not(0). If provided, this mask will be applied to the input array prior to source identification.

fwhm : float

Full-width half-maximum (fwhm) of the PSF in pixels.

threshold : float or None

Value from the image which serves as the limit for determining sources. If None, compute a default value of (background+5*rms(background)). If threshold < 0.0, use absolute value as scaling factor for default value.

source_box : int

Size of box (in pixels) which defines the minimum size of a valid source.

classify : bool

Specify whether or not to apply classification based on invarient moments of each source to determine whether or not a source is likely to be a cosmic-ray, and not include those sources in the final catalog.

centering_mode : str

“segmentaton” or “starfind” Algorithm to use when computing the positions of the detected sources. Centering will only take place after threshold has been determined, and sources are identified using segmentation. Centering using segmentation will rely on photutils.segmentation.source_properties to generate the properties for the source catalog. Centering using starfind will use photutils.IRAFStarFinder to characterize each source in the catalog.

nlargest : int, None

Number of largest (brightest) sources in each chip/array to measure when using ‘starfind’ mode.

outroot : str, optional

If specified, write out the catalog of sources to the file with this name rootname.

plot : bool, optional

Specify whether or not to create a plot of the sources on a view of the image.

vmax : float, optional

If plotting the sources, scale the image to this maximum value.

deblend : bool, optional

Specify whether or not to apply photutils deblending algorithm when evaluating each of the identified segments (sources) from the chip.

drizzlepac.hlautils.astrometric_utils.classify_sources(catalog, sources=None)

Convert moments_central attribute for source catalog into star/cr flag.

This algorithm interprets the central_moments from the source_properties generated for the sources as more-likely a star or a cosmic-ray. It is not intended or expected to be precise, merely a means of making a first cut at removing likely cosmic-rays or other artifacts.

Parameters:

catalog : SourceCatalog

The photutils catalog for the image/chip.

sources : tuple

Range of objects from catalog to process as a tuple of (min, max). If None (default) all sources are processed.

Returns:

srctype : ndarray

An ndarray where a value of 1 indicates a likely valid, non-cosmic-ray source, and a value of 0 indicates a likely cosmic-ray.

drizzlepac.hlautils.astrometric_utils.generate_source_catalog(image, dqname='DQ', output=False, fwhm=3.0, **detector_pars)

Build source catalogs for each chip using photutils.

The catalog returned by this function includes sources found in all chips of the input image with the positions translated to the coordinate frame defined by the reference WCS refwcs. The sources will be - identified using photutils segmentation-based source finding code - ignore any input pixel which has been flagged as ‘bad’ in the DQ array, should a DQ array be found in the input HDUList. - classified as probable cosmic-rays (if enabled) using central_moments properties of each source, with these sources being removed from the catalog.

Parameters:

image : HDUList

Input image as an astropy.io.fits HDUList.

dqname : str

EXTNAME for the DQ array, if present, in the input image HDUList.

output : bool

Specify whether or not to write out a separate catalog file for all the sources found in each chip.

fwhm : float

Full-width half-maximum (fwhm) of the PSF in pixels.

Returns:

source_cats : dict

Dict of astropy Tables identified by chip number with each table containing sources from image extension ('sci', chip).

drizzlepac.hlautils.astrometric_utils.generate_sky_catalog(image, refwcs, dqname='DQ', output=False)

Build source catalog from input image using photutils.

This script borrows heavily from build_source_catalog.

The catalog returned by this function includes sources found in all chips of the input image with the positions translated to the coordinate frame defined by the reference WCS refwcs. The sources will be - identified using photutils segmentation-based source finding code - ignore any input pixel which has been flagged as ‘bad’ in the DQ array, should a DQ array be found in the input HDUList. - classified as probable cosmic-rays (if enabled) using central_moments properties of each source, with these sources being removed from the catalog.

Parameters:

image : HDUList

Input image.

refwcs : HSTWCS

Definition of the reference frame WCS.

dqname : str, optional

EXTNAME for the DQ array, if present, in the input image.

output : bool, optional

Specify whether or not to write out a separate catalog file for all the sources found in each chip.

Returns:

master_cat : Table

Source catalog for all ‘valid’ sources identified from all chips of the input image with positions translated to the reference WCS coordinate frame.

drizzlepac.hlautils.astrometric_utils.compute_photometry(catalog, photmode)

Compute magnitudes for sources from catalog based on observations photmode.

Parameters:

catalog : Table

Astropy Table with ‘source_sum’ column for the measured flux for each source.

photmode : str

Specification of the observation filter configuration used for the exposure as reported by the ‘PHOTMODE’ keyword from the PRIMARY header.

Returns:

phot_cat : Table

Astropy Table object of input source catalog with added column for VEGAMAG photometry (in magnitudes).

drizzlepac.hlautils.astrometric_utils.filter_catalog(catalog, bright_limit=1.0, max_bright=None, min_bright=20, colname='vegamag')

Create a new catalog selected from input based on photometry.

Parameters:

catalog : Table

Table containing the full set of identified sources.

bright_limit : float

Fraction of catalog based on brightness that should be retained. Value of 1.00 means full catalog.

max_bright : int

Maximum number of sources to keep regardless of bright_limit.

min_bright : int

Minimum number of sources to keep regardless of bright_limit.

colname : str

Name of column to use for selection/sorting.

Returns:

new_catalog : Table

New table which only has the sources that meet the selection criteria.

drizzlepac.hlautils.astrometric_utils.build_self_reference(filename, clean_wcs=False)

This function creates a reference, undistorted WCS that can be used to apply a correction to the WCS of the input file.

Parameters:

filename : str

Filename of image which will be corrected, and which will form the basis of the undistorted WCS.

clean_wcs : bool

Specify whether or not to return the WCS object without any distortion information, or any history of the original input image. This converts the output from utils.output_wcs() into a pristine HSTWCS object.

Returns:

customwcs : HSTWCS

HSTWCS object which contains the undistorted WCS representing the entire field-of-view for the input image.

Examples

This function can be used with the following syntax to apply a shift/rot/scale change to the same image:

>>> import buildref
>>> from drizzlepac import updatehdr
>>> filename = "jce501erq_flc.fits"
>>> wcslin = buildref.build_self_reference(filename)
>>> updatehdr.updatewcs_with_shift(filename, wcslin, xsh=49.5694,
... ysh=19.2203, rot = 359.998, scale = 0.9999964)

drizzlepac.hlautils.astrometric_utils.within_footprint(img, wcsobj, x, y)

Determine whether input x, y fall in the science area of the image.

Parameters:

img : ndarray

ndarray of image where non-science areas are marked with value of NaN.

wcsobj : HSTWCS

HSTWCS or WCS object with naxis terms defined.

x, y : ndarray

arrays of x, y positions for sources to be checked.

Returns:

x, y : ndarray

New arrays which have been trimmed of all sources that fall outside the science areas of the image

drizzlepac.hlautils.astrometric_utils.find_hist2d_offset(filename, reference, refwcs=None, refnames=['ra', 'dec'], match_tolerance=5.0, chip_catalog=True, search_radius=15.0, min_match=10, classify=True)

Iteratively look for the best cross-match between the catalog and ref.

Parameters:

filename : HDUList or str

Single image to extract sources for matching to the external astrometric catalog.

reference : str or Table

Reference catalog, either as a filename or astropy.Table containing astrometrically accurate sky coordinates for astrometric standard sources.

refwcs : HSTWCS

This WCS will define the coordinate frame which will be used to determine the offset. If None is specified, use the WCS from the input image filename to build this WCS using build_self_reference().

refnames : list

List of table column names for sky coordinates of astrometric standard sources from reference catalog.

match_tolerance : float

Tolerance (in pixels) for recognizing that a source position matches an astrometric catalog position. Larger values allow for lower accuracy source positions to be compared to astrometric catalog

chip_catalog : bool

Specify whether or not to write out individual source catalog for each chip in the image.

search_radius : float

Maximum separation (in arcseconds) from source positions to look for valid cross-matches with reference source positions.

min_match : int

Minimum number of cross-matches for an acceptable determination of the offset.

classify : bool

Specify whether or not to use central_moments classification to ignore likely cosmic-rays/bad-pixels when generating the source catalog.

Returns:

best_offset : tuple

Offset in input image pixels between image source positions and astrometric catalog positions that results in largest number of matches of astrometric sources with image sources

seg_xy, ref_xy : Table

Source catalog and reference catalog, respectively, used for determining the offset. Each catalog includes sources for the entire field-of-view, not just a single chip.

drizzlepac.hlautils.astrometric_utils.build_wcscat(image, group_id, source_catalog)

Return a list of FITSWCS objects for all chips in an image.

Parameters:

image : str, HDUList

Either filename or HDUList of a single HST observation.

group_id : int

Integer ID for group this image should be associated with; primarily used when separate chips are in separate files to treat them all as one exposure.

source_catalog : dict

If provided, these catalogs will be attached as catalog entries in each chip’s FITSWCS object. It should be provided as a dict of astropy Tables identified by chip number with each table containing sources from image extension ('sci', chip) as generated by generate_source_catalog().

Returns:

wcs_catalogs : list of FITSWCS

List of FITSWCS objects defined for all chips in input image.

Wrappers for astroquery-related functionality

drizzlepac.hlautils.astroquery_utils.retrieve_observation(obsid, suffix=['FLC'], archive=False, clobber=False)

Simple interface for retrieving an observation from the MAST archive

If the input obsid is for an association, it will request all members with the specified suffixes.

Parameters:

obsid : string

ID for observation to be retrieved from the MAST archive. Only the IPPSSOOT (rootname) of exposure or ASN needs to be provided; eg., ib6v06060.

suffix : list, optional

List containing suffixes of files which should be requested from MAST. Default value “[‘FLC’]”.

archive : Boolean, optional

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

clobber : Boolean, optional

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

Returns:

local_files : list

List of filenames