---

12.3.7 Dimensions (dimension.h) ¶

An array is a contiguous region of memory. Hence, at the lowest level, every element of an array just has one single-valued position: the number of elements that lie between it and the first element in the array. This is also known as the index of the element within the array. A dataset’s number of dimensions is high-level abstraction (meta-data) that we project onto that contiguous patch of memory. When the array is interpreted as a one-dimensional dataset, this index is also the coordinate of the element. But once we associate the patch of memory with a higher dimension, there must also be one coordinate for each dimension.

The functions and macros in this section provide you with the tools to convert an index into a coordinate and vice-versa along with several other issues for example, issues with the neighbors of an element in a multi-dimensional context.

Function:
size_t
gal_dimension_total_size (size_t ndim, size_t *dsize) ¶

Return the total number of elements for a dataset with ndim dimensions that has dsize elements along each dimension.

Function:
int
gal_dimension_is_different (gal_data_t *first, gal_data_t *second) ¶

Return 1 (one) if the two datasets do not have the same size along all dimensions. This function will also return 1 when the number of dimensions of the two datasets are different.

Function:
size_t *
gal_dimension_increment (size_t ndim, size_t *dsize) ¶

Return an allocated array that has the number of elements necessary to increment an index along every dimension. For example, along the fastest dimension (last element in the dsize and returned arrays), the value is 1 (one).

Function:
size_t
gal_dimension_num_neighbors (size_t ndim) ¶

The maximum number of neighbors (any connectivity) that a data element can have in ndim dimensions. Effectively, this function just returns \(3^n-1\) (where \(n\) is the number of dimensions).

Function-like macro: GAL_DIMENSION_FLT_TO_INT (FLT) ¶

Calculate the integer pixel position that the floating point FLT number belongs to. In the FITS format (and thus in Gnuastro), the center of each pixel is allocated on an integer (not it edge), so the pixel which hosts a floating point number cannot simply be found with internal type conversion.

Function:
void
gal_dimension_add_coords (size_t *c1, size_t *c2, size_t *out, size_t ndim) ¶

For every dimension, add the coordinates in c1 with c2 and put the result into out. In other words, for dimension i run out[i]=c1[i]+c2[i];. Hence out may be equal to any one of c1 or c2.

Function:
size_t
gal_dimension_coord_to_index (size_t ndim, size_t *dsize, size_t *coord) ¶

Return the index (counting from zero) from the coordinates in coord (counting from zero) assuming the dataset has ndim elements and the size of the dataset along each dimension is in the dsize array.

Function:
void
gal_dimension_index_to_coord (size_t index, size_t ndim, size_t *dsize, size_t *coord) ¶

Fill in the coord array with the coordinates that correspond to index assuming the dataset has ndim elements and the size of the dataset along each dimension is in the dsize array. Note that both index and each value in coord are assumed to start from 0 (zero). Also that the space which coord points to must already be allocated before calling this function.

Function:
size_t
gal_dimension_dist_manhattan (size_t *a, size_t *b, size_t ndim) ¶

Return the manhattan distance (see Wikipedia) between the two coordinates a and b (each an array of ndim elements).

Function:
float
gal_dimension_dist_radial (size_t *a, size_t *b, size_t ndim) ¶

Return the radial distance between the two coordinates a and b (each an array of ndim elements).

Function:
float
gal_dimension_dist_elliptical (double *center, double *pa_deg, double *q, size_t ndim, double *point) ¶

Return the elliptical/ellipsoidal distance of the single point point (containing ndim values: coordinates of the point in each dimension) from an ellipse that is defined by center, pa_deg and q. center is the coordinates of the ellipse center (also with ndim elements). pa is the position-angle in degrees (the angle of the semi-major axis from the first dimension in a 2D ellipse) and q is the axis ratio.

In a 2D ellipse, pa and q are a single-element array. However, in a 3D ellipsoid, pa must have three elements, and q must have 2 elements. For more see Defining an ellipse and ellipsoid.

Function:
gal_data_t *
gal_dimension_collapse_sum (gal_data_t *in, size_t c_dim, gal_data_t *weight) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by summing all elements in that direction. If weight!=NULL, it must be a single-dimensional array, with the same size as the dimension to be collapsed. The respective weight will be multiplied to each element during the collapse.

For generality, the returned dataset will have a GAL_TYPE_FLOAT64 type. See Copying datasets for converting the returned dataset to a desired type. Also, for more on the application of this function, see the Arithmetic program’s collapse-sum operator (which uses this function) in Arithmetic operators.

Function:
gal_data_t *
gal_dimension_collapse_mean (gal_data_t *in, size_t c_dim, gal_data_t *weight) ¶

Similar to gal_dimension_collapse_sum (above), but the collapse will be done by calculating the mean along the requested dimension, not summing over it.

Function:
gal_data_t *
gal_dimension_collapse_number (gal_data_t *in, size_t c_dim) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by counting how many non-blank elements there are along that dimension.

For generality, the returned dataset will have a GAL_TYPE_INT32 type. See Copying datasets for converting the returned dataset to a desired type. Also, for more on the application of this function, see the Arithmetic program’s collapse-number operator (which uses this function) in Arithmetic operators.

Function:
gal_data_t *
gal_dimension_collapse_minmax (gal_data_t *in, size_t c_dim, int max1_min0) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by using the largest/smallest non-blank value along that dimension. If max1_min0 is non-zero, then the collapsed dataset will have the maximum value along the given dimension and if it is zero, the minimum.

