---

7.4.7.2 Upper-limit settings ¶

The upper-limit magnitude was discussed in Quantifying measurement limits. Unlike other measured values/columns in MakeCatalog, the upper limit magnitude needs several extra parameters which are discussed here. All the options specific to the upper-limit measurements start with up for “upper-limit”. The only exception is --envseed that is also present in other programs and is general for any job requiring random number generation in Gnuastro (see Generating random numbers).

One very important consideration in Gnuastro is reproducibility. Therefore, the values to all of these parameters along with others (like the random number generator type and seed) are also reported in the comments of the final catalog when the upper limit magnitude column is desired. The random seed that is used to define the random positions for each object or clump is unique and set based on the (optionally) given seed, the total number of objects and clumps and also the labels of the clumps and objects. So with identical inputs, an identical upper-limit magnitude will be found. However, even if the seed is identical, when the ordering of the object/clump labels differs between different runs, the result of upper-limit measurements will not be identical.

MakeCatalog will randomly place the object/clump footprint over the dataset. When the randomly placed footprint does not fall on any object or masked region (see --upmaskfile) it will be used in the final distribution. Otherwise that particular random position will be ignored and another random position will be generated. Finally, when the distribution has the desired number of successfully measured random samples (--upnum) the distribution’s properties will be measured and placed in the catalog.

When the profile is very large or the image is significantly covered by detections, it might not be possible to find the desired number of samplings in a reasonable time. MakeProfiles will continue searching until it is unable to find a successful position (since the last successful measurement²²³), for a large multiple of --upnum (currently²²⁴ this is 10). If --upnum successful samples cannot be found until this limit is reached, MakeCatalog will set the upper-limit magnitude for that object to NaN (blank).

MakeCatalog will also print a warning if the range of positions available for the labeled region is smaller than double the size of the region. In such cases, the limited range of random positions can artificially decrease the standard deviation of the final distribution. If your dataset can allow it (it is large enough), it is recommended to use a larger range if you see such warnings.

--upmaskfile=FITS

File name of mask image to use for upper-limit calculation. In some cases (especially when doing matched photometry), the object labels specified in the main input and mask image might not be adequate. In other words they do not necessarily have to cover all detected objects: the user might have selected only a few of the objects in their labeled image. This option can be used to ignore regions in the image in these situations when estimating the upper-limit magnitude. All the non-zero pixels of the image specified by this option (in the --upmaskhdu extension) will be ignored in the upper-limit magnitude measurements.

For example, when you are using labels from another image, you can give NoiseChisel’s objects image output for this image as the value to this option. In this way, you can be sure that regions with data do not harm your distribution. See Quantifying measurement limits for more on the upper limit magnitude.

--upmaskhdu=STR

The extension in the file specified by --upmask.

--upnum=INT

The number of random samples to take for all the objects. A larger value to this option will give a more accurate result (asymptotically), but it will also slow down the process. When a randomly positioned sample overlaps with a detected/masked pixel it is not counted and another random position is found until the object completely lies over an undetected region. So you can be sure that for each object, this many samples over undetected objects are made. See the upper limit magnitude discussion in Quantifying measurement limits for more.

--uprange=INT,INT

The range/width of the region (in pixels) to do random sampling along each dimension of the input image around each object’s position. This is not a mandatory option and if not given (or given a value of zero in a dimension), the full possible range of the dataset along that dimension will be used. This is useful when the noise properties of the dataset vary gradually. In such cases, using the full range of the input dataset is going to bias the result. However, note that decreasing the range of available positions too much will also artificially decrease the standard deviation of the final distribution (and thus bias the upper-limit measurement).

--envseed ¶

Read the random number generator type and seed value from the environment (see Generating random numbers). Random numbers are used in calculating the random positions of different samples of each object.

--upsigmaclip=FLT,FLT

The raw distribution of random values will not be used to find the upper-limit magnitude, it will first be \(\sigma\)-clipped (see Sigma clipping) to avoid outliers in the distribution (mainly the faint undetected wings of bright/large objects in the image). This option takes two values: the first is the multiple of \(\sigma\), and the second is the termination criteria. If the latter is larger than 1, it is read as an integer number and will be the number of times to clip. If it is smaller than 1, it is interpreted as the tolerance level to stop clipping. See Sigma clipping for a complete explanation.

--upnsigma=FLT

The multiple of the final (\(\sigma\)-clipped) standard deviation (or \(\sigma\)) used to measure the upper-limit sum or magnitude.

--checkuplim=INT[,INT]

Print a table of positions and measured values for all the full random distribution used for one particular object or clump. If only one integer is given to this option, it is interpreted to be an object’s label. If two values are given, the first is the object label and the second is the ID of requested clump within it.

The output is a table with three columns (whether it is FITS or plain-text is determined with the --tableformat option, see Input/Output options). The first two columns are the pixel X,Y positions of the center of each label’s tile (see next paragraph), in each random sampling of this particular object/clump. The third column is the measured flux over that region. If the region overlapped with a detection or masked pixel, then its measured value will be a NaN (not-a-number). The total number of rows is thus unknown before running. However, if an upper-limit measurement was made in the main output of MakeCatalog, you can be sure that the number of rows with non-NaN measurements is the number given to the --upnum option.

The “tile” of each label is defined by the minimum and maximum positions of each label: values of the --min-x, --max-x, --min-y and --max-y columns in the main output table for each label. Therefore, the tile center position that is recorded in the output of this column ignores the distribution of labeled pixels within the tile.

Precise interpretation of the position is only relevant when the footprint of your label is highly un-symmetrical and you want to use this catalog to insert your object into the image. In such a case, you can also ask for --min-x and --min-y and manually calculate their difference with the following two positional measurements of your desired label: --geo-x and --geo-y (which report the label’s “geometric” center; only using the label positions ignoring any “values”) or --x and --y (which report the value-weighted center of the label). Adding the difference with the position reported by this column, will let you define alternative “center”s for your label in particular situations (this will usually not be necessary!). For more on these positional columns, see Position measurements in pixels.