---
title: 'Hyper-Py: Efficient Compact-Source Photometry'
url: https://www.emergentmind.com/topics/hyper-py
type: topic
---

# Hyper-Py: Efficient Compact-Source Photometry

Hyper-Py is an open-source Python package for compact-source extraction and photometry in astronomical images, especially in the far-infrared, sub-millimeter, and millimeter regimes. It is presented as a fully restructured and extended Python implementation of the earlier IDL-based HYPER algorithm, preserving the original hybrid logic—source detection via high-pass filtering, local background estimation through polynomial fitting, source modeling with 2D elliptical Gaussians, simultaneous fitting for deblending, and aperture photometry on cleaned images—while adding improved configurability, parallel execution, more flexible background modeling, and native support for 3D FITS datacubes [2509.22453].

## 1. Definition, lineage, and problem setting

Hyper-Py stands for **HYbrid Photometry and Extraction Routine in PYthon**. Its scientific target is robust and reproducible photometry of compact sources embedded in maps with structured diffuse emission and source crowding, conditions that are particularly common in star-forming regions observed in FIR/sub-mm/mm bands [2509.22453]. The package is explicitly framed as a Python reimplementation and extension of the original IDL HYPER method introduced by Traficante et al. (2015), but not as a thin port. The paper describes it as a full restructuring that retains the defining HYPER workflow while modernizing the implementation and extending its applicability, most notably to spectrally resolved 3D data products [2509.22453].

The underlying problem is not merely source detection. In the regimes emphasized by the paper, compact-source photometry is difficult because the background is spatially variable, often filamentary, and not well represented by a global baseline. Blending further complicates the assignment of flux to individual objects, while naive rms estimation can be biased upward by bright compact emission and structured backgrounds. Hyper-Py is designed for this regime: it is neither purely a segmentation tool nor purely a profile-fitting tool, but a hybrid system in which model fitting is used to define source geometry and separate companions, after which aperture photometry is performed on images from which background and nearby-source contributions have already been subtracted [2509.22453].

This design implies a specific scientific niche. Hyper-Py is most directly aimed at compact sources that are unresolved or moderately extended, located on locally modelable but nontrivial backgrounds, and embedded in fields where crowding and overlap cannot be ignored. A plausible implication is that its methodology is best aligned with surveys and targeted studies in which local background systematics dominate the photometric error budget.

## 2. Hybrid extraction and photometric workflow

The core Hyper-Py pipeline begins with a robust noise estimate, proceeds through compact-source detection, and then applies local background fitting, parametric source modeling, deblending, and final aperture photometry on cleaned data products [2509.22453]. The paper states that the map rms is estimated using iterative sigma clipping, specifically to reduce contamination from bright sources and structured emission. Candidate sources are then detected on a high-pass-filtered image using a configurable threshold of the form \(n_\sigma \times \mathrm{rms}\) [2509.22453].

The paper does not print an exact filtering equation, but it explicitly describes detection as high-pass based. A conceptual reconstruction given in the source material is
\[
I_{\mathrm{HP}}(x,y) = I(x,y) - I_{\mathrm{LP}}(x,y),
\]
where \(I_{\mathrm{HP}}\) emphasizes compact structure relative to a low-pass representation \(I_{\mathrm{LP}}\). This reconstructed form is interpretive rather than a verbatim formula from the paper, but it captures the intended detection logic [2509.22453].

After detection, Hyper-Py defines local cutouts around candidate sources and estimates the background on masked data. The paper states that background estimation is based on local polynomial fitting rather than a flat local offset, reflecting the need to model gradients and curved diffuse structure. Again, the paper does not print a single canonical polynomial equation, but the source material gives a conceptual form such as
\[
B(x,y) = \sum_{i+j \le p} a_{ij} x^i y^j,
\]
to represent the local 2D background surface [2509.22453]. This is the central distinction between Hyper-Py and simpler aperture-based workflows: the background is treated as a fitted local surface, not a scalar pedestal.

