HAP API
These modules provide the basic functionality used to process automatically data using this package to apply the distortion models to the WCS of HST observations and to verify the alignment of the observations.
align
This script is a modernized implementation of tweakreg.
- drizzlepac.align.perform_align(input_list, catalog_list, num_sources, archive=False, clobber=False, debug=False, update_hdr_wcs=False, result=None, runfile='temp_align.log', print_fit_parameters=True, print_git_info=False, output=False, headerlet_filenames=None, fit_label=None, product_type=None, **alignment_pars)[source]
Actual Main calling function.
This function performs
a posteriori
astrometric fits to the images specified in theinput_list
. The images are fit to all the catalogs listed in thecatalog_list
parameter with the results being saved and returned as an Astropy Table object. This allows the user to select the solution that is most appropriate.- Parameters:
- input_listlist
List of one or more IPPSSOOTs (rootnames) to align.
- catalog_listlist
Set of astrometric catalogs which should be used as references for fitting the input images. A separate fit will be performed for each catalog specified. The catalog name will also be used as part of the output
WCSNAME
value for the fit determined from that catalog.- num_sourcesint, None
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.
- archiveBoolean
Retain copies of the downloaded files in the astroquery created sub-directories?
- clobberBoolean
Download and overwrite existing local copies of input files?
- debugBoolean
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_wcsBoolean
Write newly computed WCS information to image image headers?
- result: Table
name of variable to be updated by subroutine run.
- runfilestring
log file name
- print_fit_parametersBoolean
Specify whether or not to print out FIT results for each chip.
- print_git_infoBoolean
Display git repository information?
- outputBoolean
Should utils.astrometric_utils.create_astrometric_catalog() generate file ‘ref_cat.ecsv’ and should the alignment source catalogs get written out to files?
- headerlet_filenamesdictionary, optional
dictionary that maps the flt/flc.fits file name to the corresponding custom headerlet filename.
- fit_labelstr
String to use as a unique tag for the WCS solutions generated by these fits. This tag will be inserted between the
-FIT
and the catalog name in theWCSNAME` keyword value; for example, ``fit_label="User"
will result in fits to GAIAedr3 with names ending in-FIT_User_GAIAedr3
.- alignment_parsdictionary or keyword args
keyword-arg parameters containing user-specified values for the parameters used in source identification and alignment which should replace the default values found in the JSON parameter files in
drizzlepac.pars.hap_pars
based on the instrument and detector. The code will look for default values for all the parameters in the JSON parameter files usingget_default_pars
. For example, should the user feel it would be more successful to only look out to a radius of 25 pixels during alignment, the user could simply specifysearchrad=25
.
- Returns:
- filtered_tableAstropy Table
Table gets updated to contain processing information and alignment results for every raw image evaluated
- drizzlepac.align.determine_fit_quality(imglist, filtered_table, catalogs_remaining, align_pars, print_fit_parameters=True, loglevel=0, runfile='temp_align.log')[source]
Determine the quality of the fit to the data
- Parameters:
- imglistlist
output of interpret_fits. Contains sourcelist tables, newly computed WCS info, etc. for every chip of every valid input image. This list should have been updated, in-place, with the new RMS values; specifically,
‘FIT_RMS’: RMS of the separations between fitted image positions and reference positions
‘TOTAL_RMS’: mean of the FIT_RMS values for all observations
‘NUM_FITS’: number of images/group_id’s with successful fits included in the TOTAL_RMS
These entries are added to the ‘fit_info’ dictionary.
- filtered_tableobject
Astropy Table object containing data pertaining to the associated dataset, including the doProcess bool. It is intended this table is updated by subsequent functions for bookkeeping purposes.
- catalogs_remainingbool
Specify whether additional catalogs remain to be fit against.
- align_parsdict
Parameters from the appropriate ‘_align_all.json’ parameter file
- print_fit_parametersbool
Specify whether or not to print out FIT results for each chip
- log_levelint, optional
The desired level of verboseness in the log statements displayed on the screen and written to the .log file. Default value is 20, or ‘info’.
- runfilestring
log file name
- Returns:
- max_rms_valfloat
The best Total rms determined from all of the images
- num_xmatches: int
The number of stars used in matching the data
- fit_qualityint
- fit quality category:
1 = valid solution with rms < 10 mas
2 = Valid but compromised solution with rms < 10 mas
3 = Valid solution with RMS >= 10 mas
4 = Valid but compromised solution with RMS >= 10 mas
5 = Not valid solution
- filtered_tableobject
modified filtered_table object
- fit_status_dictdictionary
- Dictionary containing the following:
overall fit validity (Boolean)
total (visit-level) RMS value in mas (float)
number of matched sources (int)
fit compromised status (Boolean)
reason fit is considered ‘compromised’ (only populated if “compromised” field is “True”)
haputils.astrometric_utils
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.haputils.astrometric_utils.create_astrometric_catalog(inputs, catalog='GAIAedr3', output='ref_cat.ecsv', gaia_only=False, table_format='ascii.ecsv', existing_wcs=None, num_sources=None, use_footprint=False, full_catalog=False, user_epoch='match', log_level=20)[source]
Create an astrometric catalog that covers the inputs’ field-of-view.
This function will return a table containing sources derived from the selected astrometric catalog specified by the user for the field-of-view covered by the list of input images.
Note
The output table generated by this function will have a pre-defined set of columns with common names for catalogs included in
SUPPORTED_CATALOGS
. Columns which don’t exist in the catalog will be added with null (None) values. The common column names are:RA, DEC : RA, DEC of source
RA_error, DEC_error : error in RA, DEC position
objID : object ID from catalog
pmra, pmdec : Proper motion in RA and DEC
pmra_error, pmdec_error : errors in the proper motion
mag : reported magnitude for the source
epoch : epoch of RA, DEC after applying proper motions from catalog (if any)
All tables where columns have been renamed have ‘.meta[“converted”]’ set to ‘True’.
- Parameters:
- inputstr, list
Filenames of images to be aligned to astrometric catalog
- catalogstr, optional
Name of catalog to extract astrometric positions for sources in the input images’ field-of-view. Default: GAIAeDR3. Only those catalogs listed in
SUPPORTED_CATALOGS
will be returned with standardized column names. Catalog names are case-insensitive.- outputstr, 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_onlybool, optional
Specify whether or not to only use sources from GAIA in output catalog
- existing_wcsstwcs.wcsutil.HSTWCS
existing WCS object specified by the user
- num_sourcesint
Maximum number of brightest/faintest sources to return in catalog. If
num_sources
is negative, return that number of the faintest sources. By default, all sources are returned.- use_footprintbool, optional
Use the image footprint as the source identification bounds insted of using a circle centered on a given RA and Dec? By default, use_footprint = False.
- full_catalogbool, optional
Return the full set of columns provided by the web service.
- user_epochstr or float, optional
Epoch of returned astrometric catalog. If ‘match’, match the epoch of the specified observation. If None, return the values at the epoch of the catalog. If a decimal year is specified, returned values will be for that epoch.
- Returns:
- ref_tableastropy.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.haputils.astrometric_utils.compute_radius(wcs)[source]
Compute the radius from the center to the furthest edge of the WCS.
- Parameters:
- wcsstwcs.wcsutil.HSTWCS object
HSTWCS object for an exposure including a valid footprint
- drizzlepac.haputils.astrometric_utils.build_auto_kernel(imgarr, whtarr, fwhm=3.0, threshold=None, source_box=7, good_fwhm=[1.0, 4.0], num_fwhm=30, isolation_size=11, saturation_limit=70000.0, log_level=20)[source]
Build kernel for use in source detection based on image PSF This algorithm looks for an isolated point-source that is non-saturated to use as a template for the source detection kernel. Failing to find any suitable sources, it will return a Gaussian2DKernel based on the provided FWHM as a default.
- Parameters:
- imgarrndarray
Image array (ndarray object) with sources to be identified
- whtarrndarray
Image array (ndarray object) for
imgarr
that provides an estimate of the weight or errors for the processed image.- fwhmfloat
Value of FWHM to use for creating a Gaussian2DKernel object in case no suitable source can be identified in the image.
- thresholdfloat
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_boxint
Size of box (in pixels) which defines the minimum size of a valid source.
- isolation_sizeint
Separation (in pixels) to use to identify sources that are isolated from any other sources in the image.
- saturation_limitfloat
Flux in the image that represents the onset of saturation for a pixel.
Notes
Ideally, it would be best to determine the saturation_limit value from the data itself, perhaps by looking at the pixels flagged (in the DQ array) as saturated and selecting the value less than the minimum flux of all those pixels, or maximum pixel value in the image if non-were flagged as saturated (in the DQ array).
- drizzlepac.haputils.astrometric_utils.find_fwhm(psf, default_fwhm)[source]
Determine FWHM for auto-kernel PSF
This function iteratively fits a Gaussian model to the extracted PSF using photutils.psf.IterativelySubtractedPSFPhotometry to determine the FWHM of the PSF.
- Parameters:
- psfndarray
Array (preferably a slice) containing the PSF to be measured.
- default_fwhmfloat
Starting guess for the FWHM
- Returns:
- fwhmfloat
Value of the computed Gaussian FWHM for the PSF
- drizzlepac.haputils.astrometric_utils.get_catalog(ra, dec, sr=0.1, epoch=None, catalog='GSC241')[source]
Extract reference catalog from VO web service.
Queries the catalog available at the
SERVICELOCATION
specified for this module to get any available astrometric source catalog entries around the specified position in the sky based on a cone-search.- Parameters:
- rafloat
Right Ascension (RA) of center of field-of-view (in decimal degrees)
- decfloat
Declination (Dec) of center of field-of-view (in decimal degrees)
- srfloat, optional
Search radius (in decimal degrees) from field-of-view center to use for sources from catalog. Default: 0.1 degrees
- epochfloat, optional
Catalog positions returned for this field-of-view will have their proper motions applied to represent their positions at this date, if a value is specified at all, for catalogs with proper motions.
- catalogstr, optional
Name of catalog to query, as defined by web-service. Default: ‘GSC241’
- Returns:
- csvCSV object
CSV object of returned sources with all columns as provided by catalog
- drizzlepac.haputils.astrometric_utils.get_catalog_from_footprint(footprint, epoch=None, catalog='GSC241')[source]
Extract catalog from VO web service based on the specified footprint
Queries the catalog available at the
SERVICELOCATION
specified for this module to get any available astrometric source catalog entries around the specified position in the sky based on the input footprint.- Parameters:
- footprintnumpy.ndarray
Array of RA, Dec points that describe the footprint polygon
- epochfloat, optional
Catalog positions returned for this field-of-view will have their proper motions applied to represent their positions at this date, if a value is specified at all, for catalogs with proper motions.
- catalogstr, optional
Name of catalog to query, as defined by web-service. Default: ‘GSC241’
- Returns:
- csvCSV object
CSV object of returned sources with all columns as provided by catalog
- drizzlepac.haputils.astrometric_utils.extract_sources(img, dqmask=None, fwhm=3.0, kernel=None, photmode=None, segment_threshold=None, dao_threshold=None, dao_nsigma=3.0, source_box=7, classify=True, centering_mode='starfind', nlargest=None, outroot=None, plot=False, vmax=None, deblend=False, log_level=20)[source]
Use photutils to find sources in image based on segmentation.
- Parameters:
- imgndarray
Numpy array of the science extension from the observations FITS file.
- dqmaskndarray
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.
- fwhmfloat
Full-width half-maximum (fwhm) of the PSF in pixels.
- kernelndarray
A numpy array representing the PSF to be used for identifying sources. Image will be convolved with this kernel to highlight sources with shapes similar to the kernel. [Starting in v3.6.0] If None is given, a default 2D Gaussian kernel will be generated with
build_gaussian_kernel
and used based onfwhm
andsource_box
for the size.- photmodestr
Specification of the observation filter configuration used for the exposure as reported by the ‘PHOTMODE’ keyword from the PRIMARY header.
- segment_thresholdndarray 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)).
- dao_thresholdfloat, optional
[Deprecated] This parameter is not used. In fact, it now gets computed internally using the
sigma_clipped_bkg()
function which uses thedao_nsigma
parameter.- dao_nsigmafloat
This number gets used to determine the threshold for detection of point sources. The threshold gets computed using a simple
mean + dao_nsigma * rms
, where themean
andrms
are computed from the background levels usingastropy.stats.sigma_clipped_stats
.- source_boxint
Size of each side of a box (in pixels) which defines the minimum size of a valid source.
- classifybool
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_modestr
“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 usingsegmentation
will rely onphotutils.segmentation.SourceCatalog
to generate the properties for the source catalog. Centering usingstarfind
will usephotutils.detection.IRAFStarFinder
to characterize each source in the catalog.- nlargestint, None
Number of largest (brightest) sources in each chip/array to measure when using ‘starfind’ mode.
- outrootstr, optional
If specified, write out the catalog of sources to the file with this name rootname.
- plotbool, optional
Specify whether or not to create a plot of the sources on a view of the image.
- vmaxfloat, optional
If plotting the sources, scale the image to this maximum value.
- deblendbool, optional
Specify whether or not to apply photutils deblending algorithm when evaluating each of the identified segments (sources) from the chip.
- log_levelint, optional
The desired level of verboseness in the log statements displayed on the screen and written to the .log file. Default value is 20, or ‘info’.
- drizzlepac.haputils.astrometric_utils.classify_sources(catalog, fwhm, sources=None)[source]
Convert moments_central attribute for source catalog into star/cr flag.
This algorithm interprets the central_moments from the SourceCatalog 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:
- catalogphotutils.segmentation.SourceCatalog
The photutils catalog for the image/chip.
- sourcestuple
Range of objects from catalog to process as a tuple of (min, max). If None (default) all sources are processed.
- Returns:
- srctypendarray
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.haputils.astrometric_utils.generate_source_catalog(image, dqname='DQ', output=False, fwhm=3.0, **detector_pars)[source]
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:
- imageastropy.io.fits.HDUList
Input image as an astropy.io.fits HDUList.
- dqnamestr
EXTNAME for the DQ array, if present, in the input image HDUList.
- outputbool
Specify whether or not to write out a separate catalog file for all the sources found in each chip.
- fwhmfloat
Full-width half-maximum (fwhm) of the PSF in pixels.
- Returns:
- source_catsdict
Dict of astropy Tables identified by chip number with each table containing sources from image extension
('sci', chip)
.
- drizzlepac.haputils.astrometric_utils.generate_sky_catalog(image, refwcs, dqname='DQ', output=False)[source]
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:
- imageastropy.io.fits.HDUList
Input image.
- refwcsstwcs.wcsutil.HSTWCS
Definition of the reference frame WCS.
- dqnamestr, optional
EXTNAME for the DQ array, if present, in the input image.
- outputbool, optional
Specify whether or not to write out a separate catalog file for all the sources found in each chip.
- Returns:
- master_cat
astropy.table.Table
Source catalog for all ‘valid’ sources identified from all chips of the input image with positions translated to the reference WCS coordinate frame.
- master_cat
- drizzlepac.haputils.astrometric_utils.compute_photometry(catalog, photvals)[source]
Compute magnitudes for sources from catalog based on observations photmode.
Magnitudes will be AB mag values.
- Parameters:
- catalogastropy.table.Table
Astropy Table with ‘source_sum’ column for the measured flux for each source.
- photmodestr
Specification of the observation filter configuration used for the exposure as reported by the ‘PHOTMODE’ keyword from the PRIMARY header.
- Returns:
- phot_catastropy.table.Table
Astropy Table object of input source catalog with added column for ABMAG photometry (in magnitudes).
- drizzlepac.haputils.astrometric_utils.filter_catalog(catalog, bright_limit=1.0, max_bright=None, min_bright=20, colname='vegamag')[source]
Create a new catalog selected from input based on photometry.
- Parameters:
- catalogastropy.table.Table
Table containing the full set of identified sources.
- bright_limitfloat
Fraction of catalog based on brightness that should be retained. Value of 1.00 means full catalog.
- max_brightint
Maximum number of sources to keep regardless of
bright_limit
.- min_brightint
Minimum number of sources to keep regardless of
bright_limit
.- colnamestr
Name of column to use for selection/sorting.
- Returns:
- new_catalogastropy.table.Table
New table which only has the sources that meet the selection criteria.
- drizzlepac.haputils.astrometric_utils.build_self_reference(filename, clean_wcs=False)[source]
This function creates a reference, undistorted WCS that can be used to apply a correction to the WCS of the input file.
- Parameters:
- filenamestr
Filename of image which will be corrected, and which will form the basis of the undistorted WCS.
- clean_wcsbool
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 stwcs.wcsutil.HSTWCS object.
- Returns:
- customwcsstwcs.wcsutil.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.haputils.astrometric_utils.within_footprint(img, wcsobj, x, y)[source]
Determine whether input x, y fall in the science area of the image.
- Parameters:
- imgndarray
ndarray of image where non-science areas are marked with value of NaN.
- wcsobjstwcs.wcsutil.HSTWCS
HSTWCS or WCS object with naxis terms defined.
- x, yndarray
arrays of x, y positions for sources to be checked.
- Returns:
- maskndarray
Boolean array of same length as x,y arrays where sources that fall within the footprint are True.
- drizzlepac.haputils.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)[source]
Iteratively look for the best cross-match between the catalog and ref.
- Parameters:
- filenameastropy.io.fits.HDUList or str
Single image to extract sources for matching to the external astrometric catalog.
- referencestr or astropy.table.Table
Reference catalog, either as a filename or
astropy.Table
containing astrometrically accurate sky coordinates for astrometric standard sources.- refwcsstwcs.wcsutil.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 usingbuild_self_reference()
.- refnameslist
List of table column names for sky coordinates of astrometric standard sources from reference catalog.
- match_tolerancefloat
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_catalogbool
Specify whether or not to write out individual source catalog for each chip in the image.
- search_radiusfloat
Maximum separation (in arcseconds) from source positions to look for valid cross-matches with reference source positions.
- min_matchint
Minimum number of cross-matches for an acceptable determination of the offset.
- classifybool
Specify whether or not to use central_moments classification to ignore likely cosmic-rays/bad-pixels when generating the source catalog.
- Returns:
- best_offsettuple
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_xyastropy.table.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.haputils.astrometric_utils.build_wcscat(image, group_id, source_catalog)[source]
Return a list of tweakwcs.correctors.FITSWCSCorrector objects for all chips in an image.
- Parameters:
- imagestr, astropy.io.fits.HDUList
Either filename or HDUList of a single HST observation.
- group_idint
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_catalogdict
If provided, these catalogs will be attached as
catalog
entries in each chip’sFITSWCSCorrector
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 bygenerate_source_catalog()
.
- Returns:
- wcs_catalogslist of tweakwcs.correctors.FITSWCSCorrector
List of tweakwcs.correctors.FITSWCSCorrector objects defined for all chips in input image.
- drizzlepac.haputils.astrometric_utils.compute_similarity(image, reference)[source]
Compute a similarity index for an image compared to a reference image.
Similarity index is based on a the general algorithm used in the AmphiIndex algorithm.
identify slice of image that is a factor of 256 in size
rebin image slice down to a (256,256) image
rebin same slice from reference down to a (256,256) image
sum the differences of the rebinned slices
divide absolute value of difference scaled by reference slice sum
Note
This index will typically return values < 0.1 for similar images, and values > 1 for dis-similar images.
- Parameters:
- imagendarray
Image (as ndarray) to measure
- referencendarray
Image which serves as the ‘truth’ or comparison image.
- Returns:
- similarity_indexfloat
Value of similarity index for
image
- drizzlepac.haputils.astrometric_utils.determine_focus_index(img, sigma=1.5)[source]
Determine blurriness indicator for an image
This returns a single value that serves as an indication of the sharpness of the image based on the max pixel value from the image after applying a Laplacian-of-Gaussian filter with sigma.
Implementation based on discussion from: https://stackoverflow.com/questions/7765810/is-there-a-way-to-detect-if-an-image-is-blurry
as supported by: Pertuz, S., et.al., 2013, Pattern Recognition, 46:1415–1432
This index needs to be based on ‘max’ value in order to avoid field-dependent biases, since the ‘max’ value will correspond to point-source-like sources regardless of the field (nebula, galaxy, …). Care must be taken, though, to ignore cosmic-rays as much as possible as they will mimic real sources without providing information on the actual focus through the optics. Similarly, saturation regions must also be ignored as they also only indicate a detector feature, not the focus through the optics or alignment of actual sources.
- drizzlepac.haputils.astrometric_utils.max_overlap_diff(total_mask, singlefiles, prodfile, sigma=2.0, scale=1, lsigma=3.0)[source]
Determines the difference in the region of max overlap for all drizzled products
- Parameters:
- total_maskndarray
Mask (array) showing where each input exposure contributes to the final drizzle product
prodfile
. This could be created usingcell_utils.SkyFootprint
.- singlefileslist
List of filenames for each single input exposure drizzled onto the same WCS as the final drizzle product
prodfile
- prodfilestr
Filename for the final drizzle product
- scaleint, optional
Factor to use in downsizing (resizing smaller) the images to be evaluated. The larger the value, the less sensitive this measurement becomes.
- sigmafloat, optional
Size of default kernel (in pixels) to use for determining the focus.
- Returns:
- diff_dictdictionary
Dictionary of difference scores for each input exposure drizzle product (from
singlefiles
) calculated for the region of maximum overlap with the final drizzle productprodfile
. Entries for each singlefile includes:distance
Hamming distance of singlefile from prodfile
focus
focus index of singlefile
focus_pos
position for best focus in singlefile
product_focus
focus index for prodfile
product_focus_pos
position for best focus in prodfile
haputils.astroquery_utils
Wrappers for astroquery-related functionality
- drizzlepac.haputils.astroquery_utils.retrieve_observation(obsid, suffix=['FLC'], archive=False, clobber=False, product_type=None)[source]
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:
- obsidstring or list of strings
ID or list of IDs for observations to be retrieved from the MAST archive. Only the IPPSSOOT (rootname) of exposure or ASN needs to be provided; eg., ib6v06060. Additionally, a wild-carded
obsid
can be provided to retrieve all products for a visit; e.g., “ib6v06*”. Data from multiple ASNs, exposures or visits can be retrieved by simply providing them as a list.- suffixlist, optional
List containing suffixes of files which should be requested from MAST. Default value “[‘FLC’]”.
- 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”.
- product_typestr, optional
Specify what type of product you want from the archive, either ‘pipeline’ or ‘HAP’ or ‘both’ (default). By default, all versions of the products processed for the requested datasets will be returned. This would include:
- pipelinefiles processed by
runastrodriz
to include the latest distortion calibrations and the best possible alignment to GAIA with
ipppssoot_fl[tc].fits
filenames for FLT/FLC files.
- pipelinefiles processed by
- HAPfiles processed as a single visit and aligned (as possible) to GAIA
with
hst_<propid>_<visit>_<instr>_<det>_<filter>_<ipppssoo>_fl[tc].fits
filenames.
- Returns:
- local_fileslist
List of filenames
haputils.analyze
Utilities to analyze an input and determine whether the input is viable for a given process
The fundamental function analyze_data opens an input list containing FLT and/or FLC FITS filenames in order to access the primary header data. Based upon the values of specific FITS keywords, the function determines whether or not each file within this dataset can or should be reconciled against an astrometric catalog and, for multiple images, used to create a mosaic.
The functions, mvm_analyze_wrapper and analyze_wrapper, are thin wrappers around analyze_data to accommodate special case uses. The mvm_analyze_wrapper takes a filename as input and returns a boolean indicator. The analyze_wrapper has the same function signature as analyze_data, but it returns a list instead of an astropy table.
- drizzlepac.haputils.analyze.analyze_data(input_file_list, log_level=10, type='')[source]
Determine if images within the dataset can be aligned
- Parameters:
- input_file_listlist
List containing FLT and/or FLC filenames for all input images which comprise an associated dataset where ‘associated dataset’ may be a single image, multiple images, an HST association, or a number of HST associations
- log_levelint, optional
The desired level of verboseness in the log statements displayed on the screen and written to the .log file. Default value is 20, or ‘info’.
- typestring
String indicating whether this file is for MVM or some other processing. If type == “MVM”, then Grism/Prism data is ignored. If type == “” (default) or any other string, the Grism/Prism data is considered available for processing unless there is some other issue (i.e., exposure time of zero).
- Returns:
- output_tableobject
Astropy Table object containing data pertaining to the associated dataset, including the do_process bool. It is intended this table is updated by subsequent functions for bookkeeping purposes.
- analyze_data_good_indexlist
indices of the viable images in the input_file_list
Notes
The keyword/value pairs below define the “cannot process categories”. OBSTYPE : is not IMAGING MTFLAG : T SCAN-TYP : C or D (or !N) FILTER : G*, PR*, where G=Grism and PR=Prism FILTER1 : G*, PR*, where G=Grism and PR=Prism FILTER2 : G*, PR*, where G=Grism and PR=Prism TARGNAME : DARK, TUNGSTEN, BIAS, FLAT, EARTH-CALIB, DEUTERIUM EXPTIME : 0 CHINJECT : is not NONE DRIZCORR : OMIT, SKIPPED
The keyword/value pairs below define the category which the data can be processed, but the results may be compromised FGSLOCK : FINE/GYRO, FINE/GY, COARSE, GYROS
FITS Keywords only for WFC3 data: SCAN_TYP, FILTER, and CHINJECT (UVIS) FITS Keywords only for ACS data: FILTER1 and FILTER2
Please be aware of the FITS keyword value NONE vs the Python None.
haputils.align_utils
- class drizzlepac.haputils.align_utils.AlignmentTable(input_list, clobber=False, dqname='DQ', process_type='', log_level=0, **alignment_pars)[source]
This class handles alignment operations for HST data.
- Steps managed by this class include:
find_alignment_sources : iterates over all inputs and identifies sources suitable for alignment.
perform_fit : cross-matches sources using user-specified method and performs fit to user-specified catalog. Cross-matching options include:
relative
,2dhist
ordefault
as reported by theget_fit_methods
method. It then populates the table with the results for this fit.select_fit : extracts the ‘best’ fit to be applied to the data with the ‘best’ fit determined externally by the user based on the set of fit results stored in the
fit_dict
table.apply_fit : Updates all input image WCSs with the result of the selected ‘best’ fit
- Parameters:
- input_listlist
List of input file names to be provided to
analyze.analyze_data
function.- clobberbool, optional
Specifies whether or not to overwrite data on disk with updated versions of the data.
- dqnamestr, optional
Allows the user to customize the name of the extension (
extname
) containing the data quality flags to be applied to the data during source identification.- process_typestr, optional
Specifies what type of data processing is being done on the input data. Values include: ‘’ (default for pipeline processing), ‘SVM’, ‘MVM’.
- log_levelint, optional
Set the logging level for this processing
- alignment_parsdict
Set of alignment parameters to be used for the input data.
**alignment_pars
needs to contain the following entries:{'fwhmpsf': 0.12, # kernel defining, source finding par # background computing pars 'box_size': BKG_BOX_SIZE, 'win_size': BKG_FILTER_SIZE, 'bkg_estimator': SExtractorBackground, 'rms_estimator': StdBackgroundRMS, 'nsigma': 5., 'threshold_flag': None, # object finding pars 'source_box': 7, 'classify': True, 'centering_mode': "starfind", 'nlargest': None, 'plot': False, 'vmax': None, 'deblend': False }
- class drizzlepac.haputils.align_utils.HAPImage(filename)[source]
Core class defining interface for each input exposure/product
Note
This class is compatible with the CatalogImage class, while including additional functionality and attributes required for processing beyond catalog generation.
- drizzlepac.haputils.align_utils.match_relative_fit(imglist, reference_catalog, **fit_pars)[source]
Perform cross-matching and final fit using relative matching algorithm
The fitting performed by this algorithm first aligns all input images specified in the
imglist
to the FIRST image in that list. When this fit is successful, it insures that the images are aligned RELATIVE to each other. This set of co-aligned WCSs are then fit to the specifiedreference_catalog
to improve the absolute astrometry for all input images (when successful).- Parameters:
- imglistlist
List of input image tweakwcs.correctors.FITSWCSCorrector objects with metadata and source catalogs
- reference_catalogTable
Astropy Table of reference sources for this field
- fit_parsdict
Set of parameters and values to be used for the fit. This should include
fitgeom
as well as any tweakwcs.XYXYMatch parameter which the user feels needs to be adjusted to work best with the input data.
- Returns:
- imglistlist
List of input image tweakwcs.correctors.FITSWCSCorrector objects swith metadata and source catalogs
- drizzlepac.haputils.align_utils.match_default_fit(imglist, reference_catalog, **fit_pars)[source]
Perform cross-matching and final fit using default tolerance matching
This function performs the specified type of fit (‘general’, ‘rscale’, …) directly between all input images and the reference catalog. If successful, each input image will have its absolute WCS aligned to the reference catalog.
- Parameters:
- imglistlist
List of input image tweakwcs.correctors.FITSWCSCorrector objects with metadata and source catalogs
- reference_catalogTable
Astropy Table of reference sources for this field
- fit_parsdict
Set of parameters and values to be used for the fit. This should include
fitgeom
as well as any tweakwcs.XYXYMatch parameter which the user feels needs to be adjusted to work best with the input data.
- Returns:
- imglistlist
List of input image tweakwcs.correctors.FITSWCSCorrector objects with metadata and source catalogs
- drizzlepac.haputils.align_utils.match_2dhist_fit(imglist, reference_catalog, **fit_pars)[source]
Perform cross-matching and final fit using 2dHistogram matching
This function performs cross-matching of each separate input image to the sources in the reference catalog by looking for common integer offsets between all sources in the input list and all sources in the reference catalog. This offset is then used as the starting point for the final fit to the reference catalog to align each input image SEPARATELY to the reference catalog.
- Parameters:
- imglistlist
List of input image tweakwcs.correctors.FITSWCSCorrector objects with metadata and source catalogs
- reference_catalogTable
Astropy Table of reference sources for this field
- fit_parsdict
Set of parameters and values to be used for the fit. This should include
fitgeom
as well as any tweakwcs.XYXYMatch parameter which the user feels needs to be adjusted to work best with the input data.
- Returns:
- imglistlist
List of input image tweakwcs.correctors.FITSWCSCorrector objects with metadata and source catalogs