4.32 sddscontour

• description: sddscontour makes contour and color-map plots from an SDDS data set column, array data, or from a rpn expression in terms of the values in the columns of a data set. It supports FFT interpolation and filtering and also provides -columnmatch and waterfall modes for plotting multiple columns or pages. If the data set contains more than one data page, data from successive pages is plotted on separate pages.
• examples: This will generate a two-dimensional color-shaded map of the function sin(4π(x² + y²)) on the region x:[-1, 1] and y:[-1, 1]:
  sddscongen example.sdds -xRange=-1,1,101 -yRange=-1,1,101 \  
    -zEquation="x x * y y * + 4 * pi * sin"  
  sddscontour example.sdds -shade -equalaspect  
    

• synopsis:
  sddscontour [-pipe[=input][,output]] [<inputfile>] [options]  
    

• switches:
  • Choice of what to plot and data source:

    [ -quantity=columnName | -equation=rpnExpression[,algebraic] | -columnmatch=indepColumnName,matchingExpression | -waterfall=parameter=<parameter>,independentColumn=<xColumn>, colorColumn=<colorColumn>[,scroll=vertical|horizontal]] [-array=<zArray>[,<xArray>,<yArray>]] [-swaparray] [-xyz=xColumnName,yColumnName,zColumnName]

    • quantity — Specifies the name of the column to make a contour or color map of.
    • equation — Specifies a rpn expression to make a contour or color map of. The expression may refer to the values in the columns by the appropriate column name, and may also refer to the variable values by name. Adding algebraic allows the expression to be given in standard algebraic form instead of RPN.
    • columnmatch — Specifies plotting of all columns matching matchingExpression as a function of the column indepColumnName. Each matching column is displayed as a horizontal color bar.
    • waterfall — Specifies plotting of colorColumn in all pages as a function of the independentColumn. The parameter in each page is displayed as horizontal or vertical (provided by the scroll) bar, the default is horizontal. The independentColumn should be the same in each page.
    • array — Reads data from an SDDS array named zArray. Optional one-dimensional arrays xArray and yArray may be given for axis values.
    • swaparray — Requests that the row and column order of array data be swapped.
    • xyz — Specifies the names of two independent columns xColumnName and yColumnName, along with a third dependent column zColumnName that is plotted as a function of the others. The x and y values must form a grid.

    In the case of the first two choices, the file must contain tabular data with at least one numeric column, which will be organized into a 2d array with R rows and C columns. By default, the values are assumed to come in row-major order (i.e., the file should contain a series of R sequences each containing the C values of a single row). The parameters of the 2d grid over which the plot is to be made are communicated to the program in one of two ways:

    1. The string parameters Variable1Name and Variable2Name contain the names of the x and y axis variables, which I’ll represent as x and y respectively. The program expects to find six more parameters, with names xMinimum, xInterval, and xDimension, and similarly for y. These parameters must be numeric, and contain the minimum value, the interval between grid points, and the number of points, respectively, for the dimension in question. The data must be arranged so that y varies fastest as the row in the file increases. Put another way, variable 1 is the row index and variable 2 is the column index.
    2. The numeric parameters NumberOfRows and NumberOfColumns contain the values of R and C, respectively.

    Use -v1v2preferred to force the first method to be used when both parameter sets are present.

  • rpn control:

    [-rpndefinitionsfiles=filename[,filename...]] [-rpnexpressions=setupExpression[,setupExpression...][,algebraic]] [-rpntransform=expression[,algebraic]]

    • rpndefinitionsfiles — Specifies the names of files containing rpn expressions to be executed before any other processing takes place.
    • rpnexpressions — Specifies rpn expressions to be executed before any other processing takes place, immediately after any definitions files. Adding algebraic treats the expressions as standard algebraic formulas.
    • rpntransform — Specifies an rpn expression applied to each data value after it is read. Use algebraic to supply the transform in algebraic form.
  • Data range control:

    [-fixedrange] [-showgaps]

    • fixedrange — Retains the initial data range for all pages, rather than recomputing it.
    • showgaps — Leaves regions with missing data unplotted rather than interpolated.
  • Shade and contour control:

    {-shade=number[,min,max,gray] | -contours=number[,min,max]} [-labelcontours=interval[,offset]] [-levellist=listOfLevels] [-limitlevels=minimum=<value>,maximum=<value>] [-mapshade=hue0,hue1]

    • shade — Specifies that a color (or grey-scale) map should be produced, with the indicated number of shades mapped onto the range from min to max. If min and max are not given, they are taken to be equal to the minimum and maximum data values.
    • contours — Specifies that contour lines should be drawn, with the indicated number of lines for the range from min to max. If min and max are not given, they are taken to be equal to the minimum and maximum data values.
    • labelcontours — Specifies that every interval^th contour line, starting with the offset^th line, should be labeled with the contour value.
    • levellist — Gives an explicit comma-separated list of contour or shade levels to use.
    • limitlevels — Restricts contour or shade levels to the specified range.
    • mapshade — Maps the shades from hue hue0 to hue1 instead of the default rainbow.
  • Image processing:

    [-interpolate=nx,ny[,floor | ceiling | antiripple]] [-filter=xcutoff,ycutoff]

    • interpolate — Specifies that the 2d map should be interpolated to have nx times more rows (or x grid points) and ny times more columns (or y grid points). Since FFTs are used to do the interpolation, the original number of grid points must be a power of 2, as must the factor. Giving a factor of 1 disables interpolation for the dimension in question. floor, ceiling, and antiripple specify image processing of the interpolated map. floor and ceiling respectively force values below (above) the minimum (maximum) value of the data to be set equal to that value. antiripple causes the map to be altered so that non-zero values in the new map between zero values on the original map are set to zero; this suppresses ripples that sometimes occur in regions where the data was originally all zero.
    • filter — Applies low-pass filters to the data with the specified normalized cutoff frequencies. The integer cutoff values give the number of frequencies starting at the Nyquist frequency that are to be eliminated.
  • Plot labeling:

    [-xlabel=string|@<parameter-name>[,scale=<value>][,edit=<string>]] [-ylabel=string|@<parameter-name>[,scale=<value>][,edit=<string>]] [-title=string|@<parameter-name>|filename[,edit=<string>]] [-topline=string|@<parameter-name>|filename[,edit=<string>][,format=<string>]] [-toptitle] [-nolabels] [-noscales] [-noborder] [-datestamp] [-fixfontsize[=all=.02][,legend=.015][,<x|y>xlabel=<value>][,<x|y>ticks=<value>][,title=<value>][,topline=<value>]]

    • xlabel, ylabel, title, topline — These specify strings to be placed in the various label locations on the plot. If @¡parameter-name¿ is provided, the value of the given parameter will be printed. If -topline=filename[,edit=¡string¿][,format=¡string¿] or -title=filename[,edit=¡string¿] option is provided, then the input file name or edited file name (if edit command is also provided) will be printed to the topline or title. The format qualifier allows a printf-style format for numeric parameter values in the topline.
    • toptitle — Requests that the title label be placed at the top of the plot, rather than at the bottom.
    • nolabels — Requests that no labels be placed on the plot.
    • noscales — Requests omission of the numeric scales.
    • noborder — Requests omission of the border around the data. Implies -noscales.
    • datestamp — Requests that the date and time be placed on the plot.
    • fixfontsize — Disables automatic font scaling and sets the font sizes explicitly.
  • Plot tick labeling (only valid for -columnmatch plots):

    [-xrange=minimum=value|@parameterName,maximum=value|@parameterName] [-yrange=minimum=value|@parameterName,maximum=value|@parameterName] [-xaxis=scaleValue=<value>|scaleParameter=<name>[,offsetValue=<number>|offsetParameter=<name>]] [-yaxis=scaleValue=<value>|scaleParameter=<name>[,offsetValue=<number>|offsetParameter=<name>]] [-ystrings=[edit=<editCommand>][,sparse=<integer>][,scale=<value>]] [-yeditstrings=<editCommand>]

    • xrange — Specifies the minimum and maximum value of the x axis. The value can be provided or obtained from parameters. If -xrange is provided, the independent column will be ignored.
    • yrange — Specifies the minimum and maximum value of the y axis. The value can be provided or obtained from parameters. If -yrange is provided, the y tick labels will be numerically labeled with the provided range.
    • xaxis — Sets scale and offset for x-axis tick labels using explicit values or parameter references. Labels are computed as index * scale + offset.
    • yaxis — Sets scale and offset for y-axis tick labels using explicit values or parameter references. Labels are computed as index * scale + offset.
    • ystrings — Controls the y tick labels, allowing optional editing, sparsity, and scaling.
    • yeditstrings — Provides an edit command for y tick labels; equivalent to using edit with -ystrings.

    For example, parameters origin1, delta1, max_ext1, origin2, delta2, and max_ext2 in sddscontour.input1 define the coordinate ranges. The first three give the minimum, spacing, and maximum of the x coordinate, while the latter three give the same for y. The Index column provides the x index so that x = Index * delta1 + origin1. Columns Ex˙n contain field values at y = (n-1)*delta2 + origin2. Without -xrange and -yrange the plot shows index values rather than coordinates:

    sddscontour sddscontour.input1 -columnmatch=Index,Ex* -ystrings=sparse=10 -ylabel=y -shade show_plot

    To remove the string portion of the y tick labels, use -ystrings:

    sddscontour sddscontour.input1 -columnmatch=Index,Ex* -ystrings=edit=%/Ex˙//,sparse=10 -ylabel=y -shade show_plot

    The previous plot still labels y with indexes. Supplying -yrange displays the actual y values:

    sddscontour sddscontour.input1 -columnmatch=Index,Ex* -yrange=minimum=@origin2,maximum=@max_ext2 -ylabel=y -shade show_plot

    To label the x axis with coordinate values, add -xrange:

    sddscontour sddscontour.input1 -columnmatch=Index,Ex* -yrange=minimum=@origin2,maximum=@max_ext2 -xrange=minimum=@origin1,maximum=@max_ext1 -xlabel=x -ylabel=y -shade show_plot

    In this case the independent column (Index) is redundant. The -xrange option allows contour plots of a set of columns without an explicit independent column. If sddsprocess is used to create an x column via x=Index * delta1 + origin1, the same plot results from

    sddscontour sddscontour.input1 -columnmatch=x,Ex* -yrange=minimum=@origin2,maximum=@max_ext2 -ylabel=y -shade show_plot

    These examples obtain xrange and yrange from parameters, but fixed values may also be given on the command line.

  • Data scaling:

    [-deltas[={fractional | normalize}]] [-logscale[=floor]] [-xlog]

    • deltas — For use with -columnmatch and -waterfall option. Specifies plotting only differential values (relative to the mean of each column). If the fractional qualifier is given, then the differential values normalized to the individual means are plotted. If the normalize qualifier is given, then all differential values are normalized to the range [-1, 1] before plotting.
    • logscale — Specifies plotting the base-10 logarithm of the values. If a floor value is given, it is added to each value prior to taking the logarithm; this can help prevent taking the log of zero, for example.
    • xlog — Plots the horizontal coordinate using a base-10 logarithmic scale.
  • Miscellaneous plot control:

    [-scales=xl,xh,yl,yh] [-swapxy] [-yflip] [-equalaspect[=-1,1]] [-layout=nx,ny] [-ticksettings=xytime] [-nocolorbar] [-thickness=integer] [-fillscreen] [-shapes=filename,xColumn,yColumn[,type=lineType][,thickness=value]] [-symbols=filename,xColumn,yColumn[,type=symbolType][,fill][,thickness=value][,scale=factor]] [-drawline={x0value=value | p0value=value | x0parameter=name | p0parameter=name}, {x1value=value | p1value=value | x1parameter=name | p1parameter=name}, {y0value=value | q0value=value | y0parameter=name | q0parameter=name}, {y1value=value | q1value=value | y1parameter=name | q1parameter=name}, [,linetype=integer][,thickness=integer][,clip]]

    • scales — Specifies the extent of the plot region.
    • swapxy — Requests that the horizontal and vertical coordinates be interchanged.
    • yflip — Reverses the vertical direction of the plot.
    • equalaspect — Requests plotting with an aspect ratio of 1. If the ’1’ qualifier is given, then the aspect ratio is achieved by changing the size of the plot region within the window; this is the default. If the ’-1’ qualifier is given, then the aspect ratio is achieved by changing the size of the plot region in user’s coordinates.
    • layout — Specifies that each page of the plot should have a nx by ny grid of contour plots.
    • ticksettings — Specify use of time mode for tick settings.
    • nocolorbar — Specify suppression of the color bar in -shade mode.
    • thickness — Sets the line thickness used for drawing.
    • fillscreen — Expands the plot to fill the entire screen.
    • shapes — Plots line shapes read from filename using columns xColumn and yColumn.
    • symbols — Plots symbols from filename using columns xColumn and yColumn.
    • drawline — Requests drawing of lines on the plot, using any combination of real coordinate values or plot-space values, either specified as literal values or drawn from parameters in the data file. Optional qualifiers linetype, thickness, and clip control the appearance and clipping of the line. Suitable for multi-page files.
  • Miscellaneous:

    [-pipe] [-device=name[,deviceArguments]] [-output=filename] [-verbosity[=level]] [-convertunits=column|parameter,<name>,<new-units-name>,<old-units-name>[,<factor>]]

    • pipe — Reads from the standard input and/or writes to the standard output.
    • device — Specifies the device name and optional device-specific arguments. Qt device arguments include -dashes <01¿—, -linetype <filename>, -movie 1 [-interval <sec>], -keep <number>, -share <name>, -timeoutHours <hours>, and -spectrum. png devices take rootname and template identifiers. rootname=string specifies a rootname for automatic filename generation; the resulting filenames are of the form rootname.DDD, where DDD is a three-digit integer. template=string provides a more general facility; one uses it to specify an sprintf-style format string to use in creating filenames. For example, the behavior obtained using rootname=name may be obtained using template=name.%03ld.
    • output — Requests SDDS output of a new file containing the data with any modifications resulting in the processing requested.
    • verbosity — Sets the verbosity level of informational printouts. Higher integer values of the level parameter result in more output.
    • convertunits — Converts the units of a named column or parameter to new units, applying an optional factor.
• see also:
  • sddscongen()
  • sddshist2d()
  • sddsimageconvert()
  • sddsimageprofiles()
  • sddsplot()
  • sddsspotanalysis()
  • rpn()
• author: M. Borland, ANL/APS.