tessl/pypi-drizzlepac

HST image combination using the drizzle algorithm to combine astronomical images, to model image distortion, to remove cosmic rays, and generally to improve the fidelity of data in the final image.

Overview

Eval results

Files

HAP Processing

Name: tessl/pypi-drizzlepac
Author: tessl

Advanced processing capabilities for Hubble Advanced Products (HAP), including sophisticated catalog management, source detection, automated quality assessment, and standardized product generation. The HAP framework provides enhanced algorithms and quality control for systematic HST data processing.

Capabilities

Product Management

Hierarchical product classes for managing different types of HAP outputs with standardized metadata and quality metrics.

class HAPProduct:
    """
    Base class for HAP product management and mosaicing.

    Parameters:
    - prop_id: str, proposal ID
    - obset_id: str, observation set ID
    - instrument: str, HST instrument name
    - detector: str, detector identifier
    - aperture_from_poller: str, aperture from poller system
    - filename: str, output filename
    - filetype: str, product file type
    - log_level: int, logging level

    Methods:
    - generate(): Create product from input data
    - validate(): Perform quality validation
    - write(): Save product to file system
    """

class TotalProduct(HAPProduct):
    """
    Total detection products combining all filters.

    Attributes:
    - total_exposure_time: Combined exposure time
    - filters: List of contributing filters
    - n_exposures: Number of input exposures
    """

class FilterProduct(HAPProduct):
    """
    Filter-specific products for individual filters.

    Attributes:
    - filter_name: HST filter identifier
    - central_wavelength: Filter central wavelength
    - bandwidth: Filter bandwidth
    """

class ExposureProduct(HAPProduct):
    """
    Single exposure products for individual observations.

    Attributes:
    - rootname: HST observation rootname
    - exptime: Exposure time
    - date_obs: Observation date
    """

class GrismExposureProduct(HAPProduct):
    """
    Grism-specific exposure products for spectroscopy.

    Attributes:
    - grism: Grism identifier
    - orient: Grism orientation angle
    - dispersion: Dispersion solution
    """

class SkyCellExposure(HAPProduct):
    """
    Sky cell exposure products for wide-area surveys.

    Attributes:
    - skycell_id: Sky cell identifier
    - ra_center: Right ascension center
    - dec_center: Declination center
    """

class SkyCellProduct(HAPProduct):
    """
    Sky cell combination products.

    Attributes:
    - cell_size: Angular size of sky cell
    - n_visits: Number of contributing visits
    - coverage_map: Exposure coverage information
    """

Advanced Catalog Management

Comprehensive catalog system for source detection, photometry, and quality assessment across multiple HST instruments and observing modes.

class HAPCatalogs:
    """
    Main catalog management class for HAP processing.

    Methods:
    - identify(): Identify sources in image
    - measure(): Perform aperture photometry
    - filter(): Apply quality filters
    - annotate(): Add metadata and flags
    - write(): Save catalog to standard formats
    """

class HAPCatalogBase:
    """
    Base class for HAP catalogs with common functionality.

    Attributes:
    - catalog_type: Type of catalog (point, segment, etc.)
    - n_sources: Number of detected sources
    - columns: List of catalog column names
    """

class HAPPointCatalog(HAPCatalogBase):
    """
    Point source catalog management for stellar objects.

    Methods:
    - detect_sources(): Find point-like sources
    - measure_aperture(): Aperture photometry
    - measure_psf(): PSF fitting photometry
    - compute_colors(): Calculate color indices
    """

class HAPSegmentCatalog(HAPCatalogBase):
    """
    Extended source catalog management for galaxies.

    Methods:
    - segment_image(): Create segmentation map
    - measure_morphology(): Morphological parameters
    - measure_photometry(): Extended source photometry
    - deblend_sources(): Separate blended objects
    """

class CatalogImage:
    """
    Image processing for catalog generation.

    Methods:
    - compute_background(): Background estimation
    - detect_threshold(): Compute detection threshold
    - create_segmap(): Generate segmentation map
    - measure_properties(): Extract source properties
    """

Astrometric Processing

Enhanced astrometric capabilities using external catalogs and advanced fitting algorithms for improved positional accuracy.

def create_astrometric_catalog(inputs, catalog="GAIAedr3", output="ref_cat.ecsv",
                              existing_wcs=None, **kwargs):
    """
    Create reference catalogs from external astrometric sources.

    Parameters:
    - inputs: list, input images for astrometric processing
    - catalog: str, reference catalog ('GAIADR2', 'GAIADR3', 'GSC241', etc.)
    - output: str, output reference catalog filename
    - existing_wcs: WCS, existing WCS for catalog extraction
    - **kwargs: dict, catalog query parameters

    Returns:
    str, path to created reference catalog
    """

