# TWEAKUTILS: Utility Functions for Tweakreg

The functions in this module support the various aspects of `tweakreg`, including finding the objects in the images and plotting the residuals.

Authors: | Warren Hack
License: | http://www.stsci.edu/resources/software_hardware/pyraf/LICENSE

`drizzlepac.tweakutils.``build_pos_grid`(start, end, nstep, mesh=False)

  Return a grid of positions starting at X,Y given by ‘start’, and ending at X,Y given by ‘end’. The grid will be completely filled in X and Y by every ‘step’ interval.

`drizzlepac.tweakutils.``build_xy_zeropoint`(imgxy, refxy, searchrad=3.0, histplot=False, figure_id=1, plotname=None, interactive=True)

  Create a matrix which contains the delta between each XY position and each UV position.

`drizzlepac.tweakutils.``createWcsHDU`(wcs)

  Generate a WCS header object that can be used to populate a reference WCS HDU.

  For most applications, stwcs.wcsutil.HSTWCS.wcs2header() will work just as well.

`drizzlepac.tweakutils.``find_xy_peak`(img, center=None, sigma=3.0)

  Find the center of the peak of offsets

`drizzlepac.tweakutils.``gauss`(x, sigma)

  Compute 1-D value of gaussian at position x relative to center.

`drizzlepac.tweakutils.``gauss_array`(nx, ny=None, fwhm=1.0, sigma_x=None, sigma_y=None, zero_norm=False)

  Computes the 2D Gaussian with size nx*ny.

  Parameters: | nx : int ny : int [Default: None] Size of output array for the generated Gaussian. If ny == None, output will be an array nx X nx pixels. fwhm : float [Default: 1.0] Full-width, half-maximum of the Gaussian to be generated sigma_x : float [Default: None] sigma_y : float [Default: None] Sigma_x and sigma_y are the stddev of the Gaussian functions. zero_norm : bool [Default: False] The kernel will be normalized to a sum of 1 when True.
  Returns: | gauss_arr : array A numpy array with the generated gaussian function

`drizzlepac.tweakutils.``isfloat`(value)

  Return True if all characters are part of a floating point value

`drizzlepac.tweakutils.``make_vector_plot`(coordfile, columns=[1, 2, 3, 4], data=None, figure_id=None, title=None, axes=None, every=1, labelsize=8, ylimit=None, limit=None, xlower=None, ylower=None, output=None, headl=4, headw=3, xsh=0.0, ysh=0.0, fit=None, scale=1.0, vector=True, textscale=5, append=False, linfit=False, rms=True, plotname=None)

  Convert a XYXYMATCH file into a vector plot or set of residuals plots.

  This function provides a single interface for generating either a vector plot of residuals or a set of 4 plots showing residuals. The data being plotted can also be adjusted for a linear fit on-the-fly.

  Parameters: | coordfile : string Name of file with matched sets of coordinates. This input file can be a file compatible for use with IRAF’s geomap. columns : list [Default: [0,1,2,3]] Column numbers for the X,Y positions from each image data : list of arrays If specified, this can be used to input matched data directly title : string Title to be used for the generated plot axes : list List of X and Y min/max values to customize the plot axes every : int [Default: 1] Slice value for the data to be plotted limit : float Radial offset limit for selecting which sources are included in the plot labelsize : int [Default: 8] or str Font size to use for tick labels, either in font points or as a string understood by tick_params(). ylimit : float Limit to use for Y range of plots. xlower : float ylower : float Limit in X and/or Y offset for selecting which sources are included in the plot output : string Filename of output file for generated plot headl : int [Default: 4] Length of arrow head to be used in vector plot headw : int [Default: 3] Width of arrow head to be used in vector plot xsh : float ysh : float Shift in X and Y from linear fit to be applied to source positions from the first image scale : float Scale from linear fit to be applied to source positions from the first image fit : array Array of linear coefficients for rotation (and scale?) in X and Y from a linear fit to be applied to source positions from the first image vector : bool [Default: True] Specifies whether or not to generate a vector plot. If False, task will generate a set of 4 residuals plots instead textscale : int [Default: 5] Scale factor for text used for labelling the generated plot append : bool [Default: False] If True, will overplot new plot on any pre-existing plot linfit : bool [Default: False] If True, a linear fit to the residuals will be generated and added to the generated residuals plots rms : bool [Default: True] Specifies whether or not to report the RMS of the residuals as a label on the generated plot(s). plotname : str [Default: None] Write out plot to a file with this name if specified.

