hyper-py-photometry 0.1.6__tar.gz → 1.0.1__tar.gz

{hyper_py_photometry-0.1.6/src/hyper_py_photometry.egg-info → hyper_py_photometry-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyper-py-photometry
-Version: 0.1.6
+Version: 1.0.1
 Summary: HYPER: Hybrid Photometry Photometry and Extraction Routine
 Author-email: Alessio Traficante <alessio.traficante@inaf.it>
 Project-URL: Homepage, https://github.com/alessio-traficante/hyper-py

hyper_py_photometry-1.0.1/paper/paper.md

@@ -0,0 +1,72 @@
+---
+title: 'HYPER-PY: HYbrid Photometry and Extraction Routine in PYthon'
+tags:
+  - Python
+  - astronomy
+  - photometry
+  - astronomy tools
+authors:
+  - name: Alessio Traficante
+    orcid: 0000-0003-1665-6402
+    affiliation: 1 
+    corresponding: true
+  - name: Fabrizio De Angelis
+    affiliation: 1
+  - name: Alice Nucara
+    affiliation: 1
+  - name: Milena Benedettini
+    affiliation: 1
+affiliations:
+  - name: INAF-IAPS, Via Fosso del Cavaliere, 100, 00133 Rome (IT)
+    index: 1
+date: 02 September 2025
+repository: https://github.com/Alessio-Traficante/hyper-py
+bibliography: paper.bib
+---
+
+ 
+ 
+# Summary
+ 
+Source extraction and photometry of compact objects are key tasks in observational astronomy. Numerous tools have been developed to tackle the complexities of astronomical data, especially for precise background estimation and source deblending, which are essential for reliable flux measurements across wavelengths (e.g., Cutex: @Molinari11; getsources: @Menshinkov12; Fellwalker: @Berry15; Astrodendro). These challenges are particularly significant in star-forming regions, best observed in the far-infrared (FIR), sub-millimeter, and millimeter bands, where cold, dense compact sources emit strongly. To address this, several software packages have been designed for handling the structured backgrounds and blended sources typical of observations by instruments like Herschel (70–500 μm) and ALMA (1–3 mm). These tools differ in detection and flux estimation approaches. Within this context, we developed HYPER (HYbrid Photometry and Extraction Routine, @Traficante15), originally implemented in IDL, aiming to deliver robust and reproducible photometry of compact sources in FIR/sub-mm/mm maps. HYPER combines source detection via high-pass filtering, background estimation through local polynomial fitting, and source modeling with 2D elliptical Gaussians, simultaneously fitting multiple Gaussians to deblend overlapping sources.
+
+Aperture photometry in **HYPER** is performed on background- and companion-subtracted images, using footprints defined by the source’s 2D Gaussian models, ensuring robust flux measurements in crowded or structured environments (@Traficante15; @Traficante23). The hybrid approach combines parametric Gaussian modeling with classical aperture photometry.
+Here, we present **Hyper-Py**, a fully restructured and extended Python implementation of **HYPER**. **Hyper-Py** preserves the original logic while offering improvements in performance, configurability, and background modeling capabilities, making it a flexible modern tool for source extraction and photometry across diverse datasets. Notably, **Hyper-Py** enables background estimation and subtraction across individual slices of 3D datacubes, allowing consistent background modeling along the spectral axis for line or continuum studies in spectrally resolved observations.
+
+ 
+ 
+# Statement of need
+*Hyper-Py* is an open-source Python package freely available to the community. This new implementation builds upon and improves the original IDL **HYPER** by incorporating several major advancements:
+
+**Parallel execution for multi-map analysis**. *Hyper-Py* employs built-in parallelization where each input map is independently assigned to a processing core on multi-core systems. This allows concurrent execution of the complete photometric pipeline on different maps simultaneously. This parallel framework dramatically increases computational efficiency without altering individual map results.
+
+**Native support for FITS datacubes**. The software treats each slice along the third axis as an independent 2D map, compatible with parallel processing, allowing simultaneous background subtraction per slice. The output is a 3D background cube matching the input cube’s shape, configurable for targeted regions or full spatial coverage through a user-friendly configuration file. This capability provides flexibility for both line-specific and broader continuum background modeling.
+
+**Improved source detection reliability**. Source detection has been enhanced with a robust sigma-clipping algorithm that iteratively estimates the root mean square (*rms*) noise of input maps, excluding outliers to characterize background fluctuations accurately—even with bright sources or structures present. This *rms* serves as a threshold reference for detecting compact sources exceeding a configurable significance level (*n_sigma* × *rms*), settable via the config file. Such refinement increases detection reliability and reproducibility across heterogeneous datasets.
+
+**Advanced background estimation strategy**. Unlike the original IDL implementation @Traficante15, which modeled background separately from source fitting, *Hyper-Py* supports multiple statistical fitting techniques—least-squares, Huber, and Theil–Sen regressions—applied to masked cutouts around each source. Least-squares performs well in regions dominated by Gaussian noise; Huber regression balances L2 and L1 losses to reduce outlier effects via a tunable parameter ε (huber_epsilons in the config file); and Theil–Sen is a non-parametric, robust method ideal for non-Gaussian noise or contamination. When multiple methods are enabled, *Hyper-Py* selects the best model by minimizing residuals, ensuring accurate background reconstruction even with gradients or faint extended emission. Furthermore, an optional joint fit of background and 2D Gaussian models with L2 (ridge) regularization stabilizes fits in regions with strong gradients, preventing background overfitting at the expense of source flux.
+
+**Gaussian plus background model optimization strategy**. *Hyper-py* utilizes the Levenberg–Marquardt algorithm through the lmfit package’s “least_squares” minimizer, allowing control over the cost function’s residual weighting by selecting different loss models. The default “cauchy” loss diminishes outlier influence, improving robustness to data artifacts, unmasked sources, or non-Gaussian noise. Alternatives like “soft_l1” and “huber” are also available for specific dataset optimization.
+
+**Model selection criteria for background fitting**. Background model selection criteria are configurable, offering Normalized Mean Squared Error (NMSE), reduced chi-squared ($\chi^2_\nu$), or Bayesian Information Criterion (BIC) via the config file. NMSE is default due to its robust, scale- and weighting-independent nature, ideal under varying masking or pixel weighting. Reduced chi-squared depends on noise models and pixel counts, potentially biasing selection. BIC penalizes model complexity, favoring simplicity when residuals are comparable. These options allow users to select criteria best suited to their scientific aims and data noise properties.
+
+**Improved user configurability**. *Hyper-Py* is designed to be more user-friendly, featuring a clear and well-documented configuration file. This allows users to adapt the full photometric workflow to a wide range of observational conditions and scientific goals by modifying only a minimal set of parameters. 
+ 
+We assessed *Hyper-Py* performance using extensive simulations. Starting from a noise-only map based on ALMA program #2022.1.0917.S, we generated two maps with reference headers and superimposed varying backgrounds plus 500 synthetic 2D Gaussian sources. These sources mimic real compact objects with integrated fluxes spanning 8–20 times the map rms (peak fluxes ~1–1.5 × *rms*) and FWHM sizes of 0.5–1.5 times the beam size to include both unresolved and moderately extended sources (@Elia21). Random position angles and a minimum 30% overlap ensured realistic blending, thus providing a rigorous test of the code under realistic and challenging conditions.
+We compared the original IDL **HYPER** and *Hyper-Py* under equivalent configurations, with the latter benefiting from improved background estimation, optional regularization, and parallel processing. The key results are presented in **Table 1**, detailing differences in source identification and false positives between the codes.
+
+
+| Catalog | Source Type | Total | Matched | False | False Percentage |
+|--------:|:------------|------:|--------:|------:|------------------:|
+|       1 | *Hyper-py*    |   500 |     490 |     4 |          0.8%   |
+|       1 | **HYPER (IDL)**   |   500 |     493 |    73 |         12.9%   |
+|       2 | *Hyper-py*    |   500 |     487 |     4 |          0.8%   |
+|       2 | **HYPER (IDL)**   |   500 |     487 |    46 |          8.6%   |
+
+In addition, Figure 1 and Figure 2 show the differences between the peak fluxes and the integrated fluxes of the sources with respect to the reference values of the simulated input sources as estimated by *Hyper-Py* and HYPER, respectively.
+
+*Hyper-Py* is freely available for download via its [GitHub repository](https://github.com/Alessio-Traficante/hyper-py), and can also be installed using pip, as described in the accompanying README file.
+
+![histogram of the differences between the peak fluxes of the sources as recovered by *Hyper-Py* and HYPER, respectively, with respect to the reference values of the simulated input sources](Figures/Flux_Diff_Histogram_Peak.png)
+
+![histogram of the differences between the peak fluxes of the sources as recovered by *Hyper-Py* and HYPER, respectively, with respect to the reference values of the simulated input sources](Figures/Flux_Diff_Histogram_Int.png)

{hyper_py_photometry-0.1.6 → hyper_py_photometry-1.0.1}/src/hyper_py/data_output.py

@@ -23,7 +23,7 @@ def write_tables(data_dict, output_dir, config, sigma_thres, real_rms, base_file
         flux_units_beam = 'mJy/beam'
     else:
         flux_units_beam = 'Jy/beam'
-        flux_units = 'Jy/beam'
+        flux_units = 'Jy'
         
     units = {
         'MAP_ID': '', 'HYPER_ID': '', 'BAND': 'GHz',

{hyper_py_photometry-0.1.6 → hyper_py_photometry-1.0.1}/src/hyper_py/detection.py

@@ -3,8 +3,6 @@ from astropy.stats import sigma_clipped_stats
 from photutils.detection import DAOStarFinder
 from scipy.ndimage import convolve
 from astropy.table import Table
-from astropy.wcs import WCS
-
 
 
 def select_channel_map(map_struct):
@@ -52,7 +50,8 @@ def estimate_rms(image, sigma_clip=3.0):
     return sigma
 
 
-def detect_peaks(filtered_image, threshold, fwhm_pix, roundlim=(-1.0, 1.0), sharplim=(-1.0, 2.0)):
+def detect_peaks(filtered_image, threshold, fwhm_pix, roundlim=(-1.0, 1.0), sharplim=(-1.0, 2.0)):  
+    
     finder = DAOStarFinder(
         threshold=threshold,
         fwhm=fwhm_pix,

{hyper_py_photometry-0.1.6 → hyper_py_photometry-1.0.1}/src/hyper_py/map_io.py

@@ -50,8 +50,10 @@ def read_and_prepare_map(filepath, beam, beam_area_arcsec2, beam_area_sr, conver
 
 
     # --- Unit conversions ---
-    bunit = header.get('BUNIT')
-    if bunit == 'MJy /sr':
+    header_for_units = hdul[0].header
+    bunit = header_for_units.cards['BUNIT'].value
+
+    if bunit == 'MJy/sr' or bunit == 'MJy / sr':
         arcsec_to_rad = np.pi / (180.0 * 3600.0)
         pix_area_sr = (pix_dim * arcsec_to_rad)**2
         image_data *= 1e6 * pix_area_sr  # MJy/sr to Jy/pixel

{hyper_py_photometry-0.1.6 → hyper_py_photometry-1.0.1}/src/hyper_py/single_map.py

@@ -95,7 +95,7 @@ def main(map_name=None, cfg=None, dir_root=None, logger=None, logger_file_only=N
     flux_err = []
 
 
-    fit_statuts_val = []
+    fit_status_val = []
     deblend_val = []
     cluster_val = []
 
@@ -143,14 +143,16 @@ def main(map_name=None, cfg=None, dir_root=None, logger=None, logger_file_only=N
     
 
     # --- map rms used to define real sources in the map - accounting for non-zero background --- #
+    map_zero_mean_detect = real_map - np.nanmean(real_map)
+    
     use_maual_rms = cfg.get("detection", "use_manual_rms", False)
     if use_maual_rms == True:
         real_rms = cfg.get("detection", "rms_value", False)
     else:         
         sigma_clip = SigmaClip(sigma=3.0, maxiters=10)
-        map_zero_mean_detect = real_map - np.nanmean(real_map)
         clipped = sigma_clip(map_zero_mean_detect)    
         real_rms = np.sqrt(np.nanmean(clipped**2))
+    
         
         
     # --- run sources identification  --- #
@@ -234,12 +236,24 @@ def main(map_name=None, cfg=None, dir_root=None, logger=None, logger_file_only=N
         # Convert to sky coordinates
         x_pixels = np.array(xcen, dtype=np.float64)
         y_pixels = np.array(ycen, dtype=np.float64)
-        ra, dec = wcs.wcs_pix2world(x_pixels, y_pixels, 0)
-        ra_save = np.where(ra < 0., ra + 360., ra)
-        
-        skycoords = SkyCoord(ra=ra, dec=dec, unit='deg', frame='icrs')
-        glon = skycoords.galactic.l.deg
-        glat = skycoords.galactic.b.deg
+
+        ctype1 = header.get('CTYPE1', '').upper()
+        ctype2 = header.get('CTYPE2', '').upper()
+
+        if 'GLON' in ctype1 and 'GLAT' in ctype2:
+            # Input coordinates are Galactic
+            glon, glat = wcs.wcs_pix2world(x_pixels, y_pixels, 0)
+            skycoords = SkyCoord(l=glon, b=glat, unit='deg', frame='galactic')
+            ra = skycoords.fk5.ra.deg
+            dec = skycoords.fk5.dec.deg
+            ra_save = np.where(ra < 0., ra + 360., ra)
+        else:
+            # Assume input coordinates are Equatorial (FK5/ICRS)
+            ra, dec = wcs.wcs_pix2world(x_pixels, y_pixels, 0)
+            ra_save = np.where(ra < 0., ra + 360., ra)
+            skycoords = SkyCoord(ra=ra, dec=dec, unit='deg', frame='fk5')
+            glon = skycoords.galactic.l.deg
+            glat = skycoords.galactic.b.deg
     
         # Prepare zeroed output table
         N = len(xcen)
@@ -386,7 +400,7 @@ def main(map_name=None, cfg=None, dir_root=None, logger=None, logger_file_only=N
         redchi_val.append(final_redchi)
         bic_val.append(final_bic)
         
-        fit_statuts_val.append(fit_status)
+        fit_status_val.append(fit_status)
         deblend_val.append(0)       # not deblended
         cluster_val.append(1)       # only one source
         
@@ -568,7 +582,7 @@ def main(map_name=None, cfg=None, dir_root=None, logger=None, logger_file_only=N
             redchi_val.append(final_redchi)
             bic_val.append(final_bic)
             
-            fit_statuts_val.append(fit_status)
+            fit_status_val.append(fit_status)
             deblend_val.append(1)                   # multi-Gaussian fit
             cluster_val.append(len(group_indices))  # number of sources in the group
             
@@ -586,18 +600,31 @@ def main(map_name=None, cfg=None, dir_root=None, logger=None, logger_file_only=N
             
     # Assuming you have your WCS object (usually from your FITS header)
     header = map_struct["header"]
-    # Convert pixel coordinates to sky coordinates (RA, Dec)
     x_pixels = np.array(updated_xcen, dtype=np.float64)
     y_pixels = np.array(updated_ycen, dtype=np.float64)
     
     # Initialize WCS from header
     wcs = WCS(header)
-    ra, dec = wcs.wcs_pix2world(x_pixels, y_pixels, 0)
-    ra_save = np.where(ra < 0., ra + 360., ra)
-        
-    skycoords = SkyCoord(ra=ra, dec=dec, unit='deg', frame='icrs')
-    glon = skycoords.galactic.l.deg
-    glat = skycoords.galactic.b.deg
+
+    # Detect coordinate type from header
+    ctype1 = header.get('CTYPE1', '').upper()
+    ctype2 = header.get('CTYPE2', '').upper()
+
+    if 'GLON' in ctype1 and 'GLAT' in ctype2:
+        # Input coordinates are Galactic
+        glon, glat = wcs.wcs_pix2world(x_pixels, y_pixels, 0)
+        # Convert to FK5 (RA/Dec)
+        skycoords = SkyCoord(l=glon, b=glat, unit='deg', frame='galactic')
+        ra = skycoords.fk5.ra.deg
+        dec = skycoords.fk5.dec.deg
+        ra_save = np.where(ra < 0., ra + 360., ra)
+    else:
+        # Assume input coordinates are Equatorial (FK5/ICRS)
+        ra, dec = wcs.wcs_pix2world(x_pixels, y_pixels, 0)
+        ra_save = np.where(ra < 0., ra + 360., ra)
+        skycoords = SkyCoord(ra=ra, dec=dec, unit='deg', frame='fk5')
+        glon = skycoords.galactic.l.deg
+        glat = skycoords.galactic.b.deg
 
 
 ######################## Write Table after photometry ########################
@@ -639,7 +666,7 @@ def main(map_name=None, cfg=None, dir_root=None, logger=None, logger_file_only=N
             "FWHM_1": list(radius_val_1),
             "FWHM_2": list(radius_val_2),
             "PA": list(PA_val),
-            "STATUS": list(fit_statuts_val),
+            "STATUS": list(fit_status_val),
             "GLON": list(glon),
             "GLAT": list(glat),
             "RA": list(ra_save),

{hyper_py_photometry-0.1.6 → hyper_py_photometry-1.0.1/src/hyper_py_photometry.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyper-py-photometry
-Version: 0.1.6
+Version: 1.0.1
 Summary: HYPER: Hybrid Photometry Photometry and Extraction Routine
 Author-email: Alessio Traficante <alessio.traficante@inaf.it>
 Project-URL: Homepage, https://github.com/alessio-traficante/hyper-py

hyper_py_photometry-0.1.6/paper/paper.md

@@ -1,73 +0,0 @@
----
-title: 'HYPER-PY: HYbrid Photometry and Extraction Routine in PYthon'
-tags:
-  - Python
-  - astronomy
-  - photometry
-  - astronomy tools
-authors:
-  - name: Alessio Traficante
-    orcid: 0000-0003-1665-6402
-    affiliation: 1 
-    corresponding: true
-  - name: Fabrizio De Angelis
-    affiliation: 1
-  - name: Alice Nucara
-    affiliation: 1
-  - name: Milena Benedettini
-    affiliation: 1
-affiliations:
-  - name: INAF-IAPS, Via Fosso del Cavaliere, 100, 00133 Rome (IT)
-    index: 1
-date: 02 September 2025
-repository: https://github.com/Alessio-Traficante/hyper-py
-bibliography: paper.bib
----
-
- 
- 
-# Summary
- 
-Source extraction and photometry of compact objects are fundamental tasks in observational astronomy. Over the years, various tools have been developed to address the inherent complexity of astronomical data—particularly for accurate background estimation and removal, and for deblending nearby sources to ensure reliable flux measurements across multiple wavelengths (e.g. Cutex: @Molinari11; getsources: @Menshinkov12; Fellwalker: @Berry15; [Astrodendro](http://www.dendrograms.org/)). These challenges are especially pronounced in star-forming regions, which are best observed in the far-infrared (FIR), sub-millimeter, and millimeter regimes, where the cold, dense envelopes of compact sources emit most strongly.
-To address these needs, several software packages have been designed to handle the structured backgrounds and blended source populations typical of observations with instruments such as Herschel (70–500 μm) and ALMA (1–3 mm). These packages differ significantly in their detection strategies and flux estimation methods. In this framework, we developed **HYPER** (HYbrid Photometry and Extraction Routine, @Traficante15), originally implemented in Interactive Data Language (IDL), with the goal of providing robust and reproducible photometry of compact sources in FIR/sub-mm/mm maps. **HYPER** combines: (1) source detection via high-pass filtering; (2) background estimation and removal through local polynomial fitting; and (3) source modeling using 2D elliptical Gaussians. For blended regions, HYPER fits multiple Gaussians simultaneously to deblend overlapping sources, subtracting companions before performing photometry.
-Aperture photometry in **HYPER** is then carried out on the background-subtracted, companion-subtracted images, using the footprint defined by each source’s 2D Gaussian model. This ensures a consistent and robust integrated flux measurement, even in crowded or strongly structured environments @Traficante15; @Traficante23.
-The hybrid nature of **HYPER** lies in its combined approach: using 2D Gaussian modeling, while retaining classical aperture photometry techniques.
-In this work, we present **Hyper-Py**, a fully restructured and extended version of **HYPER** developed entirely in Python. *Hyper-Py* not only replicates the core logic of the original IDL implementation, but introduces multiple improvements in performance, configurability, and background modeling capabilities—making it a modern and flexible tool for source extraction and photometric analysis across a wide range of datasets. Notably, *Hyper-Py* also introduces the ability to estimate and subtract the background emission across individual slices of 3D datacubes, enabling consistent background modeling along the spectral axis for line or continuum studies in spectrally resolved observations.
-
- 
- 
-# Statement of need
-*Hyper-Py* is a Python package freely accessible to the community. This new Python implementation is a conversion of the IDL version **HYPER** which includes several
-improvements to the original package:
-
-**Parallel execution for multi-map analysis**. *Hyper-Py* introduces built-in parallelization for the analysis of multiple input maps. On multi-core systems, each map is independently assigned to a dedicated core, allowing concurrent execution of the full photometric pipeline—source detection, background fitting, Gaussian modeling, and aperture photometry—for each map. This parallel framework substantially improves computational efficiency without altering the scientific output for individual maps.
-
-**Native support for the analysis of FITS datacubes**. The code enables users to treat each slice along the third axis as an independent 2D map. This functionality is fully compatible with the existing parallelization framework, allowing multiple slices to be processed simultaneously across different cores. The primary goal of this mode is to estimate the spatially-varying background emission on a per-slice basis. The final output is a reconstructed 3D background datacube with the same shape as the input cube. This background cube can either be focused on a specific region or line of sight—leaving all other voxels as NaNs—or computed across the full spatial extent of the cube. The region where to perform the extraction and related parameters are configurable via the config.yaml file, offering flexibility for both targeted and global background modeling.
-
-**Improved source detection reliability**. The source detection module has been significantly improved through the implementation of a more robust sigma-clipping algorithm for estimating the root mean square (*rms*) noise of the input map. This enhancement ensures a more accurate characterization of the background fluctuations by iteratively excluding outliers and recalculating the noise level, even in the presence of bright sources or residual structures. The resulting *rms* value is then used as a reference threshold to identify compact sources with peak intensities exceeding a user-defined significance level, set as *n_sigma* × *rms*, where *n_sigma* is configurable via the config.yaml file. This refinement improves the reliability and reproducibility of the source detection process across heterogeneous datasets.
-
-**Advanced background estimation strategy**. *Hyper-Py* introduces a robust and flexible background estimation framework designed to improve subtraction accuracy in complex regions and in case of blended sources. Unlike the original IDL version, which estimated and subtracted the background independently of source modeling @Traficante15, *Hyper-Py* supports multiple statistical methods for background fitting, applied to masked cutouts around each source. Users can select from least-squares regression, Huber regression, and Theil–Sen regression, either individually or in combination. The least-squares method is optimal in regions dominated by Gaussian noise. The Huber regressor provides robustness against outliers by interpolating between L2 and L1 loss functions, with the tuning parameter ε (huber_epsilons in the config file) controlling the transition. The Theil–Sen estimator is a non-parametric, highly robust approach particularly suited for non-Gaussian noise or residual contamination. When multiple methods are enabled, *Hyper-Py* evaluates all and selects the background model that minimizes the residuals within the unmasked region, ensuring accurate reconstruction even in the presence of variable gradients or faint extended emission. In addition, *Hyper-Py* offers an optional joint fit of the background and 2D elliptical Gaussians, which may improve stability or convergence in specific cases. When this combined fit is used, the background polynomial terms can be regularized using L2 (ridge) regression, helping suppress unphysically large coefficients. This constraint enhances the robustness of the background model in regions with strong intensity gradients or spatially variable emission, reducing the risk of overfitting the background at the expenses of the source flux estimation.
-
-**Gaussian + background model optimization strategy**. The combined fitting is optimized using the Levenberg–Marquardt algorithm, implemented via the "least_squares" minimizer from the lmfit package (equivalent to the scipy.optimize.least_squares function). This method allows flexible control over the cost function via the loss parameter, which modifies the residuals used during minimization.
-Specifically, we adopt a robust loss function, setting loss = "cauchy". This choice reduces the influence of outliers by scaling the residuals in a non-linear way, effectively down-weighting pixels that deviate significantly from the model. Compared to the standard least-squares loss ("linear"), robust losses like "cauchy" are better suited to data affected by small-scale artifacts, unmasked sources, or non-Gaussian noise features. Alternative loss functions such as "soft_l1" and "huber" are also available and may offer improved convergence speed in some cases, particularly when dealing with moderately noisy data.
-
-**Model selection criteria for background fitting**. In *Hyper-Py*, the optimal background model—i.e., the best combination of box size and polynomial order—is determined by evaluating the residuals between the observed data and the fitted model. The framework offers a configurable choice of model selection criteria, specified via the config.yaml file. Users can select from three statistical metrics: Normalized Mean Squared Error (NMSE), reduced chi-squared ($\chi^2_\nu$), or the Bayesian Information Criterion (BIC). By default, *Hyper-Py* adopts NMSE, a robust, unitless, and scale-independent metric that quantifies the fraction of residual power relative to the total signal power in the cutout. Unlike reduced chi-squared, NMSE is not sensitive to changes in pixel weighting schemes or the number of valid (unmasked) pixels, making it particularly reliable when background fits are performed under varying masking conditions, inverse-rms weighting, or SNR-based weighting. In contrast, the reduced chi-squared statistic depends directly on the assumed noise model and weighting, and may therefore be biased when the number or distribution of contributing pixels changes. The BIC criterion offers an alternative that penalizes overfitting by incorporating the number of model parameters and the sample size, favoring simpler models when multiple fits achieve similar residuals. This flexibility allows users to tailor the model selection strategy to the scientific context or noise characteristics of their data, ensuring that the chosen background model is both statistically sound and physically meaningful.
-
-**Improved user configurability**. *Hyper-Py* is designed to be more user-friendly, featuring a clear and well-documented configuration file. This allows users to adapt the full photometric workflow to a wide range of observational conditions and scientific goals by modifying only a minimal set of parameters. The modular structure of the configuration also enhances transparency and reproducibility in all stages of the analysis.
- 
-We assessed the performance of the *Hyper-Py* pipeline using a dedicated suite of simulations. Specifically, we adopted a noise-only map derived from the ALMA program #2022.1.0917.S and produced two maps with this reference header. In each of these maps we injected a variable background and 500 synthetic 2D Gaussian sources into it. These sources were designed to emulate the properties of real, compact astronomical objects: integrated fluxes ranged between 8 and 20 times the map *rms* (corresponding to peak fluxes of approximately 1–1.5 times the *rms*), and FWHMs spanned from 0.5 to 1.5 times the beam size, as computed from the FITS header, to simulate both unresolved and moderately extended sources @Elia21. The source position angles were randomly assigned, and a minimum overlap fraction of 30% was imposed to ensure a significant level of blending, thus providing a rigorous test of the code under realistic and challenging conditions. We then compared the performance of the original IDL implementation of **HYPER** with the new Python-based *Hyper-Py* version. Both codes were run using equivalent configurations, with *Hyper-Py* additionally benefiting from its extended capabilities—such as improved background estimation, optional L2 regularization, and multi-core parallel processing. The main results of this comparison are presented in **Table 1**, where we show the differences between the number of identified sources and the false positives by *Hyper-Py* and **HYPER**, respectively. 
-
-| Catalog | Source Type | Total | Matched | False | False Percentage |
-|--------:|:------------|------:|--------:|------:|------------------:|
-|       1 | *Hyper-py*    |   500 |     490 |     4 |          0.8%   |
-|       1 | **HYPER (IDL)**   |   500 |     493 |    73 |         12.9%   |
-|       2 | *Hyper-py*    |   500 |     487 |     4 |          0.8%   |
-|       2 | **HYPER (IDL)**   |   500 |     487 |    46 |          8.6%   |
-
-In addition, Figure 1 and Figure 2 show the differences between the peak fluxes and the integrated fluxes of the sources with respect to the reference values of the simulated input sources as estimated by *Hyper-Py* and HYPER, respectively.
-
-*Hyper-Py* is freely available for download via its [GitHub repository](https://github.com/Alessio-Traficante/hyper-py), and can also be installed using pip, as described in the accompanying README file.
-
-![histogram of the differences between the peak fluxes of the sources as recovered by *Hyper-Py* and HYPER, respectively, with respect to the reference values of the simulated input sources](Figures/Flux_Diff_Histogram_Peak.png)
-
-![histogram of the differences between the peak fluxes of the sources as recovered by *Hyper-Py* and HYPER, respectively, with respect to the reference values of the simulated input sources](Figures/Flux_Diff_Histogram_Int.png)