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_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_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_number**`*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:

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

`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_`

.

JavaScript license information

GNU Astronomy Utilities 0.20 manual, April 2023.