master2reg

master2reg - Convert Master Table to DS9 Region File

Space Telescope Science Institute

Synopsis

Convert a master table file containing source positions and region definitions into a DS9-compatible region file for visualization and analysis.

Command Line Usage

master2reg.py [-h] [-r radius] [-color color] masterfile [regionfile]

Required Arguments:

masterfile

Input master table file (ASCII or FITS format) containing source definitions with columns for position and region geometry.

Optional Arguments:

regionfile

Output DS9 region file name. If not specified, defaults to <masterfile>.reg.

-h

Display this help message and exit.

-r radius

Default radius in arcseconds for circular regions when size is not specified in the input file. Default is 3.0 arcsec.

-color color

Color for region outlines (e.g., red, green, blue, cyan, magenta). Default is red.

Description

This program reads a master table and converts it to a DS9 region file. The master table can be in various formats:

Full format (with region geometry):

The table should contain the following columns:

  • Source_name : str - Source identifier

  • RA : float - Right Ascension in degrees

  • Dec : float - Declination in degrees

  • RegType : str - Region type (‘circle’, ‘ellipse’, ‘box’, or ‘annulus’)

  • Major : float - Major axis or radius in arcseconds

  • Minor : float - Minor axis in arcseconds (0 for circles)

  • Theta : float - Position angle in degrees

Minimal format (positions only):

If only Source_name, RA, and Dec are provided, circular regions with the default radius (-r option) will be created.

RA/Dec only format:

If only RA and Dec columns are present, source names will be auto-generated.

Output

A DS9 region file in FK5 coordinate format with:

  • Region shapes (circle, ellipse, box, annulus)

  • Source labels

  • Color specifications

Notes

Supported region types:

  • circle - Circular aperture (Major = radius)

  • ellipse - Elliptical aperture (Major, Minor = semi-axes, Theta = angle)

  • box - Rectangular region (Major, Minor = dimensions, Theta = angle)

  • annulus - Circular annulus (Major = outer radius, Minor = inner radius)

History

090109 ksl

Initial coding

111216 ksl

Modified to produce region file from first 3 columns if geometry columns cannot be interpreted

121212 ksl

Added -color option

130830 ksl

Added -r option for default radius

150220 ksl

Modified to use astropy for reading master files

251210 ksl

Added support for FITS format input and Color column handling

Attributes

argc

Functions

doit(argv)

Parse command line and execute master to region file conversion.

radec2deg(ra, dec)

Convert RA/Dec strings to decimal degrees.

read_masterfile(filename[, xtype, xmajor, xminor, xtheta])

Read a master table file and standardize column names.

write_regionfile(regionfile, records[, source, type, ...])

Write a DS9 region file from a master table.

Module Contents

master2reg.argc
master2reg.doit(argv)

Parse command line and execute master to region file conversion.

Parameters

argvlist of str

Command line arguments (typically sys.argv).

Returns

None

Writes region file to disk.

Notes

Main driver function that:

  1. Parses command line options (-h, -r, -color)

  2. Reads the master table file

  3. Writes the DS9 region file

master2reg.radec2deg(ra, dec)

Convert RA/Dec strings to decimal degrees.

Handles both sexagesimal (HH:MM:SS, DD:MM:SS) and decimal degree formats.

Parameters

rastr or float

Right Ascension as ‘HH:MM:SS’ string or decimal degrees.

decstr or float

Declination as ‘DD:MM:SS’ string or decimal degrees.

Returns

tuple of (float, float)

RA and Dec in decimal degrees.

Notes

If inputs are already floats, they are returned unchanged. RA in sexagesimal format is assumed to be in hours and is converted to degrees (multiplied by 15).

master2reg.read_masterfile(filename, xtype='circle', xmajor=3, xminor=3, xtheta=0.0)

Read a master table file and standardize column names.

Reads ASCII or FITS format master tables and ensures all required columns are present, adding defaults where necessary.

Parameters

filenamestr

Path to the master table file (ASCII or FITS format).

xtypestr, optional

Default region type if not specified in file. Default is ‘circle’.

xmajorfloat, optional

Default major axis/radius in arcseconds. Default is 3.

xminorfloat, optional

Default minor axis in arcseconds. Default is 3.

xthetafloat, optional

Default position angle in degrees. Default is 0.0.

Returns

tuple of (astropy.table.Table, str)

Standardized table with columns (Source_name, RA, Dec, RegType, Major, Minor, Theta, Color) and the coordinate type string.

Notes

The function handles various input formats:

  • Tables with full column headers

  • Generic tables with columns named col1, col2, etc.

  • Tables with only RA/Dec (source names auto-generated)

  • Tables with only positions and names (default geometry applied)

master2reg.write_regionfile(regionfile, records, source='unknown', type='unknown', color='red')

Write a DS9 region file from a master table.

Creates a DS9-compatible region file with circles, ellipses, boxes, or annuli based on the input table records.

Parameters

regionfilestr

Output filename for the DS9 region file.

recordsastropy.table.Table

Table containing region definitions with columns: Source_name, RA, Dec, RegType, Major, Minor, Theta, Color.

sourcestr, optional

Source identifier for header comment. Default is ‘unknown’.

typestr, optional

Coordinate type (‘fk5’, ‘physical’, ‘image’). Default is ‘unknown’ which outputs as ‘fk5’.

colorstr, optional

Default color for regions. Default is ‘red’.

Returns

None

Writes region file to disk.

Notes

If different rows have different colors in the Color column, each region will be written with its individual color. Otherwise, the default color is used for all regions.