### Install Documentation Dependencies

Source: https://drizzlepac.readthedocs.io/en/latest/CONTRIBUTING.html

Install the necessary dependencies for building documentation locally. This includes Sphinx and its themes, which are specified in pyproject.toml.

```bash
>> pip install -e ".[docs]"

```

--------------------------------

### photeq Module Initialization and Logging Setup

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/photeq.html

This snippet demonstrates the internal setup of the photeq module, including time tracking, input validation for the 'files' argument, and the configuration of file-based logging. It shows how to handle potential errors with log file creation and handler management.

```python
from datetime import datetime
import logging

# Assume _log, _sh_log, __taskname__, __version__ are defined elsewhere
# For demonstration purposes:
_log = logging.getLogger(__name__)
_sh_log = logging.StreamHandler()
__taskname__ = 'photeq'
__version__ = '1.0'

runtime_begin = datetime.now()

# Check that input file name is a string:
if not isinstance(files, str):
    raise TypeError("Argument 'files' must be a comma-separated list of "
                    " file names")

# Set-up log files:
if isinstance(logfile, str):
    # first, in case there are any "leftover" file handlers,
    # close and remove them:
    for h in _log.handlers:
        if h is not _sh_log and isinstance(h, logging.FileHandler):
            h.close()
            _log.removeHandler(h)
    # create file handler:
    log_formatter = logging.Formatter('[%(levelname)s:] %(message)s')
    log_file_handler = logging.FileHandler(logfile)
    log_file_handler.setFormatter(log_formatter)
    # add log_file_handler to logger
    _log.addHandler(log_file_handler)

elif logfile is not None:
    raise TypeError("Unsupported 'logfile' type")

# BEGIN:
_mlinfo("***** {0} started on {1}".format(__taskname__, runtime_begin))
_mlinfo("      Version {0} ".format(__version__))

# check that extension names are strings (or None for error ext):
if sciext is None:
    sci_ext4parse = '*'
    ext2get = None
else:
    if not isinstance(sciext, str):
        raise TypeError("Argument 'sciext' must be a string or None")
    sciext = sciext.strip()
    if sciext.upper() == 'PRIMARY':
        sciext = sciext.upper()
        ext2get = (sciext, 1)
    else:
        ext2get = (sciext, '*')

    sci_ext4parse = ext2get

if errext is not None and not isinstance(errext, str):
    raise TypeError("Argument 'errext' must be a string or None")

# check that phot_kwd is supported:
if not isinstance(phot_kwd, str):
    raise TypeError("Argument 'phot_kwd' must be a string")
phot_kwd = phot_kwd.strip().upper()
```

--------------------------------

### Install Drizzlepac from Source

Source: https://drizzlepac.readthedocs.io/en/latest/_sources/getting_started/installation.rst.txt

Install the Drizzlepac package after cloning the repository and potentially building the documentation. This command installs the package locally.

```shell
python setup.py install
```

--------------------------------

### TweakReg Catalog File Example

Source: https://drizzlepac.readthedocs.io/en/latest/api/drizzlepac.tweakreg.TweakReg.html

This example shows the format for a 'catfile' which lists input images and their associated catalog files for TweakReg. Each line specifies an input image followed by the catalog files for its science extensions.

```text
image1_flt.fts  cat1_sci1.coo  cat1_sci2.coo
image2_flt.fts  cat2_sci1.coo  cat2_sci2.coo

```

--------------------------------

### Example WCSNAME Format

Source: https://drizzlepac.readthedocs.io/en/latest/mast_data_products/svm_processing.html

Illustrates the format of a WCSNAME for an a priori solution, which includes the starting WCS and the astrometric catalog used.

```text
<Starting WCS>-<Astrometric Catalog>
```

```text
IDC_0461802ej-GSC240
```

--------------------------------

### Get Help for Tweakback

Source: https://drizzlepac.readthedocs.io/en/latest/user_reprocessing/tweakback.html

Prints syntax help for running the tweakback module. Optionally, help can be written to a specified file.

```python
tweakback.help()
```

--------------------------------

### Example Usage of processCommonInput

Source: https://drizzlepac.readthedocs.io/en/latest/drizzlepac_api/process.html

Demonstrates how to call processCommonInput, optionally setting createOutwcs to False.

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

--------------------------------

### Get Exposure Start and End Times

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/util.html

Determines the exposure start and end times from a header, prioritizing primary header if 'expstart' is present.

```python
def get_expstart(header, primary_hdr):
    """shouldn't this just be defined in the instrument subclass of imageobject?"""

    if 'expstart' in primary_hdr:
        exphdr = primary_hdr
    else:
        exphdr = header

    if 'EXPSTART' in exphdr:
        expstart = float(exphdr['EXPSTART'])
        expend = float(exphdr['EXPEND'])
    else:
        expstart = 0.
        expend = 0.0

    return (expstart, expend)
```

--------------------------------

### Get DrizzlePac Version

Source: https://drizzlepac.readthedocs.io/en/latest/CHANGELOG.html