Sources are modeled as 2D elliptical Gaussians. The paper does not print the analytic Gaussian explicitly in the summary, but the source material reconstructs the standard form
\[
G(x,y) = A \exp\!\left[-\frac{1}{2}\left(\frac{x'^2}{\sigma_x^2} + \frac{y'^2}{\sigma_y^2}\right)\right],
\]
with rotated coordinates \((x',y')\) defined by the source center and position angle [2509.22453]. When multiple sources overlap, Hyper-Py performs simultaneous fitting of several Gaussians in the same local region, which the paper identifies as a key deblending mechanism. In reconstructed notation, the model becomes
\[
M(x,y) = B(x,y) + \sum_{i=1}^{N_{\mathrm{src}}} G_i(x,y).
\]
The important operational point is that the Gaussian model is not itself the final photometric estimator. Instead, Hyper-Py uses the fitted source geometry and companion model to subtract background and overlapping neighbors, then performs aperture photometry on the cleaned image [2509.22453].

That final step is essential to the package’s “hybrid” identity. A common misconception would be to treat Hyper-Py as a purely Gaussian-integral photometry code. The paper explicitly describes a different strategy: Gaussian fitting is used for source characterization, footprint definition, and deblending, while the final flux measurement is aperture-based after subtraction of background and companions [2509.22453].

## 3. Background modeling, robust regression, and optimization

Background estimation is one of the main areas in which Hyper-Py extends the original IDL implementation. The paper states that Hyper-Py supports multiple fitting strategies for the masked local cutouts: **least-squares**, **Huber regression**, and **Theil–Sen regression** [2509.22453]. This is a substantive methodological expansion, because it allows the user to adapt the local background solver to different residual structures and outlier regimes.

The configuration system exposes this flexibility directly. Huber regression is controlled through the parameter `huber_epsilons`, and the preferred background model can be chosen by minimizing one of three criteria: **NMSE** (the default), **reduced chi-squared**, or **BIC** [2509.22453]. The paper motivates NMSE as the default because it is comparatively robust to scale differences and less tied to a specific noise-weighting assumption, whereas reduced chi-squared depends more directly on the adopted noise model and BIC penalizes background-model complexity [2509.22453].

Hyper-Py also adds a joint fitting mode in which the background surface and 2D Gaussian source model are optimized simultaneously, with optional **L2 regularization** to stabilize the fit in the presence of strong background gradients [2509.22453]. The paper does not print the corresponding optimization objective, but the source material reconstructs it conceptually as a robust residual minimization with a ridge penalty on background coefficients. This suggests a deliberate attempt to prevent an overly flexible polynomial surface from absorbing source flux in difficult regions.

At the nonlinear optimization level, the package uses the **Levenberg–Marquardt algorithm** through `lmfit`’s `least_squares` minimizer, and it allows several robust loss functions: **`cauchy`** as default, plus **`soft_l1`** and **`huber`** [2509.22453]. This optimization layer is important because the masked cutouts may still contain residual contamination from nearby emission, structured diffuse features, or artifacts that are not perfectly captured by the polynomial-plus-Gaussian model. The robust loss selection therefore operates as a second line of defense against non-Gaussian residual structure.

In methodological terms, Hyper-Py combines robust detection, robust local background regression, and robust nonlinear fitting. The paper repeatedly frames the result as more reliable and reproducible source extraction under structured-background conditions than would be expected from a simpler threshold-plus-aperture workflow [2509.22453].

## 4. Python implementation, configuration model, and 3D datacube support

Hyper-Py is presented as a Python package rather than a standalone binary application. It supports standard astronomical **2D FITS maps** and also **3D FITS datacubes**, which the paper identifies as one of its most important extensions beyond the original IDL HYPER [2509.22453]. In the cube mode, each slice along the third axis is treated as an independent 2D map, and the package performs background estimation and subtraction slice by slice. The output can therefore include a **3D background cube** with the same shape as the input cube, enabling consistent background modeling along the spectral axis for line or continuum studies in spectrally resolved observations [2509.22453].

The package incorporates built-in parallelization. The paper states that each input map is assigned to a separate processing core, and that the same logic extends naturally to multiple datacube slices [2509.22453]. This is described as producing a dramatic increase in computational efficiency for multi-map analysis, although the paper does not provide wall-clock benchmark tables. The important architectural point is that Hyper-Py parallelizes over maps or slices rather than altering the solution for any individual map.

The user interface is configuration-driven. The paper emphasizes a clear, documented configuration file controlling items such as the detection threshold \(n_\sigma\), the choice among `cauchy`, `soft_l1`, and `huber` loss functions, the list `huber_epsilons`, the background-model selection criterion, and whether cube processing is applied to the full field or to targeted spatial regions [2509.22453]. This design makes Hyper-Py closer to a pipeline framework than to a single-function library.

