Association Modules

These modules contain functions for the two main association methods in astro_ghost: Directional Light Radius (DLR) and Gradient Ascent (GA). A brief summary of each technique is given below.

DLR

The module to associate transients using the Directional Light Radius (DLR) method outlined in Gupta et al., 2013. The DLR method estimates the radius of each candidate host in the direction of the transient, normalizes each galaxy-transient distance by this value, and takes the source with the lowest normalized distance as the true host.

astro_ghost.DLR.calc_DLR(ra_SN, dec_SN, ra_host, dec_host, r_a, r_b, source, best_band)[source]
Calculate the directional light radius for a given galaxy and transient pair. Calculation is adapted from

Gupta et al., 2013 found at https://repository.upenn.edu/cgi/viewcontent.cgi?referer=https://www.google.com/&httpsredir=1&article=1916&context=edissertations.

Parameters:

  • ra_SN (float) – The right ascension of the SN, in degrees.

  • dec_SN (float) – The declination of the SN, in degrees.

  • ra_host (float) – The right ascension of the host, in degrees.

  • dec_host (float) – The declination of the host, in degrees.

  • r_a (float) – The semi-major axis of the host in arcseconds.

  • r_b (float) – The semi-minor axis of the host in arcseconds.

  • source (Pandas DataFrame) – The Dataframe containing the PS1 information for the candidate host galaxy.

  • best_band (str) – The PS1 passband with the highest S/N, from which second-order moments are estimated.

Returns:

The angular separation between galaxy and transient, in arcseconds.

Return type:

float

Returns:

The normalized distance (angular separation divided by the DLR).

Return type:

float

astro_ghost.DLR.calc_DLR_SM(ra_SN, dec_SN, ra_host, dec_host, r_a, elong, phi, source, best_band)[source]
Calculate the DLR method but for Skymapper (southern-hemisphere) sources,

which don’t have xx and yy moments reported in the catalog.

Parameters:

  • ra_SN (float) – The right ascension of the SN, in degrees.

  • dec_SN (float) – The declination of the SN, in degrees.

  • ra_host (float) – The right ascension of the host, in degrees.

  • dec_host (float) – The declination of the host, in degrees.

  • r_a (float) – The semi-major axis of the host in arcseconds.

  • elong (float) – The elongation parameter of the galaxy.

  • phi (float) – The rotation angle of the galaxy, in radians.

  • source (Pandas DataFrame) – The Dataframe containing the PS1 information for the candidate host galaxy.

  • best_band (str) – The PS1 passband with the highest S/N, from which second-order moments are estimated.

Returns:

The angular separation between galaxy and transient, in arcseconds.

Return type:

float

Returns:

The normalized distance (angular separation divided by the DLR).

Return type:

float

astro_ghost.DLR.calc_DLR_glade(ra_SN, dec_SN, ra_host, dec_host, r_a, a_over_b, phi)[source]

Calculates the DLR between transients and GLADE host galaxy candidates.

(very similar to calc_DLR but the parameters are calculated slightly differently)

Parameters:

  • ra_SN (float) – The right ascension of the SN, in degrees.

  • dec_SN (float) – The declination of the SN, in degrees.

  • ra_host (float) – The right ascension of the host, in degrees.

  • dec_host (float) – The declination of the host, in degrees.

  • r_a (float) – The semi-major axis of the host in arcseconds.

  • a_over_b (float) – The candidate host axis ratio.

  • phi (float) – The galaxy position angle (in radians).

Returns:

The angular separation between galaxy and transient, in arcseconds.

Return type:

float

Returns:

The normalized distance (angular separation divided by the DLR).

Return type:

float

astro_ghost.DLR.chooseByDLR(path, hosts, transients, fn, orig_dict, todo='s')[source]
The wrapper function for selecting hosts by the directional light radius method

introduced in Gupta et al., 2013.

Parameters:

  • path (str) – Filepath where to write out the results of the DLR algorithm.

  • hosts (Pandas DataFrame) – DataFrame containing PS1 information for all candidate hosts.

  • transients (Pandas DataFrame) – DataFrame containing TNS information for all transients.

  • fn (str) – Filename to write the results of the associations (useful for debugging).

  • orig_dict (dictionary) – Dictionary consisting of key,val pairs of transient names, and lists of their candidate host galaxy objIDs in PS1.

  • todo (str) – If todo == 's', save the dictionary and the list of remaining sources. If todo == 'r', return them.