Use this snippet to check the installed version of DrizzlePac.

```python
import drizzlepac
>>> drizzlepac.__version__

```

--------------------------------

### Print photeq syntax help

Source: https://drizzlepac.readthedocs.io/en/latest/utilities/photeq.html

Use this function to display the syntax help for running the photeq command. Optionally, specify a filename to write the help output to a file.

```python
drizzlepac.photeq.help(_file =None_)
```

--------------------------------

### Image File Handling and Setup

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/imgclasses.html

Opens image and data quality files, setting up file handles and extensions. Handles releasing existing handles and re-opening if necessary.

```python
    def openFile(self, openDQ=False):
        """ Open file and set up filehandle for image file
        """

        if self._im.closed:
            if not self._dq.closed:
                self._dq.release()
            assert(self._dq.closed)
            fi = FileExtMaskInfo(clobber=False,
                                 doNotOpenDQ=not openDQ,
                                 im_fmode=self.open_mode)
            fi.image = self.name
            self._im = fi.image
            fi.append_ext(spu.get_ext_list(self._im, extname='SCI'))
            fi.finalize()
            self._im = fi.image
            self._dq = fi.DQimage
            self._imext = fi.fext
            self._dqext = fi.dqext
```

--------------------------------

### Import adrizzle Module

Source: https://drizzlepac.readthedocs.io/en/latest/api/drizzlepac.adrizzle.drizzle.html

Basic example of how to import the `adrizzle` module from the `drizzlepac` library. This is the starting point for using the module's functionalities.

```python
from drizzlepac import adrizzle
```

--------------------------------

### Build Documentation Locally

Source: https://drizzlepac.readthedocs.io/en/latest/CONTRIBUTING.html

Build the project documentation locally to ensure it renders correctly. The output HTML files will be generated in the `_build/html` directory.

```bash
>> make html

```

--------------------------------

### Run AstroDrizzle with a Configuration File

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/astrodrizzle.html

This example demonstrates running AstroDrizzle by specifying a configuration file. This is useful for managing complex parameter sets.

```python
import drizzlepac
from drizzlepac import astrodrizzle
astrodrizzle.AstroDrizzle('*flt.fits', configobj='myparam.cfg')
```

--------------------------------

### Example MVM Drizzled Filename

Source: https://drizzlepac.readthedocs.io/en/latest/mast_data_products/mvm_utilities.html

An example of a real MVM filter-level, drizzled filename.

```text
hst_skycell-p0081x14y14_wfc3_uvis_f225w_all_drc.fits
```

--------------------------------

### List installed packages with Conda

Source: https://drizzlepac.readthedocs.io/en/latest/CONTRIBUTING.html

Use this command to verify that the development versions of your packages are correctly installed in your environment.

```bash
>> conda list

```

--------------------------------

### Initialize and Populate Observation Products

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/haputils/poller_utils.html

Sets up dictionaries to store information and files for different observation products, including total products, filter products, and individual exposure products. It iterates through detector and filter trees to categorize and store file information.

```python
    log.setLevel(log_level)

    # Initialize products dict
    obset_products = {}

    # For each level, define a product, starting with the detector used...
    prev_det_indx = 0
    det_indx = 0
    filt_indx = 0
    sep_indx = 0

    tdp_list = []

    # Setup products for each detector used
    for filt_tree in det_tree.values():
        totprod = TDP_STR.format(det_indx)
        obset_products[totprod] = {"info": "", "files": []}
        det_indx += 1
        # Find all filters used...
        for filter_files in filt_tree.values():
            # Use this to create and populate filter product dictionary entry
            fprod = FP_STR.format(filt_indx)
            obset_products[fprod] = {"info": "", "files": []}
            filt_indx += 1
            # Populate single exposure dictionary entry now as well
            filter_members, filetype = select_common_filetype(filter_files)

            for filename, is_member in zip(filter_files, filter_members):
                if det_indx != prev_det_indx:
                    prev_det_indx = det_indx

                if not is_member:
                    # This logic should get the opposite filetype from the
                    # value returned for the entire filter (at least that is the plan)
                    exp_filetype = "drz" if filetype == "drc" else "drc"
                else:
                    exp_filetype = filetype

                # Generate the full product dictionary information string:
                # proposal_id, obset_id, instrument, detector, ipppssoot, filter, and filetype
                # filename = ('11515 01 WFC3 UVIS IACS01T9Q F200LP', 'iacs01t9q_flt.fits')
                exp_prod_info = (filename[0] + " " + exp_filetype).lower()

                # Set up the single exposure product dictionary
                sep = SEP_STR.format(sep_indx)
                obset_products[sep] = {"info": exp_prod_info, "files": [filename[1]]}
                # Increment single exposure index
                sep_indx += 1

                # Create a single exposure product object

                # The GrismExposureProduct is only an attribute of the TotalProduct.
                prod_list = exp_prod_info.split(" ")

                # prod_list is 0: proposal_id, 1:observation_id, 2:instrument, 3:detector,
                # 4:aperture_from_poller, 5:filename, 6:filters, 7:filetype

                # The prod_list[6] is the filter - use this information to distinguish between
                # a direct exposure for drizzling (ExposureProduct) and an exposure
                # (GrismExposureProduct) which is carried along (Grism/Prism) to make analysis
                # easier for the user by having the same WCS in both the direct and
                # Grism/Prism products.

                # Determine if this image is a Grism/Prism or a nominal direct exposure
                is_grism = False
                if (
                    prod_list[6].lower().find("g") != -1
                    or prod_list[6].lower().find("pr") != -1
                ):
                    is_grism = True
                    filt_indx -= 1
                    grism_sep_obj = GrismExposureProduct(
                        prod_list[0], # prop_id
                        prod_list[1], # obset_id
                        prod_list[2], # instrument
                        prod_list[3], # detector
                        prod_list[4], # aperture_from_poller
                        filename[1], # filename
                        prod_list[6], # filters
                        prod_list[7], # filetype
                        log_level, # log_level
                    )
                else:
                    sep_obj = ExposureProduct(
                        prod_list[0],
                        prod_list[1],
                        prod_list[2],
                        prod_list[3],
                        prod_list[4],
                        filename[1],
                        prod_list[6],
                        prod_list[7],
                        log_level,
                    )
                # Now that we have defined the ExposureProduct for this input exposure,
                # do not include it any total or filter product.
                if not is_member:
                    continue

                prod_info = (filename[0] + " " + filetype).lower()

```

