HEADAS help file for mxregion

NAME

mxregion

USAGE

mxregion ra dec src_radius bkg_outer_radius bkg_inner_radius rootname catalog

DESCRIPTION

Create DS9 source and background region files for a given RA and DEC. The source region is defined by a circle around the given RA and DEC, and background can be defined as:

an annulus around the source region;
a circular region offset from the source with no overlap;
no background region

Unless set otherwise, the task will also read a standard reference catalog of 269 known bright sources detectable with MAXI and any sources in that catalog will be excluded from the region files. The user can also supplement, or replace, this reference catalog with their own.

PARAMETERS

ra [real] (J2000; degrees): Right ascension of the source.
dec [real] (J2000; degrees): Declination of the source.
src_radius [real] (degrees): Radius around the source sky location to include in the source region.
(bkg_ra = -1.0) [real] (degrees): Right ascension of the center of the background region. Set to a negative value (default) to use a shared center for the source and background. Valid positive values are 0 - 360 degrees in J2000 coordinates.
(bkg_dec = ) [real] (degrees): Declination of the center of the background region. Ignored if the background is centered on the source (i.e. 'bkg_ra' is less than zero) or if no background is requested (i.e. 'bkg_outer_radius' is less than zero). Valid values are -90 - 90 degrees in J2000 coordinates.
(bkg_outer_radius = 3.0) [real] (degrees): Outer radius of the background region. Set to a negative value to skip creating a background region file. Default is 3.0 degrees.
(bkg_inner_radius = 1.7) [real] (degrees): Inner radius of the background region, which is excluded to define an annulus. If the background region is centered on the source, this should be at least 0.1 degree larger than source radius. Set to 0 to skip (i.e. background region is a circle, not an annulus). Default is 1.7 degrees.
rootname [string]: Prefix for output region files.
(catalog = "REFDATA" [filename]: A bright source catalog in FITS format. Set to "NONE" to skip. Set to "REFDATA" (default) to use the default MAXI bright source catalog file included with HEASoft. Set to a filename to use a different catalog of bright sources.
(confusion_radius = 1.0) [real] (degrees): Radius around any bright sources in the catalog(s) to exclude. Ignored if no catalogs are desired. Default is 1.0 degrees.
(reject_radius = 0.7) [real] (degrees): Radius around input source location within which any known bright source is NOT excluded. If there is a neighboring known bright source within this radius, it is presumed not possible for MAXI to resolve them as separate objects, and the region file will not attempt to exclude it. This also prevents confusion possible from inexact matches between the catalog and the input RA and Dec setting. Default is 0.7 degrees.
(usercat = "NONE") [filename]: Set to "NONE" to ignore (default). A user supplied catalog of sources. This should be a text file with comma separated values, one source per line, in either of the following formats: RA, DEC; or Name, RA, DEC. Sky coordinates must be in J2000 (FK5) using units of decimal degrees. This file can supplement the catalog file or replace it: in the latter case, by setting the bright source catalog to "NONE".
(clobber = NO) [boolean]: If region file already exists, then "clobber = yes" will overwrite it. Default is "no".
(chatter = 1) [integer]: Sets the amount of output from the code. Values range from 0 (little to no output) to 3 (verbose: provides considerable output). NOTE: This feature is not implemented in the current version of this task.
(debug = no) [boolean]: If set to "yes", the code will provide detailed logging of variables and settings as the code runs in considerable detail. This can be useful when debugging features in the code or deciphering unexpected error conditions. NOTE: This feature is not implimented in the current version of this task.
(mode = ql) [string ql|hl|q]: Mode to query the parameter file. Acceptable values include: "ql" (query and learn/remember) (default), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

Create a source region with radius 1.6 degrees and a background region around the source region with inner radius 2.0 degrees and outer radius 3.0 degrees. Do not check for known MAXI bright sources.
```
mxregion ra=260.0 dec=-26.5 src_radius=1.6 bkg_outer_radius=3.0 bkg_inner_radius=2.0 \
  rootname=test catalog=NONE
```

Create a source region with radius 2.0 degrees around RA 120.0 Dec 24.0 and exclude bright sources using a radis of 1.0 degrees around these sources where they overlap with the source region. Use the catalog file "bright_sources.fits" to define the known sources. Do not create a background region file.
```
mxregion 120.0 24.0 2.0 0.0 0.0 test2 bright_sources.fits.fits 1.0
```

Create a source region with radius 3.0 degrees around RA 6.4 Dec 66.0, and a background region located away from the source region centered on RA 42.0 Dec 71.0 with radius 3.0 degrees. Exclude known sources with a radius of 0.5 degrees. Define the position of known sources with an ASCII text file "exclude_srcs.txt" instead of the built-in MAXI bright source catalog.
```
mxregion ra=6.4 dec=66.0 src_radius=3.0 bkg_ra=42.0 bkg_dec=71.0 bkg_outer_radius=3.0 bkg_inner_radius=0.0 \
  rootname=test3 catalog=NONE usercat=exclude_srcs.txt confusion_radius=0.5
```

LAST MODIFIED

July 2025 (mxregion v 0.101)