rrprof - create radial profiles from an image
rrprof [options] image x y
rrprof operates upon an image, generating radial profiles. It can use an image mask to determine which parts of the image should be used in the profiles and can generate profiles in different regions of the image.
rrprof uses an optional mask image to determine which pixels should be included in the radial profiles (--mask). If a region file (--regfile) or region mask file (--regmask) is specified, it operates separately on the valid pixels in each region, else it operates on all valid pixels.
The pixels are sorted by distance from the specified center (x, y), and then binned. The surface brightness in each bin is calculated, and is output along with its error, the bin boundaries, and other quantities (see Output).
rrprof can bin the input data using one of several algorithms. The --bin option is used to specify the scheme and its arguments.
The specification string can take one of two forms:
In this form the binning parameters are specified via a
colon (:) delimited list:
algorithm:p1:p2:p3
The first element in the list is the name of the binning algorithm, followed by parameter values. The parameter values must occur in the specified order.
For example:
linear:0:11:10
Some parameters may be optional, but the separating colons must still be specified:
linear:::10
In the following documentation, square brackets ([, ])
surrounding a parameter name indicate that that parameter is optional.
The separating : delimiter may be left out from an optional
trailing element if it is not specified.
This takes the form
algorithm:k1=v1,k2=v2
For example,
linear:min=0,max=11,binw=10
In the following documentation, the verbose form is only described if there is some deviation from the above format. The concise form is always described. A parameter is mandatory unless otherwise documented.
The following algorithms are available:
Bin widths are constant. Either the number of bins or the bin width must be specified.
The parameters are:
The minimum radius at which to start binning. Optional, defaults to 0.
The maximum radius at which to stop binning. Optional, defaults to no limit.
The bin width. Do not also specify nbins.
The number of bins. Do not also specify binw.
Binning specification:
linear:[rmin]:[rmax]:binw linear:[rmin]:[rmax]:#nbins
The # character in the latter specification is required to indicate
that the parameter is the number of bins.
Bin widths increase by a geometric factor:
binw = binw0 * factor**n
where n is the zero-based index of a bin.
The parameters are:
The minimum radius at which to start binning. Optional, defaults to 0.
The maximum radius at which to stop binning. Optional, defaults to no limit.
The initial bin width.
The multiplicative factor
Binning specifications
dratio:[rmin]:[rmax]:binw0:factor
Bin bounds increase by a geometric factor. The initial bound may be specified as an absolute radius or as an offset from the minimum:
Absolute Relative -------------- --------------------- r0 * factor**n rmin + r0 * factor**n
The parameters are:
The minimum radius at which to start binning. Optional, defaults to 0.
The maximum radius at which to stop binning. Optional, defaults to no limit.
Whether or not the initial bound is absolute or relative to
rmin. In the concise specification the abs parameter is not
explicitly specified. Instead, the r0 parameter is prefixed with a
+ to indicate that the initial bound is relative.
In the verbose form this parameter may take the values yes, no,
1, or 0.
The default is for the initial bound to be absolute.
The initial bound.
Binning specifications:
ratio:[rmin]:[rmax]:r0:factor ratio:[rmin]:[rmax]:+r0:factor
where the + in the latter indicates a relative offset.
Bins are adaptively constructed to achieve a minimum signal-to-noise ratio in each bin.
The parameters are:
The minimum radius at which to start binning. Optional, defaults to 0.
The maximum radius at which to stop binning. Optional, defaults to no limit.
The minimum Signal to Noise Ratio (SNR) in each bin.
The minimum number of pixels in each bin. It must be at least 2.
Optional, defaults to 2.
The maximum number of pixels in each bin.
Optional, defaults to no limit.
The minimum and maximum widths of a bin, where width is approximately the distance between the first and last pixels in a bin.
Optional, defaults to no limit.
Binning specifications:
snr:[rmin]:[rmax]:min_snr[:[min_npix][:[max_npix[:[min_width][:max_width]]]]
Bins limits are read from an RDB formatted file which contains two columns, rmin and rmax, corresponding to the lower and upper limits of the bins. Bins must be contiguous.
The parameters are:
The name of the file containing the bin limits.
Binning specification:
file:filename
Errors (noise) are calculated based upon the following combinations of options:
If set, this specifies another image (of the same size as the image specified on the command line) whose pixels contain errors. A bin's error is the RSS of the error in each included pixel.
If these are set, the image specified by errimg contains counts; the errors are assumed to be Poisson and are the square root of the pixel values. A bin's error is the RSS of the error in each included pixel.
The error is assumed to be Poisson and is the square root of the image specified on the command line. A bin's error is the RSS of the error in each included pixel.
A bin's error is the standard deviation of the included pixel values.
rrprof will subtract the mean counts in an area of the image from the radial profile if the --bgregfile option is specified. At present it is only possible to perform background subtraction if either --errcnts or --errimg options are specified.
rrprof will by default output a separate file containing the surface brightness data for each region (--outfile). By default only bins with a non-zero number of pixels are output (see --output-all-bins).
If the --combine option is specified, all of the output is written to a single file.
By default, the radii will be output in units of pixels. If --runits is specified and the input image has WCS information in its header, the radii will be converted to the specified units. If --rscale is specified, the radii will be multiplied by that scale factor. Note that --runits and --rscale may both be specified, in which case the radii are first converted to the unit specified by --runits and the multiplied by the --rscale factor. The --units option provides a label for the resultant units. It need not be specified if --rscale is not.
The following data are output for each region:
The region identifier. This is output only if --combine is set or if the output is sent to the standard output stream and a region file or mask has been specified.
The unary based bin index.
The bin upper and lower bounds.
The bin center.
The half-width of the bin.
The sum of the pixel values in each bin.
The surface brightness in the bin (counts/pixel**2) and its error.
The number of pixels in the bin.
The following arguments must appear on the command line in the specified order.
The FITS image file upon which to operate.
The x position about which to generate the profile, in image coordinates.
The y position about which to generate the profile, in image coordinates.
Options may be abbreviated. Options which take values may be separated from the values by whitespace or the "=" character.
A FITS mask image. It should have the same size as the original image. It is used to determine which pixels in the original image are valid (e.g. on the detector). A non-zero mask value indicates a valid image pixel. Exposure maps can be used here.
A FITS region mask image. This differs from the mask image in that the values of pixels are used to identify individual regions. The mask should be of integer type. Zero valued pixels are ignored. Here's an example of how to create such an image using funimage:
funimage /dev/null'[TEXT(x:I:256,y:I:256),panda(128,128,0,360,4,0,100,1)]'\
mask.fits bitpix=8,mask=all
This option may be used in conjunction with --mask, but not with --regfile.
A ds9 region file. It must be in image coordinates. rrprof will use this to generate a mask file matched to the input image file. The maskfile may be saved with the --saveregmask option.
If --regfile is also specified, the resulting mask will be written as a FITS image to the specified file.
A ds9 region file. It must be in image coordinates. rrprof will use this to extract a background count rate which will be subtracted from the image.
If specified, surface brightness profiles for all regions are written to a single file. This parameter is automatically set if the output is written to the standard output stream and --regfile or --regmask is specified.
The name of the file to which to write the profile. If there are multiple regions, each profile is written to a separate file; the region number will be appended to the base of the given file name. For example, if the name is foo.rdb, separate profiles will be written to foo_01.rdb, foo_02.rdb, etc.
If this is not specified all output is written to the standard output stream. In this case, if --regfile or --regmask is specified, then --combine is automatically set.
The format in which the radial profiles will be written. The available formats are:
rdb
The error is the square root of the number of counts. If --errimg is specified, than the square root of that image is used. If --errimg is not specified, the square root of the input image is used.
errorfile is a FITS image file containing errors for each pixel. If --errcnts is also specified, the image data are treated as counts. See --errcnts for more information.
The binning specification. See Binning Schemes for more information. It defaults to
linear:mbins=10
Some of the binning methods result in non-contiguous bins because the
bin boundaries are determined from the distances of the included
pixels to the image center, which are quantized. This option "cleans"
the bins so that they are contiguous by setting the inner boundary
of each bin to the outer boundary of the next innermost bin. The
inner boundary of the innermost bin is set to 0.
Normally only bins with a non-zero number of pixels in them are output. Specifying this option results in all bins being output.
The units of the output radii. This is merely a label written to the output file. It need not be specified if --rscale is not used.
This may be one of
The input image world coordinate system will be used to convert the pixel size into the specified units.
This may be used in combination with --rscale, in which case this conversion is performed first, and then the scale parameter is applied.
A scale factor applied to the bin radii, after the possible units conversion specified by --runits. The --units option may be used in conjunction with this to label the units in the output files.
Output the version and exit.
Print the usual program information
This documents version @VERSION@ of rrprof.
Copyright 2008-2009 The Smithsonian Astrophysical Observatory. rrprof is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
Diab Jerius <djerius@cfa.harvard.edu>