--------------------------------

### Initialize Instrument Parameters

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/processInput.html

Sets up instrument parameters, including unit conversions, from the configuration object.

```python
instrpars = configObj['INSTRUMENT PARAMETERS']
# pass in 'proc_unit' to initialize unit conversions as necessary
instrpars['proc_unit'] = configObj['proc_unit']
```

--------------------------------

### Example SkyCell Dictionary Output

Source: https://drizzlepac.readthedocs.io/en/latest/mast_data_products/mvm_processing.html

An example of the dictionary returned by `get_sky_cells`, showing SkyCell names and their corresponding SkyCell objects.

```python
sky_cells_dict
{'skycell-p1889x07y19': SkyCell object: skycell-p1889x07y19,
 'skycell-p1889x07y20': SkyCell object: skycell-p1889x07y20,
 'skycell-p1970x15y03': SkyCell object: skycell-p1970x15y03,
 'skycell-p1970x15y02': SkyCell object: skycell-p1970x15y02,
 'skycell-p1970x16y02': SkyCell object: skycell-p1970x16y02}
```

--------------------------------

### Install Test Dependencies

Source: https://drizzlepac.readthedocs.io/en/latest/CONTRIBUTING.html

Installs optional dependencies required for running tests, including pytest. Use this command to set up your environment for development.

```bash
>> pip install -e ".[test]"
```

--------------------------------

### Running TweakReg from Python

Source: https://drizzlepac.readthedocs.io/en/latest/api/drizzlepac.tweakreg.TweakReg.html

Examples demonstrating how to run the TweakReg task from a Python prompt, including options for specifying source finding parameters and output files.

```APIDOC
## Running TweakReg from Python

### Description
This section shows how to execute the TweakReg task using Python, illustrating different ways to pass parameters.

### Example 1: Specifying parameters directly

```python
import drizzlepac
from drizzlepac import tweakreg
tweakreg.TweakReg('*flt.fits',
      imagefindcfg={'threshold' : 200, 'conv_width' : 3.5},
      refimagefindcfg={'threshold' : 400, 'conv_width' : 2.5},
      updatehdr=False, shiftfile=True, outshifts='shift.txt')
```

### Example 2: Using dictionary constructor

```python
import drizzlepac
from drizzlepac import tweakreg
tweakreg.TweakReg('*flt.fits',
      imagefindcfg=dict(threshold=200, conv_width=3.5),
      refimagefindcfg=dict(threshold=400, conv_width=2.5),
      updatehdr=False, shiftfile=True, outshifts='shift.txt')
```

### Example 3: Using a configuration file

```python
import drizzlepac
from drizzlepac import tweakreg
tweakreg.TweakReg('*flt.fits', configobj='myparam.cfg')
```

### Accessing Help

To access help for the tweakreg task:

```python
from drizzlepac import tweakreg
help(tweakreg)
```
```

--------------------------------

### Example Output Dictionary Structure

Source: https://drizzlepac.readthedocs.io/en/latest/mast_data_products/run_singlehap.html

Illustrates the expected dictionary format for storing observation information and associated files, used for creating product filenames.

