# Step 1: Process Input

This module supports the interpretation and initial verification of all the input files specified by the user. These functions:

> - reads in parameter values from MDRIZTAB reference file and merges those merges those values in with the rest of the parameters from the GUI/configObj, if use of MDRIZTAB was specified
> - insure that all input files are multi-extension FITS files and converts them if they are not
> - updates all input WCS’s to be consistent with IDCTAB, if specified
> - generates the ImageObject instances for each input file
> - resets the DQ bits if specified by the user
> - adds info about any user-provided IVM files to the ImageObjects
> - generates the output WCS based on user inputs

Process input to MultiDrizzle/PyDrizzle.

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

The input can be one of:

> - a python list of files
> - a comma separated string of filenames (including wild card characters)
> - an association table
> - an @file (can have a second column with names of ivm files)

No mixture of instruments is allowed. No mixture of association tables, @files and regular fits files is allowed. Files can be in GEIS or MEF format (but not waiver fits).

Runs some sanity checks on the input files. If necessary converts files to MEF format (this should not be left to `makewcs` because `updatewcs` may be `False`). Runs makewcs. The function `process_input` returns an association table, ivmlist, output name

The common interface interpreter for MultiDrizzle tasks, ‘processCommonInput()’, not only runs ‘process_input()’ but ‘createImageObject()’ and ‘defineOutput()’ as well to fully setup all inputs for use with the rest of the MultiDrizzle steps either as stand-alone tasks or internally to MultiDrizzle itself.

`drizzlepac.processInput.``addIVMInputs`(imageObjectList, ivmlist)

  Add IVM filenames provided by user to outputNames dictionary for each input imageObject.

`drizzlepac.processInput.``applyContextPar`(imageObjectList, contextpar)

  Apply the value of the parameter `context` to the input list, setting the name of the output context image to None if `context` is False

`drizzlepac.processInput.``buildASNList`(rootnames, asnname, check_for_duplicates=True)

  Return the list of filenames for a given set of rootnames

`drizzlepac.processInput.``buildEmptyDRZ`(input, output)

  Create an empty DRZ file.

  This module creates an empty DRZ file in a valid FITS format so that the HST pipeline can handle the Multidrizzle zero expossure time exception where all data has been excluded from processing.

  Parameters:

  input : str

  > filename of the initial input to process_input

  output : str

  > filename of the default empty _drz.fits file to be generated

`drizzlepac.processInput.``buildFileList`(input, output=None, ivmlist=None, wcskey=None, updatewcs=True, **workinplace)

  Builds a file list which has undergone various instrument-specific checks for input to MultiDrizzle, including splitting STIS associations.

`drizzlepac.processInput.``buildFileListOrig`(input, output=None, ivmlist=None, wcskey=None, updatewcs=True, **workinplace)

  Builds a file list which has undergone various instrument-specific checks for input to MultiDrizzle, including splitting STIS associations. Compared to buildFileList, this version returns the list of the original file names as specified by the user (e.g., before GEIS->MEF, or WAIVER FITS->MEF conversion).

`drizzlepac.processInput.``changeSuffixinASN`(asnfile, suffix)

  Create a copy of the original asn file and change the name of all members to include the suffix.

`drizzlepac.processInput.``checkDGEOFile`(filenames)

  Verify that input file has been updated with NPOLFILE

  This function checks for the presence of ‘NPOLFILE’ kw in the primary header when ‘DGEOFILE’ kw is present and valid (i.e. ‘DGEOFILE’ is not blank or ‘N/A’). It handles the case of science files downloaded from the archive before the new software was installed there. If ‘DGEOFILE’ is present and ‘NPOLFILE’ is missing, print a message and let the user choose whether to (q)uit and update the headers or (c)ontinue and run astrodrizzle without the non-polynomial correction. ‘NPOLFILE’ will be populated in the pipeline before astrodrizzle is run.

  In the case of WFPC2 the old style dgeo files are used to create detector to image correction at runtime.

  Parameters:

  filenames : list of str

  > file names of all images to be checked

`drizzlepac.processInput.``checkForDuplicateInputs`(rootnames)

  Check input files specified in ASN table for duplicate versions with multiple valid suffixes (_flt and _flc, for example).

`drizzlepac.processInput.``checkMultipleFiles`(input)

  Evaluates the input to determine whether there is 1 or more than 1 valid input file.

`drizzlepac.processInput.``createImageObjectList`(files, instrpars, group=None, undistort=True, inmemory=False)

  Returns a list of imageObject instances, 1 for each input image in the list of input filenames.

`drizzlepac.processInput.``getMdriztabPars`(input)

  High-level function for getting the parameters from MDRIZTAB

  Used primarily for TEAL interface.

`drizzlepac.processInput.``manageInputCopies`(filelist, **workinplace)

  Creates copies of all input images in a sub-directory.

  The copies are made prior to any processing being done to the images at all, including updating the WCS keywords. If there are already copies present, they will NOT be overwritten, but instead will be used to over-write the current working copies.

`drizzlepac.processInput.``processFilenames`(input=None, output=None, infilesOnly=False)

  Process the input string which contains the input file information and return a filelist,output

`drizzlepac.processInput.``process_input`(input, output=None, ivmlist=None, updatewcs=True, prodonly=False, wcskey=None, **workinplace)

  Create the full input list of filenames after verifying and converting files as needed.

