4.55 sddshist

• description: sddshist does weighted and unweighted one-dimensional histograms of column data from an SDDS file. It also does limited statistical analysis of data, and basic filtering of data.
• examples: Make a 20-bin histogram of a series of PAR x beam-position-monitor readouts:
  sddshist par.bpm par.bpmhis -data=P1P1x -bins=20  
      

• synopsis:
  sddshist [-pipe=[input][,output]] [inputFile] [outputFile] \  
    -dataColumn=columnName [-bins=number | -sizeOfBins=value] \  
    [-lowerLimit=value] [-upperLimit=value] [-filter=columnName,lowerLimit,upperLimit] \  
    [-weightColumn=columnName] [-sides] [-normalize={sum | area | peak}] \  
    [-statistics] [-threads=number] [-verbose]  
      

• files: inputFile is the name of an SDDS file containing data to be histogrammed, along with optional weight data. If inputFile contains multiple data pages, each is treated separately. The histogram or histograms are placed in outputFile, which has two columns. One column has the same name as the histogrammed variable, and consists of equispaced values giving the centers of the bins. The other column, named frequency, contains the histogram frequencies. Its precise meaning is dependent on normalization modes and weighting. By default, it contains the number of data points in the corresponding bin.

  If requested, outputFile will also contain parameters giving statistics for the data being histogrammed. See below for details.

• switches:
  • -pipe[=input][,output] — The standard SDDS Toolkit pipe option.
  • -dataColumn=columnName — Specifies the name of the data column to be histogrammed.
  • -bins=number — Specifies the number of bins to use. The default is 20.
  • -sizeOfBins=value — Specifies the size of bins to use. The number of bins is computed from the range of the data.
  • -lowerLimit=value — Specifies the lower limit of the histogram. By default, the lower limit is the minimum value in the data.
  • -upperLimit=value — Specifies the upper limit of the histogram. By default, the upper limit is the maximum value in the data.
  • -filter=columnName,lowerLimit,upperLimit — Specifies the name of a column by which to filter the input rows. Rows for which the named data is outside the specified interval are discarded. Alternatively, one can use sddsprocess() to winnow data and pipe it into sddshist.
  • -weightColumn=columnName — Specifies the name of a column by which to weight the histogram. This means that data points with a higher corresponding weight value are counted proportionally more times in the histogram.
  • -sides — Specifies that zero-height bins should be attached to the lower and upper ends of the histogram. Many prefer the way this looks on a graph.
  • -normalize[={sum | area | peak}] — Specifies that the histogram should be normalized, and how. The default is sum. sum normalization means that the sum of the heights will be 1. area normalization means that the area under the histogram will be 1. peak normalization means that the maximum height will be 1.
  • -statistics — Specifies that statistics should be computed for the data and placed in outputFile. These presently include arithmetic mean, rms, and standard deviation. The parameters are named by appending the strings Mean, RMS, and StDev to the name of the data column. If -weightColumn is given, the statistics are weighted.
  • -threads=number — Specifies the number of threads for histogram binning and statistics calculations where applicable. The default is 1.
• see also:
  • Data for Examples
  • sddshist2d()
  • sddsprocess()
• author: M. Borland, ANL/APS.