The software is described as open-source, hosted on GitHub, and installable with `pip` [2509.22453]. The source material also indicates that the package produces source catalogs, fitted source parameters, background products, and cleaned data products implied by the subtraction workflow. The paper does not present a formal schema for every output field, so a detailed catalog specification would go beyond the available evidence. What is explicit is that Hyper-Py is meant as a reusable, maintainable Python implementation with modern fitting backends, documented configuration, and direct support for batch and datacube processing [2509.22453].

## 5. Validation against the IDL HYPER implementation

The paper validates Hyper-Py by comparison with the original IDL HYPER on simulated data built from a **noise-only map based on real ALMA data**. Two synthetic maps with realistic headers were generated, each containing **500 synthetic 2D Gaussian sources** added on top of varying backgrounds [2509.22453]. The simulated sources were constructed to resemble compact astronomical objects, with integrated fluxes spanning roughly **8–20 times the map rms**, peak fluxes around **1–1.5 \(\times\) rms**, and **FWHM sizes of 0.5–1.5 times the beam size**. The simulations also imposed random position angles and a minimum **30% overlap**, making them explicitly deblending-intensive test cases [2509.22453].

The principal quantitative result is a strong reduction in false detections relative to the IDL code, with broadly similar matched-source counts. The paper’s Table 1 is summarized below [2509.22453].

| Catalog | Hyper-Py | HYPER (IDL) |
|---|---|---|
| 1 | matched 490; false 4 (0.8%) | matched 493; false 73 (12.9%) |
| 2 | matched 487; false 4 (0.8%) | matched 487; false 46 (8.6%) |

These numbers support the paper’s main empirical claim: in the reported simulations, Hyper-Py preserves comparable recovery of true sources while reducing false positives by roughly an order of magnitude [2509.22453]. The source material attributes this improvement to better background estimation, optional regularization, the more robust detection framework, and the broader redesign of the pipeline. The matched-source totals are similar enough that the dominant gain is reliability rather than a dramatic shift in completeness.

The paper also presents histograms of differences between recovered and true **peak fluxes** and **integrated fluxes** for Hyper-Py and HYPER, but the extracted text does not contain numerical summaries of those histograms [2509.22453]. The safe conclusion is therefore limited: the paper intends these figures as evidence of improved or at least competitive flux recovery, but the available text supports only the detection-level metrics quoted above.

## 6. Scientific scope, assumptions, and limitations

Hyper-Py is optimized for compact-source photometry under complex-background conditions, not for arbitrary astronomical morphology. The paper’s methodological assumptions are explicit. First, sources are represented by **elliptical Gaussians**, which is suitable for unresolved or moderately extended compact objects but less natural for highly asymmetric, filamentary, or strongly multicomponent sources [2509.22453]. Second, the local background is approximated by a **polynomial surface**, which is effective for smooth local gradients but may become strained in the presence of strongly non-polynomial or sharply varying diffuse structure [2509.22453].

The method also depends on effective masking and on the definition of the local fitting region. In crowded fields, incomplete masking of nearby emission can bias the polynomial background estimate even when robust regressors and robust nonlinear losses are used [2509.22453]. Similarly, simultaneous multi-Gaussian fitting is a strong deblending strategy, but extreme overlap or severe shape nonuniqueness can still make the decomposition unstable. The paper therefore does not present Hyper-Py as a universal solution to crowding, but as a more controlled and configurable framework for the class of problems where local parametric modeling remains scientifically reasonable.

Threshold choice remains consequential. As with any \(n_\sigma\)-based detection method, lower thresholds increase false positives and higher thresholds reduce completeness [2509.22453]. Hyper-Py improves the rms estimate through sigma clipping, but it does not abolish the basic detection trade-off. A related misconception would be to interpret the lower false-positive rate as removing the need for parameter tuning; the paper does not support that conclusion.

Within those bounds, Hyper-Py is positioned as especially useful for compact-source analysis in star-formation studies and in spectrally resolved datasets, where consistent background modeling along the spectral axis is itself a scientific requirement [2509.22453]. Its broader significance lies in translating the original HYPER strategy into a modern Python environment while expanding the background-modeling and datacube capabilities enough to make the method practical for contemporary FITS-based workflows. A plausible implication is that Hyper-Py occupies a methodological middle ground between simple aperture pipelines and more aggressively parametric source extractors: it treats background and blending as first-class problems, but retains an aperture-based final flux measurement grounded in cleaned images rather than in the Gaussian fit alone.

Source: https://www.emergentmind.com/topics/hyper-py