Miscellaneous Functions

Table of Contents

  1. Introduction
  2. color_wheel(n,v,b)
  3. cv(main_nao[,dim_number])
  4. derivative(a[,dim_number])
  5. fill_holes(x)
  6. fuzzy_floor(x[,eps])
  7. fuzzy_ceil(x[,eps])
  8. gets_matrix(filename)
  9. head(x[,n])
  10. hsv2rgb(hsv)
  11. isMissing(x)
  12. isPresent(x)
  13. magnify_interp(a, mag_factor)
  14. mixed_base(x,b)
  15. nub(x)
  16. outer(dyad,y[,x])
  17. scattered2grid(xyz,ycv,xcv)
  18. scaleAxis(xstart,xend[,nmax[,nice]])
  19. scaleAxisSpan(xstart,xend[,nmax[,nice]])
  20. range(a)
  21. tail(x[,n])

Introduction

The following functions are defined in the file nap_function_lib.tcl.

color_wheel(n,v,b)

Square containing color wheel.
n is number rows & columns
v is desired "value" level
b is background colour outside circle

Example:
nap "color_wheel(100,255,3#150)"
This produces a u8 array with shape {3 100 100} & values from 0 to 255.

cv(main_nao[,dim_number])

This is simply an alias for coordinate_variable.

derivative(a[,dim_number])

Estimate derivative along dimension dim_number (default is 0) of array a. The result has the same shape as a.

