1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
|
.help substar May00 noao.digiphot.daophot
.ih
NAME
substar -- subtract photometry results from an image
.ih
USAGE
substar image photfile exfile psfimage subimage
.ih
PARAMETERS
.ls image
The list of images from which to subtract the scaled and shifted PSF.
.le
.ls photfile
The list of PSF fitted photometry files. There must be one photometry file
for every input image. If photfile is "default", "dir$default", or a directory
specification, SUBSTAR will look for a file called image.nst.? where the
question mark stands for the highest existing version number. Photfile is
usually the output of the NSTAR task but may also be the output of the PEAK
and ALLSTAR tasks or even the PHOT task. Photfile may be an APPHOT/DAOPHOT text
database or an STSDAS table.
.le
.ls exfile
The list of photometry files containing the ids of stars to be excluded
from the subtraction. Exfile must be undefined or contain one exclude file
for every input image. If exfile is "default", "dir$default", or a directory
specification, SUBSTAR will look for a file called image.pst.? where the ?
mark stands for the highest existing version number. Exfile is usually the
output of the PSTSELECT task but may also be the output of the PEAK, NSTAR and
ALLSTAR tasks or even the PHOT task. Exfile may be an APPHOT/DAOPHOT text
database or an STSDAS table.
.le
.ls psfimage
The list of images containing the PSF models computed by the DAOPHOT PSF task.
The number of PSF images must be equal to the number of input images. If
psfimage is "default", "dir$default", or a directory specification,
then PEAK will look for an image with the name image.psf.?, where
? is the highest existing version number.
.le
.ls subimage
The list of output subtracted images. There must be one output subtracted
image for every input image. If subimage is "default", "dir$default", or a
directory specification, then SUBSTAR will write an image called image.sub.?
where question mark stands for the next available version number.
.le
.ls datapars = ""
The name of the file containing the data dependent parameters. The parameters
\fIscale\fR, \fIdatamin\fR, and \fIdatamax\fR are located here. If datapars
is undefined then the default parameter set in uparm directory
.le
.ls daopars = ""
The name of the file containing the daophot fitting parameters. The parameters
\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined
then the default parameter set in uparm directory is used.
.le
.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf"
The coordinate system of the input coordinates read from \fIphotfile\fR, of the
psf model \fIpsfimage\fR, and of the output coordinates written to
the standard output if \fIverbose\fR = "yes". The image header coordinate
system is used to transform from the input coordinate system to the "logical"
pixel coordinate system used internally, from the internal logical system to
the PSF model system, and from the internal "logical" pixel coordinate system
to the output coordinate system. The input coordinate system options are
"logical", "tv", "physical", and "world". The PSF model and output coordinate
system options are "logical", "tv", and "physical". The image cursor coordinate
system is assumed to be the "tv" system.
.ls logical
Logical coordinates are pixel coordinates relative to the current image.
The logical coordinate system is the coordinate system used by the image
input/output routines to access the image data on disk. In the logical
coordinate system the coordinates of the first pixel of a 2D image, e.g.
dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are
always (1,1).
.le
.ls tv
Tv coordinates are the pixel coordinates used by the display servers. Tv
coordinates include the effects of any input image section, but do not
include the effects of previous linear transformations. If the input
image name does not include an image section, then tv coordinates are
identical to logical coordinates. If the input image name does include a
section, and the input image has not been linearly transformed or copied from
a parent image, tv coordinates are identical to physical coordinates.
In the tv coordinate system the coordinates of the first pixel of a
2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300]
are (1,1) and (200,200) respectively.
.le
.ls physical
Physical coordinates are pixel coordinates invariant with respect to linear
transformations of the physical image data. For example, if the current image
was created by extracting a section of another image, the physical
coordinates of an object in the current image will be equal to the physical
coordinates of the same object in the parent image, although the logical
coordinates will be different. In the physical coordinate system the
coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D
image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200)
respectively.
.le
.ls world
World coordinates are image coordinates in any units which are invariant
with respect to linear transformations of the physical image data. For
example, the ra and dec of an object will always be the same no matter
how the image is linearly transformed. The units of input world coordinates
must be the same as those expected by the image header wcs, e. g.
degrees and degrees for celestial coordinate systems.
.le
The wcsin, wcspsf, and wcsout parameters default to the values of the package
parameters of the same name. The default values of the package parameters
wcsin, wcspsf, and wcsout are "logical", "physical" and "logical" respectively.
.le
.ls cache = ")_.cache"
Cache the image pixels in memory. Cache may be set to the value of the apphot
package parameter (the default), "yes", or "no". By default caching is
disabled.
.le
.ls verify = ")_.verify"
Verify the critical SUBSTAR task parameters? Verify can be set to the DAOPHOT
package parameter value (the default), "yes", or "no".
.le
.ls update = ")_update"
Update the SUBSTAR task parameters if \fIverify\fR is "yes"? Update can be
set to the default daophot package parameter value, "yes", or "no".
.le
.ls verbose = ")_.verbose"
Print messages about the progress of the task ? Verbose can be set to the
DAOPHOT package parameter value (the default), "yes", or "no".
.le
.ih
DESCRIPTION
SUBSTAR task takes an input photometry list \fIphotfile\fR containing
the fitted coordinates and magnitudes, and an input PSF \fIpsfimage\fR, and
for each star in the photometry list scales and shifts the PSF and subtracts
it from the input image \fIimage\fR. The final subtracted image is saved in the
output image \fIsubimage\fR.
The input photometry list can be the output from of the PEAK, NSTAR or ALLSTAR
tasks or even the PHOT task although most people would not want to use the PHOT
output for this purpose.
Selected stars may be omitted from the subtraction by supplying their ids in
the file \fIexfile\fR. \fIExfile\fR is normally the output the PSTSELECT task
and is used to tell SUBSTAR to subtract the PSF star neighbors, but not the
PSF stars themselves.
The coordinates read from \fIphotfile\fR are assumed to be in coordinate
system defined by \fIwcsin\fR. The options are "logical", "tv", "physical",
and "world" and the transformation from the input coordinate system to the
internal "logical" system is defined by the image coordinate system. The
simplest default is the "logical" pixel system. Users working on with image
sections but importing pixel coordinate lists generated from the parent image
must use the "tv" or "physical" input coordinate systems.
The coordinate system of the PSF model is the coordinate system defined by the
\fIwcspsf\fR parameter. Normally the PSF model was derived from the input image
and this parameter default to "logical". However if the PSF model was derived
from a larger image which is a "parent" of the input image, then wcspsf should
be set to "tv" or "physical" depending on the circumstances.
The coordinates written to the standard output if \fIverbose\fR = yes are in the
coordinate system defined by \fIwcsout\fR. The options are "logical", "tv",
and "physical". The simplest default is the "logical" system. Users wishing to
correlate the output coordinates of objects measured in image sections or
mosaic pieces with coordinates in the parent image must use the "tv" or
"physical" coordinate systems.
If \fIcache\fR is yes and the host machine physical memory and working set size
are large enough the input and output image pixels are cached in memory. If
caching is enabled and SUBSTAR is run interactively the first subtraction
will appear to take a long time as the entire image must be read in before
the measurement is actually made. All subsequent measurements will be very
fast because SUBSTAR is accessing memory not disk. The point of caching is
to speed up random image access by making the internal image i/o buffers the
same size as the image itself. However if the input object lists are sorted
in row order which SUBSTAR does internally and are sparse caching may
actually worsen not improve the execution time. Also at present there is no
point in enabling caching for images that are less than or equal to 524288
bytes, i.e. the size of the test image dev$ypix, as the default image i/o
buffer is exactly that size. However if the size of dev$ypix is doubled by
converting it to a real image with the chpixtype task then the effect of
caching in interactive is can be quite noticeable if measurements
of objects in the top and bottom halves of the image are alternated.
The SUBSTAR task is most commonly used to check on the quality of the PSF
fitting produced by PEAK and NSTAR, to search for non-stellar objects and close
binary stars, to generate an improved PSF in crowded fields, and to remove
neighbors from bright stars which are to be used to determine aperture
corrections.
.ih
EXAMPLES
1. Subtract the NSTAR photometry results for the test image dev$ypix from the
image dev$ypix.
.nf
da> datapars.epadu = 14.0
da> datapars.readnoise = 75.0
... set the gain and readout noise for the detector
da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0
... answer verify prompts
... find stars in the image
... answer will appear in ypix.coo.1
da> phot dev$ypix default default annulus=10. dannulus=5. \
apertures = 3.0
... answer verify prompts
... do aperture photometry on the detected stars
... answer will appear in ypix.mag.1
da> display dev$ypix 1
da> psf dev$ypix default "" default default default psfrad=11.0 \
fitrad=3.0 mkstars=yes display=imdr
... verify the critical parameters
... move the image cursor to a candidate star and hit the a key,
a plot of the stellar data appears
... type ? for a listing of the graphics cursor menu
... type a to accept the star, d to reject it
... move to the next candidate stars and repeat the previous
steps
... type l to list all the psf stars
... type f to fit the psf
... move cursor to first psf star and type s to see residuals,
repeat for all the psf stars
... type w to save the PSF model
... type q to quit, and q again to confirm
... the output will appear in ypix.psf.1.imh, ypix.pst.1 and
ypix.psg.1
da> group dev$ypix default default default
... verify the prompts
... the output will appear in ypix.grp.1
da> nstar dev$ypix default default default default
... verify the prompts
... the results will appear in ypix.nst.1 and ypix.nrj.1
da> pdump ypix.nst.1 sharpness,chi yes | graph
... plot chi versus sharpness, the stars should cluster around
sharpness = 0.0 and chi = 1.0, note that the frame does
not have a lot of stars
da> substar dev$ypix default "" default default
... subtract the fitted stars
da> display ypix.sub.1 2
... note that the psf stars subtract reasonably well but other
objects which are not stars don't
.fi
2. Rerun the previous example on a section of the test image using the group
file and PSF model derived in example 1 for the parent image and writing the
results in the coordinate system of the parent image.
.nf
da> nstar dev$ypix[150:450,150:450] default default default default \
wcsin=tv wcspsf=tv wcsout=tv
... answer the verify prompts
... fit the stars
... the results will appear in ypix.nst.2 and ypix.nst.2
da> display dev$ypix[150:450,150:450] 1
... display the image
da> pdump ypix.nst.2 xc,yc yes | tvmark 1 STDIN col=204
... mark the stars
da> substar dev$ypix ypix.nst.2 "" default default
... subtract stars from parent image
... the output images is ypix.sub.2
da> substar dev$ypix[150:450,150:450] ypix.nst.2 "" default default \
wcsin=tv wcspsf=tv wcsout=tv
... subtract stars from the nstarinput image
... the output images is ypix.sub.3
.fi
.ih
TIME REQUIREMENTS
.ih
BUGS
.ih
SEE ALSO
datapars,daopars,nstar,peak
.endhelp
|