Function:
gal_data_t *
gal_dimension_collapse_median (gal_data_t *in, size_t c_dim, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the median non-blank value along that dimension. Since the median involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management.

Function:
gal_data_t *
gal_dimension_collapse_sclip_std (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the standard deviation of pixels along that dimension after sigma-clipping. Since sigma-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on sigma clipping, see Sigma clipping.

Function:
gal_data_t *
gal_dimension_collapse_sclip_fill_std (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_sclip_std, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_sclip_mad (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the median absolute deviation (MAD) of pixels along that dimension after sigma-clipping. Since sigma-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on sigma clipping, see Sigma clipping.

Function:
gal_data_t *
gal_dimension_collapse_sclip_fill_mad (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_sclip_mad, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_sclip_mean (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the mean of pixels along that dimension after sigma-clipping. Since sigma-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on sigma clipping, see Sigma clipping.

Function:
gal_data_t *
gal_dimension_collapse_sclip_fill_mean (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_sclip_mean, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_sclip_median (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the median of pixels along that dimension after sigma-clipping. Since sigma-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on sigma clipping, see Sigma clipping.

Function:
gal_data_t *
gal_dimension_collapse_sclip_fill_median (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_sclip_median, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_sclip_number (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the number of pixels along that dimension after sigma-clipping. Since sigma-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on sigma clipping, see Sigma clipping.

Function:
gal_data_t *
gal_dimension_collapse_sclip_fill_number (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_sclip_number, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_mclip_std (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the standard deviation of pixels along that dimension after median absolute deviation (MAD) clipping. Since MAD-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on MAD-clipping, see MAD clipping.

Function:
gal_data_t *
gal_dimension_collapse_mclip_fill_std (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_mclip_std, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_mclip_mad (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the median absolute deviation (MAD) of pixels along that dimension after median absolute deviation (MAD) clipping. Since MAD-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on MAD-clipping, see MAD clipping.

Function:
gal_data_t *
gal_dimension_collapse_mclip_fill_mad (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_mclip_mad, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_mclip_mean (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the mean of pixels along that dimension after median absolute deviation (MAD) clipping. Since MAD-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on MAD-clipping, see MAD clipping.

Function:
gal_data_t *
gal_dimension_collapse_mclip_fill_mean (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_mclip_mean, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_mclip_median (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the median of pixels along that dimension after median absolute deviation (MAD) clipping. Since MAD-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on MAD-clipping, see MAD clipping.

Function:
gal_data_t *
gal_dimension_collapse_mclip_fill_median (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_mclip_median, but with filled re-clipping (see Contiguous outliers).

Function:
gal_data_t *
gal_dimension_collapse_mclip_number (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Collapse the input dataset (in) along the given dimension (c_dim, in C definition: starting from zero, from the slowest dimension), by finding the number of pixels along that dimension after median absolute deviation (MAD) clipping. Since MAD-clipping involves sorting, this operator benefits from many threads (which needs to be set with numthreads). For more on minmapsize and quietmmap see Memory management. For more on MAD-clipping, see MAD clipping.

Function:
gal_data_t *
gal_dimension_collapse_mclip_fill_number (gal_data_t *in, size_t c_dim, float multip, float param, size_t numthreads, size_t minmapsize, int quietmmap) ¶

Similar to gal_dimension_collapse_mclip_number, but with filled re-clipping (see Contiguous outliers).

Function:
size_t
gal_dimension_remove_extra (size_t ndim, size_t *dsize, struct wcsprm *wcs) ¶

Remove extra dimensions (those that only have a length of 1) from the basic size information of a dataset. If the total number of elements (in all dimensions) is 1, this function will not remove anything (because an “extra” is only meaningful when some dimensions have more than one element length).

ndim is the number of dimensions and dsize is an array with ndim elements containing the size along each dimension in the C dimension order. When wcs!=NULL, the respective dimension will also be removed from the WCS.

This function will return the new number of dimensions and the dsize elements will contain the length along each new dimension.

Function-like macro: GAL_DIMENSION_NEIGHBOR_OP (index, ndim, dsize, connectivity, dinc, operation) ¶

Parse the neighbors of the element located at index and do the requested operation on them. This is defined as a macro to allow easy definition of any operation on the neighbors of a given element without having to use loops within your source code (the loops are implemented by this macro). For an example of using this function, please see Library demo - inspecting neighbors. The input arguments to this function-like macro are described below:

index

Distance of this element from the first element in the array on a contiguous patch of memory (starting from 0), see the discussion above.

ndim

The number of dimensions associated with the contiguous patch of memory.

dsize

The full array size along each dimension. This must be an array and is assumed to have the same number elements as ndim. See the discussion under the same element in Generic data container (gal_data_t).

connectivity

Most distant neighbors to consider. Depending on the number of dimensions, different neighbors may be defined for each element. This function-like macro distinguish between these different neighbors with this argument. It has a value between 1 (one) and ndim. For example, in a 2D dataset, 4-connected neighbors have a connectivity of 1 and 8-connected neighbors have a connectivity of 2. Note that this is inclusive, so in this example, a connectivity of 2 will also include connectivity 1 neighbors.

dinc

An array keeping the length necessary to increment along each dimension. You can make this array with the following function. Just do not forget to free the array after you are done with it:

size_t *dinc=gal_dimension_increment(ndim, dsize);
free(dinc);

dinc depends on ndim and dsize, but it must be defined outside this function-like macro since it involves allocation to help in performance.

operation

Any C operation that you would like to do on the neighbor. This macro will provide you a nind variable that can be used as the index of the neighbor that is currently being studied. It is defined as ‘size_t ndim;’. Note that operation will be repeated the number of times there is a neighbor for this element.

This macro works fully within its own {} block and except for the nind variable that shows the neighbor’s index, all the variables within this macro’s block start with gdn_.