Run Module

This doc describes the run module which provides a high-level interface for running PATH analysis on a single transient given an input dictionary of parameters and a catalog of candidate host galaxies.

Overview

The run module provides three main functions:

  • run_on_dict(): Execute PATH analysis given configuration and catalog

  • set_anly_sizes(): Compute appropriate analysis sizes from localization

  • build_idict(): Convenience function to construct input dictionaries

This module is designed to be self-contained within astropath, with no external dependencies beyond the standard astropath requirements.

Input Dictionary

The run_on_dict() function expects a dictionary with the following structure:

Required Keys

  • ra (float): Right ascension in degrees

  • dec (float): Declination in degrees

  • ssize (float): Radius for probing the survey in arcmin

  • ltype (str): Localization type ('eellipse' or 'healpix')

  • lparam (dict): Localization parameters (see below)

  • priors (dict): PATH prior configuration (see below)

  • max_box (float): Maximum box size for PATH analysis in arcsec

Localization Parameters (lparam)

For error ellipse (ltype='eellipse'):

lparam = {
    'a': 1.0,      # Semi-major axis in arcsec
    'b': 0.5,      # Semi-minor axis in arcsec
    'theta': 45.0  # Position angle in degrees, E from N
}

For HEALPix (ltype='healpix'):

lparam = {
    'healpix_data': healpix_array,    # HEALPix probability map
    'healpix_nside': 512,             # NSIDE parameter
    'healpix_coord': 'C',             # Coordinate system ('C' for celestial)
    'healpix_ordering': 'RING'        # Pixel ordering ('RING' or 'NESTED')
}

Prior Configuration (priors)

priors = {
    'P_O_method': 'inverse',  # Method for candidate prior ['inverse', 'identical', etc.]
    'PU': 0.1,                # Prior probability of unseen host (0 to 1)
    'scale': 0.5,             # Scale factor for offset prior
    'theta_PDF': 'exp',       # PDF for offset prior ['exp', 'core', 'uniform']
    'theta_max': 6.0,         # Maximum offset for prior
    'survey': 'Pan-STARRS'    # Optional: survey for automatic catalog query
}

The survey key is optional. If provided and no catalog is passed to run_on_dict(), the catalog will be queried automatically using the catalogs module. See Catalogs Module for details.

Candidate Catalog

The catalog must be an astropy.table.Table with the following required columns:

  • ra: Right ascension in degrees

  • dec: Declination in degrees

  • ang_size: Angular size (half-light radius) in arcsec

  • <mag_key>: Magnitude column (name specified by mag_key parameter)

Optional columns:

  • ID: Source identifier

  • z_phot_median, z_phot, etc.: Photometric redshift columns (will be propagated to output)

Basic Usage

Here is a complete example using the FRB example data:

import os
import pandas
from importlib.resources import files as resource_files
from astropy.table import Table
from astropy.coordinates import SkyCoord

from astropath import run

# Load candidates
cand_file = os.path.join(str(resource_files('astropath').joinpath('data')),
                         'frb_example', 'frb180924_candidates.csv')
candidates_df = pandas.read_csv(cand_file, index_col=0)

# Convert to astropy Table
catalog = Table()
catalog['ra'] = candidates_df.ra.values
catalog['dec'] = candidates_df.dec.values
catalog['ang_size'] = candidates_df.half_light.values
catalog['mag'] = candidates_df.VLT_FORS2_g.values
catalog['ID'] = candidates_df.index.values

# FRB coordinates
frb_coord = SkyCoord('21h44m25.255s -40d54m00.10s', frame='icrs')

# Build input dictionary
idict = run.build_idict(
    ra=frb_coord.ra.deg,
    dec=frb_coord.dec.deg,
    ltype='eellipse',
    lparam={'a': 0.1, 'b': 0.1, 'theta': 0.},
    P_O_method='inverse',
    PU=0.,
    scale=1.,
    theta_PDF='exp',
    theta_max=6.
)

# Run PATH
result_candidates, P_Ux, Path, mag_key, cut_catalog, _ = run.run_on_dict(
    idict,
    verbose=True,
    catalog=catalog,
    mag_key='mag'
)

The output result_candidates is a pandas DataFrame sorted by posterior probability (P_Ox), with the most likely host first.

Using set_anly_sizes

If you need to compute appropriate analysis sizes from localization parameters, use set_anly_sizes():

from astropath import run

# For an error ellipse
lparam = {'a': 5.0, 'b': 2.0, 'theta': 30.}
ssize, max_box = run.set_anly_sizes('eellipse', lparam)

print(f"Survey search radius: {ssize} arcmin")
print(f"Analysis box size: {max_box} arcsec")

