NeSDaC

iros, extract X-ray source list form detector image

NAME

SYNOPSIS

• iros
• iros -p [options] di irs
• iros -q

The program can be started with no arguments at all, in which case the parameter values are taken from the parameterfile.
Alternatively, values can be passed via the commandline, the required items as command arguments, the optional ones as valued switches.

The last form (iros -q) creates the parameterfile in $PFILES.

The table lists all the parameters used by iros, the second column lists the paramater key names used in the parameterfile, the first column gives the corresponding switch letter.

iros parameters

switch	key	value	IO	description
	expfile	string	i	input di, detector image file.
	resfile	string	o	output, reduced sky and det image, sourcelist .res
a	islfile	string	i	initial list, accepted as genuine sources, catalog format.
A	xysilst	string	i	extra initial sources, listing optional name, position and spectral index: name,X,Y,si.... , name is optional, if present has to start with a letter.
b	attfile	string	i	attitude data file, overrides default path/name
c	cmode	int	i	correlation mode, correlate
d	decorum	string	i	set (1), to restore subtracted Xray source(s) pixels in the output skyimage.
e	chnlset	string	i	for TSPZ(TeleSPaZio)-format detectorimage input only, set the channel (energy) selectionwindow. the header of these detector images contains no such information, it is needed in the psf computation..
f	ofits	int	i	by default, if inputimage is in TSPZ format, output will be too, set to force force FITS output.
h	atmhght	real	i	earth atmosphere thickness (km), used in source visibility (earth occultation) determination.
j	skyrsltn	ipair	i	skypixels can be different sources if they are separated by at least this many pixels.
k	catfile	string	i	overrides default X-ray source catalog (environment).
m	iros	int	i	1 suppress use of X-ray source catalogs. 2 interactive operation, subtract detected sources one by one, prompting the user for position, flux and pointspread function modification. 4 use all detected sources in second and next iterations, whether this source could be identified or not. 8 accept any pixelconfiguartion as valid source. 16 suppres use of source list found as (FITS)extension in input detector image (usually simulated data). 32 treat detector as having no pointspread function, all pixels from a reconstructed x-ray source in the celestial image are treated separately. 64 subtract only sources/pixels when found in catalog.
n	niros	int	i	absolute limit on number of iros iterations, default is 15, but if niros is not assigned iros will also stop at an increase in the detecor rms (root-mean-square).
p	p_filtr	area	i	include section, x0-x1:y0-y1[,x2-x3,y2-y3 .... ], from input detectorimage.
px	p_filtr	area	i	As above, but exclude section.
r	radius	real	i	maximum radial distance (pixels) between a candidate- and a catalog X-ray source for identification.
s	srclim	int	i	limit number of sources considered to subtract.
t	thrshld	real	i	stop criterium, threshold, stop search for more sources, if the combined detected sources account for more than a fraction 'r' of the total counts on the detector.
V	voigt	rpair	i	voigt function parameters (pointspreadfunction model) , DO NOT USE - not calibrated.
x	pointing	string	i	override any pointing from input (.exp) file, format: ra,dec.na, in decimal degrees.
y	inlcrcn	int	i	set to 1 to use integral detector non-linearity data.
Z	gssnfctr	rpair	i	general multiplication factors, detector gaussian response, better not use.
-	xchisq	int	i	NOT used in this releasedet. fit control,
I	insfile	string	i	overrides the IDF name in expfile.
p, L, i				StageII global switches

DESCRIPTION

• di0, the input detector image.
• ci0 <- correlate (mask, di0),
  the initial sky image, a balanced, weighted cross correlation of the wfc-mask and the detector image. Also compute err0, the poisson error, ie. the root of the total number of events used in the computation of ci0, in each skypixel