Returns:

The dataframe of PS1 properties for host galaxies found by DLR.

Return type:

Pandas DataFrame

Returns:

Dictionary of matches after DLR, with transient names as keys and a list of host galaxy pan-starrs objIDs as values.

Return type:

dictionary

Returns:

List of transients for which no reliable host galaxy was found.

Return type:

array-like

Returns:

List of transients for which an issue arose in DLR (most likely, a candidate host galaxy in the field didn’t have radius information). This list is used to recommend candidates to associate via the gradient ascent method.

Return type:

array-like

astro_ghost.DLR.chooseByGladeDLR(path, fn, snDF, verbose=False, todo='r')[source]

The wrapper function for selecting hosts by the DLR method (Gupta et al., 2013).

Here, candidate hosts are taken from the GLADE (Dalya et al., 2021; arXiv:2110.06184) catalog.

Parameters:

  • path (str) – Filepath where to write out the results of the DLR algorithm.

  • fn (str) – Filename to write the results of the associations (useful for debugging).

  • transients (Pandas DataFrame) – DataFrame containing TNS information for all transients.

  • todo (str) – If todo == 's', save the dictionary and the list of remaining sources. If todo == 'r', return them.

Returns:

The dataframe of properties for GLADE host galaxies found by DLR.

Return type:

Pandas DataFrame

Returns:

List of transients for which no reliable GLADE host galaxy was found.

Return type:

array-like

astro_ghost.DLR.choose_band_SNR(host_df)[source]
Gets the PS1 band (of grizy) with the highest SNR in PSF mag.

From https://www.eso.org/~ohainaut/ccd/sn.html, Error on Mag ~ 1/ (S/N) So calculating S/N for each band as 1/PSFMagErr Estimate the S/N of each band and choose the bands with the highest S/N for the rest of our measurements.

Parameters:

host_df (Pandas DataFrame) – The dataframe containing the candidate host galaxy (should just be one galaxy).

Returns:

The PS1 band with the highest S/N.

Return type:

str

gradientAscent

The module to associate transients using the Gradient Ascent (GA) method outlined in Gagliano et al., 2021. The GA method downloads PS1 postage stamps of the field, preprocesses the images to remove local structure such as HII regions, and then follows the 2D image gradients from the position of the transient to a local brightness maximum. It then queries PS1 for sources near the final position. This is slower than DLR (because of the time needed to download large postage stamps), but can be more accurate for well-resolved low-redshift hosts.

astro_ghost.gradientAscent.denoise(img, weight=0.1, eps=0.001, num_iter_max=200)[source]
Perform total-variation denoising on a grayscale image.

Uses Rudin, Osher and Fatemi algorithm.

Parameters:

  • img (array-like) – 2-D input data to be de-noised.

  • weight (float, optional) – Denoising weight. The greater weight, the more de-noising (at the expense of fidelity to img).

  • eps (float, optional) – Relative difference of the value of the cost function that determines the stop criterion. The algorithm stops when: (E_(n-1) - E_n) < eps * E_0

  • num_iter_max (int, optional) – Maximal number of iterations used for the optimization.

Returns:

De-noised array of floats.

Return type:

array-like

astro_ghost.gradientAscent.dist(p1, p2)[source]

Measure the euclidean distance between two points.

Parameters:

  • p1 (array-like) – The first point.

  • p2 (array-like) – The second point.

Returns:

The euclidean distance.

Return type:

float

astro_ghost.gradientAscent.getSteps(SN_dict, transientNames, hostDF)[source]
Calculates a scale factor for the gradient ascent step

based on the mean kron radius of the galaxies in the field.

Parameters:

  • SN_dict (dictionary) – Key,value pairs of transient names and lists of candidate host galaxy objIDs in PS1.

  • transientNames (array-like) – Names of transients to associate.

  • hostDF (Pandas DataFrame) – Dataframe of all candidate host galaxies.

Returns:

List of calculated steps.

Return type:

array-like

astro_ghost.gradientAscent.get_clean_img(path, ra, dec, px, band)[source]
Takes PS1 images, removes bad pixels, and