```python
obs_info_dict["single exposure product 00": {"info": '11665 06 wfc3 uvis empty_aperture ib4606c5q f555w drc',
                                             "files": ['ib4606c5q_flc.fits']}
. 
. 
. 
obs_info_dict["single exposure product 08": {"info": '11665 06 wfc3 ir empty_aperture ib4606clq f110w drz',
                                             "files": ['ib4606clq_flt.fits']}

obs_info_dict["filter product 00": {"info": '11665 06 wfc3 uvis empty_aperture ib4606c5q f555w drc',
                                    "files": ['ib4606c5q_flc.fits', 'ib4606c6q_flc.fits']},
. 
. 
. 
obs_info_dict["filter product 01": {"info": '11665 06 wfc3 ir empty_aperture ib4606cmq f160w drz',
                                    "files": ['ib4606cmq_flt.fits', 'ib4606crq_flt.fits']},

obs_info_dict["total detection product 00": {"info": '11665 06 wfc3 uvis empty_aperture ib4606c5q f555w drc',
                                             "files": ['ib4606c5q_flc.fits', 'ib4606c6q_flc.fits']}
. 
. 
. 
obs_info_dict["total detection product 01": {"info": '11665 06 wfc3 ir empty_aperture ib4606cmq f160w drz',
                                             "files": ['ib4606cmq_flt.fits', 'ib4606crq_flt.fits']}
```

--------------------------------

### Install Drizzlepac with pip

Source: https://drizzlepac.readthedocs.io/en/latest/_sources/getting_started/installation.rst.txt

Use this command to install Drizzlepac directly from its GitHub repository. The `--no-use-pep517` option may be necessary for older pip versions.

```shell
pip install git+https://github.com/spacetelescope/drizzlepac.git
```

--------------------------------

### Initialize File Handles and WCS Key

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/adrizzle.html

Initializes file handles to None and sets up the WCS key, defaulting to a space if not provided.

```python
    # Keep track of any files we need to open
    in_sci_handle = None
    in_wht_handle = None
    out_sci_handle = None
    out_wht_handle = None
    out_con_handle = None

    _wcskey = configObj["wcskey"]
    if util.is_blank(_wcskey):
        _wcskey = " "
```

--------------------------------

### Analyze Linear Features and Detect Guiding Issues

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/haputils/analyze.html

Performs statistical analysis on detected linear features to identify potential guiding issues. It generates a histogram of line angles, ignoring those close to 90 degrees (likely artifacts). If a significant peak in similar angles is found, it indicates potential guiding problems.

```python
diff_lines = np.isclose(np.abs(lines['angles']), 90, atol=2.0)
angles = lines['angles'][~diff_lines]

angle_bins = np.linspace(-180., 180., 91)
ahist = np.histogram(angles, bins=angle_bins)

max_angles = ahist[0].max()
alimit = max(len(angles) / 10.0, diff_lines.sum())

log.debug(f"Peak number of similar lines: {max_angles} based on a threshold of {alimit}")
log.debug(f"number of probable sources: {num_sources}")

lines_detected = (max_angles > alimit)
log.info(f"{max_angles} lines were similar, so linear features were detected.")
return lines_detected
```

--------------------------------

### ACS/HRC Instrument Detector Index Example

Source: https://drizzlepac.readthedocs.io/en/latest/_sources/mast_data_products/hap-parameters.rst.txt

Example of an index file for ACS/HRC, mapping HAP tasks to their configuration files. This file is used to initialize processing variables.

```json
{
    "alignment": {
        "all": "acs/hrc/acs_hrc_alignment_all.json"
    },
    "astrodrizzle": {
        "any_n1": "acs/hrc/acs_hrc_astrodrizzle_any_n1.json",
        "acs_hrc_any_n2": "acs/hrc/acs_hrc_astrodrizzle_any_n2.json",
        "acs_hrc_any_n4": "acs/hrc/acs_hrc_astrodrizzle_any_n4.json",
        "acs_hrc_any_n6": "acs/hrc/acs_hrc_astrodrizzle_any_n6.json",
        "filter_basic": "any/any_astrodrizzle_filter_hap_basic.json",
        "single_basic": "any/any_astrodrizzle_single_hap_basic.json",
        "total_basic": "acs/hrc/acs_hrc_astrodrizzle_any_total.json"
    },
    "catalog generation": {
        "all": "acs/hrc/acs_hrc_catalog_generation_all.json"
    },
    "quality control": {
        "all": "acs/hrc/acs_hrc_quality_control_all.json"
    }
}
```

--------------------------------

### Create Median Image

Source: https://drizzlepac.readthedocs.io/en/latest/api/drizzlepac.createMedian.median.html

This example demonstrates how to use the `median` function to create a median image from a set of FITS files. Ensure that the input files match the specified pattern.

```python
>>> from drizzlepac import createMedian
>>> createMedian.median('*flt.fits')

```

--------------------------------

### build_pos_grid

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/tweakutils.html

Returns a grid of positions starting at a given 'start' point and ending at an 'end' point. The grid is filled with steps of a specified interval. Optionally, it can return a meshgrid.

