# Utility Functions

These functions perform various small operations within `Multidrizzle`.

A library of utility functions

Authors: | Warren Hack
License: | LICENSE

class `drizzlepac.util.``ProcSteps`

  This class allows MultiDrizzle to keep track of the start and end times of each processing step that gets run as well as computing/reporting the elapsed time for each step.

  The code for each processing step must call the ‘addStep()’ method to initialize the information for that step, then the ‘endStep()’ method to record the end and elapsed times.

  The ‘reportTimes()’ method can then be used to provide a summary of all the elapsed times and total run time.

  `addStep`(key)

    Add information about a new step to the dict of steps The value ‘ptime’ is the output from ‘_ptime()’ containing both the formatted and unformatted time for the start of the step.

  `endStep`(key)

    Record the end time for the step.

    If key==None, simply record ptime as end time for class to represent the overall runtime since the initialization of the class.

  `reportTimes`()

    Print out a formatted summary of the elapsed times for all the performed steps.

class `drizzlepac.util.``WithLogging`

`drizzlepac.util.``applyUserPars_steps`(configObj, input_dict, step='3a')

  Apply logic to turn on use of user-specified output WCS if user provides any parameter on command-line regardless of how final_wcs was set.

`drizzlepac.util.``atfile_ivm`(filename)

  Return the filename of the IVM file which is assumed to be the second word in the atfile the user gave.

`drizzlepac.util.``atfile_sci`(filename)

  Return the filename of the science image which is assumed to be the first word in the atfile the user gave.

`drizzlepac.util.``base_taskname`(taskname, packagename=None)

  Extract the base name of the task.

  Many tasks in the `drizzlepac` have “compound” names such as ‘drizzlepac.sky’. This function will search for the presence of a dot in the input `taskname` and if found, it will return the string to the right of the right-most dot. If a dot is not found, it will return the input string.

  Parameters:

  taskname : str, None

    Full task name. If it is `None`, `base_taskname()` will return `None`.

  packagename : str, None (Default = None)

    Package name. It is assumed that a compound task name is formed by concatenating `packagename` + ‘.’ + `taskname`. If `packagename` is not `None`, `base_taskname()` will check that the string to the left of the right-most dot matches `packagename` and will raise an `AssertionError` if the package name derived from the input `taskname` does not match the supplied `packagename`. This is intended as a check for discrepancies that may arise during the development of the tasks. If `packagename` is `None`, no such check will be performed.

  Raises:

  AssertionError

    Raised when package name derived from the input `taskname` does not match the supplied `packagename`

`drizzlepac.util.``check_blank`(cvar)

  Converts blank value (from configObj?) into a value of None.

`drizzlepac.util.``computeRange`(corners)

  Determine the range spanned by an array of pixel positions.

`drizzlepac.util.``compute_texptime`(imageObjectList)

  Add up the exposure time for all the members in the pattern, since ‘drizzle’ doesn’t have the necessary information to correctly set this itself.

`drizzlepac.util.``countImages`(imageObjectList)

`drizzlepac.util.``count_sci_extensions`(filename)

  Return the number of SCI extensions and the EXTNAME from a input MEF file.

`drizzlepac.util.``createFile`(dataArray=None, outfile=None, header=None)

  Create a simple fits file for the given data array and header. Returns either the FITS object in-membory when outfile==None or None when the FITS file was written out to a file.

`drizzlepac.util.``displayBadRefimageWarningBox`(display=True, parent=None)

  Displays a warning box for the ‘input’ parameter.

`drizzlepac.util.``displayEmptyInputWarningBox`(display=True, parent=None)

  Displays a warning box for the ‘input’ parameter.

`drizzlepac.util.``displayMakewcsWarningBox`(display=True, parent=None)

  Displays a warning box for the ‘makewcs’ parameter.

`drizzlepac.util.``end_logging`(filename=None)

  Close log file and restore system defaults.

