Processing Modules

Scientific data extraction, aperture photometry, background estimation, and time-series analysis.

Aperture photometry extraction for SPHEREx data.

spxquery.processing.photometry.repair_variance_for_flagged_pixels(variance: ndarray, flags: ndarray) → ndarray[source]

Repair NaN variance values for pixels with non-zero flags.

This function validates that NaN variance correlates with flagged pixels (expected behavior) and provides a reasonable variance estimate using the median of valid variance values across the full image.

Parameters:

  • variance (np.ndarray) – Variance array that may contain NaN values

  • flags (np.ndarray) – Flag array (bitmap) indicating pixel quality issues

Returns:

Repaired variance array with NaN replaced for flagged pixels only

Return type:

np.ndarray

Raises:

ValueError – If NaN variance is found in pixels with zero flags (unexpected condition)

Notes

  • Only repairs NaN variance if the pixel has non-zero flags

  • Uses median of valid variance values as replacement

  • Keeps NaN for unflagged pixels to trigger errors (data quality issue)

spxquery.processing.photometry.extract_aperture_photometry(image: ndarray, error: ndarray, x: float, y: float, radius: float) → Tuple[float, float][source]

Perform circular aperture photometry.

Parameters:

  • image (np.ndarray) – Image data (surface brightness units)

  • error (np.ndarray) – Error array (same units as image)

  • x (float) – Pixel coordinates (0-based)

  • y (float) – Pixel coordinates (0-based)

  • radius (float) – Aperture radius in pixels

Returns:

  • flux (float) – Integrated flux (same units as image, summed over aperture)

  • flux_error (float) – Flux uncertainty (same units as image)

spxquery.processing.photometry.process_flags_in_aperture(flags: ndarray, x: float, y: float, radius: float) → int[source]

Combine flags within aperture using bitwise OR.

Parameters:

  • flags (np.ndarray) – Flag array (bitmap)

  • x (float) – Pixel coordinates (0-based)

  • y (float) – Pixel coordinates (0-based)

  • radius (float) – Aperture radius in pixels

Returns:

Combined flag bitmap

Return type:

int

spxquery.processing.photometry.extract_aperture_photometry_with_background(image: ndarray, variance: ndarray, flags: ndarray, x: float, y: float, aperture_radius: float, background_method: str = 'annulus', window_size: int | Tuple[int, int] = 50, min_usable_pixels: int = 10, max_outer_radius: float = 5.0, bg_sigma_clip_sigma: float = 3.0, bg_sigma_clip_maxiters: int = 3, max_annulus_attempts: int = 5, annulus_expansion_step: float = 0.5, annulus_inner_offset: float = 1.414) → Tuple[float, float, float, float, int][source]

Perform aperture photometry with local background subtraction.

Parameters:

  • image (np.ndarray) – Image data (surface brightness units)

  • variance (np.ndarray) – Variance array (surface brightness units squared)

  • flags (np.ndarray) – Flag array

  • x (float) – Source coordinates

  • y (float) – Source coordinates

  • aperture_radius (float) – Aperture radius in pixels. Used for photometry and for excluding aperture pixels from window background estimation.

  • background_method (str) – Background estimation method (‘annulus’ or ‘window’)

  • window_size (int or tuple of (height, width)) – Background window size in pixels (for window method). Aperture pixels are automatically excluded.

  • min_usable_pixels (int) – Minimum number of usable background pixels

  • max_outer_radius (float) – Maximum outer radius for background annulus (for annulus method)

  • bg_sigma_clip_sigma (float) – Sigma threshold for sigma clipping

  • bg_sigma_clip_maxiters (int) – Maximum iterations for sigma clipping

  • max_annulus_attempts (int) – Maximum attempts to expand annulus (for annulus method)

  • annulus_expansion_step (float) – Step size for annulus expansion (for annulus method)

  • annulus_inner_offset (float) – Offset from aperture edge to inner annulus (for annulus method)

Returns:

  • flux (float) – Background-subtracted flux (same units as image, summed over aperture)

  • flux_error (float) – Flux error (same units as image)

  • background (float) – Background level per pixel (same units as image)

  • background_error (float) – Background error per pixel (same units as image)

  • n_bg_pixels (int) – Number of background pixels used

Notes

Inner and outer annulus radii are calculated automatically based on aperture_radius and annulus_inner_offset. Not exposed as parameters to keep interface simple.

spxquery.processing.photometry.extract_source_photometry(mef_file: Path, source: Source, photometry_config: PhotometryConfig | None = None) → PhotometryResult | None[source]

Extract photometry for a source from a SPHEREx MEF file with local background subtraction.

This function reads SPHEREx data in uJy/arcsec2 units, performs aperture photometry, and converts to integrated flux density (microJansky) using WCS-derived pixel scales.

All photometry parameters (aperture sizing, background method, zodiacal subtraction, etc.) are controlled via PhotometryConfig.

Parameters:

  • mef_file (Path) – Path to SPHEREx MEF file

  • source (Source) – Source with RA/Dec coordinates

  • photometry_config (PhotometryConfig, optional) – Photometry configuration. If None, uses defaults.