```APIDOC
## build_pos_grid

### Description

Returns 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. If `mesh` is True, it returns a meshgrid.

### Parameters

- **start** (tuple or list) - The starting X,Y coordinates.
- **end** (tuple or list) - The ending X,Y coordinates.
- **nstep** (int) - The number of steps to take between start and end.
- **mesh** (bool, optional) - If True, return a meshgrid. Defaults to False.

### Returns

- **xarr** (numpy.ndarray) - Array of X coordinates.
- **yarr** (numpy.ndarray) - Array of Y coordinates.
```

--------------------------------

### Find GSC to GAIA Offset

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/haputils/astrometric_utils.html

Determines the offset between the Guide Star Catalog (GSC) and GAIA based on guide star coordinates. This function is deprecated and replaced by `stwcs.updatewcs.astrometry_utils.find_gsc_offset`.

```python
from drizzlepac.haputils import astrometric_utils as au
from astropy.io import fits
from astropy.utils.exceptions import AstropyDeprecationWarning
import warnings
import requests
from lxml import etree
from io import BytesIO

# Suppress deprecation warnings for this example
warnings.simplefilter('ignore', AstropyDeprecationWarning)

# Mocking necessary components for a runnable example
SERVICELOCATION = "http://mock_service.com"
log = print # Mocking logger
fu = type('obj', (object,), {'buildNewRootname': lambda x: 'mock_rootname'})() # Mocking fu

@deprecated(since="3.2.1",
            message="Replaced by stwcs.updatewcs.astrometry_utils.find_gsc_offset",
            name='drizzlepac.haputils.astrometric_utils.find_gsc_offset',
            alternative='stwcs.updatewcs.astrometry_utils.find_gsc_offset')
def 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.
    """
    serviceType = "GSCConvert/GSCconvert.aspx"
    spec_str = "TRANSFORM={}-{}&IPPPSSOOT={}"

    if 'rootname' in fits.getheader(image):
        ippssoot = fits.getval(image, 'rootname').upper()
    else:
        ippssoot = fu.buildNewRootname(image).upper()

    spec = spec_str.format(input_catalog, output_catalog, ippssoot)
    serviceUrl = "{}/{}? புகை".format(SERVICELOCATION, serviceType, spec)
    rawcat = requests.get(serviceUrl)
    if not rawcat.ok:
        log.info(f"Problem accessing service with:\n{serviceUrl}")
        raise ValueError

    delta_ra = delta_dec = None
    tree = BytesIO(rawcat.content)
    for _, element in etree.iterparse(tree):
        if element.tag == 'deltaRA':
            delta_ra = float(element.text)
        elif element.tag == 'deltaDEC':
            delta_dec = float(element.text)

    return delta_ra, delta_dec

```

--------------------------------

### Initialize Grid Definitions

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/haputils/cell_utils.html

Sets up tessellation based on installed grid definitions. Reads default scale, cell size, and sky cell overlap parameters from a FITS file.

```python
fname = os.path.join(PCELL_PATH, PCELL_FILENAME)

        self.hdu = fits.open(fname)
        self.rings = self.hdu[1].data

        # Extract projection cell defaults
        self.scale = scale if scale else self.hdu[0].header['PC_SCALE']
        self.cell_size = cell_size if cell_size else self.hdu[0].header['PC_SIZE']
        # Extract sky cell defaults
        self.sc_overlap = self.hdu[0].header['SC_OLAP']
        self.sc_nxy = self.hdu[0].header['SC_NXY']
```

--------------------------------

### Install Drizzlepac in Editable Mode

Source: https://drizzlepac.readthedocs.io/en/latest/CONTRIBUTING.html

Install the 'drizzlepac' package from the local source code in editable mode. This allows changes in the source code to be reflected immediately without reinstallation.

```bash
>> pip install -e .

```

--------------------------------

### Command-line Usage Example

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/haputils/generate_custom_svm_mvm_param_file.html

Illustrates how to use the script from the command line. Specify the poller filename and optional flags for overwriting, verbosity, output file name, and pipeline type.

