Basic Example

import hostphot
print('HostPhot version:', hostphot.__version__)

Due to scheduled system maintenance, the access to eJWST data products might be intermittent on Monday 20th April 2026 from 15:00 to 16:00 CEST. We apologize for the inconvenience.
HostPhot version: 3.2.0

Cutouts

This module allows you to download image cutouts from several surveys. For this, the user can use the download_images() function with the coordinates of an object:

from hostphot.cutouts import download_images

name = 'SN2004eo'
ra, dec =  308.22579, 9.92853
host_ra, host_dec = 308.2092, 9.92755  # coords of host galaxy
z = 0.0157  # redshift
survey = 'PanSTARRS'

download_images(name, host_ra, host_dec, survey=survey)

A new directory is created with the name and survey under the working directory (see :external:ref:Working Directory <work_dir>). The downloaded fits images will have the format <survey>_<filter>.fits. If the filters are not specified, images in all the available filters (survey dependent) are downloaded. It is recommended to use the coordinates of the host galaxy to have it in the centre of the image. Sometimes, the transient can be very far from the host galaxy, so having separate images for the object and its host might be better.

Let’s check the downloaded image:

from hostphot.utils import plot_fits

plot_fits('images/SN2004eo/PanSTARRS/PanSTARRS_g.fits')

Image Processing

A set of pre-processing steps can be performed to ensure an accurate photometry calculation. Note that all the steps are performed following the structure given by the working directory (see :ref:Working Directory <work_dir>).

Coadding

from hostphot.processing import coadd_images

coadd_filters = 'riz'
coadd_images(name, filters=coadd_filters, survey=survey)  # creates a new fits file

This creates a new fits image under the object’s directory, in this case, with the name PS1_riz.fits. Coadding images is useful for common aperture photometry (see below). For the coadd, HostPhot makes use of reproject.

Masking

Some low-redshift galaxy can have foreground stars on top of them. HostPhot can remove these first detecting them with pseudo-sigma clipping (using sep) and cross-matching the sources with a catalog of stars (using astroquery MAST), and then masking them using a 2D Gaussian kernel. The coadded image created above can be masked and the parameters of the mask can be extracted to be used on single filter images of the same object:

from hostphot.processing import create_mask

# one can extract the mask parameters from the coadd
# this also creates new fits files
create_mask(name,
            host_ra,
            host_dec,
            filt=coadd_filters,
            survey=survey,
            threshold=23,
            ra=ra,
            dec=dec,
            save_plots=True,
            save_mask_params=True)

for filt in 'grizy':
    create_mask(name,
                host_ra,
                host_dec,
                filt,
                survey=survey,
                ra=ra,
                dec=dec,
                ref_filt=coadd_filters,
                ref_survey=survey,
                save_plots=False,
                save_input=False)

Note that the host-galaxy coordinates need to be provided so HostPhot knows which object not to mask out. The SN coordinates are optional to plot its position. The steps above create masked fits images, in this case, with the names PanSTARRS_<filter>_masked.fits. See below an example of this mask applied:

from hostphot.utils import plot_image

plot_image('images/SN2004eo/PanSTARRS/PanSTARRS_riz_masked.jpg')

If the user is not happy with the result of the masking, there are a few parameters that can be adjusted. For instance, threshold sets the threshold (how many sigmas above the background noise) used by sep for detecting objects. Lowering it will allow the detection of fainter objects. sigma is the width of the gaussian used for convolving the image and masking the detected objects. If crossmatch is set to True, the detected objects are cross-matched with the Gaia catalog and only those in common are kept. This is useful for very nearby host galaxies (e.g. that of SN 2011fe) so the structures of the galaxy are not maked out, artificially lowering its flux. Note that the images can be background subtracted by setting bkg_sub=True, although this is already performed by default for the surveys that need it.

Photometry

HostPhot can calculate the photometry of the entire galaxy (global) or in a given circular aperture (local). For this, the code heavily relies on astropy and photutils.

Local Photometry

Local photometry can be obtained for the downloaded images. For this, a circular aperture is used (multiple apertures can be set), assuming a cosmology (H0=70 and Om0=0.3 by default; hence a redshift is needed):

from hostphot.photometry import local_photometry as lp

ap_radii = [3, 4]  # aperture radii in units of kpc
results = lp.multi_band_phot(name,
                             ra,
                             dec,
                             z,
                             survey=survey,
                             ap_radii=ap_radii,
                             use_mask=True,
                             correct_extinction=True,
                             save_plots=False,
                             save_results=True)

results is a pandas DataFrame with the photometry (flux and magnitudes) of the filters used (the results are saved into a CSV file). Note that the coordinates are at the position of the object (SN2004eo). The cosmology can be changed with lp.choose_cosmology(). Setting use_mask=True tells HostPhot to used the masked images previously created and setting save_plots=True provides output plots with the images and the apertures used, which are saved under the object’s directory.

results

	name	ra	dec	redshift	survey	ap_units	g_3	g_3_err	g_3_flux	g_3_flux_err	...	z_zeropoint	y_3	y_3_err	y_3_flux	y_3_flux_err	y_4	y_4_err	y_4_flux	y_4_flux_err	y_zeropoint
0	SN2004eo	308.22579	9.92853	0.0157	PanSTARRS	kpc	22.108579	0.719498	14.34063	6.992727	...	25	18.824586	0.233082	295.233381	56.960825	17.578233	0.100314	930.479385	77.263242	25

1 rows × 51 columns

_ = lp.multi_band_phot(name,
                       ra,
                       dec,
                       z,
                       survey=survey,
                       ap_radii=3,
                       use_mask=True,
                       correct_extinction=True,
                       filters='r',
                       save_plots=True)

Image with local aperture:

plot_image('images/SN2004eo/PanSTARRS/local_PanSTARRS_r_3kpc.jpg')

The star marks the position of the SN and the red circle the aperture used.

Global Photometry

Global photometry relies on sep and uses Kron fluxes. It works in a relatively similar way to the local photometry:

from hostphot.photometry import global_photometry as gp

results = gp.multi_band_phot(name,
                             host_ra,
                             host_dec,
                             survey=survey,
                             ra=ra,
                             dec=dec,
                             use_mask=True,
                             correct_extinction=True,
                             save_aperture_params=False,
                             save_plots=True)

results

	name	host_ra	host_dec	survey	g	g_err	g_flux	g_flux_err	g_zeropoint	r	...	z	z_err	z_flux	z_flux_err	z_zeropoint	y	y_err	y_flux	y_flux_err	y_zeropoint
0	SN2004eo	308.2092	9.92755	PanSTARRS	12.558013	0.014033	94797.06445	901.792005	25	11.84092	...	11.238463	0.015025	319606.050841	3892.310272	25	10.917236	0.018049	429640.970413	6419.423796	25

1 rows × 29 columns

Setting common_aperture=True tells HostPhot to used the same aperture for all the filters, obtained from the coadded image (coadd_filters='riz') and setting optimize_kronrad=True provides a more “reliable” aperture than using the default parameters commonly used by SExtractor, as the aperture is increased until the change in flux is samller than a given percent (this can be changed with eps). The rest of the parameters are the same as before.

Image with global aperture:

plot_image('images/SN2004eo/PanSTARRS/global_PanSTARRS_r.jpg')

The parameters ra and dec are only used to plot the position of the SN. By default, HostPhot corrects for Milky Way extinction using the recalibrated dust maps by Schlafly & Finkbeiner (2011) and the extinction law from Fitzpatrick (1999).