Returns:

Photometry result with flux in microJansky (μJy) and AB magnitude, or None if extraction failed

Return type:

PhotometryResult or None

Notes

  • Uses read_spherex_mef() with target_unit=’uJy/arcsec2’ for automatic unit conversion

  • All parameters come from photometry_config (aperture_method, subtract_zodi, background_method, etc.)

spxquery.processing.photometry.process_all_observations(file_paths: list[Path], source: Source, photometry_config: PhotometryConfig | None = None) → list[PhotometryResult][source]

Process photometry for all observation files with local background subtraction.

Reads SPHEREx data in uJy/arcsec2 units and converts to integrated flux using WCS-derived pixel scales. Supports both sequential and parallel processing.

All photometry parameters (aperture sizing, background method, zodiacal subtraction, parallel processing workers, etc.) are controlled via PhotometryConfig.

Parameters:

  • file_paths (list[Path]) – List of MEF file paths

  • source (Source) – Target source

  • photometry_config (PhotometryConfig, optional) – Photometry configuration. If None, uses defaults.

Returns:

List of photometry results with flux in microJansky (μJy)

Return type:

list[PhotometryResult]

Background estimation for SPHEREx photometry.

This module provides both window-based and annulus-based background estimation methods for local background subtraction in aperture photometry.

spxquery.processing.background.fast_sigma_clip(data: ndarray, sigma: float = 3.0, maxiters: int = 3)[source]

Sigma-clipped stats using numpy directly (avoids astropy object overhead).

Parameters:

  • data (np.ndarray) – Input data (will be flattened internally).

  • sigma (float) – Clipping threshold in standard deviations.

  • maxiters (int) – Maximum clipping iterations.

Returns:

mean, median, std

Return type:

float, float, float

spxquery.processing.background.estimate_window_background(image: ndarray, variance: ndarray, flags: ndarray, x: float, y: float, window_size: int | Tuple[int, int], aperture_radius: float, min_usable_pixels: int = 10, bg_sigma_clip_sigma: float = 3.0, bg_sigma_clip_maxiters: int = 3) → Tuple[float, float, int][source]

Estimate local background using a rectangular window around the source.

This method uses a rectangular region around the source with automatic exclusion of pixels intersecting the aperture. It is simpler than annulus-based methods and can be more robust in crowded fields.

Parameters:

  • image (np.ndarray) – Image data

  • variance (np.ndarray) – Variance array

  • flags (np.ndarray) – Flag bitmap array

  • x (float) – Source coordinates (center of window)

  • y (float) – Source coordinates (center of window)

  • window_size (int or tuple of (height, width)) – Size of the background window in pixels. If int: creates square window of size window_size × window_size If tuple: (height, width) for rectangular window

  • aperture_radius (float) – Aperture radius in pixels. All pixels intersecting this aperture are excluded from background estimation.

  • min_usable_pixels (int) – Minimum number of unflagged pixels required

  • bg_sigma_clip_sigma (float) – Sigma threshold for sigma clipping

  • bg_sigma_clip_maxiters (int) – Maximum iterations for sigma clipping

Returns:

  • background_level (float) – Background level per pixel

  • background_error (float) – Background error per pixel

  • n_usable (int) – Number of usable pixels in window

Notes

  • If window extends beyond image boundaries, it is clipped to image edges with a warning (not an error)

  • Pixels with flags set are excluded from background estimation

  • Pixels intersecting the aperture are excluded (using conservative estimate)

  • Sigma clipping is used to reject outliers before computing statistics

spxquery.processing.background.determine_annulus_radii(aperture_radius: float, min_annulus_area_pixels: int = 10, max_outer_radius: float = 5.0, annulus_inner_offset: float = 1.414) → Tuple[float, float][source]

Determine inner and outer radii for background annulus.

Inner and outer radii are calculated automatically based on aperture size and configuration parameters.

Parameters:

  • aperture_radius (float) – Source aperture radius in pixels

  • min_annulus_area_pixels (int) – Minimum annulus area in pixels

  • max_outer_radius (float) – Maximum allowed outer radius

  • annulus_inner_offset (float) – Offset from aperture edge to inner annulus radius

Returns:

inner_radius, outer_radius – Annulus inner and outer radii in pixels

Return type:

float, float

Notes

Inner radius is calculated as: aperture_radius + annulus_inner_offset Outer radius is calculated to achieve minimum annulus area, capped at max_outer_radius.

spxquery.processing.background.create_annulus_mask(image_shape: Tuple[int, int], x: float, y: float, inner_radius: float, outer_radius: float) → ndarray[source]

Create boolean mask for annular region.

Parameters:

  • image_shape (tuple) – Shape of image (ny, nx)

  • x (float) – Center coordinates

  • y (float) – Center coordinates

  • inner_radius (float) – Annulus radii in pixels

  • outer_radius (float) – Annulus radii in pixels

Returns:

Boolean mask (True = within annulus)

Return type:

np.ndarray

