GNU Astronomy Utilities


Previous: , Up: Generate radial profile   [Contents][Index]


10.2.1 Invoking astscript-radial-profile

This installed script will measure the radial profile of an object within an image. 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 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 --axisratio=0.32 \
                           --positionangle=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 doesn’t 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 don’t 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 (--axisratio) and position angle (--positionangle).

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 don’t belong to your target to blank using Arithmetic (in particular, its where operator).

-h STR
--hdu=STR

The HDU/extension of the input image to use.

-o STR
--output=STR

Filename of measured radial profile. It can be either a FITS table, or plain-text table (determined from your given file name suffix).

-c FLT[,FLT[,...]]
--center=FLT[,FLT[,...]]

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.

-O STR
--mode=STR

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.

-R FLT
--rmax=FLT

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).

-Q FLT
--axisratio=FLT

The axis ratio of the apertures (minor axis divided by the major axis in a 2D ellipse). By default (when this option isn’t 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.

-a FLT[,FLT[,...]]
--azimuth=FLT[,FLT[,...]]

Azimuthal angles range (in degrees, from 0 to 360) from the major axis. This parameter is used as the option --qcol=azimuth in the generation of the apertures with astmkprof. For example, if you want to obtain the radial profile only in between 55 and 78 degrees (taking as the reference the major axis), use --azimuth=55,78.

-p FLT
--positionangle=FLT

The position angle (in degrees) of the profiles relative to the first FITS axis (horizontal when viewed in SAO DS9). By default, it is --positionangle=0, which means that the semi-major axis of the profiles will be parallel to the first FITS axis.

-m STR
--measure=STR

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, sigclip-number, etc. can be used here. For a full list of MakeCatalog’s measurements, please run astmkcatalog --help. Multiple values can be given to this option, each separated by a comma. This option can also be called multiple times.

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 Zeropoint, 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 isn’t given), the mean of all pixels at each radial position will be computed.

-s FLT,FLT
--sigmaclip=FLT,FLT

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 isn’t 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 "
-z FLT
--zeropoint=FLT

The Zeropoint of the input dataset. This is necessary when you request measurements like Magnitude, or Surface brightness.

-v INT
--oversample=INT

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.

-u INT
--undersample=INT

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.

-i FLT/STR
--instd=FLT/STR

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 don’t require a standard deviation, it is best to ignore this option (because it will slow down the script).

-d INT/STR
--stdhdu=INT/STR

HDU/extension of the sky standard deviation image specified with --instd.

-t STR
--tmpdir=STR

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 isn’t called), it will be built in the running directory and given an input-based name. If the directory doesn’t 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.

-k
--keeptmp

Don’t 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.


Previous: Generate radial profile, Up: Generate radial profile   [Contents][Index]