grid-utils package

Introduction and Background

This library is built on top of Liam Healy’s antik/grid library. It contains utilities that are not already present in the “map-grid-utils” and “sequence-grid” libraries.

The library has the following types of routines

• grid io (input only so far)
• iterating functions for grids
• functions that manipulate grids
• functions that reduce grids

Several special variables control the behavior of the routines. The first two are from antik/grid.

*default-grid-type*

determines the type of grids, native CL, array, or foreign-array

*default-element-type*

determines the float type stored in grids, single-float or double-float

*default-integer-type*

determines the integer type stored in grids, (unsigned-byte 32)

*default-complex-type*

determines the type of float that makes up complex variables, complex or (complex double-float)

As with grid, loading the foreign-array package prior to loading grid-utils enables the use of foreign arrays.

Functionality overview

This section is meant to provide a functionality overview (which can be improved), not a detailed documentation. For the documentation, consult the source code and the unit tests associated with each function (which can be improved).

Mapping with respect to CL functions

There is overlap between some of the functions, and that needs to be cleaned up.

Iterating functions

CL-name	Our name	Simple	-if	if-not
count	grid-count
find	find-row	M	M
	find-col	M	M
position	grid-position	V	V
	grid-positions	V	V/M
	position-nearest	V
	positions	V
	position-element	V
remove	remove-row	M	M
	remove-col	M	M
substitute	grid-substitute	M/V

Whole grid manipulations

reverse	reverse-vector	V
copy-seq
concatenate

Sorting and merging

sort
merge

Grid manipulations

subseq

Grid predicates

every
some
notany
notevery

All operations are non-destructive – the old grid is never modified. There are additional functions such as reverse-vector

Grid iterating functions

These are functions that iterate over a grid, and return a result based on grid contents, or modify a grid element. These are mostly inspired by CL’s sequence functions

Some of these duplicate functionality and may need to be cleaned

• grid-position, grid-position-if
• grid-positions
• position-nearest
• positions is similar to grid-position-if but does not accept the key argument
• position-element
• grid-substitute
• remove-row, remove-row-if
• remove-col, remove-col-if
• find-row, find-row-if
• find-col, find-col-if
• reverse-vector

Grid manipulations

• reform return a matrix filled with vector elements
• grid-coerce return a new grid with elements coerced to new type
• grid-bind is a macro that binds elements of a grid to variables

Mapping over grids

There are two types of mapping. In mappings of the first type, all arguments are must be vectors, and the result is built by applying the function to each element in turn.

Mappings of the second type are macros that allow for mappings over a mixture of vectors and scalars, or construct a matrix from a mapping over two vectors.

Mapping over matrix rows or columns

• reduce-vector reduces a vector
• reduce-columns loops over columns, reducing each. The result is a vector
• reduce-rows loops over rows, reducing each. The result is a vector
• map-rows maps a function over matrix rows, returning the result as a vector

Grid input/output

read-grid reads a grid from stream. It accepts generic or cvs files - see documentation

Coding Notes

Design goals

The calling and naming convention should follow CL, and not languages like IDL, Matlab, R, etc.

Status

The code is still in early development. Some stuff is missing. The calling and naming of functions is subject to change.

Testing

lisp-unit is used for testing and usage documentation.

Development platforms

I have developed this library on the following two platforms:

• CLISP on cygwin & windows
• SBCL on linux

The development and testing is not always in sync, and development on one platform may introduce bugs on the other that do eventually get fixed.