#+title: ~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.