• sl0 <- analyse (ci0),
  the initial list of sources. the method used is simple, create a list of the 100 or so most significant pixels (using err0) in ci0. The position of these potential sources is then checked against a X-ray sources catalog, only sources that can thus be identified are retained, the rest of the list is discarded. The sources are then fitted to their theoretical point spread function, to determine the position and the total flux.

  ---

  This is one of uses of catalog data in iros, verification of a potential source, the cataloged sourceposition itself is NOT used in any other way. The second use of the catalog is in the supply of spectral information on a source.

  ---

  
  • di1 <- simulate (wfc, sl0),
    simulate a detector image for the source list sl0.
  • ci1 <- correlate (mask, di1),
    a next generation sky image, where most of the flux of detected sources and the related masknoise, is removed.
    Note: the err0 data is not recomputed.
  • sl1 <- analyse (ci1 + sl0),
    the sources, subtracted from the previous skyimage, are added (according to the psf used in the simulation) to the reduced ci1, restoring the flux, but not the associated masknoise. any residual flux left in ci1, because of an incorrect flux or position adds to the restored psf, at this stage new pixels will qualify for the potential source status.
    we can now iterate, until the detector rms (root mean square all detector pixels) no longer decreases.
    sl0 <- sl1 and goto

d[1]= S₁[1]*f₁ + S₂[1]*f₂ + ..... S_n[1]*f_n + S_b[1]*f_b.
d[2]= S₁[2]*f₁ + S₂[2]*f₂ + ..... S_n[2]*f_n + S_b[2]*f_b.

. . . . .

. . . . .

where

• S_i[k] simulated, normalised contribution from source f_i to the contents of detector pixel k. S_i[k] can very well be 0, detector pixel [k] may not at all be illuminated by the source f_i, otherwise a closed mask pixel possibly obstructs the path from that source to S_i[k].
  (as the detector has a 2 dimensions, with k=j*N+i, we mean pixel [i,j]),
• S_b[k] simulated, normalised contribution from the background (used model adds uniform sky and detector background) b to the contents of detector pixel k.
• f_i the strength (flux) of source i (f_b background).
• d[k] measured value of detectorpixel witht index k.

• the state, open vs closed, of the maskpixel on the path from source f_i to the detectorpixel d[k].
• deviations from the nominal detecorpixel grid, spatial non linearities.
• the detector response (point spread function), as a function of the energy range considered and (to some extent if known) spectral characteristics of source f_i.

d = S f

f = (S^T S)^-1 S^Td

• an, hopefully empty, sky image. All known, ie. cataloged sources, that made the top of the siginificance list somewhere in the proces, are removed (ie. not all sources in the FOV and in the catalog have to be subtracted, weak sources, never more significant than 'noise' peaks, are not). Any, readily visible, 'sources' in this sky image may be new or transient sources, not found in the catalog.
  A consequence of this use of the catalog is that when the pointing data in the input .exp file is wrong, usually no sources whatsoever are detected, even when the skyimage is full of sources to the naked eye.
• a cleaned, residual, detector image.
• a list of all detected sources, their position and flux.

EXAMPLE

iros -p2 w817w1 w817w1

===============================================================================
 iros[99.99]                               Fri Jul  4 13:12:53 1997  page    1
   ------------------------------------------------------------
[2]src_readcatalog: "/ruurq2/st2/lib/catalogs/XRAYSOURCESCAT", 7 potential sources in FOV
   
   "OP817(wfc1)"   Fri Aug 23 11:42:00 1996 (UT)
   "ENP + WFC gal.ce"  @ [05h41m05.304s +29d04m08.195s (na: 178.754)]
   
   iros: plane 1 (channels 2 - 18)
[1]iros_loop<00>: detector sum=   497894.0 (100.0%).  rms= 1.960604e+00
[1]src_showsl: iros_reduce: subtracting  (1).
 + seqn        name       ra     dec      -x-     -y-    -flux- signif
 + < 1>     X0531+219   83.614  22.078   86.56   17.14    0.472 1068.2 ([341,271]3x2)
[1]iros_loop<01>: detector sum=   246505.4 ( 49.5%).  rms= 1.275229e+00 ( 1 src subtracted)
[1]src_showsl: iros_reduce: subtracting  (1).
 + seqn        name       ra     dec      -x-     -y-    -flux- signif
 + < 1>     X0531+219   83.616  22.077   86.58   17.12    0.527 1220.6 ([341,271]3x2)
[1]iros_loop<02>: detector sum=   216883.4 ( 43.6%).  rms= 1.240710e+00 ( 1 src subtracted)
[1]src_showsl: iros_reduce: subtracting  (1).
 + seqn        name       ra     dec      -x-     -y-    -flux- signif
 + < 1>     X0531+219   83.616  22.076   86.59   17.11    0.532 1252.0 ([341,271]3x2)
