NCL Home > Documentation > Functions > General applied math

dim_pqsort_n

Computes the permutation vector generated by sorting the given dimension.

Prototype

	function dim_pqsort_n (
		x       : integer, float or double,  
		kflag   : integer,                   
		dim [1] : 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.

dim

The dimension of x of which sort across.

Return value

Returns an integer array dimensioned the same size as x.

Description

This function returns the permutation array generated by sorting the dim-th 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 dim-th location in the sorted order.

Examples

Example 1

This is a simple example that sorts a 2D array three different ways:

In increasing order on the rightmost dimension
In increasing order on the leftmost dimension
In decreasing order on the leftmost dimension

This example uses write_matrix to write out a nice formatted matrix to the screen.

 xorig = (/ (/3,2,1/), (/5,4,6/)/)

 opt = True

 x = xorig
 opt@title  = "Before sorting on rightmost dimension, increasing"
 write_matrix(x, "3I4", opt)

 ii_rgt = dim_pqsort_n(x,2,1)

 opt@title  = "After sorting on rightmost dimension, increasing"
 write_matrix(x, "3I4", opt)

 opt@title  = "Index vector"
 write_matrix(ii_rgt, "3I4", opt)

;---Sort leftmost dimension of x in INCR order
 x = xorig
 opt@title  = "Before sorting on leftmost dimension, increasing"
 write_matrix(x, "3I4", opt)

 ii_lft = dim_pqsort_n(x,2,0)

 opt@title  = "After sorting on leftmost dimension, increasing"
 write_matrix(x, "3I4", opt)

 opt@title  = "Index vector"
 write_matrix(ii_lft, "3I4", opt)

;---Sort leftmost dimension of x in DECR order
 x = xorig
 opt@title  = "Before sorting on leftmost dimension, decreasing"
 write_matrix(x, "3I4", opt)

 ii_lft = dim_pqsort_n(x,-2,0)

 opt@title  = "After sorting on leftmost dimension, decreasing"
 write_matrix(x, "3I4", opt)

 opt@title  = "Index vector"
 write_matrix(ii_lft, "3I4", opt)

Expected output:

 Before sorting on rightmost dimension, increasing
   3   2   1
   5   4   6
  
 After sorting on rightmost dimension, increasing
   1   2   3
   4   5   6
  
 Index vector
   2   1   0
   1   0   2
  
 Before sorting on leftmost dimension, increasing
   3   2   1
   5   4   6
  
 After sorting on leftmost dimension, increasing
   3   2   1
   5   4   6
  
 Index vector
   0   0   0
   1   1   1
  
 Before sorting on leftmost dimension, decreasing
   3   2   1
   5   4   6
  
 After sorting on leftmost dimension, decreasing
   5   4   6
   3   2   1
  
 Index vector
   1   1   1
   0   0   0

Example 2

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

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

Note: when operating across the rightmost dimension, it is simpler to use dim_pqsort.

Example 3

Define ip = dim_pqsort_n(x, 1, 0) (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 4

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