```python
#!/usr/bin/env python
""" generate_custom_mvm_svm_param_file - a module to create a template SVM/MVM processing pipeline parameter
file based on the observations present in the current working directory for the user to customize

Command-line USAGE:
    >>> python generate_custom_svm_mvm_param_file.py [-clop] poller_filename

    - poller_filename: (required) the name of the input SVM/MVM poller file

    - -c: (optional) If turned on, existing files with the same name as the output custom SVM parameter file
      created by this script will be overwritten.

    - -l: (optional) The desired level of verboseness in the log statements displayed on the screen and
      written to the .log file. Valid input options are 'critical', 'error', 'warning', 'info', or 'debug'.

    - -o: (optional) Name of the output configuration JSON file which will be created for specialized
      processing. This file will contain ALL the input parameters necessary for processing. If not explicitly
      specified, the default name for the output file is "custom_parameters.json".

    - -p: (optional) Name of the pipeline that the configurations will be prepared for. Valid options are
      'mvm' (for the HAP multi-visit mosaics pipeline) or 'svm' (for the HAP single-visit mosaic pipeline).
      If not explicitly stated, the default value is 'svm'

Python USAGE:
    >>> python
    >>> from drizzlepac.haputils import generate_custom_svm_mvm_param_file
    >>> generate_custom_svm_mvm_param_file.make_svm_input_file(input_filename,
                                                           clobber=False,
                                                           log_level=logutil.logging.INFO
                                                           output_custom_pars_file='custom_parameters.json',
                                                           hap_pipeline_name='svm')

.. note:: This script only generates a template input parameter file populated with default values based on
          the observations present in the current working directory. It is entirely incumbent on the user to
          modify this file with non-default values.
"""

import argparse
import datetime
import json
import logging
import os
import sys
import traceback

from drizzlepac.haputils import config_utils
from drizzlepac.haputils import ci_table
from drizzlepac.haputils import poller_utils

from stsci.tools import logutil

__taskname__ = 'generate_custom_svm_mvm_param_file'

MSG_DATEFMT = '%Y%j%H%M%S'
SPLUNK_MSG_FORMAT = '%(asctime)s %(levelname)s src=%(name)s- %(message)s'
log = logutil.create_logger(__name__, level=logutil.logging.NOTSET, stream=sys.stdout,
                            format=SPLUNK_MSG_FORMAT, datefmt=MSG_DATEFMT)
# ----------------------------------------------------------------------------------------------------------------------




[docs]
def make_svm_input_file(input_filename, hap_pipeline_name='svm',
                        output_custom_pars_file='custom_parameters.json', clobber=False,
                        log_level=logutil.logging.INFO):
    """
    create a custom SVM processing pipeline parameter file based on the observations present in the current
    working directory using config_utils.HapConfig() and optionally update_ci_values() to adjust CI upper and
    lower limits for filter products

    Parameters
    ----------
    input_filename: str
        The 'poller file' where each line contains information regarding an exposures taken
        during a single visit.

    hap_pipeline_name : str, optional
        Name of the pipeline that the configurations will be prepared for. Valid options are 'mvm' (for the
        HAP multi-visit mosaics pipeline) or 'svm' (for the HAP single-visit mosaic pipeline). If not
        explicitly stated, the default value is 'svm'

    output_custom_pars_file: str, optional
        Fully specified output filename which contains all the configuration parameters
        available during the processing session. Default is 'custom_parameters.json'.

    clobber : Bool, optional
        If set to Boolean 'True', existing files with the same name as *output_custom_pars_file*, the output
        custom SVM parameter file created by this script will be overwritten. Default value is Boolean
        'False'.

    log_level : int, 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'.


```

--------------------------------

### Analyze Image for Guiding Problems

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/haputils/analyze.html

Analyzes an image to detect bad pixels, identify sources, and determine if guiding problems are present. It uses source detection and line analysis to flag potential issues.

```python
dqarr = None
    for extn in hdu:
        if 'extname' in extn.header and extn.header['extname'] == 'DQ':
            dqarr = hdu[extn].data.copy()
            break
    if dqarr is not None:
        dqmask = bitfield_to_boolean_mask(dqarr, ignore_flags=BAD_DQ_FLAGS)
    else:
        dqmask = np.ones_like(data)
    # close FITS object (just to be nice to the OS...)
    hdu.close()
    del hdu

    # apply mask now...
    imgarr *= dqmask
    del dqmask  # just to clean up a little

    # Determine rough number of probable sources
    # Trying to ignore small sources (<= 4x4 pixels in size, or npixels < 17)
    #   which are either noise peaks or head-on CRs.
    if PHOTUTILS_GE_3:
        segm = detect_sources(imgarr, 0, n_pixels=17)
    else:
        segm = detect_sources(imgarr, 0, npixels=17)
    if segm is None:
        log.debug(f'Did NOT detect enough raw sources in {filename} for guiding verification.')
        return False
    n_sources = segm.n_labels if PHOTUTILS_GE_3 else segm.nlabels
    log.debug(f'Detected {n_sources} raw sources in {filename} for guiding verification.')

    src_cat = SourceCatalog(imgarr, segm)
    # Remove likely cosmic-rays based on central_moments classification
    bad_srcs = classify_sources(src_cat, 1.5)
    # Get the label IDs for sources flagged as CRs, IDs are 1-based not 0-based
    pt_srcs = np.where(bad_srcs == 0)[0] + 1
    segm.remove_labels(pt_srcs)
    # If there are no sources left, this is akin to the check above where number
    # of sources < 2, so just return False
    if segm.nlabels == 0:
        log.warning("After removal of suspected cosmic rays, there are no sources remaining in the image.")
        return False
    src_cat = SourceCatalog(imgarr, segm)  # clean up source catalog now...
    num_sources = len(src_cat)

    # trim edges from image to avoid spurious sources
    trim_slice=(slice(2, -2), slice(2, -2))

    # Now determine whether this image was affected by guiding problems
    bad_guiding = lines_in_image(imgarr[trim_slice], num_sources,
                                 min_length=min_length, min_lines=MIN_LINES)
    if bad_guiding:
        log.warning(f"Image {filename}'s GUIDING detected as: BAD.")
    else:
        log.info(f"Image {filename}'s GUIDING detected as: GOOD.")

    return bad_guiding
```