spxquery.processing.background.estimate_local_background(image: ndarray, variance: ndarray, flags: ndarray, x: float, y: float, aperture_radius: float, min_usable_pixels: int = 10, max_outer_radius: float = 5.0, bg_sigma_clip_sigma: float = 3.0, bg_sigma_clip_maxiters: int = 3, max_annulus_attempts: int = 5, annulus_expansion_step: float = 0.5, annulus_inner_offset: float = 1.414) → Tuple[float, float, int][source]

Estimate local background using annular region around source.

Annulus radii are calculated automatically based on aperture size and configuration parameters.

Parameters:

  • image (np.ndarray) – Image data

  • variance (np.ndarray) – Variance array

  • flags (np.ndarray) – Flag array

  • x (float) – Source coordinates

  • y (float) – Source coordinates

  • aperture_radius (float) – Source aperture radius

  • min_usable_pixels (int) – Minimum number of usable pixels required

  • max_outer_radius (float) – Maximum outer radius

  • bg_sigma_clip_sigma (float) – Sigma threshold for sigma clipping

  • bg_sigma_clip_maxiters (int) – Maximum iterations for sigma clipping

  • max_annulus_attempts (int) – Maximum attempts to expand annulus

  • annulus_expansion_step (float) – Step size for annulus expansion

  • annulus_inner_offset (float) – Offset from aperture edge to inner annulus

Returns:

  • background_level (float) – Background level per pixel (MJy/sr)

  • background_error (float) – Background error per pixel (MJy/sr)

  • n_usable (int) – Number of usable pixels in annulus

Notes

Inner radius = aperture_radius + annulus_inner_offset Outer radius is calculated to achieve minimum annulus area, capped at max_outer_radius.

Light curve generation and CSV export for SPHEREx time-domain analysis.

spxquery.processing.lightcurve.generate_lightcurve_dataframe(photometry_results: List[PhotometryResult], source: Source) → DataFrame[source]

Generate light curve DataFrame from photometry results.

Parameters:

  • photometry_results (List[PhotometryResult]) – List of photometry measurements

  • source (Source) – Source information

Returns:

Light curve data with all measurements

Return type:

pd.DataFrame

spxquery.processing.lightcurve.save_lightcurve_csv(df: DataFrame, output_path: Path, include_metadata: bool = True) → None[source]

Save light curve DataFrame to CSV file.

Parameters:

  • df (pd.DataFrame) – Light curve data

  • output_path (Path) – Path for output CSV file

  • include_metadata (bool) – Whether to include metadata header

spxquery.processing.lightcurve.summarize_lightcurve(df: DataFrame) → Dict[str, Any][source]

Generate summary statistics for light curve.

Parameters:

df (pd.DataFrame) – Light curve data

Returns:

Summary statistics

Return type:

Dict[str, Any]

spxquery.processing.lightcurve.load_lightcurve_from_csv(csv_path: Path) → List[PhotometryResult][source]

Load photometry results from saved lightcurve CSV file.

Parameters:

csv_path (Path) – Path to the lightcurve CSV file

Returns:

List of photometry measurements

Return type:

List[PhotometryResult]

spxquery.processing.lightcurve.print_lightcurve_summary(df: DataFrame) → None[source]

Print summary of light curve data.

Parameters:

df (pd.DataFrame) – Light curve data

Magnitude conversion functions for SPHEREx photometry.

Converts flux density measurements in Jansky to AB magnitude system using astropy units.

spxquery.processing.magnitudes.flux_jy_to_ab_magnitude(flux_jy: float, flux_error_jy: float, wavelength_micron: float) → Tuple[float, float][source]

Convert flux density in Jansky to AB magnitude using astropy units.

AB magnitude is defined as: m_AB = -2.5 * log10(f_nu) - 48.6 where f_nu is flux density in erg/s/cm²/Hz

Parameters:

  • flux_jy (float) – Flux density in Jansky

  • flux_error_jy (float) – Flux density error in Jansky

  • wavelength_micron (float) – Central wavelength in microns

Returns:

  • mag_ab (float) – AB magnitude

  • mag_ab_error (float) – AB magnitude error

spxquery.processing.magnitudes.calculate_ab_magnitude_from_jy(flux_jy: float, flux_error_jy: float, wavelength_micron: float) → Tuple[float | None, float | None][source]

Calculate AB magnitude from flux density in Jansky.

Parameters:

  • flux_jy (float) – Flux density in Jansky

  • flux_error_jy (float) – Flux density error in Jansky

  • wavelength_micron (float) – Central wavelength in microns

Returns:

  • mag_ab (float or None) – AB magnitude

  • mag_ab_error (float or None) – AB magnitude error

spxquery.processing.magnitudes.magnitude_to_flux_jy(mag_ab: float, mag_ab_error: float, wavelength_micron: float) → Tuple[float, float][source]

Convert AB magnitude back to flux density in Jansky.

Useful for validation and upper limit calculations.

Parameters:

  • mag_ab (float) – AB magnitude

  • mag_ab_error (float) – AB magnitude error

  • wavelength_micron (float) – Central wavelength in microns

Returns:

  • flux_jy (float) – Flux density in Jansky

  • flux_error_jy (float) – Flux density error in Jansky