API Reference

This is the API reference for the hotpants module.

HOTPANTS Python Wrapper - Modular Implementation

This module provides a complete Python interface to the HOTPANTS image differencing algorithms. Each step of the pipeline is exposed as an individual method for fine-grained control.

class hotpants.hotpants.Hotpants(template_data: ndarray | str, image_data: ndarray | str, t_mask: ndarray | None = None, i_mask: ndarray | None = None, t_error: ndarray | None = None, i_error: ndarray | None = None, star_catalog: ndarray | None = None, config: HotpantsConfig | None = None, output_header: Header | None = None)

Bases: object

The central HOTPANTS object for stateful image differencing.

This class orchestrates the entire image subtraction pipeline. It holds the input data, configuration, and intermediate results. The public methods correspond to the major steps of the pipeline, allowing for either a full end-to-end run or step-by-step execution for detailed analysis.

Example

>>> from hotpants import Hotpants, HotpantsConfig
>>> # Create a custom configuration
>>> config = HotpantsConfig(rkernel=15, normalize='i')
>>> # Initialize with FITS file paths
>>> hp = Hotpants('template.fits', 'science.fits', config=config)
>>> # Run the entire pipeline
>>> results = hp.run_pipeline()
>>> # Access the difference image
>>> diff_image = results['diff_image']
convolve_and_difference() → Tuple[ndarray, ndarray, ndarray, ndarray]

Step 4: Applies the kernel, performs subtraction, and creates final images.

This method uses the global kernel solution to convolve the appropriate image. It then subtracts the convolved image from the target image to produce the difference image and calculates the corresponding final noise image and output mask.

Returns:

  • diff_image (np.ndarray): The raw difference image (Target - Convolved Model).

  • convolved_image (np.ndarray): The image that was convolved to match the other.

  • noise_image (np.ndarray): The final 1-sigma noise map for the difference image.

  • output_mask (np.ndarray): The final integer mask indicating bad pixels.

Return type:

A tuple containing

find_stamps() → Tuple[List[Substamp], List[Substamp]]

Step 1: Finds potential substamp coordinates for kernel fitting.

This method scans the template and science images for suitable stars to use for constructing the convolution kernel. If a star_catalog was provided during initialization, this catalog is used directly, bypassing the automated search. Otherwise, a grid-based search is performed to find bright, isolated stars.

It populates the template_substamps and image_substamps lists with Substamp objects, which initially contain only coordinate information.

Returns:

the Substamp objects found on the template and the Substamp objects found on the science image.

Return type:

A tuple containing two lists

fit_and_select_direction() → str

Step 2: Performs initial fits and selects the best convolution direction.

This method performs a localized fit for every potential substamp found in the previous step. A figure-of-merit (FOM) is calculated for each substamp to assess its quality. Stamps that are saturated, near bad pixels, or have a poor local fit (high chi-squared) are rejected.

The aggregate FOM is then used to decide whether it is better to convolve the template to match the science image or vice-versa. The status of each Substamp is updated to either PASSED_FOM_CHECK or REJECTED_FOM_CHECK.

Returns:

The selected convolution direction, either ‘t’ (template) or ‘i’ (image).

get_final_outputs() → Dict[str, Any]

Step 5: Applies final masks, calculates statistics, and returns all products.

This is the final data-producing step. It applies fill values to masked pixels in the output images and calculates final image statistics.

Returns:

  • ‘diff_image’: The final, masked difference image.

  • ’convolved_image’: The final, masked convolved image.

  • ’noise_image’: The final, masked noise image.

  • ’output_mask’: The final integer mask.

  • ’stats’: A dictionary of final image statistics.

  • ’conv_direction’: The convolution direction (‘t’ or ‘i’).

  • ’kernel_solution’: The global kernel solution coefficients.

Return type:

A dictionary containing all final data products, including

get_substamp_details() → Dict[str, Any]

Returns the complete, stateful master lists of all substamps.

This is a diagnostic method to inspect the properties and final status of every substamp considered during the pipeline run.

Returns:

A dictionary containing the full lists of template_substamps and image_substamps.

iterative_fit_and_clip() → Tuple[ndarray, List[Substamp]]

Step 3: Solves for the global kernel using iterative sigma-clipping.

This method takes all substamps that passed the FOM check and uses them to derive a single, spatially varying kernel solution for the entire image. It iteratively rejects outlier substamps to achieve a robust fit. The status of the substamps is updated to either USED_IN_FINAL_FIT or REJECTED_ITERATIVE_FIT.

Returns:

  • The global kernel solution as a 1D NumPy array of coefficients.

  • A list of the Substamp objects that survived the clipping and were used in the final fit.

Return type:

A tuple containing

run_pipeline() → Dict[str, Any]

A convenience method to run the entire pipeline in a single call.

This executes all steps from stamp finding to final output generation and saves any configured output files.

Returns:

A dictionary containing all final data products, as returned by get_final_outputs. This includes the final difference image, noise map, mask, and statistics.

save_outputs()

Saves all configured output files (FITS images and region files).

This method checks the HotpantsConfig object for any specified output filenames and writes the corresponding files. This includes the main difference image, noise image, mask, and the diagnostic DS9 region file for the kernel fitting stamps.

visualize_kernel(at_coords: Tuple[int, int], size_factor: float = 2.0) → ndarray

Generates an image of the convolution kernel at a specific coordinate.

This method should be called after the pipeline has run and a kernel solution has been found. It uses the final kernel solution to reconstruct the kernel for the given (x, y) location.

Parameters:

  • at_coords – The (x, y) coordinates at which to visualize the kernel.

  • size_factor – A multiplier for the kernel’s width to determine the output image size. Defaults to 2.0.

Returns:

A 2D NumPy array containing the image of the kernel.

Raises:

  • HotpantsError – If the kernel fitting has not been run yet.

  • TypeError – If at_coords is not a tuple of two integers.

  • ValueError – If size_factor is not a positive number.

exception hotpants.hotpants.HotpantsError

Bases: Exception

Exception raised for HOTPANTS-specific errors.