This installed script will measure the radial profile of an object within an image. A general overview of this script has been published in Infante-Sainz et al. 2024); please cite it if this script proves useful in your research. For more on installed scripts please see (see Installed scripts). This script can be used with the following general template:
$ astscript-radial-profile [OPTION...] FITS-file
Examples:
## Generate the radial profile with default options (assuming the
## object is in the center of the image, and using the mean).
$ astscript-radial-profile image.fits
## Generate the radial profile centered at x=44 and y=37 (in pixels),
## up to a radial distance of 19 pixels, use the mean value.
$ astscript-radial-profile image.fits --center=44,37 --rmax=19
## Generate a 2D polar plot with the same properties as above:
$ astscript-radial-profile image.fits --center=44,37 --rmax=19 \
--polar
## Generate the radial profile centered at x=44 and y=37 (in pixels),
## up to a radial distance of 100 pixels, compute sigma clipped
## mean and standard deviation (sigclip-mean and sigclip-std) using
## 5 sigma and 0.1 tolerance (default is 3 sigma and 0.2 tolerance).
$ astscript-radial-profile image.fits --center=44,37 --rmax=100 \
--sigmaclip=5,0.1 \
--measure=sigclip-mean,sigclip-std
## Generate the radial profile centered at RA=20.53751695,
## DEC=0.9454292263, up to a radial distance of 88 pixels,
## axis ratio equal to 0.32, and position angle of 148 deg.
## Name the output table as `radial-profile.fits'
$ astscript-radial-profile image.fits --mode=wcs \
--center=20.53751695,0.9454292263 \
--rmax=88 --axis-ratio=0.32 \
--position-angle=148 -oradial-profile.fits
## Generate the radial profile centered at RA=40.062675270971,
## DEC=-8.1511992735126, up to a radial distance of 20 pixels,
## and calculate the SNR using the INPUT-NO-SKY and SKY-STD
## extensions of the NoiseChisel output file.
$ astscript-radial-profile image_detected.fits -hINPUT-NO-SKY \
--mode=wcs --measure=sn \
--center=40.062675270971,-8.1511992735126 \
--rmax=20 --stdhdu=SKY_STD
## Generate the radial profile centered at RA=40.062675270971,
## DEC=-8.1511992735126, up to a radial distance of 20 pixels,
## and compute the SNR with a fixed value for std, std=10.
$ astscript-radial-profile image.fits -h1 --mode=wcs --rmax=20 \
--center=40.062675270971,-8.1511992735126 \
--measure=sn --instd=10
## Generate the radial profile centered at X=1201, Y=1201 pixels, up
## to a radial distance of 20 pixels and compute the median and the
## SNR using the first extension of sky-std.fits as the dataset for std
## values.
$ astscript-radial-profile image.fits -h1 --mode=img --rmax=20 \
--center=1201,1201 --measure=median,sn \
--instd=sky-std.fits
This installed script will read a FITS image and will use it as the basis for constructing the radial profile. The output radial profile is a table (FITS or plain-text) containing the radial distance from the center in the first row and the specified measurements in the other columns (mean, median, sigclip-mean, sigclip-median, etc.).
To measure the radial profile, this script needs to generate temporary files. All these temporary files will be created within the directory given to the --tmpdir option. When --tmpdir is not called, a temporary directory (with a name based on the inputs) will be created in the running directory. If the directory does not exist at run-time, this script will create it. After the output is created, this script will delete the directory by default, unless you call the --keeptmp option.
With the default options, the script will generate a circular radial profile using the mean value and centered at the center of the image. In order to have more flexibility, several options are available to configure for the desired radial profile. In this sense, you can change the center position, the maximum radius, the axis ratio and the position angle (elliptical apertures are considered), the operator for obtaining the profiles, and others (described below).
|
Debug your profile: to debug your results, especially close to the center of your object, you can see the radial distance associated to every pixel in your input. To do this, use --keeptmp to keep the temporary files, and compare crop.fits (crop of your input image centered on your desired coordinate) with apertures.fits (radial distance of each pixel). |
|
Finding properties of your elliptical target: you want to measure the radial profile of a galaxy, but do not know its exact location, position angle or axis ratio. To obtain these values, you can use NoiseChisel to detect signal in the image, feed it to Segment to do basic segmentation, then use MakeCatalog to measure the center (--x and --y in MakeCatalog), axis ratio (--axis-ratio) and position angle (--position-angle). |
|
Masking other sources: The image of an astronomical object will usually have many other sources with your main target.
A crude solution is to use sigma-clipped measurements for the profile.
However, sigma-clipped measurements can easily be biased when the number of sources at each radial distance increases at larger distances.
Therefore a robust solution is to mask all other detections within the image.
You can use NoiseChisel and Segment to detect and segment the sources, then set all pixels that do not belong to your target to blank using Arithmetic (in particular, its |
The HDU/extension of the input image to use.
Filename of measured radial profile. It can be either a FITS table, or plain-text table (determined from your given file name suffix).
The central position of the radial profile. This option is used for placing the center of the profiles. This parameter is used in Crop to center and crop the region. The positions along each dimension must be separated by a comma (,) and fractions are also acceptable. The number of values given to this option must be the same as the dimensions of the input dataset. The units of the coordinates are read based on the value to the --mode option, see below.
Interpret the center position of the object (values given to --center) in image or WCS coordinates. This option thus accepts only two values: img or wcs. By default, it is --mode=img.
Maximum radius for the radial profile (in pixels). By default, the radial profile will be computed up to a radial distance equal to the maximum radius that fits into the image (assuming circular shape).
The precision (number of digits after the decimal point) in resolving the radius. The default value is --precision=0 (or -P0), and the value cannot be larger than 6. A higher precision is primarily useful when the very central few pixels are important for you. A larger precision will over-resolve larger radial regions, causing scatter to significantly affect the measurements.
For example, in the command below, we will generate the radial profile of an imaginary source (at RA,DEC of 1.23,4.567) and check the output without setting a precision:
$ astscript-radial-profile image.fits --center=1.23,4.567 \
--mode=wcs --measure=mean,area --rmax=10 \
--output=radial.fits --quiet
$ asttable radial.fits --head=10 -ffixed -p4
0.0000 0.0139 1
1.0000 0.0048 8
2.0000 0.0023 16
3.0000 0.0015 20
4.0000 0.0011 24
5.0000 0.0008 40
6.0000 0.0006 36
7.0000 0.0005 48
8.0000 0.0004 56
9.0000 0.0003 56
Let’s repeat the command above, but use a precision of 3 to resolve more finer details of the radial profile, while only printing the top 10 rows of the profile:
$ astscript-radial-profile image.fits --center=1.23,4.567 \
--mode=wcs --measure=mean,area --rmax=10 \
--precision=3 --output=radial.fits --quiet
$ asttable radial.fits --head=10 -ffixed -p4
0.0000 0.0139 1
1.0000 0.0056 4
1.4140 0.0040 4
2.0000 0.0027 4
2.2360 0.0024 8
2.8280 0.0018 4
3.0000 0.0017 4
3.1620 0.0016 8
3.6050 0.0013 8
4.0000 0.0011 4
Do you see how many more radii have been added? Between 1.0 and 2.0, we now have one extra radius, between 2.0 to 3.0, we have two new radii and so on. If you go to larger and larger radii, you will notice that they get resolved into many sub-components and the number of pixels used in each measurement will not be significant (you can already see that in the comparison above). This has two problems: 1. statistically, the scatter in larger radii (where the signal-to-noise ratio is usually low will make it hard to interpret the profile. 2. technically, the output table will have many more rows!
|
Use higher precision only for small radii: If you want to look at the whole profile (or the outer parts!), don’t set the precision, the default mode is usually more than enough! But when you are targeting the very central few pixels (usually less than a pixel radius of 5), use a higher precision. |
Oversample the input dataset to the fraction given to this option. Therefore if you set --rmax=20 for example, and --oversample=5, your output will have 100 rows (without --oversample it will only have 20 rows). Unless the object is heavily undersampled (the pixels are larger than the actual object), this method provides a much more accurate result and there are sufficient number of pixels to get the profile accurately.
Due to the discrete nature of pixels, if you use this option to oversample your profile, set --precision=0. Otherwise, your profile will become step-like (with several radii having a single value).
Undersample the input dataset by the number given to this option. This option is for considering larger apertures than the original pixel size (aperture size is equal to 1 pixel). For example, if a radial profile computed by default has 100 different radii (apertures of 1 pixel width), by considering --undersample=2 the radial profile will be computed over apertures of 2 pixels, so the final radial profile will have 50 different radii. This option is good to measure over a larger number of pixels to improve the measurement.
The axis ratio of the apertures (minor axis divided by the major axis in a 2D ellipse).
By default (when this option is not given), the radial profile will be circular (axis ratio of 1).
This parameter is used as the option --qcol in the generation of the apertures with astmkprof.
The position angle (in degrees) of the profiles relative to the first FITS axis (horizontal when viewed in SAO DS9). By default, it is --position-angle=0, which means that the semi-major axis of the profiles will be parallel to the first FITS axis.
Limit the profile to the given azimuthal angle range (two numbers given to this option, in degrees, from 0 to 360) from the major axis (defined by --position-angle). The radial profile will therefore be created on a wedge-like shape, not the full circle/ellipse. The pixel containing the center of the profile will always be included in the profile (because it contains all azimuthal angles!).
If the first angle is smaller than the second (for example, --azimuth=10,80), the region between, or inside, the two angles will be used. Otherwise (for example, --azimuth=80,10), the region outside the two angles will be used. The latter case can be useful when you want to ignore part of the 2D shape (for example, due to a bright star that can be contaminating it).
You can visually see the shape of the region used by running this script with --keeptmp and viewing the values.fits and apertures.fits files of the temporary directory with a FITS image viewer like SAO DS9. You can use Viewing FITS file contents with DS9 or TOPCAT to open them together in one instance of DS9, with both frames matched and locked (for easy comparison in case you want to zoom-in or out). For example, see the commands below (based on your target object, just change the image name, center, position angle, etc.):
## Generate the radial profile
$ astscript-radial-profile image.fits --center=1.234,6.789 \
--mode=wcs --rmax=50 --position-angle=20 \
--axis-ratio=0.8 --azimuth=95,150 --keeptmp \
--tmpdir=radial-tmp
## Visually check the values and apertures used.
$ astscript-fits-view radial-tmp/values.fits \
radial-tmp/apertures.fits
Generate a 2D polar-plot image in the second HDU of the output (called POLAR-PLOT).
A polar plot is a projection of the original pixel grid into polar coordinates (where the horizontal axis is the azimuthal angle and the vertical axis is the radius).
By default it assumes the full azimuthal range (from 0 to 360 degrees); if a narrower azimuthal range is desired, use --azimuth (for example --azimuth=30,50 to only generate the polar plot between 30 and 50 degrees of azimuth).
The output image contains WCS information to map the pixel coordinates into the polar coordinates. This is especially useful when the azimuthal range is not the full range: the first pixel in the horizontal axis is not 0 degrees.
Currently, the polar plot cannot to be used with --oversample and --undersample options (please get in touch with us if you need it). Until it is implemented, you can use the --scale option of Warp to do the oversampling of the input image yourself and generate the polar plot from that. A comprehensive overview of this option has been published in Eskandarlou et al. 2024. If this script yields useful results in your research, please be sure to cite it.
The operator for measuring the values over each radial distance.
The values given to this option will be directly passed to MakeCatalog.
As a consequence, all MakeCatalog measurements like the magnitude, magnitude error, median, mean, signal-to-noise ratio (S/N), std, surface brightness, sigclip-mean, and sigclip-number can be used here.
For a full list of MakeCatalog’s measurements, please run astmkcatalog --help or see MakeCatalog measurements.
Multiple values can be given to this option, each separated by a comma.
This option can also be called multiple times.
|
Masking background/foreground objects: For crude rejection of outliers, you can use sigma-clipping using MakeCatalog measurements like --sigclip-mean or --sigclip-mean-sb (see MakeCatalog measurements).
To properly mask the effect of background/foreground objects from your target object’s radial profile, you can use |
Some measurements by MakeCatalog require a per-pixel sky standard deviation (for example, magnitude error or S/N). Therefore when asking for such measurements, use the --instd option (described below) to specify the per-pixel sky standard deviation over each pixel. For other measurements like the magnitude or surface brightness, MakeCatalog will need a Zero point, which you can set with the --zeropoint option.
For example, by setting --measure=mean,sigclip-mean --measure=median, the mean, sigma-clipped mean and median values will be computed. The output radial profile will have 4 columns in this order: radial distance, mean, sigma-clipped and median. By default (when this option is not given), the mean of all pixels at each radial position will be computed.
Sigma clipping parameters: only relevant if sigma-clipping operators are requested by --measure. For more on sigma-clipping, see Sigma clipping. If given, the value to this option is directly passed to the --sigmaclip option of MakeCatalog, see MakeCatalog inputs and basic settings. By default (when this option is not given), the default values within MakeCatalog will be used. To see the default value of this option in MakeCatalog, you can run this command:
$ astmkcatalog -P | grep " sigmaclip "
The Zero point of the input dataset. This is necessary when you request measurements like magnitude, or surface brightness.
Account for zero-valued pixels in the profile. By default, such pixels are not considered (when this script crops the necessary region of the image before generating the profile). The long format of this option is identical to a similarly named option in Crop (see Invoking Crop). When this option is called, it is passed directly to Crop, therefore the zero-valued pixels are not considered as blank and used in the profile creation.
Sky standard deviation as a single number (FLT) or as the filename (STR) containing the image with the std value for each pixel (the HDU within the file should be given to the --stdhdu option mentioned below). This is only necessary when the requested measurement (value given to --measure) by MakeCatalog needs the Standard deviation (for example, the signal-to-noise ratio or magnitude error). If your measurements do not require a standard deviation, it is best to ignore this option (because it will slow down the script).
HDU/extension of the sky standard deviation image specified with --instd.
Several intermediate files are necessary to obtain the radial profile. All of these temporal files are saved into a temporal directory. With this option, you can directly specify this directory. By default (when this option is not called), it will be built in the running directory and given an input-based name. If the directory does not exist at run-time, this script will create it. Once the radial profile has been obtained, this directory is removed. You can disable the deletion of the temporary directory with the --keeptmp option.
Do not delete the temporary directory (see description of --tmpdir above). This option is useful for debugging. For example, to check that the profiles generated for obtaining the radial profile have the desired center, shape and orientation.
Give BibTeX and acknowledgment information for citing this script within your paper. For more, see Operating mode options.
GNU Astronomy Utilities 0.23 manual, July 2024.