`drizzlepac.processInput.``reportResourceUsage`(imageObjectList, outwcs, num_cores, interactive=False)

  Provide some information to the user on the estimated resource usage (primarily memory) for this run.

`drizzlepac.processInput.``resetDQBits`(imageObjectList, cr_bits_value=4096)

  Reset the CR bit in each input image’s DQ array

`drizzlepac.processInput.``runmakewcs`(input)

  Runs make wcs and recomputes the WCS keywords

  Parameters:

  input : str or list of str

  > a list of files

  Returns:

  output : list of str

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

`drizzlepac.processInput.``setCommonInput`(configObj, createOutwcs=True)

  The common interface interpreter for MultiDrizzle tasks which not only runs ‘process_input()’ but ‘createImageObject()’ and ‘defineOutput()’ as well to fully setup all inputs for use with the rest of the MultiDrizzle steps either as stand-alone tasks or internally to MultiDrizzle itself.

  Parameters:

  configObj : object

  > configObj instance or simple dictionary of input parameters

  imageObjectList : list of imageObject objects

  > list of imageObject instances, 1 for each input exposure

  outwcs : object

  > imageObject instance defining the final output frame

  Notes

  At a minimum, the configObj instance (dictionary) should contain:
    configObj = {‘input’:None,’output’:None }

  If provided, the configObj should contain the values of all the multidrizzle parameters as set by the user with TEAL. If no configObj is given, it will retrieve the default values automatically. In either case, the values from the input_dict will be merged in with the configObj before being used by the rest of the code.

  Examples

  You can set createOutwcs=False for the cases where you only want the images processed and no output wcs information in necessary; as in:

  >>>imageObjectList,outwcs = processInput.processCommonInput(configObj)

`drizzlepac.processInput.``update_member_names`(oldasndict, pydr_input)

  Update names in a member dictionary.

  Given an association dictionary with rootnames and a list of full file names, it will update the names in the member dictionary to contain ‘_*’ extension. For example a rootname of ‘u9600201m’ will be replaced by ‘u9600201m_c0h’ making sure that a MEf file is passed as an input and not the corresponding GEIS file.

`drizzlepac.processInput.``userStop`(message)

## ResetBits Update of Input

This module provides the capability to set a specific set of bit values in the input DQ arrays to zero. This allows a user to reset pixels previously erroneously flagged as cosmic-rays to good for reprocessing with improved alignment or detection parameters.

resetbits - A module to set the value of specified array pixels to zero

This module allows a user to reset the pixel values of any integer array, such as the DQ array from an HST image, to zero.

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

### PARAMETERS

filename
: str
  full filename with path
bits
: str
  sum or list of integers corresponding to all the bits to be reset

### Optional Parameters

extver
: int, optional
  List of version numbers of the arrays to be corrected (default: None, will reset all matching arrays)
extname
: str, optional
  EXTNAME of the arrays in the FITS files to be reset (default: ‘dq’)

### NOTES

This module performs a simple bitwise-and on all the pixels in the specified array and the integer value provided as input using the operation (array & ~bits).

### Usage

It can be called not only from within Python, but also from the host-level operating system command line using the syntax:

    resetbits filename bits [extver [extname]]

### EXAMPLES

1. The following command will reset the 4096 bits in all the DQ arrays of the file ‘input_flt.fits’:

       resetbits input_flt.fits 4096

   or from the Python command line:

       >>> import resetbits
       >>> resetbits.reset_dq_bits("input_file_flt.fits", 4096)

2. To reset the 2,32,64 and 4096 (sum of 4194) bits in the second DQ array, specified as ‘dq,2’, in the file ‘input_flt.fits’:

       resetbits input_flt.fits 4194 2

   or from the Python command line:

       >>> import resetbits
       >>> resetbits.reset_dq_bits("input_file_flt.fits", 2+32+64+4096, extver=2)

`drizzlepac.resetbits.``getHelpAsString`(docstring=False, show_ver=True)

  return useful help from a file in the script directory called __taskname__.help

`drizzlepac.resetbits.``help`(file=None)

  Print out syntax help for running astrodrizzle

  Parameters:

  file : str (Default = None)

  > If given, write out help to the filename specified by this parameter Any previously existing file with this name will be deleted before writing out the help.

`drizzlepac.resetbits.``reset_dq_bits`(input, bits, extver=None, extname='dq')

  This function resets bits in the integer array(s) of a FITS file.

  Parameters:

  filename : str

  > full filename with path

  bits : str

  > sum or list of integers corresponding to all the bits to be reset

  extver : int, optional

  > List of version numbers of the DQ arrays to be corrected [Default Value: None, will do all]

  extname : str, optional

  > EXTNAME of the DQ arrays in the FITS file [Default Value: ‘dq’]

  Notes

  The default value of None for the ‘extver’ parameter specifies that all extensions with EXTNAME matching ‘dq’ (as specified by the ‘extname’ parameter) will have their bits reset.

  Examples

  1. The following command will reset the 4096 bits in all the DQ arrays of the file input_file_flt.fits:

         reset_dq_bits("input_file_flt.fits", 4096)

  2. To reset the 2,32,64 and 4096 bits in the second DQ array, specified as ‘dq,2’, in the file input_file_flt.fits:

         reset_dq_bits("input_file_flt.fits", "2,32,64,4096", extver=2)

`drizzlepac.resetbits.``run`(configobj=None)

  Teal interface for running this code.