def build_reference_wcs(inputs, sciname='sci'):
    """
    Build reference WCS from input images.

    Parameters:
    - inputs: list, input image list
    - sciname: str, science extension name

    Returns:
    WCS, combined reference world coordinate system
    """

def get_catalog(ra, dec, sr=0.1, epoch=None, catalog='GSC241'):
    """
    Retrieve astrometric catalogs from external sources.

    Parameters:
    - ra: float, right ascension center (degrees)
    - dec: float, declination center (degrees)
    - sr: float, search radius (degrees)
    - epoch: float, catalog epoch for proper motion correction
    - catalog: str, catalog identifier

    Returns:
    Table, astrometric source catalog
    """

def extract_sources(img, dqmask=None, fwhm=3.0, threshold=None, **kwargs):
    """
    Extract sources from images for astrometric alignment.

    Parameters:
    - img: ndarray, input image data
    - dqmask: ndarray, data quality mask
    - fwhm: float, expected source FWHM in pixels
    - threshold: float, detection threshold
    - **kwargs: dict, source detection parameters

    Returns:
    Table, extracted source catalog
    """

def find_fwhm(psf, default_fwhm, log_level=None):
    """
    Determine FWHM values for source detection.

    Parameters:
    - psf: ndarray, point spread function image
    - default_fwhm: float, default FWHM if measurement fails
    - log_level: int, logging level

    Returns:
    float, measured or default FWHM value
    """

def perform_align(input_list, catalog_list, num_sources, archive=False,
                  clobber=False, debug=False, update_hdr_wcs=False,
                  result=None, runfile="temp_align.log",
                  print_fit_parameters=True, print_git_info=False,
                  output=False, headerlet_filenames=None, fit_label=None,
                  product_type=None, **alignment_pars):
    """
    Perform a posteriori astrometric fits to input images.

    Parameters:
    - input_list: list, input image filenames for alignment
    - catalog_list: list, reference catalog filenames
    - num_sources: int, number of sources for fitting
    - archive: bool, archive headerlets to database
    - clobber: bool, overwrite existing files
    - debug: bool, enable debug output
    - update_hdr_wcs: bool, update WCS in image headers
    - result: dict, results container for fit statistics
    - runfile: str, alignment log filename
    - print_fit_parameters: bool, print fitting parameters
    - print_git_info: bool, print software version information
    - output: bool, save detailed alignment products
    - headerlet_filenames: list, custom headerlet filenames
    - fit_label: str, label for the fit solution
    - product_type: str, type of product being aligned
    - **alignment_pars: dict, additional alignment parameters

    Returns:
    AlignmentTable, object containing alignment results and fit statistics
    """

Image Processing and Alignment

Advanced image processing capabilities with multiple alignment algorithms and quality assessment.

class HAPImage:
    """
    HAP image representation and processing.

    Attributes:
    - filename: str, image filename
    - instrument: str, HST instrument name
    - detector: str, detector identifier
    - filter: str, filter name
    - exptime: float, exposure time

    Methods:
    - load(): Load image data and metadata
    - calibrate(): Apply instrument calibrations
    - align(): Perform astrometric alignment
    - combine(): Combine with other images
    """

class SBCHAPImage(HAPImage):
    """
    SBC-specific image processing class for ACS Solar Blind Channel.

    Methods:
    - correct_distortion(): Apply SBC-specific distortion corrections
    - handle_low_counts(): Special processing for low count rate images
    """

class AlignmentTable:
    """
    Manage alignment solutions and transformations.

    Methods:
    - add_fit(): Add alignment fit results
    - get_fit(): Retrieve fit parameters for image
    - apply_fit(): Apply transformation to coordinates
    - write(): Save alignment table to file
    - read(): Load alignment table from file
    """

Quality Assessment and Flagging

Comprehensive quality flagging system for automated source and image quality assessment.

def run_source_list_flagging(drizzled_image, flt_list, param_dict,
                           log_level=None):
    """
    Main interface for source quality flagging.

    Parameters:
    - drizzled_image: str, combined image filename
    - flt_list: list, input FLT files used in combination
    - param_dict: dict, flagging parameters
    - log_level: int, logging verbosity level

    Returns:
    dict, flagging results and statistics
    """

def ci_filter(drizzled_image, catalog_name, catalog_data, **kwargs):
    """
    Concentration index filtering for stellar classification.

    Parameters:
    - drizzled_image: str, reference image
    - catalog_name: str, catalog identifier
    - catalog_data: Table, source catalog
    - **kwargs: dict, concentration index parameters

    Returns:
    ndarray, boolean mask for point-like sources
    """

def hla_saturation_flags(drizzled_image, flt_list, **kwargs):
    """
    Saturation flagging for sources.

    Parameters:
    - drizzled_image: str, combined image
    - flt_list: list, contributing exposure list
    - **kwargs: dict, saturation flagging parameters

    Returns:
    ndarray, saturation flags for sources
    """

