xcavation 1.0.2

SPHEREx Data Retrieval and Photometry Toolkit

Xcavation is a Python package for rapid forced-photometry calculations of SPHEREx QR2 spectral data. It uses ASQL PyVo to access SPHEREx images through the IRSA API. Aperture photometry are supported and include multi-threading for improved deeper analysis.

🔍 Example 🔎

The example notebook is provided through Google Colab, as it has excellent internet speed for the image API. Additionally, there is an example notebook provided on the GitHub repository.

🛠️ Installation 🛠️

pip Installation

1. Download Python: Visit here to install Python
2. Download pip: Visit here to install pip
3. Run Install Command: Run the command in terminal:

   pip install xcavation
   

🏗️ How to Use xcavation 🏗️

genspec is the primary function for generating a forced-photometry spectrum, providing a full spectrum in a single line of code. User controlled options are provided to aid in problems such as: proper motion, background subtraction, masking, plotting, etc. Multi-threading for efficient processing of large datasets is provided to speed the process further. We recommend starting with genspec rather than calling internal functions directly. genspec returns a dictionary containing all relevant information from the SPHEREx calibrated images; further information on outputted data is provided below.

How to Use genspec

1. After Xcavation is installed, verify the installation by running the following command: from xcavation.genspec import *. If you encounter any issues during installation, please reach out to Hunter Brooks for assistance.
2. Assign the relavent variables as described below.
3. Execute the command: genspec(ra, dec). These are the minimum required parameters for Xcavation to run. You can include optional variables if needed.

Relavent Variables For genspec

• Required Variables:

  • ra: Right Accension in Degrees: float:

    • example: 131.123

  • dec: Declination in Degrees: float:

    • example: -12.31254

• User Configuration:

Relavent Variables For genspec

• Required Variables:

  • ra: Right Accension in Degrees: float:

    • example: 131.123

  • dec: Declination in Degrees: float:

    • example: -12.31254

• User Configuration:

  • r_fwhm: The Number Multiplied by the Image FWHM to Get The Aperture Radius: float
    • example: 2.5, default=2
  • r_annulus_in: The Number Multiplied by the Image FWHM to Get the Inner Annulus Radius: float
    • example: 5, default= 3.5
  • r_annulus_out: The Number Multiplied by the Image FWHM to Get the Outer Annulus Radius: float
    • example: 10, default= 10
  • pmra: Proper Motion in Right Accension (in arcsec/year): float
    • example: -0.981, default=0
  • pmdec: Proper Motion in Declination (in arcsec/year): float
    • example: 0.123, default=0
  • mjd_epoch: Modified Julian Date of Epoch Position: float
    • example: 57500, default=61000
  • mjd_query: Modified Julian Date of Query Position: float
    • example: 61500, default=Time(datetime.now()).mjd
  • mjd: Modified Julian Date of inputed R.A. and Decl. from Above: float
    • example: 57170, default=61000
  • save_data: Save Q.A. Finder Chart, Spectrum, and ASCII Table if True: boolean
    • example: True, default=False
  • output_path: Saved Path (not including extention) for Q.A. Finder Chart, Spectrum, and ASCII Table if save_data is True: string
    • example: /content/drive/MyDrive/Research/example_object, default=xcavation_save
  • threads: Number of Threads for Multi-Threading: int
    • example: 2, default=1
  • enable_print: Enable xcavation.genspec Progress Printing: boolean
    • example: False, default=True
  • ram_download: Enable xcavation.aperture Downloading Image Data on RAM Instead of Local Harddrive (best for computers with small amounts of storage): boolean
    • example: True, default=False
  • retry_count: The Number of HTML 504 Retries Before xcavation.genspec Crashes: int
    • example: 1, default=10
  • clean_type: The Type of Flagged Pixel Cleaning Done to the Calibrated image: string
    • options: none, mask, median_mask, interp_mask, lacosmic
    • example: mask, default=none
  • bad_bits: Masks Out Flags Seen in SPHEREx Documentation and Performs Laplace Transforms Using the astroscrappy.detect_cosmics to Replace These Pixels: list
    • options: Go to Section 6 of HERE for each flag type.
    • example: [0, 1, 5, 6, 10, 11], default=[0, 1, 10, 11]
  • background_type: How the Background Field is Calculated: string
    • options: mean, median, mode
    • example: mode, default=mean
  • cutout_size: The Size of the Cutout in Arcsec: int
    • example: 500, default=150
  • zodi_subtract: Whether or not the Zodiacal light is subtracted: bool
    • example: False, default=True
  • sigclip_sigma: Background Annulus Astropy.SigmaClip Sigma Variable: float
    • example: 3, default=5
  • sigclip_maxiters: Background Annulus Astropy.SigmaClip Max Iterations Variable: float
    • example: 10, default=5

Output Variables:

1. wavelength: Wavelength of a queried position: $\mu m$: float
2. delta_lambda: The resolving power solution ($\Delta \lambda = \frac{\lambda}{R}$) from Table 2 of Akeson et al. (2025): $\mu m$: float
3. flux: Flux from the given aperture photometry: $\mu Jy$: float
4. flux_err: Flux error from the given aperture photometry: $\mu Jy$: float
5. flag_count: Dictionary of every bit measured in the aperture
6. SNR: Signal-to-Noise Ratio ($\frac{F}{\sigma_{F}}$): float
7. flux_cutout: The cutout flux image in $\mu Jy$: numpy array
8. flag_cutout: The cutout flag image in bits: numpy array
9. aperture: The aperture array in cutout size in booleans: numpy array
10. annulus: The annulus array in cutout size in booleans: numpy array
11. x_loc: The x_loc of the centeroid in the flux cutout: float
12. y_loc: The y_loc of the centeroid in the flux cutout: float
13. ap_radius: The radius of the aperture: 2.5 $\times$ FWHM: $arcsec$: float
14. inner_annulus: The inner radius of the annulus: $arcsec$: float
15. outer_annulus: The outer radius of the annulus: $arcsec$: float
16. url: The IPAC IRSA SPHEREx API url: string
17. mjd: The Modified Julian Date of the given SPHEREx image: float

Example

from xcavation.genspec import *

# Required Variables
ra = 12.7955492 
dec = -15.7382839 

# User Configuration
user_config = genspec_profile(pmra = 0, pmdec = 0,
                              mjd_epoch = 61000, mjd_query = 61500,
                              r_fwhm = 2, r_annulus_in = 5, r_annulus_out = 10,
                              save_data = True, output_path = 'test', 
                              threads = 10,
                              enable_print = True, ram_download = False, 
                              retry_count = 10,
                              clean_type = 'mask', bad_bits = [0, 1, 10, 11],
                              background_type = 'mean',
                              cutout_size = 150,
                              zodi_subtract = True,
                              sigclip_sigma = 5, sigclip_maxiters = 5)

# Call function with test input parameters
df = genspec(ra, dec, config = user_config)

📞 Support Team 📞

• Mr. Hunter Brooks
  • hbrooks8 (at) rockets.utoledo.edu
• Dr. Michael Cushing

📖 Acknowledgments 📖

1. If you intend to publish any calculations done by xcavation, please reference Brooks et al. (in prep.).

2. Please reference the relevant SPHEREx citations.