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