def hla_swarm_flags(drizzled_image, catalog_name, **kwargs):
    """
    Swarm source identification and flagging.

    Parameters:
    - drizzled_image: str, reference image
    - catalog_name: str, catalog identifier
    - **kwargs: dict, swarm detection parameters

    Returns:
    ndarray, boolean flags for swarm sources
    """

def hla_nexp_flags(drizzled_image, flt_list, **kwargs):
    """
    Exposure count flagging for source reliability.

    Parameters:
    - drizzled_image: str, combined image
    - flt_list: list, contributing exposure list
    - **kwargs: dict, exposure count parameters

    Returns:
    ndarray, flags based on exposure coverage
    """

Usage Examples

Basic HAP Processing

from drizzlepac.haputils import catalog_utils, product

# Create HAP product for filter-specific processing
filter_product = product.FilterProduct()
filter_product.configobj_pars.input = ['image1_flt.fits', 'image2_flt.fits']
filter_product.configobj_pars.filter = 'F606W'

# Generate product
filter_product.generate()

# Create point source catalog
point_catalog = catalog_utils.HAPPointCatalog(filter_product.drizzle_filename,
                                            catalog_type='point')
point_catalog.identify()
point_catalog.write()

Advanced Astrometric Processing

from drizzlepac.haputils import astrometric_utils

# Create reference catalog from Gaia
ref_catalog = astrometric_utils.create_astrometric_catalog(
    inputs=['obs1_flt.fits', 'obs2_flt.fits'],
    catalog='GAIADR3',
    output='gaia_reference.ecsv',
    mag_limit=20.0
)

# Extract sources for alignment
source_catalog = astrometric_utils.extract_sources(
    image_data,
    fwhm=2.5,
    threshold=5.0,
    deblend_nthresh=32
)

Quality Assessment Workflow

from drizzlepac.haputils import hla_flag_filter

# Run comprehensive quality flagging
flag_results = hla_flag_filter.run_source_list_flagging(
    'combined_drz.fits',
    ['exp1_flt.fits', 'exp2_flt.fits'],
    param_dict={
        'ci_lower_limit': 1.3,
        'ci_upper_limit': 2.0,
        'sat_limit': 60000.0
    }
)

# Apply individual quality filters
ci_flags = hla_flag_filter.ci_filter('combined_drz.fits',
                                   'point_catalog.ecsv',
                                   catalog_data)

sat_flags = hla_flag_filter.hla_saturation_flags('combined_drz.fits',
                                               flt_list)

Multi-Visit Processing

from drizzlepac.haputils import product, align_utils

# Process multiple visits for sky cell
skycell_product = product.SkyCellProduct()
skycell_product.input_list = ['visit1', 'visit2', 'visit3']
skycell_product.skycell_id = 'sc_001'

# Align all visits to common reference frame
alignment_table = align_utils.AlignmentTable()
for visit in skycell_product.input_list:
    fit_results = align_utils.match_default_fit(visit, ref_catalog)
    alignment_table.add_fit(visit, fit_results)

# Generate combined sky cell product
skycell_product.generate()

HAP Configuration

Processing Parameters

Key parameters for HAP processing:

hap_params = {
    'catalog_types': ['point', 'segment'],
    'aperture_ee': [70, 80, 85],  # Encircled energy apertures
    'ci_lower_limit': 1.3,       # Concentration index limits
    'ci_upper_limit': 2.0,
    'quality_control': True,
    'write_catalogs': True
}

Quality Control Thresholds

quality_params = {
    'min_sources': 10,           # Minimum sources for processing
    'max_rms': 0.1,             # Maximum alignment RMS (arcsec)
    'sat_limit': 60000.0,       # Saturation threshold (DN)
    'coverage_limit': 0.5        # Minimum exposure coverage
}

Output Products

Catalog Formats

HAP catalogs are saved in multiple formats:

ECSV: Enhanced CSV with metadata
FITS: Binary table format
ASCII: Human-readable text format

Standard Columns

Point Source Catalogs

X_IMAGE, Y_IMAGE: Pixel coordinates
RA, DEC: Sky coordinates (degrees)
MAG_AUTO: Automatic aperture magnitude
MAGERR_AUTO: Magnitude error
CI: Concentration index
FLAGS: Quality flags

Segment Catalogs

KRON_RADIUS: Kron radius
ELLIPTICITY: Source ellipticity
THETA_IMAGE: Position angle
A_IMAGE, B_IMAGE: Semi-major/minor axes

Error Handling

HAP-Specific Exceptions

ProductError: Product generation failures
CatalogError: Catalog processing failures
AlignmentError: Astrometric alignment failures
QualityError: Quality assessment failures

Recovery Strategies

from drizzlepac.haputils import product

try:
    hap_product = product.FilterProduct()
    hap_product.generate()
except product.ProductError as e:
    print(f"Product generation failed: {e}")
    # Implement fallback or retry logic