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.
    _________________________________________________________________
  
    Masking out non-mapping points
 
    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.
    _________________________________________________________________
  
    Additional input parameters
 
    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.
    _________________________________________________________________
 
    See also TWODSORT, POLYSMOOTH.
 
    'spheresort --t' runs a test.
 
    Usage: [ds,xs,ys,indexs]=spheresort(lat,lon,lato,lono,cutoff);
           [ds,xs,ys]=spheresort(lat,lon,lato,lono,cutoff,'mask',bool);
           [ds,xs,ys,z1s,z2s]=spheresort(lat,lon,z1,z2,lato,lono,cutoff);
    __________________________________________________________________
    This is part of JLAB --- type 'help jlab' for more information
    (C) 2008--2020 J.M. Lilly --- type 'help jlab_license' for details

contents | allhelp | index