---

8.1.4.2 MakeProfiles profile settings ¶

The profile parameters that differ between each created profile are specified through the columns in the input catalog and described in MakeProfiles catalog. Besides those there are general settings for some profiles that do not differ between one profile and another, they are a property of the general process. For example, how many random points to use in the monte-carlo integration, this value is fixed for all the profiles. The options described in this section are for configuring such properties.

--mode=STR

Interpret the center position columns (--ccol in MakeProfiles catalog) in image or WCS coordinates. This option thus accepts only two values: img and wcs. It is mandatory when a catalog is being used as input.

-r

--numrandom

The number of random points used in the central regions of the profile, see Sampling from a function.

-e ¶

--envseed

Use the value to the GSL_RNG_SEED environment variable to generate the random Monte Carlo sampling distribution, see Sampling from a function and Generating random numbers.

-t FLT

--tolerance=FLT

The tolerance to switch from Monte Carlo integration to the central pixel value, see Sampling from a function.

-p

--tunitinp

The truncation column of the catalog is in units of pixels. By default, the truncation column is considered to be in units of the radial parameters of the profile (--rcol). Read it as ‘t-unit-in-p’ for ‘truncation unit in pixels’.

-f

--mforflatpix

When making fixed value profiles (“flat”, “circumference” or “point” profiles, see ‘--fcol’), do not use the value in the column specified by ‘--mcol’ as the magnitude. Instead use it as the exact value that all the pixels of these profiles should have. This option is irrelevant for other types of profiles. This option is very useful for creating masks, or labeled regions in an image. Any integer, or floating point value can used in this column with this option, including NaN (or ‘nan’, or ‘NAN’, case is irrelevant), and infinities (inf, -inf, or +inf).

For example, with this option if you set the value in the magnitude column (--mcol) to NaN, you can create an elliptical or circular mask over an image (which can be given as the argument), see Blank pixels. Another useful application of this option is to create labeled elliptical or circular apertures in an image. To do this, set the value in the magnitude column to the label you want for this profile. This labeled image can then be used in combination with NoiseChisel’s output (see NoiseChisel output) to do aperture photometry with MakeCatalog (see MakeCatalog).

Alternatively, if you want to mark regions of the image (for example, with an elliptical circumference) and you do not want to use NaN values (as explained above) for some technical reason, you can get the minimum or maximum value in the image ²²⁹ using Arithmetic (see Arithmetic), then use that value in the magnitude column along with this option for all the profiles.

Please note that when using MakeProfiles on an already existing image, you have to set ‘--oversample=1’. Otherwise all the profiles will be scaled up based on the oversampling scale in your configuration files (see Configuration files) unless you have accounted for oversampling in your catalog.

--mcolissum

The value given in the “magnitude” column (specified by --mcol, see MakeProfiles catalog) must be interpreted as total sum of pixel values, not magnitude (which is measured from the total sum and zero point, see Brightness, Flux, Magnitude and Surface brightness). When this option is called, the zero point magnitude (value to the --zeropoint option) is ignored and the given value must have the same units as the input dataset’s pixels.

Recall that the total profile magnitude that is specified with in the --mcol column of the input catalog is not an integration to infinity, but the actual sum of pixels in the profile (until the desired truncation radius). See Profile magnitude for more on this point.

--mcolnocustprof

Do not touch (re-scale) the custom profile that should be inserted in custom-prof profile (see the description of --fcol in MakeProfiles catalog or the description of --customtable below). By default, MakeProfiles will scale (multiply) the custom image’s pixels to have the desired magnitude (or sum of pixels if --mcolissum is called) in that row.

--mcolnocustimg

Do not touch (re-scale) the custom image that should be inserted in custom-img profile (see the description of --fcol in MakeProfiles catalog). By default, MakeProfiles will scale (multiply) the custom image’s pixels to have the desired magnitude (or sum of pixels if --mcolissum is called) in that row.

--magatpeak

The magnitude column in the catalog (see MakeProfiles catalog) will be used to set the value only for the profile’s peak (maximum) pixel, not the full profile. Note that this is the flux of the profile’s peak (maximum) pixel in the final output of MakeProfiles. So beware of the oversampling, see Oversampling.

This option can be useful if you want to check a mock profile’s total magnitude at various truncation radii. Without this option, no matter what the truncation radius is, the total magnitude will be the same as that given in the catalog. But with this option, the total magnitude will become brighter as you increase the truncation radius.

In sharper profiles, sometimes the accuracy of measuring the peak profile flux is more than the overall object sum or magnitude. In such cases, with this option, the final profile will be built such that its peak has the given magnitude, not the total profile.