Example (assuming vector has dimension (& coordinate variable) time: 

derivative(vector); # result is derivative with respect to time

Examples (assuming matrix has dimensions latitude & longitude): 

derivative(matrix, 'latitude');	# result is derivative with respect to latitude
derivative(matrix, 0);		# result is derivative with respect to latitude
derivative(matrix);		# result is derivative with respect to latitude
derivative(matrix,'longitude');	# result is derivative with respect to longitude
derivative(matrix, 1);		# result is derivative with respect to longitude

Based on quadratic through 3 points (provided size of dimension is > 2 -- if only 2 then based on straight line). These always include the point corresponding to the result. For interior points, the other 2 are the closest neighbour on each side. For boundry points, these are the 2 closest neighbours.

Let D(x) be the derivative of quadratic through points (x0,y0), (x1,y1), (x2,y2). 

D1 = D(x1) = a0 * y0 + a1 * y1 + a2 * y2
where the coefficients a0, a1, a2 are defined by:
	a0 = (x1 - x2) / ((x1 - x0) * (x2 - x0))
	a1 = 1 / (x1 - x0) - 1 / (x2 - x1)
	a2 = (x1 - x0) / ((x2 - x0) * (x2 - x1))

fill_holes(x)

Replace missing values by estimates based on means of neighbours.

fuzzy_floor(x[,eps])

Like floor() except allow for rounding error.
eps is tolerance and defaults to 1e-9.

Example:
% [nap "fuzzy_floor({4.998 4.9998},1e-3)"]
4 5

fuzzy_ceil(x[,eps])

Like ceil() except allow for rounding error.
eps is tolerance and defaults to 1e-9.

Example:
% [nap "fuzzy_ceil({5.002 5.0002},1e-3)"]
6 5

gets_matrix(filename)

Read text file and return NAO matrix whose rows correspond to the lines in the file. Ignore blank lines and lines whose first non-whitespace character is '#'.

Example:
gets_matrix('my_matrix.txt')

head(x[,n])

If n ≥ 0 then result is 1st n elements of x, cycling if n > nels(x).
n defaults to 1.
If n < 0 then result is 1st nels(x)+n elements of x i.e. drop −n from end

Example: 

% [nap "head({3 1 9 2 7})"]
3
% [nap "head({3 1 9 2 7}, 2)"]
3 1
% [nap "head({3 1 9 2 7}, -2)"]
3 1 9

hsv2rgb(hsv)

Convert colour in HSV form to RGB.
hsv is an array whose leading dimension has size 3.

Layer 0 along this dimension corresponds to hue as an angle in degrees. Angles of any sign or magnitude are allowed. Red = 0, yellow = 60, green = 120, cyan = 180, blue = −120, magenta = −60.

Layer 1 along this dimension corresponds to saturation in range 0.0 to 1.0.

Layer 2 along this dimension corresponds to "value". This has the same range as the RGB values, normally either 0.0 to 1.0 or 0 to 255. If you are casting the result to an integer & want a maximum of 255 then set the maximum to say 255.999. Otherwise you will get few if any 255s.

The result has the same shape as the argument (hsv).

See Foley, vanDam, Feiner and Hughes, Computer Graphics Principles and Practice, Second Edition, 1990, ISBN 0201121107 page 593.

Example:
% [nap "hsv2rgb {180.0 0.5 100.0}"]
50 100 100

isMissing(x)

1 if x missing, 0 if present.

Example:
% [nap "isMissing {0 _ 9}"]
0 1 0

isPresent(x)

0 if x missing, 1 if present.

Example:
% [nap "isPresent {0 _ 9}"]
1 0 1

magnify_interp(a, mag_factor)

Magnify each dimension of array a by factor defined by the corresponding element of mag_factor if this is a vector. If this is a scalar then every dimension is magnified by the same factor. The new values are estimated using multi-linear interpolation.

This function can be used to make images larger or smaller.

Example:
% [nap "magnify_interp({{1 2 3}{4 5 6}}, {1 3})"] value
1.00000 1.33333 1.66667 2.00000 2.33333 2.66667 3.00000
4.00000 4.33333 4.66667 5.00000 5.33333 5.66667 6.00000

magnify_nearest(a, mag_factor)

This function is similar to magnify_interp except that the new values are defined by the nearest neighbour rather than interpolation.

Example:
% [nap "magnify_nearest({{1 2 3}{4 5 6}}, {1 3})"] value
1 1 2 2 2 3 3
4 4 5 5 5 6 6

mixed_base(x,b)

Convert scalar value x to mixed base defined by vector b.

Following example converts 87 inches to yards, feet & inches:
% [nap "mixed_base(87, {3 12})"]
2 1 3

nub(x)

Result is vector of distinct values in argument (in same order).

outer(dyad,y[,x])

Tensor outer-product.

dyad is name of either

  • function with two arguments
  • binary (dyadic) operator
    x is vector
    y is vector defaulting to x
    Result is cross-product of x and y, applying dyad to each combination of x & y.
    x & y are the coordinate variables of the result.

    Following example produces a multiplication table: 

    % [nap "outer('*', 1 .. 5)"]
 1  2  3  4  5
 2  4  6  8 10
 3  6  9 12 15
 4  8 12 16 20
 5 10 15 20 25

    scattered2grid(xyz,ycv,xcv)

    Produce a matrix grid from scattered (x,y,z) data using triangulation. Grid points within each triangle are defined by interpolating using a plane through the three vertices of the triangle.

    xyz is an n×m matrix containing data corresponding to n points (x,y,z). The number of columns (m) must be at least 3. Columns 0, 1 and 2 contain x, y and z values respectively. Any further columns are ignored.

    ycv and xcv specify the coordinate-variables for the grid.

    The following example defines a grid from the four points (2,2,0), (6,4,0), (2,4,4) and (4,5,3). Note that the missing values in the result correspond to points which are outside of both the triangles produced by the triangulation. You could eliminate these missing values by defining values at all four corners of the grid. 

    % nap "z = scattered2grid({{2 2 0}{6 4 0}{2 4 4}{4 5 3}}, 2 .. 5, 2 .. 6)"
::NAP::1020-1020
% $z
0.00    _    _    _    _
2.00 0.75 0.00    _    _
4.00 2.50 1.50 0.75 0.00
   _    _ 3.00    _    _
% [nap "z(@2, @2)"]; # Check value at x=2, y=2
0
% [nap "z(@4, @6)"]; # Check value at x=6, y=4
0
% [nap "z(@4, @2)"]; # Check value at x=2, y=4
4
% [nap "z(@5, @4)"]; # Check value at x=4, y=5
3

    scaleAxis(xstart,xend[,nmax[,nice]])

    Find suitable values for axis of graph.
    xstart: 1st data value
    xend: Final data value
    nmax: Max. allowable number of elements in result (Default: 10)
    nice: Allowable increments (Default: {1 2 5})
    Result is the arithmetic progression which:
  • is within interval from xstart to xend
  • has same order (ascending/descending) as xstart//xend
  • has increment equal to element of nice times a power (-30 .. 30) of 10
  • has at least two elements
  • has no more than nmax elements if possible
  • has as many elements as possible. (Ties are resolved by choosing earlier element in nice.)

    Example:
    % [nap "axis = scaleAxis(-370, 580, 10, {10 20 25 50})"] value
    -300 -200 -100 0 100 200 300 400 500

    scaleAxisSpan(xstart,xend[,nmax[,nice]])

    Find suitable values for axis of graph.
    xstart: 1st data value
    xend: Final data value
    nmax: Max. allowable number of elements in result (Default: 10)
    nice: Allowable increments (Default: {1 2 5})
    Result is the arithmetic progression which:
  • includes the interval from xstart to xend
  • has same order (ascending/descending) as xstart//xend
  • has increment equal to element of nice times a power (-30 .. 30) of 10
  • has at least two elements
  • has no more than nmax elements if possible
  • has as many elements as possible. (Ties are resolved by choosing earlier element in nice.)

    Example:
    % [nap "axis = scaleAxisSpan(-370, 580, 10, {10 20 25 50})"] value
    -400 -200 0 200 400 600

    range(a)

    Result is 2-element vector containing minimum and maximum of array a.
    Example:
    % [nap "range {{9 -1 -5}{2 9 3}}"]
    -5 9

    tail(x[,n])

    If n ≥ 0 then result is final n elements of x, cycling if n > nels(x).
    n defaults to 1.
    If n < 0 then result is final nels(x)+n elements of x i.e. drop −n from start.

    Example: 

    % [nap "tail({3 1 9 2 7})"]
7
% [nap "tail({3 1 9 2 7}, 2)"]
2 7
% [nap "tail({3 1 9 2 7}, -2)"]
9 2 7

    Author: Harvey Davies       © 2002, CSIRO Australia.       Legal Notice and Disclaimer
    CVS Version Details: $Id: nap_function_lib.html,v 1.7 2004/07/19 00:10:49 dav480 Exp $