NCL Home > Documentation > Functions > General applied math

dim_pqsort

Computes the permutation vector generated by sorting the n - 1th (rightmost) dimension.

Prototype

	function dim_pqsort (
		x      : integer, float or double,  
		kflag  : integer                    
	)

	return_val [dimsizes(x)] :  integer

Arguments

An integer, float, or double array of any dimensionality

kflag

2 - return the permutation vector resulting from sorting x in increasing order and sort x also.
1 - return the permutation vector resulting from sorting x in increasing order and do not sort x.
-1 - return the permutation vector resulting from sorting x in decreasing order and do not sort x.
-2 - return the permutation vector resulting from sorting x in decreasing order and sort x also.

Return value

Returns an integer array dimensioned the same size as x.

Description

This function returns the permutation array generated by sorting the rightmost (n - 1th) dimension of the x array and, optionally, rearranging the elements of the array. The array will be sorted in increasing or decreasing order. A slightly modified quicksort algorithm is used.

Ignoring missing values is not supported; they are sorted to either end of the array based on their actual value.

The output permutation array will be the index of the value in the original order of the x array; that is, in the i-th location in the sorted order.

Use dim_pqsort_n if you want to specify which dimension to do the average across.

Examples

Example 1

Let x be an array of length ntim. Generate a permutation vector in

ascending order, do not sort x:
```
ip = dim_pqsort(x, 1)
```
descending order, do not sort x:
```
ip = dim_pqsort(x, -1)
```
ascending order, sort x also:
```
ip = dim_pqsort(x, 2)
```
descending order, sort x also:
```
ip = dim_pqsort(x, -2)
```

Example 2

Define ip = dim_pqsort(x, 1) (ascending order, do not sort x) and it is desired to reorder a different array (say, y) using the permutation vector associated with x. Assume y(ntim, nlat, mlon) with named dimensions and coordinate variables "time", "lat" and "lon". Then:

  y2 = y                ; create y2 with attribute, coordinate values
  y2 = y(ip, :, :)      ; y2 will contain the values of "y"
                        ; rearranged according to the permutation
                        ; vector associated with x. 
  y2&time = y&time(ip)  ; reorder the time coordinate variable

Example 3

Define x(ntim, nlat, mlon) with named dimensions "time","lat", "lon". Then:

  ip = dim_pqsort(x(lat|:, lon|:, time|:), 1) ; ===> ip(nlat, mlon, ntim)

  ip = dim_pqsort_n(x, 1, 0)                  ; no reordering needed

Note: you need to be careful about reordering your array in the call to this function. As long as you don't want the function to reorder the original array itself, you should be okay.

However, if you want the original array reordered, you will need to reorder the array and save it to a temporary variable, pass this temporary variable to the function, and then reorder the temporary variable again.

  xtmp = x(lat|:, lon|:, time|:)
  ip   = dim_pqsort(xtmp, 2) ; ===> ip(nlat, mlon, ntim)
  x    = xtmp(time|:, lat|:, lon|:)

Or, preferably, just use dim_pqsort_n:

  ip = dim_pqsort_n(x, 2, 0)                  ; no reordering needed

Example 4

Generate 1000 series of length 30 with unique ordering.

  random_setallseed(363738674, 918273645)   ; Set seeds (NOT required)

  nvals = 30
  narr  = 1000

;---Generate 1000 x 30 random numbers
  r = random_uniform(0,1,(/narr,nvals/))  ; random numbers

;---Sorting the values and keeping the indexes gives us random indexes.
  indexes = dim_pqsort(r, 1)             ; use in 30 element segments

;--- concise print for illustration
  do i=0,narr-1
    str = ""
    do j=0,nvals-1
      str = str + " " + indexes(i,j)
    end do
    print("" + str)
  end do

Sample 'indexes'