JoinByPosition

JoinByPosition - Position-based table cross-matching

Space Telescope Science Institute

Synopsis

Cross-match two tables based on sky position (RA, Dec). By default, returns only matched rows. Use -all to preserve all rows from table1 (left join behavior).

Command Line Usage

JoinByPosition.py [-h] [-sep ARCSEC] [-all] [-out OUTFILE]
                  [-ra1 COL] [-dec1 COL] [-ra2 COL] [-dec2 COL]
                  table1 table2

Arguments

table1

Path to the primary table

table2

Path to the secondary table (matched rows joined to table1)

Options

-h

Print this help message and exit

-sep ARCSEC

Maximum separation in arcseconds for a valid match. Default: 1.0

-all

Return all rows from table1 (left join). Default: return only matches.

-out OUTFILE

Output filename. Default: table1_x_table2.fits

-ra1 COL

RA column name in table1. Default: RA

-dec1 COL

Dec column name in table1. Default: Dec

-ra2 COL

RA column name in table2. Default: RA

-dec2 COL

Dec column name in table2. Default: Dec

Description

Uses KDTree algorithm for efficient cross-matching. For each object in table1, finds the closest object in table2. If the separation is less than the maximum allowed, the table2 columns are joined.

The output table contains: - All columns from table1 (matched rows only, unless -all specified) - All columns from table2 (with ‘_2’ suffix if names conflict) - Sep: separation in arcseconds

Notes

History:

250115 ksl Coding begun, based on find_closest_objects from PhotCompare

Functions

do_join(table1, table2[, max_sep, keep_all, ra1, ...])	Cross-match two tables based on sky position.
do_one(table1_path, table2_path[, max_sep, keep_all, ...])	Cross-match two table files and write result.
read_table(filename)	Read a table from FITS or ASCII format.
steer(argv)	Parse command line arguments and execute cross-match.

Module Contents

JoinByPosition.do_join(table1, table2, max_sep=1.0, keep_all=False, ra1='RA', dec1='Dec', ra2='RA', dec2='Dec')

Cross-match two tables based on sky position.

Parameters

table1Table

Primary table

table2Table

Secondary table (matched rows joined)

max_sepfloat, optional

Maximum separation in arcseconds. Default: 1.0

keep_allbool, optional

If True, keep all rows from table1 (left join). If False, keep only matched rows. Default: False

ra1, dec1str, optional

Column names for RA/Dec in table1. Default: ‘RA’, ‘Dec’

ra2, dec2str, optional

Column names for RA/Dec in table2. Default: ‘RA’, ‘Dec’

Returns

Table

Joined table with Sep column added

JoinByPosition.do_one(table1_path, table2_path, max_sep=1.0, keep_all=False, outfile='', ra1='RA', dec1='Dec', ra2='RA', dec2='Dec')

Cross-match two table files and write result.

Parameters

table1_pathstr

Path to primary table

table2_pathstr

Path to secondary table

max_sepfloat, optional

Maximum separation in arcseconds. Default: 1.0

keep_allbool, optional

If True, keep all rows from table1. Default: False

outfilestr, optional

Output filename. If empty, auto-generated.

ra1, dec1, ra2, dec2str, optional

Column names for coordinates

Returns

Table

The joined table

JoinByPosition.read_table(filename)

Read a table from FITS or ASCII format.

Parameters

filenamestr

Path to table file

Returns

Table

Astropy Table object

Raises

IOError

If file does not exist or cannot be read

JoinByPosition.steer(argv)

Parse command line arguments and execute cross-match.

Parameters

argvlist

Command line arguments (sys.argv)