CAUTION: If you want to use this option for comparing with observations, please note that MakeProfiles does not do convolution. Unless you have deconvolved your data, your images are convolved with the instrument and atmospheric PSF, see Point spread function. Particularly in sharper profiles, the flux in the peak pixel is strongly decreased after convolution. Also note that in such cases, besides deconvolution, you will have to set --oversample=1 otherwise after resampling your profile with Warp (see Warp), the peak flux will be different.

--customtable FITS/TXT

The filename of the table to use in the custom radial profiles (see description of --fcol in MakeProfiles catalog. This can be a plain-text table, or FITS table, see Recognized table formats, if it is a FITS table, you can use --customtablehdu to specify which HDU should be used (described below).

A custom radial profile can have any value you want for a given radial profile (including NaN/blank values). Each interval is defined by its minimum (inclusive) and maximum (exclusive) radius, when a pixel center falls within a radius interval, the value specified for that interval will be used. If a pixel is not in the given intervals, a value of 0.0 will be used for that pixel.

The table should have 3 columns as shown below. If the intervals are contiguous (the maximum value of the previous interval is equal to the minimum value of an interval) and the intervals all have the same size (difference between minimum and maximum values) the creation of these profiles will be fast. However, if the intervals are not sorted and contiguous, MakeProfiles will parse the intervals from the top of the table and use the first interval that contains the pixel center (this may slow it down).

Column 1:

The interval’s minimum radius.

Column 2:

The interval’s maximum radius.

Column 3:

The value to be used for pixels within the given interval (including NaN/blank).

Gnuastro’s column arithmetic in the Table program has the sorted-to-interval operator that will generate the first two columns from a single column (your radial profile). See the description of that operator in Column arithmetic and the example below.

By default, once a 2D image is constructed for the radial profile, it will be scaled such that its total magnitude corresponds to the value in the magnitude column (--mcol) of the main input catalog. If you want to disable the scaling and use the raw values in your custom profile (in other words: you want to ignore the magnitude column) you need to call --mcolnocustprof (see above).

In the example below, we’ll start with a certain radial profile, and use this option to build its 2D representation in an image (recall that you can build radial profiles with Generate radial profile). But first, we will need to use the sorted-to-interval to build the necessary input format (see Column arithmetic).

$ cat radial.txt
# Column 1: RADIUS [pix        ,f32,] Radial distance
# Column 2: MEAN   [input-units,f32,] Mean of values.
0.0       1.00000
1.0       0.50184
1.4       0.37121
2.0       0.26414
2.2       0.23427
2.8       0.17868
3.0       0.16627
3.1       0.15567
3.6       0.13132
4.0       0.11404

## Convert the radius in each row to an interval
$ asttable radial.txt --output=interval.fits \
           -c'arith RADIUS sorted-to-interval',MEAN

## Inspect the table containing intervals
$ asttable interval.fits -ffixed
-0.500000     0.500000      1.000000
0.500000      1.200000      0.501840
1.200000      1.700000      0.371210
1.700000      2.100000      0.264140
2.100000      2.500000      0.234270
2.500000      2.900000      0.178680
2.900000      3.050000      0.166270
3.050000      3.350000      0.155670
3.350000      3.800000      0.131320
3.800000      4.200000      0.114040

## Build the 2D image of the profile from the interval.
$ echo "1 7 7 8 10 2.5 0 1 1 2" \
       | astmkprof --mergedsize=13,13 --oversample=1 \
                   --customtable=interval.fits \
                   --output=image.fits

## View the created FITS image.
$ astscript-fits-view image.fits --ds9scale=minmax

Recall that if you want your image pixels to have the same values as the MEAN column in your profile, you should run MakeProfiles with --mcolnocustprof.

In case you want to build the profile using Generate radial profile, be sure to use the --oversample option of astscript-radial-profile. The higher the oversampling, the better your result will be. For example you can run the following script to see the effect (also see bug 65106). But don’t take the oversampling too high: both the radial profile script and MakeProfiles will become slower and the precision of your results will decrease.

#!/bin/bash

# Function to avoid repeating code: first generate a radial profile
# with a certain oversampling, then build a 2D profile from it):
# The first argument is the oversampling, the second is the suffix.
gen_rad_make_2dprf () {

    # Generate the radial profile
    radraw=$bdir/radial-profile-$2.fits
    astscript-radial-profile $prof -o$radraw \
			     --oversample=$1 \
			     --zeroisnotblank

    # Generate the custom table format
    custraw=$bdir/customtable-$2.fits
    asttable $radraw --output=interval.fits \
             -c'arith RADIUS sorted-to-interval',MEAN \
	     -o$custraw

    # Build the 2D profile.
    prof2draw=$bdir/prof2d-$2.fits
    echo "1 $xc $yc 8 30 0 0 1 0 1" \
	| astmkprof --customtable=$custraw \
		    --mergedsize=$xw,$yw \
                    --output=$prof2draw \
		    --mcolnocustprof \
                    --oversample=1 \
		    --clearcanvas \
		    --mode=img
}

# Directory to hold built files
bdir=build
if ! [ -d $bdir ]; then mkdir $bdir; fi

# Build a Gaussian profile in the center of an image to start with.
prof=$bdir/prof.fits
astmkprof --kernel=gaussian,2,5 -o$prof

# Find the center pixel of the image
xw=$(astfits $prof --keyvalue=NAXIS1 --quiet)
yw=$(astfits $prof --keyvalue=NAXIS2 --quiet)
xc=$(echo $xw | awk '{print int($1/2)+1}')
yc=$(echo $yw| awk '{print int($1/2)+1}')

# Generate two 2D radial profiles, one with an oversampling of 1
# and another with an oversampling of 5.
gen_rad_make_2dprf 1 "raw"
gen_rad_make_2dprf 5 "oversample"

# View the two images beside each other:
astscript-fits-view $bdir/prof2d-raw.fits \
		    $bdir/prof2d-oversample.fits

--customtablehdu INT/STR

The HDU/extension in the FITS file given to --customtable.

--customimg=STR[,STR]

A custom FITS image that should be used for the custom-img profiles (see the description of --fcol in MakeProfiles catalog). Multiple files can be given to this option (separated by a comma), and this option can be called multiple times itself (useful when many custom image profiles should be added). If the HDU of the images are different, you can use --customimghdu (described below).

Through the “radius” column, MakeProfiles will know which one of the images given to this option should be used in each row. For example, let’s assume your input catalog (cat.fits) has the following contents (output of first command below), and you call MakeProfiles like the second command below to insert four profiles into the background back.fits image.

The first profile below is Sersic (with an --fcol, or 4-th column, code of 1). So MakeProfiles builds the pixels of the first profile, and all column values are meaningful. However, the second, third and fourth inserted objects are custom images (with an --fcol code of 10). For the custom image profiles, you see that the radius column has values of 1 or 2. This tells MakeProfiles to use the first image given to --customimg (or gal-1.fits) for the second and fourth inserted objects. The second image given to --customimage (or gal-2.fits) will be used for the third inserted object. Finally, all three custom image profiles have different magnitudes, and the values in --ncol, --pcol, --qcol and --tcol are ignored.

$ cat cat.fits
1 53.15506 -27.785165 1  20 1 20 0.6 25 5
2 53.15602 -27.777887 10 1  0 0  0   22 0
3 53.16440 -27.775876 10 2  0 0  0   24 0
4 53.16849 -27.787406 10 1  0 0  0   23 0

$ astmkprof cat.fits --mode=wcs --zeropoint=25.68 \
            --background=back.fits --output=out.fits \
            --customimg=gal-1.fits --customimg=gal-2.fits

--customimghdu=INT/STR

The HDU(s) of the images given to --customimghdu. If this option is only called once, but --customimg is called many times, MakeProfiles will assume that all images given to --customimg have the same HDU. Otherwise (if the number of HDUs is equal to the number of images), then each image will use its corresponding HDU.

-X INT,INT

--shift=INT,INT

Shift all the profiles and enlarge the image along each dimension. To better understand this option, please see \(n\) in If convolving afterwards. This is useful when you want to convolve the image afterwards. If you are using an external PSF, be sure to oversample it to the same scale used for creating the mock images. If a background image is specified, any possible value to this option is ignored.

-c

--prepforconv

Shift all the profiles and enlarge the image based on half the width of the first Moffat or Gaussian profile in the catalog, considering any possible oversampling see If convolving afterwards. --prepforconv is only checked and possibly activated if --xshift and --yshift are both zero (after reading the command-line and configuration files). If a background image is specified, any possible value to this option is ignored.

-z FLT

--zeropoint=FLT

The zero point magnitude of the input. For more on the zero point magnitude, see Brightness, Flux, Magnitude and Surface brightness.

-w FLT

--circumwidth=FLT

The width of the circumference if the profile is to be an elliptical circumference or annulus. See the explanations for this type of profile in --fcol.

-R

--replace

Do not add the pixels of each profile over the background, or other profiles. But replace the values.

By default, when two profiles overlap, the final pixel value is the sum of all the profiles that overlap on that pixel. This is the expected situation when dealing with physical object profiles like galaxies or stars/PSF. However, when MakeProfiles is used to build integer labeled images (for example, in Aperture photometry), this is not the expected situation: the sum of two labels will be a new label. With this option, the pixels are not added but the largest (maximum) value over that pixel is used. Because the maximum operator is independent of the order of values, the output is also thread-safe.