`drizzlepac.tweakutils.``ndfind_old`(array, hmin, fwhm, sharplim=[0.2, 1.0], roundlim=[-1, 1], minpix=5, datamax=None)

  Source finding algorithm based on NDIMAGE routines

  This function provides a simple replacement for the DAOFIND task.

  Parameters: | array : arr Input image as numpy array hmin : float Limit for source detection in pixel values fwhm : float Full-width half-maximum of the PSF in the image minpix : int Minimum number of pixels for any valid source sharplim : tuple [Not used at this time] roundlim : tuple [Not used at this time] datamax : float Maximum good pixel value found in any detected source
  Returns: | x : arr Array of detected source X positions (in array coordinates, 0-based) y : arr Array of detected source Y positions (in array coordinates, 0-based) flux : arr Array of detected source fluxes in pixel values id : arr Array of detected source ID numbers

`drizzlepac.tweakutils.``parse_atfile_cat`(input)

  Return the list of catalog filenames specified as part of the input @-file

`drizzlepac.tweakutils.``parse_colname`(colname)

  Common function to interpret input column names provided by the user.

  This function translates column specification provided by the user into a column number.

  Parameters: | colname : Column name or names to be interpreted
  Returns: | cols : list The return value will be a list of strings.

  Notes

  This function will understand the following inputs:

      '1,2,3' or   'c1,c2,c3' or ['c1','c2','c3']
      '1-3'   or   'c1-c3'
      '1:3'   or   'c1:c3'
      '1 2 3' or   'c1 c2 c3'
      '1'     or   'c1'
      1

`drizzlepac.tweakutils.``parse_exclusions`(exclusions)

  Read in exclusion definitions from file named by ‘exclusions’ and return a list of positions and distances

`drizzlepac.tweakutils.``parse_skypos`(ra, dec)

  Function to parse RA and Dec input values and turn them into decimal degrees

  Input formats could be:
    [“nn”,”nn”,”nn.nn”] “nn nn nn.nnn” “nn:nn:nn.nn” “nnH nnM nn.nnS” or “nnD nnM nn.nnS” nn.nnnnnnnn “nn.nnnnnnn”

`drizzlepac.tweakutils.``plot_zeropoint`(pars)

  Plot 2d histogram.

  Pars will be a dictionary containing:
    data, figure_id, vmax, title_str, xp,yp, searchrad

`drizzlepac.tweakutils.``radec_hmstodd`(ra, dec)

  Function to convert HMS values into decimal degrees.

  This function relies on the astropy.coordinates package to perform the conversion to decimal degrees.

  Parameters: | ra : list or array List or array of input RA positions dec : list or array List or array of input Dec positions
  Returns: | pos : arr Array of RA,Dec positions in decimal degrees

  See also

  `astropy.coordinates`

  Notes

  This function supports any specification of RA and Dec as HMS or DMS; specifically, the formats:

      ["nn","nn","nn.nn"]
      "nn nn nn.nnn"
      "nn:nn:nn.nn"
      "nnH nnM nn.nnS" or "nnD nnM nn.nnS"

`drizzlepac.tweakutils.``read_ASCII_cols`(infile, cols=[1, 2, 3])

  Interpret input ASCII file to return arrays for specified columns.

  Returns: | outarr : list of arrays The return value will be a list of numpy arrays, one for each ‘column’.

  Notes

  The specification of the columns should be expected to have lists for each ‘column’, with all columns in each list combined into a single entry. For example:

      cols = ['1,2,3','4,5,6',7]

  where ‘1,2,3’ represent the X/RA values, ‘4,5,6’ represent the Y/Dec values and 7 represents the flux value for a total of 3 requested columns of data to be returned.

`drizzlepac.tweakutils.``read_FITS_cols`(infile, cols=None)

  Read columns from FITS table

`drizzlepac.tweakutils.``readcols`(infile, cols=None)

  Function which reads specified columns from either FITS tables or ASCII files

  This function reads in the columns specified by the user into numpy arrays regardless of the format of the input table (ASCII or FITS table).

  Parameters: | infile : string Filename of the input file cols : string or list of strings Columns to be read into arrays
  Returns: | outarr : array Numpy array or arrays of columns from the table

`drizzlepac.tweakutils.``write_shiftfile`(image_list, filename, outwcs='tweak_wcs.fits')

  Write out a shiftfile for a given list of input Image class objects