sddscontour

**description:**`sddscontour`

makes contour and color-map plots from an SDDS data set column, or from a`rpn`

expression in terms of the values in the columns of a data set. It supports FFT interpolation and filtering. If the data set contains more than one data page, data from successive pages is plotted on separate pages.**example:**This will generate a two-dimensional color-shaded map of the function 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 example.sdds -equalAspect**synopsis:**`sddscontour`*SDDSfilename**switches***switches:**- Choice of what to plot:
`[-quantity=`*columnName*| -equation=*rpnExpression*| -columnMatch=*indepColumnName*,*matchingExpression*| -waterfall=*parameter=<parameter>,independentColumn=<xColumn>,colorColumn=<colorColumn>[,scroll=vertical|horizontal]*]`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.`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.

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:

- 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*x*`Minimum`

,*x*`Interval`

, and*x*`Dimension`

, 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. - The numeric parameters
`NumberOfRows`

and`NumberOfColumns`

contain the values of R and C, respectively.

`rpn`

control:`[-rpnDefinitionsFiles=`*filename*[,*filename*...]] [-rpnExpressions=*setupExpression*[,*setupExpression*...]]`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.

- Shade and contour control:
`{-shade=`*number*[,*min*,*max*,gray] | -contours=*number*[,*min*,*max*]} [-labelContours=*interval*[,*offset*]]`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*contour line, starting with the*offset*line, should be labeled with the contour value.

- 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>*] [-yLabel=*string|@<parameter-name>*] [-title=*string|@<parameter-name>|file[,edit=<string>]*] [-topline=*string|@<parameter-name>|file[,edit=<string>]*] [-topTitle] [-noLabels] [-noScales] [-dateStamp]`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 given parameter will be printed; If*-topline=file[,edit=<string>]*or*-title=file[,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.`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`-no_scales`

.`dateStamp`

-- Requests that the date and time be placed on the pot.

- Plot tick labeling: (only valid for -columnMatch plot)
`[-xrange=mimum=`*value*|@*parameterName*,maximum=*value*|@*parameterName*] [-yrange=mimum=*value*|@*parameterName*,maximum=*value*|@*parameterName*] [-yaxis=scaleValue=<value>|scaleParameter=<name>[,offsetValue=<number>|offsetParameter=<name>]`xrange`

-- specifies the minimum and maximum value of x axis, the value can be provided or obtained from parameters. If -xrange is provided, the indepentColumn will be ignored.`yrange`

-- specifies the minimum and maximum value of y axis, the value can be provided or obtained from parameters. If -yrange is provided, the y tick labels will be numberically labeled with provided range.`yaxis`

-- specifies the scale and offset value of y axis, the value can be provided or obtained from parameters. Only one of the -yrange and -yaxis can be provided. If -yaxis is provided, the y tick labels will be numberically labeled with provided scale and offset.

**For example**,*origin1*,*delta1*,*max_ext1*,*origin2*,*delta2*and*max_ext2*are the parameters in sddscontour.input1 file,*origin1*,*delta1*and*max_ext1*represent the minimum, delta and maximum values of x coordinate,*origin2*,*delta2*, and*max_ext2*represents the minimum, delta and maximum values of y coordinate. The*Index*column represents the index of x coordinate, i.e. value of*x=Index * delta1 + origin1*; The Ex_*n*column represents the Ex field at*n*th y value, where*y=(n-1)*delta2 + origin2*. If no -xrange and -yrange provided as in following command, the actual value of x and y will not be shown in the plot. (click the show_plot button will show you the corresponding plot.)**sddscontour sddscontour.input1 -columnMatch=Index,Ex* -ystring=sparse=10 -ylabel=y -shade show_plot**We can use -ystring to remove the string part of y label as following:

**sddscontour sddscontour.input1 -columnMatch=Index,Ex* -ystring=sparse=10,edit=%/Ex_// -ylabel=y -shade show_plot**The above y tick label still shows the index of y coordinate, not y values. Following command allows us to see the y values:

**sddscontour sddscontour.input1 -columnMatch=Index,Ex* -yrange=minimum=@origin2,maximum=@max_ext2 -ylabel=y -shade show_plot**Now, for the x tick labels, the above plot shows the Index value. Following command will show the values of x coordinate:

**sddscontour sddscontour.input1 -column=Index,Ex* -yrange=min=@origin2,max=@max_ext2 -xrange=min=@origin1,max=@max_ext1 -xlabel=x -ylabel=y -shade show_plot**The independent column - Index in the above command is useless. Therefore, -xrange provides a way for plotting a set of columns with contour without indepent column. If use sddsprocess to create x column through

*x=Index * delta1 + origin1*, the above plot can be created using following command, note that the titles in two plots are different because the independent column names are different since the title is automatically generated from input column names if it is not provided.**sddscontour sddscontour.input1 -column=x,Ex* -yrange=min=@origin2,max=@max_ext2 -ylabel=y -shade show_plot**Here shows the examples of providing xrange and yrange from parameters, however, they can be provided by fixed values from commandline also.

- Data scaling:
`[-deltas[={fractional | normalize}]] [-logscale[=`*floor*]]`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.

- Miscellaneous plot control:
`[-scales=`*xl*,*xh*,*yl*,*yh*] [-device=*name*[,*deviceArguments*]] [-swapxy] [-equalAspect[=-1,1]] [-noBorder]`scales`

-- Specifies the extent of the plot region.`device`

-- Specifies the device name and optional device-specific arguments. png devices take rootname and template identifiers.`rootname=`specifies a rootname for automatic filename generation; the resulting filenames are of the form*string**rootname*.DDD, where DDD is a three-digit integer.`template=`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*string*`rootname=`may be obtained using*name*`template=`.*name*.%03ld`swapxy`

-- Requests that the horizontal and vertical coordinates be interchanged.`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.`noBorder`

-- Specifies that no border will be placed around the graph.

- Miscellaneous:
`[-output=`*filename*] [-verbosity[=level]]`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.

- Choice of what to plot:
**see also:****author:**M. Borland, ANL/APS.