GENSSPP

Home › Software › Manual Pages › GENSSPP

NAME

SYNOPSIS

gensspp [options] -a[n[g]] xwfnum ywfnum runfile ...  

DESCRIPTION

The runfile argument, which must be specified, gives the name of the run file or analysis parameter file for the run of data to be plotted. The xwfnum and ywfnum arguments, also required, give the waveform numbers for the X-axis and Y-axis waveforms. The X-axis waveform is also the cycle waveform for the start-stop time analysis. The outname specifies the output plot file or image file name, and the default is the standard output if no outname is given. If the -f option is used, the outname is the first file name in the series of plot files or image files. The number in that name will be incremented for subsequent frames. A maximum of 10000 plot or image files will be generated, so 4 digits in the file name will ensure correct sorting of output files by name. The default name is sspp0000.plt for HPGL output, or sspp0000.gif for GIF output.  

Options

-g

Specifies that you want the HPGL plot files converted to GIF images. This can be followed by options to hpgl2gif(1), if desired, to set size and colours. Also, if valid hpgl2gif options are given without the -g option, this option is assumed.

-c[probabilities]

Specifies that circular statistics should be calculated and plotted. The mean angle, a, and the concentration of points, r, are shown, and a line of radius r is drawn at the angle a. This is intended for use with polar plots. If the probabilities are given, the Rayleigh's critical value for r is calculated and shown, plotted as a dotted line at each probability level. If more than one probability is given, they should be separated by commas within the same argument (i.e. no spaces).

-cw

Specifies a clockwise polar plot, with 0 at the top of the graph. By default, polar plots run counter-clockwise with 0 at the right.

-rnum

Specifies a number of samples to be taken at random from the generated data. By default, all data points are displayed, rather than a random sample. When using both -r and -c options, the circular statistics are calculated based on the number of samples used, not on the total number of data points from which the sample is taken.

-nnum

Specifies the number of samples (i.e. bursts or cycles) to be taken from the start of the generated data. When both -r and -n are specified, the -r option should specify a smaller number, and that number of samples will be taken at random from the first cycles selected by the -n option.

-s

Specifies that spike positions, rather than burst start times, are plotted for the Y-axis waveform number. This graph is based on the "Action potential position vs step cycle" method in analysis(1).

-sb

Specifies that several burst positions, rather than just the first burst start time, are plotted for each cycle for the Y-axis waveform number. This graph is based on the "W.F. activity burst duration vs cycle duration" method in analysis(1), using the "Burst postions in cycle" option to show positions, not durations.

-tstart,end

Specifies the start and end time in the runfile, in milliseconds or whatever is selected as the current time units in the runfile's analysis parameters. The default is the whole run, or whatever analysis range is selected in the analysis parameters.

-xppen

Specifies the plotter pen number to be used for the axes and labels in the HPGL output, or colour number for GIF output (default is 1 or black for GIF output). Pen number 0 suppresses plotting of these. See hpgl2gif(1) for information about how pen numbers are mapped to colours.

-yppen

Specifies the plotter pen number to be used for data points in the HPGL output, or colour number for GIF output (default is 1 for HPGL output, or blue - pen 2 - for GIF output).

-ymmarker

Specifies the marker symbol to be used for plotting the data points. The symbol can be selected by using one of these characters for the marker:

.       A solid (filled) circle.
o       A circle outline (not filled).
b       A solid square block.
s       A square outline.
t       A triangle outline.
d       A diamond outline (square rotated 45 degrees).
x       An X-shaped cross.

By default, the solid circle is used. You can also have a character label placed at each data point, centered vertically and horizontally, instead of one of these symbols, by specifying a hyphen as the marker and following it with the character or string of characters you want as the marker label. E.g. -ym-+, to get a + sign at each data point.

-ywwidth

Specifies the width of the marker symbols, in millimetres. They are 2 mm by default. A width of 0 causes the markers to be suppressed.

-ffps

Specifies the frame rate, in plot files per second of data (default is one single frame). Note that in the context of this program, the term frame refers to an output plot or image in a series, and not the frames that make up the triggered traces in the runfile. Given that gensspp works on cycles, you would tend to use a lower frame rate than you would for animations from rawwfplt(1), e.g. 1 or 2 fps instead of about 10.

-a

