astro_prost.helpers

Attributes

`PROB_FLOOR`
`DUMMY_FILL_VAL`
`RAD_TO_ARCSEC`
`MAX_RAD_DEG`
`REDSHIFT_FLOOR`
`SIZE_FLOOR`
`ABSMAG_FLOOR`
`STARMAG_DIFF`
`DEFAULT_LIMITING_MAG`
`CATALOG_SHRED_SETTINGS`
`DEFAULT_DUST_PATH`
`PROP_DTYPES`
`TRACE_LEVEL`

Classes

`ColorlessFormatter`	Formatter that strips ANSI color codes from log messages.
`GalaxyCatalog`	Class for a catalog containing candidate transient host galaxies.
`Transient`	Class for transient source to be associated.
`PriorzObservedTransients`	A continuous probability distribution for a redshift prior defined by
`SnRateAbsmag`	A host-galaxy absolute magnitude likelihood distribution,

Functions

`trace`(self, message, args, *kws)	Logs a message at the TRACE level, which is lower than DEBUG (verbose = 3).
`sanitize_input`(cat_name)	Cleans up catalog names for use by Prost by removing spaces, underscores, and hyphens, and converting to lowercase.
`add_console_handler`(logger, formatter)	Attach a console (stream) handler to the logger.
`add_file_handler`(logger, log_file, formatter)	Attach a file handler to the logger.
`setup_logger`([log_file, verbose, is_main])	Sets up a logger that logs messages to both the console and a file (if specified).
`flux_to_mag`(flux, zeropoint)	Convert flux to magnitude, handling nonpositive values.
`build_skymapper_url`(ra, dec, search_radius, release, ...)
`fetch_skymapper_sources`(search_pos, search_rad, ...[, ...])	Queries the skymapper catalogs (https://skymapper.anu.edu.au/about-skymapper/).
`fetch_rubin_sources`(search_pos, search_rad, cat_cols, ...)	Queries the rubin obs. lsst (placeholder now using dp0.2 and dp1 data, from tutorial 02b on the rsp!).
`fetch_panstarrs_sources`(search_pos, search_rad, ...[, ...])	Queries the panstarrs catalogs (https://catalogs.mast.stsci.edu/panstarrs/).
`fetch_decals_sources`(search_pos, search_rad, cat_cols, ...)	Queries the decals catalogs (https://www.legacysurvey.org/decamls/).
`calc_shape_props_rubin`(candidate_hosts[, band])	Wrapper to calculate the shape parameters for rubin lsst galaxies.
`calc_shape_props_panstarrs`(candidate_hosts)	Wrapper to calculate the shape parameters for pan-starrs galaxies.
`calc_shape_props_skymapper`(candidate_hosts)	Wrapper to calculate the shape parameters for skymapper galaxies.
`calc_shape_props_decals`(candidate_hosts)	Wrapper to calculate the shape parameters for decals galaxies.
`calc_shape_props_glade`(candidate_hosts)	Wrapper to calculate the shape parameters for pan-starrs galaxies.
`build_galaxy_array`(candidate_hosts, cat_cols, ...)	Builds a structured NumPy array of galaxy properties for host association.
`fetch_catalog_data`(self, transient, search_rad, cosmo, ...)	Fetch and process catalog data for a given transient.
`panstarrs_cone`(metadata, ra, dec, radius[, table, ...])	Conducts a cone search of the Pan-STARRS 3PI catalog tables.
`panstarrs_search`(metadata[, table, release, format, ...])	Queries the Pan-STARRS catalog API.
`build_glade_candidates`(transient, glade_catalog, ...)	Populates a GalaxyCatalog object with candidates from a cone search of the
`build_skymapper_candidates`(transient, cosmo, logger[, ...])	Populates a GalaxyCatalog object with candidates from a cone search of the
`build_decals_candidates`(transient, cosmo, logger[, ...])	Populates a GalaxyCatalog object with candidates from a cone search of the
`build_rubin_candidates`(transient, cosmo, logger[, ...])	Populates a GalaxyCatalog object with candidates from a cone search of the
`build_panstarrs_candidates`(transient, cosmo, logger[, ...])	Populates a GalaxyCatalog object with candidates from a cone search of the
`calc_dlr`(transient_pos_samples, galaxies_pos, a, ...)	Calculates the directional light radius (DLR) between candidate host and transient, following the
`find_shreds`(objids, coords, a, a_std, a_over_b, ...)	Finds and removes potentially shredded sources.
`is_service_available`(url[, timeout])
`get_ned_specz`(ra, dec[, search_radius, logger])	Query NED for spectroscopic redshift at given coordinates.

Module Contents

PROB_FLOOR[source]

DUMMY_FILL_VAL = -999[source]

RAD_TO_ARCSEC = 206265[source]

MAX_RAD_DEG = 0.14[source]

REDSHIFT_FLOOR = 0.001[source]

SIZE_FLOOR = 0.25[source]

ABSMAG_FLOOR = -10[source]

STARMAG_DIFF = 0.05[source]

DEFAULT_LIMITING_MAG[source]

CATALOG_SHRED_SETTINGS[source]

DEFAULT_DUST_PATH = '.'[source]

PROP_DTYPES[source]

TRACE_LEVEL = 5[source]

trace(self, message, *args, **kws)[source]

Logs a message at the TRACE level, which is lower than DEBUG (verbose = 3).

Parameters:

message (str) – The message to be logged.
*args (tuple) – Additional positional arguments to be passed to the logging call.
**kws (dict) – Additional keyword arguments to be passed to the logging call.

Return type:

None

sanitize_input(cat_name)[source]

Cleans up catalog names for use by Prost by removing spaces, underscores, and hyphens, and converting to lowercase.

Parameters:: cat_name (str) – The catalog name to be sanitized. Supported catalog names include ‘decals’, ‘glade’, ‘panstarrs’, and ‘skymapper’.
Returns:: The sanitized catalog name.
Return type:: str

class ColorlessFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)[source]

Bases: logging.Formatter

Formatter that strips ANSI color codes from log messages.

format(record)[source]

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

add_console_handler(logger, formatter)[source]

Attach a console (stream) handler to the logger.

Parameters:

logger (logging.Logger) – The logger to which the console handler will be added.
formatter (logging.Formatter) – The formatter used to format log messages.

Return type:

None

add_file_handler(logger, log_file, formatter)[source]

Attach a file handler to the logger.

Parameters:

logger (logging.Logger) – The logger to which the file handler will be added.
log_file (str) – The file path where log messages will be written.
formatter (logging.Formatter) – The formatter used to format log messages.

Return type:

None

setup_logger(log_file=None, verbose=1, is_main=False)[source]

Sets up a logger that logs messages to both the console and a file (if specified).

Parameters:: log_file (str, optional) – Path to the log file.
Returns:: Configured logger instance.
Return type:: logging.Logger

flux_to_mag(flux, zeropoint)[source]: Convert flux to magnitude, handling nonpositive values.

build_skymapper_url(ra, dec, search_radius, release, catalog)[source]

fetch_skymapper_sources(search_pos, search_rad, cat_cols, calc_host_props, logger=None, release='dr4')[source]

Queries the skymapper catalogs (https://skymapper.anu.edu.au/about-skymapper/).

Parameters:

search_pos (astropy SkyCoord object) – Search position (transient location in this code).
search_rad (astropy Angle object) – Size of the search radius.
cat_cols (boolean) – If True, concatenates all columns from the catalog to the final output.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
release (str) – Data release of the catalog; can be ‘dr1’, ‘dr2’, or ‘dr4’.

Returns:

Dataframe containing the retrieved sources.

Return type:

pandas.DataFrame

fetch_rubin_sources(search_pos, search_rad, cat_cols, calc_host_props, logger=None, release='dp1')[source]

Queries the rubin obs. lsst (placeholder now using dp0.2 and dp1 data, from tutorial 02b on the rsp!).

Parameters:

search_pos (astropy SkyCoord object) – Search position (transient location in this code).
search_rad (astropy Angle object) – Size of the search radius.
cat_cols (boolean) – If True, concatenates all columns from the catalog to the final output.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
release (str) – Catalog to query (for now only dp0.2 and dp1!)

Returns:

Dataframe containing the retrieved sources (after some basic quality cuts).

Return type:

pandas.DataFrame

fetch_panstarrs_sources(search_pos, search_rad, cat_cols, calc_host_props, logger=None, release='dr2')[source]

Queries the panstarrs catalogs (https://catalogs.mast.stsci.edu/panstarrs/).

Parameters:

search_pos (astropy SkyCoord object) – Search position (transient location in this code).
search_rad (astropy Angle object) – Size of the search radius.
cat_cols (boolean) – If True, concatenates all columns from the catalog to the final output.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
release (str) – Data release of the catalog; can be ‘dr1’ or ‘dr2’.

Returns:

Dataframe containing the retrieved sources (after some basic quality cuts).

Return type:

pandas.DataFrame

fetch_decals_sources(search_pos, search_rad, cat_cols, calc_host_props, release='dr9')[source]

Queries the decals catalogs (https://www.legacysurvey.org/decamls/).

Parameters:

search_pos (astropy SkyCoord object) – Search position (transient location in this code).
search_rad (astropy Angle object) – Size of the search radius.
cat_cols (boolean) – If True, concatenates all columns from the catalog to the final output.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
release (str) – Data release of the catalog; can be ‘dr9’ or ‘dr10’.

Returns:

Dataframe containing the retrieved sources.

Return type:

pandas.DataFrame

calc_shape_props_rubin(candidate_hosts, band='r')[source]

Wrapper to calculate the shape parameters for rubin lsst galaxies.

Parameters:

candidate_hosts (pandas.DataFrame) – Dataset containing sources with shape information.

Returns:

(temp_sizes, temp_sizes_std, a_over_b, a_over_b_std, phi, phi_std), where:

temp_sizes: Semi-major axes (arcsec)

temp_sizes_std: Uncertainty in semi-major axes

a_over_b: axis ratio

a_over_b_std: Uncertainty in axis ratio

phi: Position angles (radians)

phi_std: Uncertainty in position angles

Return type:

tuple of np.ndarray

calc_shape_props_panstarrs(candidate_hosts)[source]

Wrapper to calculate the shape parameters for pan-starrs galaxies.

Parameters:

candidate_hosts (pandas.DataFrame) – Dataset containing sources with shape information.

Returns:

(temp_sizes, temp_sizes_std, a_over_b, a_over_b_std, phi, phi_std), where:

temp_sizes: Semi-major axes (arcsec)

temp_sizes_std: Uncertainty in semi-major axes

a_over_b: axis ratio

a_over_b_std: Uncertainty in axis ratio

phi: Position angles (radians)

phi_std: Uncertainty in position angles

Return type:

tuple of np.ndarray

calc_shape_props_skymapper(candidate_hosts)[source]

Wrapper to calculate the shape parameters for skymapper galaxies.

Parameters:

candidate_hosts (pandas.DataFrame) – Dataset containing sources with shape information.

Returns:

(temp_sizes, temp_sizes_std, a_over_b, a_over_b_std, phi, phi_std), where:

temp_sizes: Semi-major axes (arcsec)

temp_sizes_std: Uncertainty in semi-major axes

a_over_b: axis ratio

a_over_b_std: Uncertainty in axis ratio

phi: Position angles (radians)

phi_std: Uncertainty in position angles

Return type:

tuple of np.ndarray

calc_shape_props_decals(candidate_hosts)[source]

Wrapper to calculate the shape parameters for decals galaxies.

Parameters:

candidate_hosts (pandas.DataFrame) – Dataset containing sources with shape information.

Returns:

(temp_sizes, temp_sizes_std, a_over_b, a_over_b_std, phi, phi_std), where:

temp_sizes: Semi-major axes (arcsec)

temp_sizes_std: Uncertainty in semi-major axes

a_over_b: axis ratio

a_over_b_std: Uncertainty in axis ratio

phi: Position angles (radians)

phi_std: Uncertainty in position angles

Return type:

tuple of np.ndarray

calc_shape_props_glade(candidate_hosts)[source]

Wrapper to calculate the shape parameters for pan-starrs galaxies.

Parameters:

candidate_hosts (pandas.DataFrame) – Dataset containing sources with shape information.

Returns:

(temp_sizes, temp_sizes_std, a_over_b, a_over_b_std, phi, phi_std), where:

temp_sizes: Semi-major axes (arcsec)

temp_sizes_std: Uncertainty in semi-major axes

a_over_b: axis ratio

a_over_b_std: Uncertainty in axis ratio

phi: Position angles (radians)

phi_std: Uncertainty in position angles

Return type:

tuple of np.ndarray

build_galaxy_array(candidate_hosts, cat_cols, transient_name, catalog, release, logger)[source]

Builds a structured NumPy array of galaxy properties for host association.

Parameters:

candidate_hosts (pandas.DataFrame) – DataFrame with candidate host galaxy properties.
cat_cols (bool) – If True, include extra catalog columns not in PROP_DTYPES.
transient_name (str) – Name of the transient (for logging purposes).
catalog (str) – Name of the catalog (e.g., ‘panstarrs’, ‘decals’, ‘glade’, ‘skymapper’).
release (str) – Catalog release version (e.g., ‘dr2’).
logger (logging.Logger) – Logger instance for messages to console or output file.

Returns:

galaxies (numpy.ndarray) – Structured array of galaxy properties with dtype defined by PROP_DTYPES (extended to include catalog properties if cat_cols is True).
cat_col_fields (list) – List of extra catalog column names from the catalog.

fetch_catalog_data(self, transient, search_rad, cosmo, logger, cat_cols, calc_host_props)[source]

Fetch and process catalog data for a given transient.

This function selects the appropriate catalog function based on the catalog name (stored in self.catalog_functions), sets default parameters (e.g. limiting magnitude), and passes common parameters (transient info, search radius, cosmology, etc.) to the catalog-specific function. For the ‘glade’ catalog, it requires that self.data is provided.

Parameters:

transient (object) – A transient object with at least name and position attributes.
search_rad (astropy.units.Angle) – Cone search radius.
cosmo (astropy.cosmology) – Cosmological model for distance conversions.
logger (logging.Logger) – Logger instance for messages to console or output file.
cat_cols (bool) – If True, include extra catalog columns in the returned data.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).

Returns:

A tuple (catalog_data, extra_columns) where:

catalog_data is the processed candidate host data (e.g. a pandas.DataFrame or structured array),
extra_columns is a list of additional catalog column names (empty if cat_cols is False).

Return type:

tuple

Raises:

ValueError – If the catalog name is unknown or if required catalog data (e.g. for ‘glade’) is missing.

class GalaxyCatalog(name, release=None, data=None, n_samples=1000)[source]

Class for a catalog containing candidate transient host galaxies.

Parameters:

name (str) – Name of the transient catalog. Currently ‘glade’, ‘decals’, and ‘panstarrs’ are supported.
data (pandas.DataFrame or None) – Locally-saved catalog data (e.g., GLADE) used for host association at low redshift.
n_samples (int) – Number of Monte Carlo samples to draw during the association process.

name[source]

Identifier for the catalog. Current supported values are ‘glade’, ‘decals’, and ‘panstarrs’.

Type:: str

data[source]

The catalog data provided to the object. Used for catalogs that do not require an external query.

Type:: pandas.DataFrame or None

n_samples[source]

The number of samples used for probabilistic host association calculations.

Type:: int

release[source]

The version or data release of the catalog (e.g., ‘dr1/dr2’ for pan-starrs; ‘dr9/dr100’ for decals). Can be None if not applicable.

Type:: str or None

shred_cut[source]

A flag indicating whether to automatically remove likely source shreds (duplicate detections) from the candidate list. The default is determined by the catalog type (only pan-starrs is True).

Type:: bool

name[source]

data = None[source]

n_samples = 1000[source]

release = None[source]

shred_cut[source]

catalog_functions[source]

get_candidates(transient, cosmo, logger, time_query=False, calc_host_props=['offset', 'absmag', 'redshift'], cat_cols=False)[source]

Hydrates the catalog attribute catalog.galaxies with a list of candidates.

Parameters:

transient (Transient) – Source to associate, of custom class Transient.
cosmo (astropy cosmology) – Assumed cosmology for conversions (defaults to LambdaCDM if not set).
logger (logging.Logger) – Logger instance for messages to console or output file.
time_query (boolean) – If True, times the catalog query and stores the result in self.query_time.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
cat_cols (boolean) – If True, contatenates catalog columns to resulting DataFrame.

class Transient(name, position, logger, redshift=np.nan, redshift_std=np.nan, spec_class='', position_err=(0.1 * u.arcsec, 0.1 * u.arcsec), phot_class='', n_samples=1000, n_hosts=2)[source]

Class for transient source to be associated.

Parameters:

name (str) – Name of transient.
position (astropy.coord.SkyCoord object) – Position of transient.
position_err (tuple of quantity objects) – Positional uncertainty of transient.
logger (logging.Logger) – Logger instance for messages to console or output file.
redshift (float) – Photometric or spectroscopic redshift of transient.
spec_class (str) – Spectroscopic class of transient, if available.
phot_class (str) – Photometric class of transient, if available.
n_samples (int) – Number of iterations for Monte Carlo association.

best_host[source]

Catalog index of host with the highest posterior probability of association. Set to -1 if no valid host.

Type:: int

best_hosts[source]

List of catalog indices for the top n_hosts host galaxies.

Type:: list of int

n_hosts[source]

Number of host galaxies to return.

Type:: int

redshift[source]

Redshift of the transient. This is either the spectroscopic/photometric redshift or an inferred value from sampling from the prior.

Type:: float

redshift_std[source]

Uncertainty in transient redshift.

Type:: float

gen_z_samples[source]

Generates samples for the transient’s redshift from the measured redshift (if available) or a user-specified prior distribution.

Type:: function

priors[source]

Prior distributions for host properties used in association. Keys are a subset of ‘offset’, ‘absmag’, and ‘redshift’.

Type:: dict

likes[source]

Likelihood functions for host properties used in association. Keys are a subset of ‘offset’, ‘absmag’, and ‘redshift’.

Type:: dict

name[source]

Name of the transient.

Type:: str

position[source]

The transient’s position.

Type:: astropy.coordinates.SkyCoord

spec_class[source]

Spectroscopic classification of the transient, if available. Defaults to an empty string.

Type:: str

phot_class[source]

Photometric classification of the transient, if available. Defaults to an empty string.

Type:: str

n_samples[source]

Number of samples used for probabilistic association. Defaults to 1000.

Type:: int

name[source]

position[source]

position_err[source]

redshift[source]

redshift_std[source]

spec_class = ''[source]

phot_class = ''[source]

n_samples = 1000[source]

n_hosts = 2[source]

best_host = -1[source]

logger[source]

best_hosts = [][source]

priors[source]

likes[source]

position_samples[source]

__str__()[source]

get_prior(type)[source]

Retrieves the transient host’s prior for a given property.

Parameters:: type (str) – Type of prior to retrieve (can be redshift, offset, or absmag).
Returns:: prior – The prior for ‘type’ property.
Return type:: scipy stats continuous distribution

get_likelihood(type)[source]

Retrieves the transient host’s likelihood for a given property.

Parameters:: type (str) – Type of prior to retrieve (can be redshift, offset, absmag).
Returns:: prior – The likelihood for ‘type’ property.
Return type:: scipy stats continuous distribution

set_likelihood(type, func)[source]

Sets the transient’s host prior for a given property.

Parameters:

type (str) – Type of likelihood to set (can be redshift, offset, absmag).
func (scipy stats continuous distribution) – The likelihood to set for ‘type’ property.

set_prior(type, func)[source]

Sets the transient host’s prior for a given property.

Parameters:

type (str) – Type of prior to set (can be redshift, offset, absmag).
func (scipy stats continuous distribution) – The prior to set for ‘type’ property.

gen_z_samples(ret=False, n_samples=None)[source]

Generates transient redshift samples for Monte Carlo association.: If redshift is not measured, samples are drawn from the prior.

Parameters:

ret (boolean) – If true, returns the samples.
n_samples (int) – Number of samples to draw.

Returns:

samples – If ret=True, redshift samples.

Return type:

np.ndarray

calc_prior_redshift(redshift_samples, reduce='mean')[source]

Calculates the prior probability of the transient redshift samples.

Parameters:

redshift_samples (np.ndarray) – Array of transient redshift samples.
reduce (str) – How to collapse the samples into a prior point-estimate. Defaults to calculating the mean across samples.

Returns:

pdf – prior probability point estimate or samples.

Return type:

float or np.ndarray

calc_prior_offset(fractional_offset_samples, reduce='mean')[source]

Calculates the prior probability of the transient’s fractional offset.

Parameters:

fractional_offset_samples (np.ndarray) – Array of transient fractional offset samples.
reduce (str) – How to collapse the samples into a prior point-estimate. Defaults to calculating the mean across samples.

Returns:

Description of returned object.

Return type:

type

calc_prior_absmag(absmag_samples, reduce='mean')[source]

Computes the prior probability for host galaxy absolute magnitude.

Parameters:

absmag_samples (np.ndarray) – 2D array of (n_galaxies, n_samples).
reduce (str) – How to collapse the samples into a prior point-estimate. Defaults to calculating the mean across samples.

Returns:

The collapsed prior probability across samples for all galaxies.

Return type:

np.ndarray

calc_like_redshift(redshift_mean, redshift_std, reduce='mean')[source]

Calculates the likelihood of a redshift with uncertainties.

Parameters:

redshift_mean (np.ndarray) – Redshift means for candidate hosts.
redshift_std (np.ndarray) – Redshift stds for candidate hosts.
reduce (str) – How to collapse the samples into a prior point-estimate. Defaults to calculating the mean across samples.

Returns:

The collapsed likelihood probability across samples for all galaxies.

Return type:

np.ndarray

calc_like_offset(fractional_offset_samples, reduce='mean')[source]

Calculates the likelihoods of a set of fractional offsets.

Parameters:

fractional_offset_samples (np.ndarray) – Array of (n_galaxies, n_samples) fractional offsets.
reduce (str) – How to collapse the samples into a prior point-estimate. Defaults to calculating the mean across samples.

Returns:

The collapsed likelihood probability across samples for all galaxies.

Return type:

np.ndarray

calc_like_absmag(absmag_samples, reduce='mean')[source]

Calculates the likelihoods of a set of absolute magnitudes.

Parameters:

fractional_offset_samples (np.ndarray) – Array of (n_galaxies, n_samples) absmag values.
reduce (str) – How to collapse the samples into a prior point-estimate. Defaults to calculating the mean across samples.

Returns:

The collapsed likelihood probability across samples for all galaxies.

Return type:

np.ndarray

associate(galaxy_catalog, cosmo, condition_host_props=['offset'])[source]

Runs the main transient association module.

Parameters:

galaxy_catalog (GalaxyCatalog object) – The catalog populated with candidate hosts and their attributes.
cosmo (astropy cosmology) – Assumed cosmology.

Returns:

galaxy_catalog – The catalog, with additional attributes including posterior probabilities, best host, and unobserved probability.

Return type:

GalaxyCatalog object

probability_of_unobserved_host(search_rad, cosmo, limiting_mag=30, n_samples=1000, condition_host_props=['offset'])[source]

Calculates the posterior probability of the host being either dimmer than the: limiting magnitude of the catalog or not in the catalog at all.

Parameters:

search_rad (float) – Cone search radius, in arcsec.
limiting_mag (float) – Limiting magnitude of the survey, in AB mag.
n_samples (int) – Number of samples for Monte Carlo association.
cosmo (astropy cosmology) – Assumed cosmology for the run.

Returns:

post_unobserved – n_samples of posterior probabilities of the host not being in the catalog.

Return type:

np.ndarray

probability_host_outside_cone(cosmo, search_rad=60, n_samples=1000, condition_host_props=['offset'])[source]

Calculates the posterior probability of the host being outside the cone search chosen: for the catalog query. Primarily set by the fractional offset and redshift prior.

Parameters:

search_rad (float) – Cone search radius, in arcsec.
n_samples (int) – Number of samples to draw for Monte Carlo association.
cosmo (astropy cosmology) – Assumed cosmology.
condition_host_props (list) – List of galaxy properties to use for association.

Returns:

post_outside – An array of n_samples posterior probabilities of the host being outside the search cone.

Return type:

np.ndarray

class PriorzObservedTransients(cosmo, z_min=0, z_max=1, n_bins=100, mag_cutoff=22, absmag_mean=-19, absmag_min=-24, absmag_max=-17, r_transient=1e-05, t_obs=1.0, **kwargs)[source]

Bases: scipy.stats.rv_continuous

A continuous probability distribution for a redshift prior defined by: an observed sample of transients with a given limiting magnitude, volumetric rate, and brightness distribution.

Parameters:

z_min (float) – Minimum redshift to draw transients from.
z_max (float) – Maximum redshift to draw transients from.
n_bins (int) – Number of bins with which to fit the observed sample to a PDF.
mag_cutoff (float) – Maximum apparent magnitude of the transient survey.
absmag_mean (float) – Expected absolute brightness of the transient.
absmag_min (float) – Description of parameter absmag_min.
absmag_max (type) – Description of parameter absmag_max.
r_transient (float) – Transient volumetric rate, in units of N/Mpc^3/yr. (This gets normalized, so this is not too important).
t_obs (float) – The observing time in years.
**kwargs (dict) – Any other params.

cosmo[source]

Assumed cosmology.

Type:: astropy cosmology

_generate_distribution[source]

Runs the experiment to build the distribution of observed transients.

Type:: function

z_min[source]

z_max[source]

n_bins[source]

mag_cutoff[source]

absmag_mean[source]

absmag_min[source]

absmag_max[source]

r_transient[source]

t_obs[source]

z_min = 0[source]

z_max = 1[source]

n_bins = 100[source]

mag_cutoff = 22[source]

absmag_mean = -19[source]

absmag_min = -24[source]

absmag_max = -17[source]

r_transient = 1e-05[source]

t_obs = 1.0[source]

cosmo[source]

_generate_distribution()[source]

Generate and store the empirical redshift distribution for the prior.

This method:

Creates redshift bins between self.z_min and self.z_max.
Computes the comoving volume element (dV/dz) for each bin using self.cosmo.
Estimates the number of supernovae per bin based on the transient rate (self.r_transient) and survey solid angle.
Samples redshifts uniformly within each bin according to the estimated counts.
Calculates luminosity distances for the sampled redshifts.
Samples and clips absolute magnitudes, then computes apparent magnitudes.
Filters the sample to include only supernovae with apparent magnitudes ≤ self.mag_cutoff.
Fits a Gaussian KDE to the resulting observed redshifts, storing the KDE in self.bestFit and the observed redshifts in self.observed_redshifts.

Returns:: The distribution is stored internally.
Return type:: None

pdf(z)[source]

Return the PDF (KDE) based on observed redshifts. Handles 1D and 2D arrays.

Parameters:: z (np.ndarray) – List of input redshifts.
Returns:: flat_pdf
Return type:: the pdf from a kde fit to the input redshifts.

rvs(size=None)[source]

Generate random variables from the empirical distribution.

Parameters:: size (int) – Number of samples to draw from the distribution
Returns:: samples – The redshift samples from the distribution.
Return type:: np.ndarray

plot()[source]: Plots the empirical redshift distribution.

class SnRateAbsmag(a, b, **kwargs)[source]

Bases: scipy.stats.rv_continuous

A host-galaxy absolute magnitude likelihood distribution,: where supernova rate scales as ~0.1*L_host in units of 10^10 Lsol. Based on Li, Chornock et al. 2011.

Parameters:

a (float) – The minimum absolute magnitude of a host galaxy.
b (float) – The maximum absolute magnitude of a host galaxy.

normalization[source]

The calculated normalization constant for the distribution.

Type:: float

_calculate_normalization[source]

Calculates the normalization constant for the distribution.

Type:: function

normalization[source]

_calculate_normalization(a, b)[source]

Calculates the normalization constant for the distribution.

Parameters:

a (float) – The minimum absolute magnitude of a host galaxy.
b (float) – The maximum absolute magnitude of a host galaxy.

Returns:

result – The calculated normalization constant for the distribution.

Return type:

float

_unnormalized_pdf(abs_mag_samples)[source]

Calculates the unnormalized PDF from the supernova rate.

Parameters:: abs_mag_samples (np.ndarray) – Array of galaxy absolute magnitudes.
Returns:: snrate – Supernovae rate for corresponding galaxies.
Return type:: np.ndarray

_pdf(m_abs_samples)[source]

The PDF of galaxies with m_abs_samples, after normalization.

Parameters:: m_abs_samples (np.ndarray) – Absolute magnitudes of galaxies.
Returns:: normalized_pdf – Normalized PDF values for m_abs_samples.
Return type:: np.ndarray

panstarrs_cone(metadata, ra, dec, radius, table='stack', release='dr2', format='csv', columns=None, baseurl='https://catalogs.mast.stsci.edu/api/v0.1/panstarrs', verbose=False, **kw)[source]

Conducts a cone search of the Pan-STARRS 3PI catalog tables.

Parameters:

metadata (dict) – Dictionary of astropy tables.
ra (float) – Right ascension of search center, in decimal degrees.
dec (float) – Declination of search center, in decimal degrees.
radius (float) – Radius of search cone, in degrees.
table (str) – The table to query.
release (str) – The pan-starrs data release. Can be “dr1” or “dr2”.
format (str) – The format for the retrieved data.
columns (np.ndarray) – A list of columns to retrieve from ‘table’.
baseurl (str) – The api endpoint to query.
verbose (boolean) – If True, prints details about the query.
**kw (dict) – Any additional search parameters.

Returns:

result – String containing retrieved data (empty if none found).

Return type:

str

panstarrs_search(metadata, table='mean', release='dr1', format='csv', columns=None, baseurl='https://catalogs.mast.stsci.edu/api/v0.1/panstarrs', verbose=False, **kw)[source]

Queries the Pan-STARRS catalog API.

Parameters:

metadata (dictionary) – A dictionary containing the tables to query.
table (str) – The table to query.
release (str) – The pan-starrs data release. Can be “dr1” or “dr2”.
format (str) – The format for the retrieved data.
columns (np.ndarray) – A list of columns to retrieve from ‘table’.
baseurl (str) – The api endpoint to query.
verbose (boolean) – If True, prints details about the query.
**kw (dict) – Any additional search parameters.

Returns:

result – String containing retrieved data (empty if none found).

Return type:

str

build_glade_candidates(transient, glade_catalog, cosmo, logger, search_rad=None, n_samples=1000, cat_cols=False, calc_host_props=['redshift', 'absmag', 'offset'], shred_cut=False, release=None)[source]

Populates a GalaxyCatalog object with candidates from a cone search of the: GLADE catalog (See https://glade.elte.hu/ for details). Reported luminosity distances have been converted to redshifts with a 5% uncertainty floor for faster processing.

Parameters:

transient (Transient) – Custom object for queried transient containing name, position, and positional uncertainty.
glade_catalog (pandas.DataFrame) – The locally-packaged GLADE catalog (to avoid querying).
search_rad (astropy.units.Angle) – Radius for cone search.
cosmo (astropy.cosmology) – Assumed cosmology for conversions.
n_samples (int) – Number of samples for Monte Carlo association.
cat_cols (boolean) – If True, concatenates catalog fields for best host to final catalog.
shred_cut (boolean) – If True, removes likely source shreds associated with the same candidate galaxy.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).

Returns:

galaxies (structured numpy array) – Array of properties for candidate sources needed for host association.
cat_col_fields (list) – List of columns retrieved from the galaxy catalog (rather than calculated internally).

build_skymapper_candidates(transient, cosmo, logger, glade_catalog=None, search_rad=None, n_samples=1000, calc_host_props=['redshift', 'absmag', 'offset'], cat_cols=False, shred_cut=False, release='dr4')[source]

Populates a GalaxyCatalog object with candidates from a cone search of the: SkyMapper catalog (See https://skymapper.anu.edu.au/about-skymapper/ for details).

Parameters:

transient (str) – Transient object with name, position, and positional uncertainties defined.
glade_catalog (pandas.DataFrame) – The locally-packaged GLADE catalog (to avoid querying).
search_rad (astropy Angle) – Radius for cone search.
cosmo (astropy cosmology) – Assumed cosmology for conversions.
n_samples (int) – Number of samples for Monte Carlo association.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
cat_cols (boolean) – If True, concatenates catalog fields for best host to final catalog.
shred_cut (boolean) – If True, removes likely source shreds associated with the same candidate galaxy.
release (str) – Can be ‘dr1’, ‘dr2’, or ‘dr4’.

Returns:

galaxies (structured numpy array) – Array of properties for candidate sources needed for host association.
cat_col_fields (list) – List of columns retrieved from the galaxy catalog (rather than calculated internally).

build_decals_candidates(transient, cosmo, logger, search_rad=None, n_samples=1000, calc_host_props=['redshift', 'absmag', 'offset'], cat_cols=False, shred_cut=False, release='dr9')[source]

Populates a GalaxyCatalog object with candidates from a cone search of the: DECaLS catalog (See https://www.legacysurvey.org/decamls/ for details).

Parameters:

transient (str) – Transient object with name, position, and positional uncertainties defined.
glade_catalog (pandas.DataFrame) – The locally-packaged GLADE catalog (to avoid querying).
search_rad (astropy Angle) – Radius for cone search.
cosmo (astropy cosmology) – Assumed cosmology for conversions.
n_samples (int) – Number of samples for Monte Carlo association.
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
cat_cols (boolean) – If True, concatenates catalog fields for best host to final catalog.
shred_cut (boolean) – If True, removes likely source shreds associated with the same candidate galaxy.
release (str) – Can be ‘dr9’ or ‘dr10’.

Returns:

galaxies (structured numpy array) – Array of properties for candidate sources needed for host association.
cat_col_fields (list) – List of columns retrieved from the galaxy catalog (rather than calculated internally).

build_rubin_candidates(transient, cosmo, logger, glade_catalog=None, search_rad=None, n_samples=1000, calc_host_props=['redshift', 'absmag', 'offset'], cat_cols=False, release='dp1', shred_cut=False, dust_path=DEFAULT_DUST_PATH)[source]

Populates a GalaxyCatalog object with candidates from a cone search of the: panstarrs catalog (See https://outerspace.stsci.edu/display/PANSTARRS/ for details).

Parameters:

transient (Transient) – Custom Transient object with name, position, and positional uncertainties defined.
transient_pos (astropy.coord.SkyCoord) – Position of transient to associate.
cosmo (astropy cosmology) – Assumed cosmology for conversions.
logger (logging.Logger) – Logger instance for messages to console or output file.
search_rad (astropy Angle) – Radius for cone search.
n_samples (int) – Number of samples for Monte Carlo association.
glade_catalog (pandas.DataFrame) – The locally-packaged GLADE catalog (to avoid querying).
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
cat_cols (boolean) – If True, concatenates catalog fields for best host to final catalog.
shred_cut (boolean) – If True, removes likely source shreds associated with the same candidate galaxy.
dust_path (str) – Path to the dust map data files.

Returns:

galaxies (structured numpy array) – Array of properties for candidate sources needed for host association.
cat_col_fields (list) – List of columns retrieved from the galaxy catalog (rather than calculated internally).

build_panstarrs_candidates(transient, cosmo, logger, glade_catalog=None, search_rad=None, n_samples=1000, calc_host_props=['redshift', 'absmag', 'offset'], cat_cols=False, release='dr2', shred_cut=True, dust_path=DEFAULT_DUST_PATH)[source]

Populates a GalaxyCatalog object with candidates from a cone search of the: panstarrs catalog (See https://outerspace.stsci.edu/display/PANSTARRS/ for details).

Parameters:

transient (Transient) – Custom Transient object with name, position, and positional uncertainties defined.
transient_pos (astropy.coord.SkyCoord) – Position of transient to associate.
cosmo (astropy cosmology) – Assumed cosmology for conversions.
logger (logging.Logger) – Logger instance for messages to console or output file.
search_rad (astropy Angle) – Radius for cone search.
n_samples (int) – Number of samples for Monte Carlo association.
glade_catalog (pandas.DataFrame) – The locally-packaged GLADE catalog (to avoid querying).
calc_host_props (list) – Properties to calculate internally for each host (‘offset’, ‘redshift’, ‘absmag’).
cat_cols (boolean) – If True, concatenates catalog fields for best host to final catalog.
shred_cut (boolean) – If True, removes likely source shreds associated with the same candidate galaxy.
dust_path (str) – Path to the dust map data files.

Returns:

galaxies (structured numpy array) – Array of properties for candidate sources needed for host association.
cat_col_fields (list) – List of columns retrieved from the galaxy catalog (rather than calculated internally).

calc_dlr(transient_pos_samples, galaxies_pos, a, a_std, a_over_b, a_over_b_std, phi, phi_std, n_samples=1000)[source]

Calculates the directional light radius (DLR) between candidate host and transient, following the: general framework in Gupta et al. (2016).

Parameters:

transient_pos_samples (array of astropy.coord.SkyCoord objects) – Array of transient positions with positional uncertainties
galaxies_pos (array of astropy.coord.SkyCoord objects) – Positions of candidate host galaxies.
a (np.ndarray) – Semi-major axes of candidates, in arcsec.
a_std (np.ndarray) – Error in semi-major axes of candidates, in arcsec.
a_over_b (np.ndarray) – Axis ratio (major/minor) of candidates.
a_over_b_std (np.ndarray) – Error in axis ratio.
phi (np.ndarray) – Position angles of sources, in radians.
phi_std (np.ndarray) – Error in position angle.
n_samples (type) – Number of DLR samples to draw for Monte Carlo association.

Returns:

dlr – 2D array of DLR samples of dimensionality (n_galaxies, n_samples).

Return type:

np.ndarray

find_shreds(objids, coords, a, a_std, a_over_b, a_over_b_std, phi, phi_std, appmag, logger)[source]

Finds and removes potentially shredded sources. Drops the dimmer source in any pair where the separation is less than either galaxy’s DLR (sep/DLR < 1). Now vectorized!

Parameters:

objids (np.ndarray) – Catalog IDs of sources.
coords (np.ndarray) – Astropy SkyCoord objects.
a (np.ndarray) – Semi-major axes (arcsec).
a_std (np.ndarray) – Errors in semi-major axes (arcsec).
a_over_b (np.ndarray) – Axis ratios (major/minor).
a_over_b_std (np.ndarray) – Errors in axis ratio.
phi (np.ndarray) – Position angles (radians).
phi_std (np.ndarray) – Errors in position angle.
appmag (np.ndarray) – Apparent magnitude, in r.

Returns:

dropidxs – Indices of sources flagged as shreds.

Return type:

np.ndarray

is_service_available(url, timeout=5)[source]

get_ned_specz(ra, dec, search_radius=1.0, logger=None)[source]

Query NED for spectroscopic redshift at given coordinates.

This function queries the NASA/IPAC Extragalactic Database (NED) for objects near the specified coordinates and retrieves spectroscopic redshift information if available. It filters out photometric redshifts and attempts to get detailed redshift measurements with uncertainties.

Parameters:

ra (float) – Right ascension in degrees.
dec (float) – Declination in degrees.
search_radius (float, optional) – Search radius in arcseconds. Default is 1.0 arcsec.
logger (logging.Logger, optional) – Logger instance for messages. If None, no logging is performed.

Returns:

z_spec (float or None) – Spectroscopic redshift if found, otherwise None.
z_spec_err (float or None) – Uncertainty in spectroscopic redshift if found, otherwise None.
has_specz (bool) – True if a spectroscopic redshift was found, False otherwise.

Notes

The function uses NED’s ‘Redshift Flag’ to distinguish between spectroscopic and photometric redshifts. It rejects objects flagged as ‘PHOT’ and accepts those with empty flags (typically spectroscopic) or ‘PUN’ (published, uncorrected).

When detailed redshift tables are available, the function filters out measurements marked with “Uncertain origin” and converts velocities to redshifts using z = v/c.

If uncertainty information is not available, the function estimates a conservative uncertainty of either 50 km/s (converted to redshift) or 5% of the redshift value.

Examples

>>> z, z_err, has_z = get_ned_specz(69.438805, -20.507317, search_radius=1.0)
>>> if has_z:
...     print(f"Spectroscopic redshift: {z:.4f} ± {z_err:.4f}")