im2shape readme

This file may be found at www.sarahbridle.net/im2shape/readme.html.

Contents:

Frequently Asked Questions

Return to the main page.

Installation

To install im2shape, download the code and unzip and untar it. Then:

cd source
make distclean
make
cd ..

NB. you will need to change the first two lines of the Makefile
depending on where your cfitsio directory is, eg.
INCL = -I/usr/local/cfitsio -I./
LIB = -L/usr/local/cfitsio/ -lcfitsio -lm

Ignore the warning
setup_im2shape.o(.text+0x20): the `gets' function is dangerous and
should not be used.

The files:
im2shape
setup_im2shape
fits2mat
should now have appeared in the im2shape directory.

Testing the code

You can test the code by downloading this test example to the directory that the im2shape code is in. First run the interactive setup program which asks questions and writes the im2shape input file. (Or alternatively write an im2shape input file using your own pipelines). The below setting should work for most problems.

setup_im2shape
data/example
2
data/example.fits
data/example.cat
16
2
0 20
1
0 1000
2
2
-2 6
2
0 20
0
1
200
data/model.txt
2
0

The file data/example.in should now have been written.
The contents should be the below:

2
data/example.out
data/example.fits
data/example.cat
16
2 0.000000 20.000000
1 0.000000 1000.000000
1
1 0.000000 16.000000
1 0.000000 16.000000
3 0.000000 1.000000
1 0.000000 3.141600
2 -2.000000 8.000000
2 0.000000 20.000000
-1 0.000000 0.000000
-1 0.000000 0.000000
-1 0.000000 0.000000
-1 0.000000 0
2 -2.000000 8.000000
2 0.000000 20.000000
data/example_psf.dat
1
200
data/model.txt
2.000000
0

In addition a dummy psf file called data/example_psf.dat should have been created, which should look like the below:

1
1
6
0 0 0 0 0 0 0.000001 1.000000

Now run im2shape on this file:

im2shape data/example.in

The im2shape output file data/example.out should now have been created. Compare example.out with example_check.out
There will be differences, due to the random nature of the sampling process, however, they should be approximately the same.

File Formats

im2shape input file, .in

2	Verbosity level, 0 minimal, 1, 2, 3, 4 very chatty
data/example.out	Output file name (see format below)
data/example.fits	Input fits file name
data/example.cat	Input catalogue file name
16	Side of square postage stamps to cut from image
2 0.000000 20.000000	Prior on noise, here is flat between 0 < log(noise) < 20
1 0.000000 1000.000000	Prior on background level after minimum in postage stamp is removed. Here it is flat between 0 < background < 1000
2	Number of Gaussians
1 0.000000 16.000000	Prior on x position of Gaussian 1 within postage stamp, ie. anywhere
1 0.000000 16.000000	Ditto y
3 0.000000 1.000000	Prior on ellipticity, here is flat in 0 < e^2 < 1
1 0.000000 3.141600	Prior on theta, here is flat in 0 < theta < 2pi Unfortunately, theta is defined as anticlockwise from the negative y axis. Therefore to get the more conventional angle, subtract 90 degrees. Combined these priors on e and theta give a flat prior on e1, e2 space
2 -2.000000 8.000000	Prior on height of Gaussian 1, here between -2 < log(A) < 8
2 0.000000 20.000000	Prior on ab of Gaussian 1, here flat on 0 < log(ab) < 20 Defined such that a circular Gaussian of width sigma has 2 sigma^2 = ab
-1 0.000000 0.000000	Prior on x position of Gaussian 2, here locked to be equal to that of Gaussian 1
-1 0.000000 0.000000	Ditto y
-1 0.000000 0.000000	Ditto e
-1 0.000000 0.000000	Ditto theta
2 -2.000000 8.000000	Ditto height. In this example is free but same priors as on Gaussian 1
2 0.000000 20.000000	Ditto ab
data/example_psf.dat	Input psf file. This file contains a delta function when produced by setup_im2shape
1	Ensemble. Parameter of the mcmc ~ number of chains to run
200	Niter. Number of iterations of the mcmc
data/model.txt	Postage stamp of the best model fitted to the last object fitted
2.000000	Smoothing length (in pixels) for estimating smoothed residuals (see below)
0	Unused.

im2shape output file, .out

When fitting just one Gaussian, the output file columns are: 1 line number in file
2 sextractor object number
3 x at the start of the postage stamp
4 y "
5 noise
6 background
7 x offset of object relative to start of postage stamp (e.g. 16x16 for this run)
8 y "
9 e (mean of e samples, which are all between 0 and 1, so only good to use this number if errors are small, otherwise you get ~0.5 for it on v noisy galaxies)
10 theta (again, mean over samples, between 0 and pi, so always pi/2 if noisy)
11 a*b
12 peak amplitude of Gaussian
*** If fitting 2 object Gaussians then 6 more lines are inserted here (x, y, e, theta, a*b, amplitude for 2nd Gaussian)
*** If fitting 3....
13 x for psf component 1
14 y "
15 e "
16 theta "
17 a*b "
18 amp "
*** If the psfs have np Gaussians then there are 6*(np-1) lines inserted here, so you have a record of what psf was used for this object
19 e1 (good to use this rather than combining e and theta)
20 e2 (")
*** If fitting ng object Gaussians then there are 2*(ng-1) more lines here, giving e1, e2 for the remaining Gaussians
21 error on noise
22 " background
23 " x
24 " y
25 " e
26 " theta
27 " a*b
28 " amp
*** If fitting ng object Gaussians then there are 6*(ng-1) more lines here, giving the uncertainties on the parameters of the remaining Gaussians
29 " x for psf component 1 (always zero since psf uncertainties were never implemented)
30 " y "
31 " e "
32 " theta "
33 " a*b "
34 " amp "
35 error on e1
36 error on e1
*** If fitting ng object Gaussians then there are 2*(ng-1) more lines here, giving the uncertainties on e1, e2 for the remaining Gaussians
37 evidence (have never used this or really looked at it though)
38 minimum value of mock image using parameter values of mean of samples
39 maximum value of mock image "
40 minimum value of the residuals map
41 maximum "
42 minimum value of smoothed residuals map
43 maximum "
44 flag, in principle, although I've never really used it or tuned it

When fitting two Gaussians to the galaxies, and using two Gaussians for the psfs (ie. used 2 Gaussians for the stars) (as for the im2shape STEP1 and STEP2 results):

1	Line number in this file
2	Object number, as given in column 1 of input catalogue
3	x at the start of the postage stamp
4	y "
5	Estimated Gaussian noise level
6	Estimated background level
7	x offset of galaxy Gaussian 1 relative to start of postage stamp (for given psf convolution)
8	y "
9	e (mean of e samples, which are all between 0 and 1, so only good to use this number if errors are small, otherwise you get ~0.5 for it on v noisy galaxies)
10	theta (again, mean over samples, between 0 and pi, so always pi/2 if noisy)
11	a*b
12	A, peak amplitude of Gaussian
13	x offset of galaxy Gaussian 2 relative to start of postage stamp (for given psf convolution)
14	y "
15	e (mean of e samples, which are all between 0 and 1, so only good to use this number if errors are small, otherwise you get ~0.5 for it on v noisy galaxies)
16	theta (again, mean over samples, between 0 and pi, so always pi/2 if noisy)
17	a*b
18	A, peak amplitude of Gaussian
19	x for psf component 1
20	y "
21	e "
22	theta "
23	a*b "
24	amp "
25	x for psf component 2
26	y "
27	e "
28	theta "
29	a*b "
30	amp "
31	e1 for galaxy Gaussian 1 (good to use this rather than combining e and theta)
32	e2 (")
33	e1 for galaxy Gaussian 2
34	e2 (")

35	error on noise
36	" background
37	" x for galaxy Gaussian component 1
38	" y
39	" e
40	" theta
41	" a*b
42	" amp
43	" x for galaxy Gaussian component 2
44	" y
45	" e
46	" theta
47	" a*b
48	" amp
49	" x for psf component 1 (always zero since psf uncertainties were never implemented)
50	" y "
51	" e "
52	" theta "
53	" a*b "
54	" amp "
55	" x for psf component 2 (always zero since psf uncertainties were never implemented)
56	" y "
57	" e "
58	" theta "
59	" a*b "
60	" amp "
61	error on e1 for galaxy Gaussian component 1
62	error on e2 "
63	error on e1 for galaxy Gaussian component 2
64	error on e2 "
65	evidence (have never used this or really looked at it though)
66	minimum value of mock image using parameter values of mean of samples
67	maximum value of mock image "
68	minimum value of the residuals map
69	maximum "
70	minimum value of smoothed residuals map
71	maximum "
72	flag, in principle, although I've never really used it or tuned it

A file samples.txt is also produced, but is only interesting if you want to know more about the shape of the probability distribution function on e.g. e for a single galaxy, if an error bar isn't enough info for you.

psf.dat

This file describes the psf to be used by im2shape, in terms of parameters of Gaussians.
The simplest psf.dat files is a delta function, ie. no psf. This is what is used in the test example above. A file called example_psf.dat is created by setup_im2shape. First lets look at this file and explain the format.

more data/example_psf.dat
1
1
6
0 0 0 0 0 0 0.000001 1.00000

Line 1 says that the psf is a single elliptical Gaussian (as opposed to making up a more complicated shape from a sum of Gaussians).
Line 2 says that the psf is specified at 1 point on the image. This is equivalent to saying that the psf is uniform across the image.
Line 3 says the number of parameters that describe the psf ie. 6*no. Gaussians used.
Line 4 gives the parameters of the psf at that point. The first two numbers give the x and y position at which the psf is being specified. When there is a uniform psf then these numbers are irrelevant.
The next 6 numbers give the parameters describing the Gaussian that makes up the psf: x,y,e,theta,a*b,A.
Therefore in this example the psf is centered on x,y=zero (so the galaxies stay in one place when convolved with this psf). In this example e and theta are both zero.
The width of the psf is tiny, a*b=0.00001 so it is very close to a Gaussian.
The peak amplitude of the Gaussian is 1. Then value of the peak amplitude is not important when using a single Gaussian to describe the psf, if you are only interested in the e1, e2 values for the galaxies. What happens if the psf is not to be a delta function but is a circular Gaussian of width 2 pixels?
You would replace the last 6 numbers above with the numbers describing your psf, ie. 0 0 0 0 4 1 gives a Gaussian with a*b=4 ie. width 2 pixels. What if I want the psf to have np Gaussian components?
Change the first line in the file from 1 to np; Add the parameters describing the additional Gaussian to the end of the third line. e.g. if the psf were made of the sum of 2 Gaussians, one with width 2 pixels and one with width 3 pixels, and with peak heights with a ratio 5 to 7, you could put:
2
1
0 0 0 0 0 0 4 5 0 0 0 0 9 7

I have run im2shape on the stars and I have a .out file. How do I convert it into a psf.dat file?
This is where it gets tricky.

Running on Data

There are many options for how you do this. The im2shape code simply fits a sum of elliptical Gaussians to each object, given that the psf is described by a sum of Gaussians in the file psf.dat. This leaves you free / burdened with the tasks of:

Selecting the stars

Running im2shape on these stars

Removing badly fitted stars

Interpolating the psf to make the file psf.dat

Selecting the galaxies

Running im2shape on the galaxies

Removing bad galaxies

Interpreting the galaxy file

Frequently Asked Questions

When is the paper coming out?
Soon.

Last updated 2 Feb 2005 Sarah Bridle