-
Notifications
You must be signed in to change notification settings - Fork 0
/
contour_map.xml
306 lines (281 loc) · 12 KB
/
contour_map.xml
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
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cxchelptopics SYSTEM "CXCHelp.dtd">
<cxchelptopics>
<ENTRY
context="tools"
key="contour_map"
refkeywords="contour map mask adaptive bin group sanders contbin"
seealsogroups="dmimgtools"
>
<SYNOPSIS>
Adaptively bin an image using a contour map algorithm
</SYNOPSIS>
<DESC>
<PARA>
The contour_map tool works by locating the maximum pixel value
in the infile image. It determines which contour levels the
pixel value is between, and then groups all contiguous pixels
with values above the lower contour limit. There is no
limit on the total flux nor SNR of the pixel values in the group.
The only restriction is that the pixels must be within
the specified radius of the starting pixel. After that
group is created, the process is repeated by locating the maximum
pixel not already included in a group, and repeating the
contour search. Disjoint regions often will have the same
contour limits.
</PARA>
<PARA>
The input image should be smoothed. It can also
background subtracted and exposure corrected. The
image does not have to be counts or flux; it could be
a hardness ratio map, a mean energy map, or any other
2D image where the goal is to create groups of pixels
with similar values.
</PARA>
<PARA>
Under the hood, the script is using the dmimglasso tool to
create the localized contour regions.
</PARA>
<PARA>
Users have two options to specify the contour levels.
The levels parameter can be used to specify a stack of
values. If levels is left blank, users must specify
the number of levels between the min and max
pixel values in the image using the nlevels parameter and the
spacing between them using scale=linear or scale=log.
In either setup, at most maxcontours individual groups will be
created. This stops the algorithm from creating many small
regions at the edge of the image (or detector field of view).
</PARA>
</DESC>
<QEXAMPLELIST>
<QEXAMPLE>
<SYNTAX>
<LINE>% aconvolve img.fits sm_img.fits "lib:gaus(2,5,1,3,3)"</LINE>
<LINE>% contour_map sm_img.fits sm_img.map binimg=sm_img.img levels=1,2,4,8,16</LINE>
</SYNTAX>
<DESC>
<PARA>
In this example the input image is smoothed with a simple
3-pixels sigma Gaussian using the aconvolve tool.
That is then used to create contour_map with
contour levels at 1,2,4,8,16. The contour level values
are arbitrary.
</PARA>
<PARA>
The tool creates two output files. The outfile, sm_img.map,
is an image whose pixel values indicate which pixels
are grouped together. Note that due to the contour
algorithm there may be holes inside a group
where the pixel in the holes belong to a different
group or remain ungrouped. (map values equal to 0
are ungrouped.) The binimg output file is the
result of applying the map file to the infile to produce
a binned image.
</PARA>
</DESC>
</QEXAMPLE>
<QEXAMPLE>
<SYNTAX>
<LINE>% aconvolve img.fits sm_img.fits "lib:gaus(2,5,1,3,3)"</LINE>
<LINE>% contour_map sm_img.fits sm_img.map binimg=sm_img.img nlevels=20 scale=log</LINE>
</SYNTAX>
<DESC>
<PARA>
This is the same example as above, except the levels are now
specified using the nlevels and and scale parameter.
The tool will create 20 logarithmically spaced levels from
the minimum pixel value to the maximum pixel value.
</PARA>
</DESC>
</QEXAMPLE>
<QEXAMPLE>
<SYNTAX>
<LINE>% contour_map sm_fluxed.fits fluxed.map distance=1000 maxcontours=500</LINE>
</SYNTAX>
<DESC>
<PARA>
This example now allows the contours to extend upto 1000
physical pixels from the starting location; but limits the
output to 500 contours (separate regions).
</PARA>
</DESC>
</QEXAMPLE>
</QEXAMPLELIST>
<PARAMLIST>
<PARAM name="infile" type="file" filetype="input" reqd="yes">
<SYNOPSIS>
Input image.
</SYNOPSIS>
<DESC>
<PARA>
Typically the input image will be a smoothed, counts (or [net] flux)
image. Contours are restricted to contiguous pixels
within the same contour limits. However, the tool is
agnostic about the input pixels values. The input file
could be a hardness ratio map, a map of the median
energy, or any other 2D image where the goal is to
group together similar contiguous pixels values.
</PARA>
<PARA>
The script will take advantage of any filter applied
and recorded in the input files subspace. Thus it can avoid
0 valued pixels outside the field-of-view or
pixels with a value NaN.
</PARA>
</DESC>
</PARAM>
<PARAM name="outfile" type="file" filetype="output" reqd="yes">
<SYNOPSIS>
Output map file
</SYNOPSIS>
<DESC>
<PARA>
The outfile is a map file containing integer pixel values.
The pixel values indicate which pixels are grouped
together by the algorithm. A pixel value of 0 are pixels
which are ungrouped (ie outside the image subspace).
</PARA>
</DESC>
</PARAM>
<PARAM name="binimg" type="file" filetype="output">
<SYNOPSIS>Optional, output binned image</SYNOPSIS>
<DESC>
<PARA>
If the binimg file is specified, the script
will use the input image and the output map file to
create a binned version of the input image.
</PARA>
</DESC>
</PARAM>
<PARAM name="distance" type="real" def="75">
<SYNOPSIS>Max distance from starting pixel (in physical pixels)</SYNOPSIS>
<DESC>
<PARA>
The distance parameter is used together with the shape
parameter to determine the maximum distance from
the starting pixel to group together.
</PARA>
<PARA>
For shape=circle, distance is the radius of a circle,
in units of physical pixels, centered on the starting pixel.
For shape=box, a square with total side length equal to
twice the distance value is used.
</PARA>
</DESC>
</PARAM>
<PARAM name="shape" type="string" def="circle">
<SYNOPSIS>Shape of distance measure</SYNOPSIS>
<DESC>
<PARA>
The distance parameter is used together with the shape
parameter to determine the maximum distance from
the starting pixel to group together.
</PARA>
<PARA>
For shape=circle, distance is the radius of a circle,
in units of physical pixels, centered on the starting pixel.
For shape=box, a square with total side length equal to
twice the distance value is used.
</PARA>
</DESC>
</PARAM>
<PARAM name="levels" type="string" stacks="yes" def="">
<SYNOPSIS>User specified contour levels</SYNOPSIS>
<DESC>
<PARA>
The level parameters is a stack of values to use
for the contour levels. If the levels
parameter is blank, then the tool will use
the nlevels and scale parameters to determine
the scales from the min and max pixel values.
</PARA>
</DESC>
</PARAM>
<PARAM name="nlevels" type="integer" min="1" def="20">
<SYNOPSIS>Number of contour levels</SYNOPSIS>
<DESC>
<PARA>
If the levels parameter is blank, the tool will
create nlevel contour levels between the min and
max pixel value; the scale parameter specifies
whether the levels are spaced linearly or
logarithmically.
</PARA>
</DESC>
</PARAM>
<PARAM name="scale" type="string" def="log">
<SYNOPSIS>Spacing between contour levels</SYNOPSIS>
<DESC>
<PARA>
If the levels parameter is blank, the tool will
create nlevel contour levels between the min and
max pixel value; the scale parameter specifies
whether the levels are spaced linearly or
logarithmically.
</PARA>
</DESC>
</PARAM>
<PARAM name="maxcontours" type="integer" def="1000" min="1">
<SYNOPSIS>Maximum number of regions</SYNOPSIS>
<DESC>
<PARA>
It is often the case that at the edge of the image
there are many isolated, small, insignificant
groups of pixels which end up in their own
contour regions. This is not only inefficient in
later processing, but it also causes this tool to
run much longer. The maxcontours parameter limits the
output to at most this many regions.
</PARA>
</DESC>
</PARAM>
<PARAM name="verbose" type="integer" def="1" min="0" max="5">
<SYNOPSIS>
Amount of chatter from the tool.
</SYNOPSIS>
</PARAM>
<PARAM name="clobber" type="boolean" def="no">
<SYNOPSIS>
Delete outfile if it already exists?
</SYNOPSIS>
</PARAM>
</PARAMLIST>
<ADESC title="Relation to Sanders' contour binning algorithm">
<PARA>
Many users reading this will already be familiar with Sander's et al.
contour binning tool, 'contbin', 2006MNRAS.371..829S. contbin is
a very powerful tool which includes internal adaptive smoothing,
as well as handling background and exposure maps as separate inputs.
</PARA>
<PARA>
While conceptually the algorithms are similar they are in fact
very different beyond just the background and exposure corrections and
internal smoothing.
Instead of pre-defined contour levels, contbin collects the
maximum neighboring pixels together until a SNR threshold is
achieved. It then moves to the next highest (or lowest) pixel
value and repeats the process; each group then has its own
limits. There are also differences in how to deal with
long, thin groups; contbin uses a robust roundness metric to
inhibit this behavior (whereas contour_map imposes a simple geometric
distance threshold).
</PARA>
<PARA>
contbin has many features that are likely going to
satisfy many users needs beyond what
contour_map offers. It also has a large number of
publication citations and active user base. In short, users
of contour_map should also evaluate contbin for their projects.
</PARA>
</ADESC>
<BUGS>
<PARA>
See the
<HREF link="http://cxc.harvard.edu/ciao/bugs/index.html">CIAO
website</HREF> for an up-to-date listing of known bugs.
</PARA>
</BUGS>
<LASTMODIFIED>January 2019</LASTMODIFIED>
</ENTRY>
</cxchelptopics>