2.4.1.3 X-Function Execution Options

XF-Execution-Options

X-Function Option SwitchesX-Function, option switch

The following option switchswitches are useful when accessing X-Functions from script:

For options with an existing Full Name, either the shortened switch name or the full name may be used in script. For instance, for the X-Function smooth,

smooth -h

is the same as

smooth -help

Examples

Open X-Function DialogOpen X-Function DialogX-Function, open dialog

Use -d switch to open X-Function dialog so that user can inter interactively supply input and parameters

The following script fills column 1 & 2 with data, use the -d switch to open the smooth X-Function dialog, where user can preview result, adjust settings, etc. Upon clicking OK, the script will continue to plot column 2 and 3 as line graph.

col(1)=data(1,100); //fill column 1 with row numbers.
col(2)=normal(100); //fill column 2 with normalized data
//open dialog with input, method and number of points loaded. 
//Play with settings in the dialog and click OK
smooth (1,2) method:=2 npts:=25 -d; 
//plot Y columns (column 2 and 3) against X column in sheet (column 1) as line graph
plotxy (?,2:3) p:=200;

Using a Theme

Use the -t switch to execute the x-function with saved dialog theme. Dialog theme is basically the settings of X-Function dialog, parameters and output. Usually input is excluded in theme file.

The following steps shows how to save a dialog theme file and then use the -t switch to use it.

1. Select column 2 created after above script. Run the following script to open smooth dialog. Or u can choose Analysis: Signal Processing: Smoothing: Open dialog... menu

   smooth -d;

2. Set the Method as Adjacent-Averaging and Points of Window as 5.
3. Click the > button next to Dialog Theme on the top and choose Save As.... Save the dialog settings as FivePtAdjAve.
4. Cancel the dialog.
5. Activate the workbook with data in previous script.
6. Run the X-Function with -t switch to perform a smoothing with XY data in column 1 and 2 using the theme named FivePtAdjAve, which means Method as Adjacent-Averaging and Points of Window as 5

   smooth (1,2) -t FivePtAdjAve;

Note: No need to specify the theme file path since Origin automatically saves and retrieves your themes from User Files\Themes\AnalysisAndReportTable\. You can share the theme file with others. They can drag and drop the theme file into Origin workspace to install it. Themes saved in one project (*.OPJ) will be available for use in other projects as well. Start from Origin 2024, Origin will first look for your themes from current project folder. If not found, then from User File Folder.

Setting Recalculate Mode

Use the -r switch to set recalculation mode of output.

Multiple switches can be used together. Two switches: -t FivePtAdjAve are used below to smooth with FivePtAdjAve theme and -r 1 to set recalculation mode to auto

smooth (1,2) -t FivePtAdjAve -r 1;

The following script runs the freqcounts X-Function with -r 1 to automatically recalculate when data in the input column changes.

newbook;
col(1)=uniform(100)*50; //generate uniformly distributed random data from 0 to 50.
//do frequency count with increment 5, recalculation mode set to auto
freqcounts irng:=col(1) min:=0 max:=50 stepby:=increment inc:=5
   end:=0 count:=1 center:=1 cumulcount:=0 rd:=col(4) -r 1;

Open X-Function Builder

Help file dumped by -h switch can be overwhelming and hard to read, while other -he, -hv is too limited.

So instead, user can use the -e switch to open the X-Function in X-Function Builder so that user can see all parameter in table view with full info.: input/output, data type, default value, etc, etc. This is also the dialog for advanced users to learn the code of built-in X-Functions. By clicking Edit X-Function in Code Builder button in the dialog. the X-Function code shows in Code Builder.

smooth -e;

Copy Format from Input to Output

Use the -cf switch to format the output data to match that of the input data:

By default, all analysis results are output as datatype double. The following script makes the output data format to be short(2), which is the input data format.

// Import a *.wav file; imported *.wav data format is short(2).
fname$ = system.path.program$ + "Samples\Signal Processing\sample.wav";
newbook s:=0; 
newsheet col:=1; 
impWav options.SparkLines:=0;

//Perform lowpass fft_filter on col 1 of 1st sheet in current book with cutoff freq = 2000
fft_filters -cf [%H]1!col(1) cutoff:=2000  
oy:=(<input>,<new name:="Lowpass Sound Frequency">);

Undo the Operation

Use the -u switch to support undo the x-function operation when running from scripts.

If a x-function is run from the dialog, by default the operation can be undone. But if it is run from scripts, we should use -u switch to support undo. The following scripts transpose the active worksheet and output the results to a new workbook and then undo the operation.

wtranspose -u ow:=<new>;
undo;