Specifies that burst start positions are averaged for each specified runfile, and a single average angle is plotted for each run. Note that with the -a option, arguments must be given in a slightly different order than without this option. The runfile arguments must be specified after the two waveform number arguments, rather than a single runfile argument before the waveform numbers. Also, no outfile argument can be specified when using -a. If you want to save the averaged output plot, you must redirect the standard output to a file using the ">" character. With -a, it's assumed that all the arguments after the two waveform numbers are runfile names, and you can specify as many of these as you wish. Finally, you can't combine -f and -a options, as they are mutually exclusive - generating frames requires stepping through the raw data.

Note also that you can use wildcards for file name matching for the runfile arguments (e.g., *, ?, [a-z]) but when you do the filename suffix (.prm or .frm) must be specified so the shell can match actual file names. When you explicitly give run names without a suffix, the .frm or .prm suffix is assumed automatically if none is given.

Because gensspp will use the same two waveform numbers for all the runs you specify, you must be consistent in how you name and number all your waveforms. For instance, if you manually rectify and filter ENGs/EMGs after capture, you should try to do it in the same order for all runs, or explicitly specify the resulting waveform numbers when filtering so they're consistent. The final graph will use the waveform names from the last runfile analyzed.

-an

Specifies that burst start positions are collected and compared across two or more runfile arguments, using three statistical analyses: a Shapiro-Wilk test and a QQ plot to test for normality of the angular data, and a Watson-Williams test to compare dispersion patterns across the runs. For the first two tests, which are based on linear statistics, and not circular statistics, data are taken relative to the mean angle for each run, so that they will correctly treat angles close to 0 or 360 degrees as being close to each other. The Watson-Williams test is part of the circular statistics module of the R statistical package. Therefore, both the R package and the circular module for it must be installed on the system for this -an option to work. As with the -a option described above, the runfile arguments must follow the two waveform number arguments, and all the other caveats associated with the -a option apply.

-ang

Specifies that burst start positions for each runfile are output to the standard output. Values are given as angles in degrees, followed by the runfile name, in CSV (comma-separated values) format, suitable for import into a spreadsheet or other data analysis software. As with the -a and -an options described above, the runfile arguments must follow the two waveform number arguments. Output should be redirected to a file using the ">" character.

As of the June 6, 2016 version, gensspp can also reuse angle data as output by the -ang option. You can specify a CSV file of angle data instead of a run file, to reanalyse extracted angle data later, or process angle data not originating from run files. This file must have a .csv or .txt file suffix. While this is specifically intended for use with the -an option, you can also use it to plot raw or averaged angles. For the plots, labels will be sparse as most of the labeling info extracted from run files is absent in the CSV file. The two waveform numbers must still be specified, but will be ignored when analysing CSV angle data.

--help

Causes the program to output a summary of command usage and options.

EXAMPLES

gensspp -c0.05,0.001 03809003 7 9 | xhpgl

Simple case using mostly defaults. The 03809003 in the command line is the runfile analyzed in Tutorial 13 (see below). Two different p values are specified, for which confidence intervals will be plotted.

gensspp -cw -c0.05,0.001 -xp2 -yp4 -t50s,100s 03809003 9 7 | xhpgl

Subset of the same data, shown in a clockwise (compass-style) polar plot, with X and Y axis waveforms swapped, alternate pen numbers specified, and time units given explicitly for the analysis range.

gensspp -c -xp2 -yp4 -a 15 17 mn2[2-5]-00.prm | xhpgl

Averages are plotted, one per run, for runfiles mn22-00 through mn25-00.

gensspp -an 15 17 mn2[2-5]-00.prm

Performs a circular statistics analysis on the angles represented by waveform 17, relative to the cycles on waveform 15. Results of the Shapiro-Wilk test and Watson-Williams test appear on the standard output (the terminal window), and the Q-Q plots appear in a pop-up window.

gensspp -ang 15 17 mn2[2-5]-00.prm > mn22-25-w17v15.csv

The angles represented by waveform 17, relative to waveform 15, are saved in the specified .csv file.

gensspp -an 15 17 mn22-25-w17v15.csv

The angles saved in the .csv file from the example above are reanalysed later using circular statistics.

FILES

SEE ALSO

http://www.scrc.umanitoba.ca/doc/faq.html#q4.4

for more information on polar plots in SCRC analysis software.

http://www.scrc.umanitoba.ca/doc/tutorial/tutorial_13.html

for more information on making polar plots using gensspp.

http://www.scrc.umanitoba.ca/doc/tutorial/tutorial_18.html

for information on making animations of multiple frame output (use gensspp rather than rawwfplt in step 2).

BUGS

Index

NAME

SYNOPSIS

DESCRIPTION

Options

EXAMPLES

FILES

SEE ALSO

BUGS