--------------------------------

### Print updatenpol syntax help

Source: https://drizzlepac.readthedocs.io/en/latest/utilities/updatenpol.html

Prints out the syntax help for running the `updatenpol` command. Optionally, help can be written to a specified file.

```python
drizzlepac.updatenpol.help(_file =None_)
```

--------------------------------

### Create Static Mask with Default Parameters

Source: https://drizzlepac.readthedocs.io/en/latest/api/drizzlepac.staticMask.createMask.html

This example demonstrates how to call the createMask function from the command line using default parameters. It assumes input files are named with the '*.flt.fits' pattern.

```python
from drizzlepac import staticMask
staticMask.createMask('*flt.fits')
```

--------------------------------

### Automated Poller Input File Format Example

Source: https://drizzlepac.readthedocs.io/en/latest/_sources/mast_data_products/svm_processing.rst.txt

This example shows the comma-separated value format of the automated poller input file used for populating the MAST archive. Each line represents an exposure with specific metadata.

```text
ic0s17h4q_flt.fits,12861,C0S,17,602.937317,F160W,IR,ic0s/ic0s17h4q/ic0s17h4q_flt.fits
ic0s17h5q_flt.fits,12861,C0S,17,602.937317,F160W,IR,ic0s/ic0s17h5q/ic0s17h5q_flt.fits
ic0s17h7q_flt.fits,12861,C0S,17,602.937317,F160W,IR,ic0s/ic0s17h7q/ic0s17h7q_flt.fits
ic0s17hhq_flt.fits,12861,C0S,17,602.937317,F160W,IR,ic0s/ic0s17hhq/ic0s17hhq_flt.fits
```

--------------------------------

### drizzlepac.pixreplace.help

Source: https://drizzlepac.readthedocs.io/en/latest/utilities/pixreplace.html

Prints out syntax help for running the pixreplace task. Optionally, help can be written to a specified file.

```APIDOC
## drizzlepac.pixreplace.help

### Description
Print out syntax help for running `pixreplace`.

### Method
`help(_file =None_)`

### Parameters
#### Path Parameters
- **file** (str) - Optional - 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. [Default: None]

### Request Example
```python
>>> epar pixreplace
```

### Response
#### Success Response (200)
- **None** - This function prints help information to the console or a file.

#### Response Example
```python
>>> epar pixreplace
```
```

--------------------------------

### Python: Transform single pixel coordinate (forward) - Example 1

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/pixtopix.html

Example demonstrating the transformation of a specific pixel position (256, 256) from an input FITS file to an output FITS file using the forward direction.

```python
from drizzlepac import pixtopix
outx,outy = pixtopix.tran("input_file_flt.fits[sci,1]",
                         "output_drz.fits[sci,1]", "forward", 256, 256)
```

--------------------------------

### MapReg Task Example

Source: https://drizzlepac.readthedocs.io/en/latest/api/drizzlepac.mapreg.MapReg.html

This example demonstrates how to use the MapReg task to replicate a master region file ('master.reg') to all SCI extensions of multiple FITS images ('img*.fits'). The 'img_wcs_ext' parameter specifies the WCS extensions to use for coordinate transformation.

```python
>>> mapreg(input_reg='master.reg', images='img*.fits', img_wcs_ext=[2,8])

```

--------------------------------

### Define Help Functions for a Module

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/util.html

Sets up 'getHelpAsString' and 'help' functions within a module dictionary. 'getHelpAsString' retrieves help text, while 'help' prints or writes it to a file.

```python
def _def_help_functions(module, module_file, task_name, module_doc):
    tname = base_taskname(task_name)

    def getHelpAsString(docstring=False, show_ver=True):
        return _get_help_as_string(docstring, show_ver, module_file=module_file,
                                   task_name=task_name, module_doc=module_doc)

    getHelpAsString.__doc__ = f"""
    Return help string from a file in the script directory called
    ``{tname}.help`` or from the module's docstring.
    """
    module['getHelpAsString'] = getHelpAsString

    def help(file=None):
        helpstr = getHelpAsString(docstring=True, show_ver=True)
        if file is None:
            print(helpstr)
        else:
            with open(file, mode='w') as f:
                f.write(helpstr)

    help.__doc__ = f"""
    Print out syntax help for running ``{tname}``.

    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.
    """
    module['help'] = help

    return getHelpAsString(docstring=True, show_ver=False)
```

--------------------------------

### drizzlepac.mdzhandler.getMdriztabParameters

Source: https://drizzlepac.readthedocs.io/en/latest/mast_data_products/mdztab.html

Gets entry in MDRIZTAB where task parameters live.

```APIDOC
## Function: getMdriztabParameters

### Description
Gets entry in MDRIZTAB where task parameters live. This method returns a record array mapping the selected row.

### Parameters
* `_files_` (any) - The input files to process.

### Returns
(any) - A record array mapping the selected row.
```

