4.63 sddslocaldensity

• description: sddslocaldensity computes the local density of points in n-dimensional space for each point in the space.
• examples:
  sddslocaldensity <inputFile> <outputFile> -columns=none,x,y -kde=bins=40 -threads=20  
      

• synopsis:
  sddslocaldensity [<inputfile>] [<outputfile>] [-pipe=[input][,output]] [-threads=<number>]  
  {-fraction=<value> | -spread=<value> |  
   -kde=bins=<number>[,gridoutput=<filename>][,nsigma=<value>][,explimit=<value>]  
        [,sample=<fraction>|use=<number>]}  
  -columns=<normalizationMode>,<name>[,...] [-output=<columnName>] [-verbose]  
      

• files: The input file contains a collection of points in n-dimensional space, defined by named columns. The output file contains the same data, but with an additional column LocalDensity that gives the density of points in the vicinity of each point.
• switches:
  • -pipe[=input] — The standard SDDS Toolkit pipe option.
  • -columns={none|range|rms},<column1Name>,<column2Name>... — Specifies the normalization mode and column names for analysis. Note that the normalization mode is irrelevant when -fraction, -spread, or -kde options are used.
  • -fraction, -spread, -kde — Specify the calculation mode, if different from the default. Note that all methods except the KDE method show N² growth in run time, where N is the number of points.
    • By default, the “local density” for each point is the inverse of the mean distance to all other points.
    • For -fraction=f mode, the “local density” for each point is the number of points inside a distance d_i in dimension i, where d_i = f * (max(x_i) - min(x_i)).
    • For -spread=f mode, the “local density” for each point is the sum over all other points of the product of unnormalized gaussian spread functions in each dimension, where the gaussian parameter is σ = f * (max(x_i) - min(x_i)). Since the gaussians are unnormalized, the result is roughly the number of nearby points.
    • -kde=bins=<number>[,gridoutput=<filename>][,nsigma=<value>][,explimit=<value>][,sample=<fraction>use=¡number¿]— — Performs Kernel Density Estimation in n dimensions using the given number of bins in all dimensions, using Silverman’s method to estimate the bandwidth in each dimension. The gridOutput qualifier results in writing the density map to the named file. The nsigma qualifier specifies truncation of contributions to the density outside the given number of bandwidths; it defaults to 5. The explimit qualifier specifies a cutoff in the magnitude of e^-z2∕2 for including contributions to the density; it defaults to 10^-16. Setting nsigma to a smaller value and explimit to a larger value can significantly reduce run time with little impact on accuracy. The sample and use qualifiers allow reducing the number of input points used for computing the density map; this again can significantly reduce run time and may have little impact on results if the number of input points is large; regardless of this setting, the estimated local density is output for every input point.
  • -threads=<number> — Specify the number of threads to use for KDE-based computations. Defaults to 1. The speed-up is best when the number of KDE bins is relatively small or the number of dimensions is relatively small.
  • -outputColumn=<name> — Gives the name of the output column containing the “local density.” Defaults to LocalDensity.
  • -verbose — If given, provides informational output during execution.
• author: M. Borland, ANL/APS.