4.46 sddsgroupedenvelope

• description: sddsgroupedenvelope processes pages from SDDS files in a directory, groups the pages by a parameter value, and writes an output file with one page for each group. Each output page contains the requested row-by-row quantities across pages for selected columns. It is intended for cases where separate envelope files would otherwise be made for many groups; it avoids temporary SDDS files and can read multiple input files concurrently.
• examples: Make grouped PSD envelopes for selected files:
  sddsgroupedenvelope -inputDir 2024/09/10 -pattern "PSD-00:0*" \  
    -groupBy=PSName -copy=f -maximum=SqrtIntegPsdCurrent \  
    -minimum=SqrtIntegPsdCurrent -mean=SqrtIntegPsdCurrent \  
    -output 2024/09/10/PSD-envelope.final  
    

• synopsis:
  sddsgroupedenvelope [-inputDir directory] [-pattern pattern]  
                      [-groupBy parameter] [-groupValue value]  
                      [-output file] [-copy=columnNames]  
                      [-maximum=columnNames] [-minimum=columnNames]  
                      [-mean=columnNames] [-largest=columnNames]  
                      [-signedLargest=columnNames]  
                      [-sum=power,columnNames] [-rms=columnNames]  
                      [-standardDeviations=columnNames] [-sigma=columnNames]  
                      [-wmean=weightColumn,columnNames]  
                      [-wstandardDeviations=weightColumn,columnNames]  
                      [-wrms=weightColumn,columnNames]  
                      [-wsigma=weightColumn,columnNames]  
                      [-cmaximum=independentColumn,columnNames]  
                      [-cminimum=independentColumn,columnNames]  
                      [-pmaximum=independentParameter,columnNames]  
                      [-pminimum=independentParameter,columnNames]  
                      [-slope=independentParameter,columnNames]  
                      [-intercept=independentParameter,columnNames]  
                      [-exmmMean=columnNames]  
                      [-majorOrder={row|column}] [-noOverwrite]  
                      [-threads=number]  
                      [-nowarnings] [-verbose]  
    

• switches:
  • -inputDir \emph{directory} — Specifies the directory containing input files. The default is the current working directory.
  • -pattern \emph{pattern} — Specifies an input glob pattern relative to -inputDir. This option may be repeated. The default patterns are PSD-*.xz and PSD-*.gz.
  • -groupBy \emph{parameter} — Specifies the parameter used to group pages. The default is PSName.
  • -groupValue \emph{value} — Specifies a group value to include. This option may be repeated. If omitted, all group values found in the input files are included.
  • -output \emph{file} — Specifies the output file. Relative paths are resolved against the current working directory, not -inputDir. The default is PSD-envelope.sdds.
  • -copy=\emph{columnNames} — Copies the named columns from the first accepted page of each group.
  • -maximum=\emph{columnNames}, -minimum=\emph{columnNames}, -mean=\emph{columnNames}, -largest=\emph{columnNames}, -signedLargest=\emph{columnNames}, -rms=\emph{columnNames}, -standardDeviations=\emph{columnNames}, -sigma=\emph{columnNames}, -exmmMean=\emph{columnNames} — Specifies row-by-row statistics to compute across pages for the named columns.
  • -sum=\emph{power},\emph{columnNames} — Computes the row-by-row sum of the named column values raised to the indicated integer power.
  • -wmean=\emph{weightColumn},\emph{columnNames}, -wstandardDeviations=\emph{weightColumn},\emph{columnNames}, -wrms=\emph{weightColumn},\emph{columnNames}, -wsigma=\emph{weightColumn},\emph{columnNames} — Computes weighted row-by-row statistics using the named weight column.
  • -cmaximum=\emph{independentColumn},\emph{columnNames}, -cminimum=\emph{independentColumn},\emph{columnNames} — For each named column and row, records the independent column value from the page containing the maximum or minimum value.
  • -pmaximum=\emph{independentParameter},\emph{columnNames}, -pminimum=\emph{independentParameter},\emph{columnNames} — For each named column and row, records the independent parameter value from the page containing the maximum or minimum value.
  • -slope=\emph{independentParameter},\emph{columnNames}, -intercept=\emph{independentParameter},\emph{columnNames} — Computes a row-by-row linear fit of the named columns against the independent parameter.
  • -majorOrder={row|column} — Specifies the output data order. The default is column-major order.
  • -threads=\emph{number} — Specifies the number of input files to read concurrently. The default is 1. At most this many per-file accumulators are kept before being merged and freed. Results are merged in sorted input-file order, so output ordering and first-page choices remain deterministic.
  • -noOverwrite — Refuses to replace an existing output file.
  • -nowarnings — Suppresses warnings about degenerate weighted statistics.
  • -verbose — Prints details about input files and row-count selection.
• files: Input files are selected by applying each -pattern in -inputDir. Each input file may contain pages for multiple group values, but a group value may not appear more than once in the same input file. The output contains one page per group value and is written as a binary SDDS file. At least one statistic option must be supplied; no statistics are computed by default. Exact median, percentile, and decile-range statistics are not implemented because they require retaining page histories.
• see also:
  • sddsenvelope()
  • sddscombine()
• author: R. Soliday, ANL/APS.