The function enforces a minimum search radius of 3 arcmin.

Using build_idict

The build_idict() function simplifies creating input dictionaries:

from astropath import run

# Minimal usage - sizes are auto-computed
idict = run.build_idict(
    ra=180.0,
    dec=-45.0,
    lparam={'a': 2.0, 'b': 1.0, 'theta': 0.}
)

# Full specification
idict = run.build_idict(
    ra=180.0,
    dec=-45.0,
    ltype='eellipse',
    lparam={'a': 2.0, 'b': 1.0, 'theta': 0.},
    P_O_method='inverse',
    PU=0.1,
    scale=0.5,
    theta_PDF='exp',
    theta_max=6.0,
    ssize=5.0,      # Override auto-computed value
    max_box=300.0   # Override auto-computed value
)

# With automatic catalog querying
idict = run.build_idict(
    ra=180.0,
    dec=-45.0,
    lparam={'a': 2.0, 'b': 1.0, 'theta': 0.},
    survey='Pan-STARRS'  # Will query Pan-STARRS when run_on_dict is called
)

Automatic Catalog Querying

Instead of providing a catalog manually, you can let run_on_dict() query public surveys automatically. This requires the frb package.

Specify a survey in the input dictionary:

from astropath import run

# Build idict with survey
idict = run.build_idict(
    ra=180.0,
    dec=45.0,
    lparam={'a': 5.0, 'b': 3.0, 'theta': 0.},
    survey='Pan-STARRS',
    PU=0.1
)

# Run PATH - catalog is queried automatically
result, P_Ux, Path, mag_key, cut_catalog, stars = run.run_on_dict(
    idict,
    verbose=True,
    skip_NGC=False,      # Include NGC/IC galaxies
    dust_correct=True    # Apply dust correction
)

print(f"Using {mag_key} magnitudes")
print(f"Rejected {len(stars) if stars else 0} stars")

Supported surveys:

  • 'Pan-STARRS': Pan-STARRS DR1 (dec > -30°)

  • 'DECaL': DECaLS DR10

See Catalogs Module for detailed information about catalog querying, cleaning, and star/galaxy separation.

Return Values

The run_on_dict() function returns a tuple of 6 values:

  1. result_candidates (pandas.DataFrame): Candidates with computed posteriors, sorted by P_Ox (descending). Contains columns:

    • ra, dec: Coordinates

    • ang_size: Angular size

    • mag: Magnitude

    • P_O: Prior probability

    • P_Ox: Posterior probability

    • P_Ux: Probability of unseen host (same for all rows)

    • p_xO: Likelihood p(x|O)

    • sep: Separation from localization center (arcsec)

    • ID: Source ID (if provided in input catalog)

  2. P_Ux (float): Probability that the true host is unseen

  3. Path (PATH): The PATH object used for analysis

  4. mag_key (str): The magnitude column key used

  5. cut_catalog (astropy.Table): Catalog cut to the analysis box

  6. stars (astropy.Table or None): Table of sources rejected as stars during catalog querying. Only populated when using automatic catalog querying via the survey parameter; otherwise None.

Example with Unseen Prior

When you expect the true host might not be in the catalog, set PU > 0:

idict = run.build_idict(
    ra=frb_coord.ra.deg,
    dec=frb_coord.dec.deg,
    lparam={'a': 5.0, 'b': 5.0, 'theta': 0.},
    PU=0.2,  # 20% prior probability of unseen host
)

result, P_Ux, Path, _, _, _ = run.run_on_dict(
    idict, catalog=catalog, mag_key='mag'
)

# Check probability conservation
total = result['P_Ox'].sum() + P_Ux
assert abs(total - 1.0) < 1e-5  # Should sum to 1

API Reference

Run PATH on a single FRB given a dictionary of inputs

This module provides a high-level interface for running PATH analysis.

astropath.run.build_idict(ra: float, dec: float, ltype: str = 'eellipse', lparam: dict = None, P_O_method: str = 'inverse', PU: float = 0.0, scale: float = 0.5, theta_PDF: str = 'exp', theta_max: float = 6.0, use_numba: bool = False, pmode: str = 'local', step_size_mode: str = 'relative', step_size: float = 0.05, survey: str = None, ssize: float = None, max_box: float = None)[source]

Build an input dictionary for run_on_dict().

This is a convenience function to construct the input dictionary with proper structure and optional auto-calculation of analysis sizes.

