AHELP for CIAO 4.2

# dmellipse

Context: tools

## Synopsis

finds best fit ellipse for specified fraction

## Syntax

```dmellipse  infile outfile fraction [shape] [x_centroid] [y_centroid]
[angle] [ellipticity] [fix_centroid] [fix_angle] [fix_ellipticity]
[tolerance] [minstep] [maxwalk] [step] [normalize] [clobber] [verbose]```

## Description

`dmellipse' finds the best-fit ellipse that encloses the user supplied fraction to within some specified tolerance.

The tool works by first finding the centroid, angle, radii, and ellipticity of the entire image. It uses these as a starting point. The fraction inside the ellipse defined by those parameters is computed. If the fraction computed is bigger than the fraction desired, the radius is decreased and the process is repeated (opposite if fraction is too small). During this process if the direction changes (so for example the previous iteration was too small and the current too big) we change the divide the step size by 2. This lets us converge onto a value. During the iterations the centroid, ellipticity, and/or angle may be taken from the previous iteration, from some user supplied values, or fixed to be the global values computed in the 1st step; the user controls these with the fix_* parameters.

Once we find a radius that mets the requirement that the fraction is within the 'tolerance' of the requested fraction we then do one more iteration. This is to check that with the final centroid, angle, and ellipticity that we still have the requested fraction. If not, then we use the new values to seed the next iteration. We refer to this as 'walking' since its kind of like a random-walk process.

The iterations can stop for several reason. First, if we find a radius with moments such that the fraction is met we stop successfully. Second, if we keep stepping and keep changing direction then the step size can get increasingly small; there is a limit on this. Third, if we keep 'walking' at the same step-size but unable to find an ellipse whose moments are consistent with fraction we stop after 'maxwalk' steps.

The output is written to an ASCII region-like file. Multiple values can be specified via stacks including the 'lgrid()' directive to compute an array of values.

## Example 1

`dmellipse img.fits 50perc.reg 0.5`

Finds the best-fit ellipse that encloses 50% of the energy/flux in the image.

## Example 2

`dmellipse img.fits 50perc.reg 0.5,0.9`

Finds the best-fit ellipses that encloses 50% and 90% of the energy/flux in the image.

## Example 3

`dmellipse img.fits 50perc.reg lgrid(0.5:0.91:0.1)`

Finds the best-fit ellipse that encloses 50%, 60%, 70%, 80% and 90% of the energy/flux in the image.

Note that to get the 90% radii we used an upper limit of 0.91 in the grid specification. This is because the stack grid computes values x<value for floating-point-value not x<=value.

## Example 4

`dmellipse img.fits 50perc.reg 0.5 fix_centroid=yes`

Finds the best-fit ellipses that encloses 50% and 90% of the energy/flux in the image. The centroid is fixed to be the centroid of the entire image; rather than being left to vary.

## Example 5

```dmellipse img.fits 50perc.reg 0.5 fix_centroid=yes x_centroid=4096
y_centroid=4096```

Similar to above. Finds the best-fit ellipses that encloses 50% and 90% of the energy/flux in the image. The centroid is fixed to be the user supplied value (4096,4096).

## Example 6

`dmellipse img.fits 50perc.reg 0.5 shape=rotbox`

Finds the best-fit rotated-box (rectangle) that encloses 50% of the energy/flux in the image.

## Example 7

`dmellipse img.fits[sky=circle(4096,4096,100) 50perc.reg 0.5 normalize=no`

Find ellipse that encloses 50% of the flux; setting normalize=no lets the tool know that the data have already been normalized (so 'no' the tool should not normalize the data).

## Parameters

name type ftype def min max reqd stacks
infile file input       yes
outfile file output       yes
fraction string         yes yes
shape string   ellipse     no
x_centroid real   INDEF     no
y_centroid real   INDEF     no
angle real   INDEF     no
ellipticity real   INDEF     no
fix_centroid boolean   no     no
fix_angle boolean   no     no
fix_ellipticity boolean   no     no
tolerance real   0.001 0 1 no
minstep real   0.001 0 1 no
maxwalk integer   10 1   no
step real   1 0   no
normalize boolean   yes     no
clobber boolean   no
verbose integer   0 0 5

## Detailed Parameter Descriptions

#### Parameter=infile (file required filetype=input)

Input image

Input image. It must have all positive values (so if background subtracted, make sure to threshold).

#### Parameter=outfile (file required filetype=output)

Output region file

ASCII region file. One row per fraction computed.

#### Parameter=fraction (string required stacks=yes)

Enclosed counts/flux fraction.

The value(s) to find the best-fit ellipse. This can be specified using any of the stack syntax including lgrid() or just a comma separated list (or just a single value).

#### Parameter=shape (string not required default=ellipse)

shape of region

can be either 'ellipse' or 'rotbox'

#### Parameter=x_centroid (real not required default=INDEF)

default x-centroid

The default x-centroid can be input via this parameter or if the value is set to INDEF the value will be computed over the entire image.

#### Parameter=y_centroid (real not required default=INDEF)

default y-centroid

The default y-centroid can be input via this parameter or if the value is set to INDEF the value will be computed over the entire image.

#### Parameter=angle (real not required default=INDEF)

default angle

The default angle can be input via this parameter or if the value is set to INDEF the value will be computed over the entire image.

#### Parameter=ellipticity (real not required default=INDEF)

default ellipticity

The default ellipticity can be input via this parameter or if the value is set to INDEF the value will be computed over the entire image.

#### Parameter=fix_centroid (boolean not required default=no)

allow centroid to vary

during the iterations the centroid can be allowed to vary or it can be held fixed at the default value (see x_ and y_centroid for default value)

#### Parameter=fix_angle (boolean not required default=no)

allow angle to vary

during the iterations the angle can be allowed to vary or it can be held fixed at the default value (see angle parameter for the default value)

#### Parameter=fix_ellipticity (boolean not required default=no)

allow ellipticity to vary

during the iterations the ellipticity can be allowed to vary or it can be held fixed at the default value (see ellipticity parameter for the default value).

#### Parameter=tolerance (real not required default=0.001 min=0 max=1)

How close to desired fraction is close enough?

The iterations will continue until the fraction is within fraction-tolerance to fraction+tolerance (so total-width is 2*tolerance).

#### Parameter=minstep (real not required default=0.001 min=0 max=1)

minimum step size

As the iterations proceed and we change from increasing to decreasing the radii we make the step size increasing smaller; this is the minimum step size to use. After reaching this the iterations will stop.

#### Parameter=maxwalk (integer not required default=10 min=1)

maximum number of equally applicable iterations.

We we have a candidate radii we use the ellipticity, angle, and centroid to do one last check. If the ellipse defined by those is still good (fraction is within tolerance) the we stop. If not, we 'walk' to the next iteration. This could lead to a situation where we oscillate between good and bad without changing step-size. This parameter limits this condition.

#### Parameter=step (real not required default=1 min=0)

Initial step size

The intial step size. If the program seems to be taking a long time it may be because the algorithm is creaping slowly towards the solution. Setting verbose greater than 2 will show the progress of the tool. Increasing the step size will allow the program to get close to the optimal solution quicky and then more quickly refine the solution until the tolerance (or other exit conditions) is (are) met.

#### Parameter=normalize (boolean not required default=yes)

Normalize input image or not?

Is the fraction really a fraction (% of total flux) or is it the integral?

#### Parameter=clobber (boolean default=no)

Remove output if it exists?

Used to specify whether or not to clobber existing file that has the same name as the specified output file

#### Parameter=verbose (integer default=0 min=0 max=5)

The tool chatter level

Verbose can be from 0 to 5, generating different amounts of debugging output.

## Bugs

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.