--------------------------------

### openFile

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/imgclasses.html

Open file and set up filehandle for image file.

```APIDOC
## openFile

### Description
Open file and set up filehandle for image file.

### Method
`openFile(openDQ=False)`

### Parameters
* **openDQ** (bool) - Optional - Whether to open the Data Quality (DQ) image.

### Returns
None
```

--------------------------------

### Verify Guiding Problems in Image

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/haputils/analyze.html

Checks if an input image was affected by guiding problems, which can mimic SCAN or GRISM modes. This function is intended for 'MVM' processing types but can be invoked directly. It first checks header keywords and then analyzes the image data for trail-like features.

```python
def verify_guiding(filename, min_length=33):
    """ Verify whether or not the input image was affected by guiding problems.

    This algorithm evaluates the data from (SCI,1) to try to determine whether
    the image was affected by guiding problems which mimic SCAN mode or GRISM data
    with the trails in an arbitrary angle across the image.

    Parameters
    ==========
    filename : str
        Name of image to be evaluated

    min_length : int, optional
        Minimum length of trails (in pixels) to be detected in image.

    Returns
    ========
    bad_guiding : bool
        Boolean specifying whether or not the image was detected as
        being affected by guiding problems.  Value is True if image
        was affected.

    Note: This function will only be called from analyze_wrapper if the processing
          type is "MVM".  It is deliberately False for other processing (e.g., SVM and
          pipeline).  However, this routine can be invoked directly for pipeline
          processing from runastrodriz.py with the appropriate parameter setting.
    """
    log.info(f"Verifying that {filename} was not affected by guiding problems.")

    hdu = fits.open(filename)
    # Let's start by checking whether the header indicates any problems with
    # the guide stars or tracking.
    # Using .get() insures that this check gets done even if keyword is missing.
    gs_quality = hdu[0].header.get('quality', default="").lower()
    if 'gsfail' in gs_quality or 'tdf-down' in gs_quality:
        hdu.close()
        log.warning(f"Image {filename}'s QUALITY keywords report GUIDING: BAD.")
        return True  # Yes, there was bad guiding...

    # No guide star problems indicated in header, so let's check the
    # data.  There are many instances where the data is compromised
    # despite what values are found in the header.
    data = hdu[("SCI", 1)].data.copy()
    scale_data = hdu[("SCI",1)].header["bunit"].endswith('/S')
    data = np.nan_to_num(data, nan=0.0)  # just to be careful
    if scale_data:
        # Photutils works best in units of DN
        scale_hdr = hdu[0].header if 'exptime' in hdu[0].header else hdu[1].header
        scale_val = scale_hdr['exptime']
        data *= scale_val
    bkg_stats = sigma_clipped_stats(data, maxiters=2)
    bkg_limit = bkg_stats[1] + bkg_stats[2]  # only need a 1-sigma detection limit here...
    log.debug(f"bkg_limit found to be: {bkg_limit:.2f}")

    data -= bkg_limit
    imgarr = np.clip(data, 0, data.max())
```

--------------------------------

### Initialize Sky Subtraction Configuration

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/sky.html

Sets up the configuration object for sky subtraction, handling input parameters and loading default configurations. Raises a ValueError if no input image is provided.

```python
if input is not None:
        inputDict['input']=input
        inputDict['output']=None
        inputDict['updatewcs']=False
        inputDict['group']=group
    else:
        log.error("Please supply an input image")
        raise ValueError

    configObj = util.getDefaultConfigObj(__taskname__,configObj,inputDict,loadOnly=(not editpars))
    if configObj is None:
        return

    if not editpars:
        run(configObj,outExt=outExt)
```

--------------------------------

### main

Source: https://drizzlepac.readthedocs.io/en/latest/mast_data_products/make_custom_mosaic.html

Command-line interface for the make_custom_mosaic module.

```APIDOC
## main

### Description
Command-line interface.

### Method
`main`

### Parameters
None

### Returns
- **return_value** (int) - return value from the run. 0 for successful run, something else otherwise.
```

--------------------------------

### compute_edge

Source: https://drizzlepac.readthedocs.io/en/latest/_modules/drizzlepac/haputils/cell_utils.html

Returns a list of equally spaced points between a start and end point.

```APIDOC
def compute_edge(start, end, int_pixel=True):
    """Return a list of nb_points equally spaced points between start and end"""
    # If we have 8 intermediate points, we have 8+1=9 spaces
    # between p1 and p2
    nb_points = max(abs(end[0] - start[0]), abs(end[1] - start[1]))
    x_spacing = (end[0] - start[0]) / (nb_points + 1)
    y_spacing = (end[1] - start[1]) / (nb_points + 1)

    xy = [[start[0] + i * x_spacing, start[1] + i * y_spacing]
            for i in range(1, nb_points + 1)]

    if int_pixel:
        xy = np.array(xy, dtype=np.int32)
    else:
        xy = np.array(xy)

    return xy
```