Parameters:

  • ra (float) – Right ascension in degrees

  • dec (float) – Declination in degrees

  • ltype (str) – Localization type. Default ‘eellipse’

  • lparam (dict) – Localization parameters. For ‘eellipse’: {‘a’: arcsec, ‘b’: arcsec, ‘theta’: deg} Required if ltype is ‘eellipse’.

  • P_O_method (str) – Method for candidate prior. Default ‘inverse’

  • PU (float) – Prior probability of unseen host. Default 0.0

  • scale (float) – Scale factor for offset prior. Default 0.5

  • theta_PDF (str) – PDF for offset prior. Default ‘exp’

  • theta_max (float) – Maximum offset for prior. Default 6.0

  • survey (str, optional) – Survey name for automatic catalog query. Supported: ‘Pan-STARRS’, ‘DECaL’. If None, catalog must be provided to run_on_dict().

  • use_numba (bool) – Use numba for calculations. Default False.

  • ssize (float) – Survey search radius in arcmin. If None, auto-computed.

  • max_box (float) – Maximum analysis box in arcsec. If None, auto-computed.

Returns:

Input dictionary suitable for run_on_dict()

Return type:

dict

Raises:

ValueError – If required parameters are missing

astropath.run.run_on_dict(idict: dict, verbose: bool = False, catalog: Table = None, mag_key: str = None, skip_NGC: bool = False, dust_correct: bool = True, use_local: bool = False, star_galaxy_sep: dict = None)[source]

Run PATH on a single FRB, given a dictionary of inputs.

The idict must have the following keys:

  • ra (float): Right ascension (deg)

  • dec (float): Declination (deg)

  • ssize (float): Radius for probing the survey (arcmin)

    This should usually be set with the set_anly_sizes() method

  • ltype (str): Localization type (e.g. ‘eellipse’, ‘healpix’)

  • lparam (dict): Localization parameters
    For ‘eellipse’: {‘a’: 0.2, ‘b’: 0.2, ‘theta’: 0.}

    • a, b are in units of arcsec

    • theta is in deg and is E from N

    For ‘healpix’: {‘healpix_data’: healpix_data, ‘healpix_nside’: nside,

    ‘healpix_coord’: coord_sys, ‘healpix_ordering’: ordering}

  • priors (dict): PATH priors
    e.g. {‘P_O_method’: ‘inverse’, ‘PU’: 0.5, ‘scale’: 0.5,

    ‘theta_PDF’: ‘exp’, ‘theta_max’: 6.}

    Can also include ‘survey’ key for automatic catalog query.

  • max_box (float): Maximum box size for PATH analysis (arcsec)

    This should usually be set with the set_anly_sizes() method

The dict needs to be simple enough to serialize with JSON for eellipse localization.

Parameters:

  • idict (dict) – Input dictionary with FRB and analysis parameters

  • verbose (bool, optional) – Print more diagnostic info. Defaults to False.

  • catalog (astropy.table.Table, optional) – Catalog of candidates. If None and idict[‘priors’][‘survey’] is set, will query the survey. Must have columns: ‘ra’, ‘dec’, ‘ang_size’, and the magnitude column specified by mag_key. Optionally includes ‘ID’ for source identification.

  • mag_key (str, optional) – Magnitude column key for the catalog. If None and catalog is queried, will be determined from the survey.

  • skip_NGC (bool, optional) – Skip adding NGC galaxies when querying. Defaults to False.

  • dust_correct (bool, optional) – Dust correct magnitudes when querying. Defaults to True.

  • star_galaxy_sep (dict, optional) – Star/galaxy separation parameters for catalog query.

  • use_local (bool, optional) – Use the local method for calculating posteriors. Defaults to False. If True, will use the local method for calculating posteriors. If False, will use the fixed method for calculating posteriors.

Returns:

6 items –

  • pandas.DataFrame: Candidates with computed posteriors

  • float: P(U|x) - probability of unseen host

  • PATH: PATH object used for analysis

  • str: mag_key used

  • astropy.Table: Catalog cut down to the analysis box

  • astropy.Table or None: Stars rejected from catalog (if queried), else None

Return type:

tuple

astropath.run.set_anly_sizes(ltype: str, lparam: dict)[source]

Set the analysis sizes for PATH.

This helper function computes appropriate survey search radius (ssize) and maximum analysis box size (max_box) based on localization parameters.

Note: These are guidelines recommended by the PATH developers. You should use your own judgement

Parameters:

  • ltype (str) – Type of localization [‘eellipse’, ‘healpix’]

  • lparam (dict) – Parameters for localization For ‘eellipse’: {‘a’: semi_major_arcsec, ‘b’: semi_minor_arcsec, ‘theta’: PA_deg} For ‘healpix’: Should compute from healpix resolution

Returns:

(ssize, max_box)

ssize (float): Radius of box to probe the survey (arcmin) max_box (float): Maximum box size for PATH analysis (arcsec)

Return type:

tuple

Raises:

ValueError – If ltype is not supported