estimates new pixel values through a 2D interpolation.

Parameters:

  • path (str) – filepath where the image will be saved.

  • ra (float) – Right ascension of image position, in degrees.

  • dec (float) – Declination of image position, in degrees.

  • px (int) – Image size, in pixels.

  • band (str) – Passband of image.

Returns:

Image data, with bad pixels masked.

Return type:

2D array

Returns:

Astropy world coordinate system object

Return type:

wcs of image fits file.

Returns:

Header of image fits file.

Return type:

Fits header

astro_ghost.gradientAscent.gradientAscent(path, SN_dict, SN_dict_postDLR, transientNames, hostDF, transientDF, fn, plot=True, px=800)[source]

The gradient ascent algorithm for identifying a final host galaxy.

Parameters:

  • path (str) – Filepath to save the output log for the algorithm.

  • SN_dict (dictionary) – Key, val pairs are transient name, list of PS1 objIDs of potential hosts. Dictionary is before the DLR method.

  • SN_dict_postDLR (dictionary) – Key, val pairs are transient name, list of PS1 objIDs of potential hosts. Dictionary is after the DLR method (so should have mostly one host per transient).

  • transientNames (array-like) – List of transient names.

  • hostDF (Pandas DataFrame) – PS1 info for candidate hosts.

  • transientDF (Pandas DataFrame) – TNS info for associated transients.

  • fn (str) – Filename for gradientAscent log.

  • plot (bool, optional) – If True, plot the associated transients, the background maps, and the gradient fields associated with each transient.

  • px (int) – Image size (in pixels).

Returns:

Dictionary of transient, host objID pairs after gradient ascent.

Return type:

dictionary

Returns:

Dataframe of final associated hosts (after gradient ascent).

Return type:

Pandas Dataframe

Returns:

List of transients for which gradient ascent failed.

Return type:

array-like

astro_ghost.gradientAscent.plot_DLR_vectors_GD(size, path, transient, transient_df, host_dict_candidates, host_dict_final, host_df, R_dict, ra_dict, scale=1)[source]

Plots the DLR vectors associated with each candidate host in a transient’s field.

Parameters:

  • size (int) – Size of the plotted image, in pixels.

  • path (str) – Filepath where image will be saved.

  • transient (str) – Name of transient.

  • transient_df (Pandas DataFrame) – Dataframe of transient properties from TNS.

  • host_dict_candidates (dictionary) – key,value pairs of transient name, list of PS1 objIDs of candidate hosts. Dictionary is before gradient ascent is run.

  • host_dict_final (dictionary) – key,value pairs of transient name, list of PS1 objIDs of candidate hosts. Dictionary is after gradient ascent is run.

  • host_df (Pandas DataFrame) – List of all candidate hosts in the field (before gradient ascent).

  • R_dict (dictionary) – The r/DLR normalized distance metrics for all candidate hosts.

  • ra_dict (dictionary) – The DLR values for all candidate hosts.

  • scale (float) – An additional scale factor for the image size (to fully capture low-z hosts).

Returns:

figure axis

Return type:

axes of the plotted image (to overlay a quiver map, or 2D field of gradient arrows).

astro_ghost.gradientAscent.plot_ellipse(ax, px, s, ra, dec, color)[source]

Plots an ellipse on an image.

Parameters:

  • ax (figure axis) – Axis of figure for plotting.

  • px (int) – Image size, in pixels.

  • s (Pandas DataFrame) – PS1 source, with shape parameters (phi, r_a, and r_b)

  • ra (float) – Right ascension of image center, in degrees.

  • dec (float) – Declination of image center, in degrees.

  • color (str) – Color of plotted ellipse.

astro_ghost.gradientAscent.updateStep(px, gradx, grady, step, point, size)[source]

Determine direction of movement by image gradients. :param px: The maximum size of the image, in pixels. :type px: int :param gradx: The horizontal gradient of the image. :type gradx: float :param grady: The vertical gradient of the image. :type grady: float :param step: The step size for updating the position. :type step: float :param point: The current position. :type point: array-like :param size: The predicted size of the true host. Can be “small”, “medium”, or “large”. :type size: str :return: The updated position. :rtype: array-like