# SPHERESORT is the jMap module of jLab.

``` SPHERESORT  Sorted great circle distances to nearby points on the earth.

Computing great circle distances on the earth between two sets of
points --- data points and a fixed grid, say --- is computationally
expensize.  SPHERESORT speeds this up substantially.

[DS,XS,YS]=SPHERESORT(LAT,LON,LATO,LONO,CUTOFF) returns the great
circle distances DS between data points at locations LAT, LON and
nearby grid points located at LATO, LONO, sorting in order of distance.

XS and YS are the corresponding coordinates of the sorted data points
in a local tangent plane about each grid point.

LAT and LON are arrays of the same size into data point locations.
Any NaN values in LAT/LON are ignored.

LATO and LONO are arrays of length M and N, say, specifying the
latitudes and longitudes of an M x N matrix of grid points, i.e.

LATO =  [LATO_1;    LONO= [LONO_1 LONO_2 ... LONO_N].
LATO_2;
...
LATO_M]

SPHERESORT only computes distances for nearby points, up to a distance
of CUTOFF, which is given in kilometers.  CUTOFF should be less than
1/4 of the circumference of the earth, RADEARTH * PI/2, so that sorted
(LAT,LON) points will lie in the same hemisphere as the grid points.

The output arrays are M numerical arrays arranged as a length M cell
array.  That is, there is one cell per latitude band. Each numerical
array has N columns, i.e., the number of longitudes, with the number of
rows varying between arrays.

DS gives the distances of data points less than CUTOFF kilometers
from the (m,n)th grid point, sorted in order of increasing distance.
Entries farther than CUTOFF in all output fields are filled with NaNs.

XS and YS give the coordinates, in kilometers, of the corresponding
data points in a plane tangent to the (m,n)th grid point.

The choice to put latitude bands into cell arrays is made because the
number of points less than CUTOFF distance tends to vary with latitude,
and for convenience in parallelizing POLYSMOOTH.
_________________________________________________________________

Limiting output dimension

SPHERESORT(LAT,LON,LATO,LONO,[CUTOFF JMAX]), where the fifth input
argument is a 2-vector, additionally specifies that number of rows of
in each cell of the output will be no larger than JMAX.  This option is
useful for the 'fixed population' algorithm in POLYSMOOTH.
_________________________________________________________________

SPHERESORT(...,'mask',BOOL,...), where BOOL is a boolean array with
LENGTH(LATO) rows and LENGTH(LONO), only returns DS, XS, and YS at
points for which BOOL is true.  Where BOOL is false, the output arrays
will consist of all NaNs.

This is useful in preventing SPHERESORT from sorting data for locations
one has no intention of mapping.  For example, in creating a map of an
oceanic quantity, BOOL would be set to false for all land grid points.
_________________________________________________________________

Let's say some additional variables Z1, Z2,...,ZK are given at
the data locations LAT, LON.  Then

[DS,XS,YS,Z1S,Z2S,...,ZKS]=
SPHERESORT(LAT,LON,Z1,Z2,...,ZK,LATO,LONO,CUTOFF);

also returns the sorted values of these variables.

Z1D, Z2D,...,ZKD are the same size as the other output arguments, and
give the values of Z1, Z2,...,ZK sorted according to distance.
_________________________________________________________________

Outputting an index

[DS,XS,YS,INDEXS]=SPHERESORT(LAT,LON,LATO,LONO,CUTOFF), with no
additional input arguments, returns a cell array of indices, INDEXS,
which is the same size as the other output fields.  This can be used
together with POLYSMOOTH_EXTRACT to find sorted field values.

If there are many fields to be mapped all using the same grid, this
approach is preferred to directly inputting Z1, Z2,...,ZK as in the
previous step.  Instead the ZK would be output by POLYSMOOTH_EXTRACT.

For details, see the "One grid, many fields" section in POLYSMOOTH.
_________________________________________________________________

Parellel algorithm

SPHERESORT(...'parallel') parallelizes the computation using a parfor
loop over latitudes, which can speed things up dramatically.  This
requires Matlab's Parallel Computing Toolbox to be installed.

SPHERESORT will then using an existing parallel pool, or if one does
not exist, a pool will be created using all availabale workers.

SPHERESORT(...'parallel',Nworkers) alternately specifies the number of
workers to use. If you run into memory constraints, reduce Nworkers.
_________________________________________________________________