[1]iros_loop<03>: detector sum=   214217.8 ( 43.0%).  rms= 1.238627e+00 ( 1 src subtracted)
[1]src_showsl: iros_reduce: subtracting  (1).
 + seqn        name       ra     dec      -x-     -y-    -flux- signif
 + < 1>     X0531+219   83.616  22.076   86.59   17.11    0.532 1268.8 ([341,271]3x2)
[1]iros_loop<04>: detector sum=   214581.9 ( 43.1%).  rms= 1.239049e+00 ( 1 src subtracted)
[2]iros_solve final chisquare: 1.162030
   iros_loop: 4 iterations, final detector sum= -5003.5, -1.00%.  rms= 1.118583e+00
[1]src_showsl: iros: final sourcelist (2).
 + seqn        name       ra     dec      -x-     -y-    -flux- signif
 + < 1>     X0531+219   83.616  22.076   86.59   17.11    0.506 1252.0 ([341,271]3x2)
 + < 2>   :background:  85.272  29.069    0.00    0.00    1.298    0.0 ([  0,  0]0x0)
[1]evt_open: "/ruurq2/817/WOP817_0000w1att1.fits"[ATTITUDE], 1 of 1.
 +          time  50318.48730 - 50318.56047 (MJD)  [  6322.00 sec.]
[2]iros_effetime: X0531+219 : 2778.38 sec. (51.9%)
[2]iros_effetime: :background:: 2721.38 sec. (50.8%)

  No. Type     EXTNAME      BITPIX Dimensions(columns)      PCOUNT  GCOUNT
 
   0  PRIMARY                -32     510 510 2                   0    1
   1  IMAGE    rdi           -32     680 680                     0    1
   2  BINTABLE WFC_Sourcelis   8     1384(19) 2                  0    1

the PRIMARY image in the .res file is the so-called residual skyimage, the correlation of the reduced detector image and the mask, any sources showing up in this image were not identifyable, as there is no entry for these sources in the catalog.

the binary table extension WFC_Sourcelist (fstruct list only 13 char's in the name) harbours the list of all detected sources. the table has the following structure and a row for every detected source plus one for the background:

iros columns

name	type	description
ra	1D	right ascension, degrees. (J2000,FK5)
dec	1D	declination, degrees.
xtm	1D	exposure time, seconds, corrected for mean ltf and earth occultation.
cname	32A	sax-wfc canonical source name, X0000-000
tname	32A	trivial source name.
flux	32E	source flux estimate, cts/sec.cm2.
dflux	32E	error in source flux, cts/sec.cm2, 1 sigma level established in source - pointspread model fit.
x	32E	source offset from center, in skypixels.
dx	32E	error in above offset, in skypixels, 1 sigma level established in source - pointspread model fit.
y	32E	source offset from center, in skypixels.
dy	32E	error in above offset, in skypixels, 1 sigma level established in source - pointspread model fit.
sigma	32E	pure poisson error in source flux, square root of total number of events used in flux computation.
signif	32E	source significance, flux divided by above defined sigma.
chisq	32E	source - pointspread model fit, final chi square.
F	32E	"goodness of fit", chisq reduction in comparison to flat model.
type	1J	spectral type, copied from input catalog.
nh	1E	H column density, copied from input catalog.
index	1E	spectral index, copied from input catalog.
spare	1J

though it does look promising, the flux and pixel position related columns have 32 entries, suggesting full energy resolution in all 32 channels, this is NOT automatically the case. In the current iros revision, sources fluxes are determined in the same energy bands that were selected in the input .exp file, there is no extrapolation to other channels.
Only the first m positions in the flux .. F columns are filled, when the input file has m detector images. So. if you want full energy resolution, you must first use cdi to produce a .exp file with 31 detector images, one for each channel. (channel 0 does not occur in the WFC event data.)
Note: The amount of memory needed in cdi is then quite large, for the images only ca. 31*680²*4 = 60 Mb, greater problems loom in iros, this program has, in this version, still some memory leaks, it is likely to crash eventually. In all, its better to break up the problem in a few smaller steps.