`drizzlepac.util.``findWCSExtn`(filename)

  Return new filename with extension that points to an extension with a valid WCS.

  Returns:

  extnum : str, None

    Value of extension name as a string either as provided by the user or based on the extension number for the first extension which contains a valid HSTWCS object. Returns None if no extension can be found with a valid WCS.

  Notes

  The return value from this function can be used as input to

    create another HSTWCS with the syntax:

        `HSTWCS('{}[{}]'.format(filename,extnum))

`drizzlepac.util.``findrootname`(filename)

  Return the rootname of the given file.

`drizzlepac.util.``getConfigObjPar`(configObj, parname)

  Return parameter value without having to specify which section holds the parameter.

`drizzlepac.util.``getDefaultConfigObj`(taskname, configObj, input_dict={}, loadOnly=True)

  Return default configObj instance for task updated with user-specified values from input_dict.

  Parameters:

  taskname : string

    Name of task to load into TEAL

  configObj : string

    The valid values for ‘configObj’ would be:

        None                      - loads last saved user .cfg file
        'defaults'                - loads task default .cfg file
        name of .cfg file (string)- loads user-specified .cfg file

  input_dict : dict

    Set of parameters and values specified by user to be different from what gets loaded in from the .cfg file for the task

  loadOnly : bool

    Setting ‘loadOnly’ to False causes the TEAL GUI to start allowing the user to edit the values further and then run the task if desired.

`drizzlepac.util.``getFullParList`(configObj)

  Return a single list of all parameter names included in the configObj regardless of which section the parameter was stored

`drizzlepac.util.``getRotatedSize`(corners, angle)

  Determine the size of a rotated (meta)image.

`drizzlepac.util.``getSectionName`(configObj, stepnum)

  Return section label based on step number.

`drizzlepac.util.``get_detnum`(hstwcs, filename, extnum)

`drizzlepac.util.``get_expstart`(header, primary_hdr)

  shouldn’t this just be defined in the instrument subclass of imageobject?

`drizzlepac.util.``get_pool_size`(usr_config_value, num_tasks)

  Determine size of thread/process-pool for parallel processing. This examines the cpu_count to decide and return the right pool size to use. Also take into account the user’s wishes via the config object value, if specified. On top of that, don’t allow the pool size returned to be any higher than the number of parallel tasks, if specified. Only use what we need (mp.Pool starts pool_size processes, needed or not). If number of tasks is unknown, call this with “num_tasks” set to None. Returns 1 when indicating that parallel processing should not be used. Consolidate all such logic here, not in the caller.

`drizzlepac.util.``init_logging`(logfile='astrodrizzle.log', default=None, level=20)

  Set up logger for capturing stdout/stderr messages.

  Must be called prior to writing any messages that you want to log.

`drizzlepac.util.``isASNTable`(inputFilelist)

  Return TRUE if inputFilelist is a fits ASN file.

`drizzlepac.util.``isCommaList`(inputFilelist)

  Return True if the input is a comma separated list of names.

`drizzlepac.util.``is_blank`(val)

  Determines whether or not a value is considered ‘blank’.

`drizzlepac.util.``loadFileList`(inputFilelist)

  Open up the ‘@ file’ and read in the science and possible ivm filenames from the first two columns.

`drizzlepac.util.``parse_colnames`(colnames, coords=None)

  Convert colnames input into list of column numbers.

`drizzlepac.util.``printParams`(paramDictionary, all=False, log=None)

  Print nicely the parameters from the dictionary.

`drizzlepac.util.``print_cfg`(cfg, logfn=None)

`drizzlepac.util.``print_key`(key, val, lev=0, logfn=<built-in function print>)

`drizzlepac.util.``print_pkg_versions`(packages=None, git=False, svn=False, log=None)

`drizzlepac.util.``readCommaList`(fileList)

  Return a list of the files with the commas removed.

`drizzlepac.util.``readcols`(infile, cols=[0, 1, 2, 3], hms=False)

  Read the columns from an ASCII file as numpy arrays.

  Parameters:

  infile : str

    Filename of ASCII file with array data as columns.

  cols : list of int

    List of 0-indexed column numbers for columns to be turned into numpy arrays (DEFAULT- [0,1,2,3]).

  Returns:

  outarr : list of numpy arrays

    Simple list of numpy arrays in the order as specifed in the ‘cols’ parameter.

`drizzlepac.util.``removeFileSafely`(filename, clobber=True)

  Delete the file specified, but only if it exists and clobber is True.

`drizzlepac.util.``runmakewcs`(input)

  Runs ‘updatewcs’ to recompute the WCS keywords for the input image.

  Parameters:

  input : list of str

    A list of file names.

  Returns:

  output : list of str

    Returns a list of names of the modified files (For GEIS files returns the translated names).

`drizzlepac.util.``updateNEXTENDKw`(fobj)

  Update NEXTEND keyword in PRIMARY header (if present) to accurately reflect the number of extensions in the MEF file.

`drizzlepac.util.``update_input`(filelist, ivmlist=None, removed_files=None)

  Removes files flagged to be removed from the input filelist. Removes the corresponding ivm files if present.

`drizzlepac.util.``validateUserPars`(configObj, input_dict)

  Compares input parameter names specified by user with those already recognized by the task.

  Any parameters provided by the user that does not match a known task parameter will be reported and a ValueError exception will be raised.

`drizzlepac.util.``verifyFilePermissions`(filelist, chmod=True)

  Verify that images specified in ‘filelist’ can be updated.

  A message will be printed reporting the names of any images which do not have write-permission, then quit.

`drizzlepac.util.``verifyRefimage`(refimage)

  Verify that the value of refimage specified by the user points to an extension with a proper WCS defined. It starts by making sure an extension gets specified by the user when using a MEF file. The final check comes by looking for a CD matrix in the WCS object itself. If either test fails, it returns a value of False.

`drizzlepac.util.``verifyUniqueWcsname`(fname, wcsname)

  Report whether or not the specified WCSNAME already exists in the file

`drizzlepac.util.``verifyUpdatewcs`(fname)

  Verify the existence of WCSNAME in the file. If it is not present, report this to the user and raise an exception. Returns True if WCSNAME was found in all SCI extensions.