Next: MakeCatalog output columns, Previous: MakeCatalog general settings, Up: Invoking astmkcatalog [Contents][Index]
The upper limit magnitude was discussed in Quantifying measurement limits. Unlike other measured values/columns in MakeCatalog, the upper limit magnitude needs several defined parameters which are discussed here. All the upper limit magnitude specific options start with up for upper-limit, except for --envseed that is also present in other programs and is general for any job requiring random number generation (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 positionings for each object or clump is unique and set based on the 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. But even if the ordering of the object/clump labels differs (and the seed is the same) the result will not be the same.
MakeCatalog will randomly place the object/clump footprint over the image and when the footprint doesn’t fall on any object or masked region (see --upmaskfile) it will be used until the desired number (--upnum) of samples are found to estimate the distribution’s standard deviation (see Quantifying measurement limits). Otherwise it will be ignored and another random position will be generated. But 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. MakeProfiles will continue searching until 50 times the value given to --upnum. If --upnum good samples cannot be found until this limit, it 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.
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.
The extension in the file specified by --upmask.
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.
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 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).
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.
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 interpretted as the tolerance level to stop clipping. See Sigma clipping for a complete explanation.
The multiple of the final (\(\sigma\)-clipped) standard deviation (or \(\sigma\)) used to measure the upper-limit brightness or magnitude.
Next: MakeCatalog output columns, Previous: MakeCatalog general settings, Up: Invoking astmkcatalog [Contents][Index]
JavaScript license information
GNU Astronomy Utilities 0.5 manual, December 2017.