# QSoas command reference

Here is the command reference of QSoas, which list all the commands, what they do, and how to use them.

To get a quick introduction at QSoas, you may look at the tutorial, or look at the list of Frequently Asked Questions.

# QSoas datasets

The basic unit to manipulate data in QSoas is the dataset (they are sometimes also called “buffer”, from the terminology used in SOAS). A dataset is a large table of number. First first column contains the X values, and the following columns are Y values. A dataset can have many columns. QSoas plots a dataset by showing the first y column as a function of the x column.

The table cannot contain text. When QSoas reads a file and is not able to make a number from what it reads, it uses a special numeric value called nan (Not A Number). They can be useful, but they “pollute” numbers: any operation that involves a nan will also have nan as a result. To get rid of points that have either X or Y values that are nan, use the following:

QSoas> strip-if x.nan?||y.nan?

You can use the edit command to see and edit the contents of the table.

In addition to the raw numbers, a QSoas dataset contains the following information:

• A name, which is originally the name of the loaded file. It is modified with each command applied to the dataset.
• A series of meta data, which are just named informations. It can be numbers, text, dates, even lists.
• Perpendicular coordinates, one for each Y column. They are used when the dataset can also be seen as a series of $y = f(x,z)$, with a different $z$ for each Y column.
• A series of flags, which can be used to retrieve them from the stack. Unlike the other attributes, flags are not kept when the dataset is modified.

# Commands, arguments and options (how to read this document)

QSoas works by entering commands inside the command prompt, or alternatively using the menus.

Most commands have arguments and options. Arguments and options are separated by spaces:

QSoas> command argument1 argument2 "argument 3" /option=option /option2="with spaces"

If you need to pass arguments or option values that have spaces, make sure you quote them using " or ', like in the above example. The = sign for the options can be replaced by a space, so that the command above could also have been run thus:

QSoas> command argument1 argument2 "argument 3" /option option /option2 "with spaces"

Arguments are italicized in the documentation below. You need to provide all the arguments for a command to work, and if you don’t, QSoas will prompt for them. Some arguments are followed by , which means that you can pass several space-separated arguments. This is the case for load, for instance:

QSoas> load file1 file2 file3

Some options are marked as “(default option)”, which means that, if all arguments of the command are already specified, you can omit the /option= part of the option. For instance, to set the temperature to 300 K, you should be doing that:

QSoas> temperature /set=300

But, as /set is the default option, you can omit the /set= and write:

QSoas> temperature 300

In this documentation, all options and arguments have mouseover texts that give a short explanation of what kind of values are expected.

Some commands can be used through a short name (like q for quit), indicated as such in the present documentation.

Some commands are marked as (interactive). This means that their use requires user input. If they are used in a script, the script pauses for user interaction.

All the commands that can be run from the command line are also available from within the menus. Running the command through the menu gives a dialog box in which one must choose the arguments of the command, and one can also select the options.

This can be a good way to discover what commands are available, and what they do.

Many commands of QSoas make use of “plain text files”, i.e. files that simply contain unformatted text. These are for instance:

On windows, use Notepad to edit them. On Linux, pico, nano, vi or emacs are pretty good choices. On MacOS, use TextEdit, but make sure you hit Cmd+Shift+T to switch to “plain text” format; the default is rich text (i.e. text with formatting informations) in the RTF format, and QSoas does not understand RTF.

## Dataset lists (or buffer lists) arguments

Many commands, such as flag, contract and others take lists of datasets as arguments. This list can take several forms:

• A comma-separated list of dataset numbers (the ones given by show-stack), such as: 1,4,7 (0 is the current dataset, 1, the one just before, which you can reach using undo, etc.).
• Negative numbers refer to the “redo” stack: -1 is the dataset you would get by running redo
• A number range, such as 1..7, meaning all datasets from 1 to 7 included.
• A number range with a step, such as 1..7:3, meaning 1,4,7.
• all for all datasets on the stack.
• displayed for the currently displayed datasets.
• latest for the datasets produced by the last command (running a script counts as many commands); this can be different from 0 if the last command produced more than one dataset, or none.
• latest:1 is the same as latest, latest:2 represents the datasets produced by the command before the last one, etc…

It is also possible to make use of dataset flags set by flag:

• flagged stands for all flagged datasets (regardless of the name of the flag);
• unflagged for all datasets that don’t have any flag;
• flagged- and unflagged- do the same, but with the datasets in the reverse order;
• flagged:flagname for all datasets that have the flag flagname;
• unflagged:flagname for all datasets that don’t have the flag flagname;
• and the variants flagged-:flagname and unflagged-:flagname for the reversed order.

Note in this documentation, the terms “buffer” and “dataset” are synonyms.

## Dataset columns

Some commands such as bin or dataset-options take dataset column names (or numbers) as arguments or options. There are three way to designate those:

• using a number: 1 is the $x$ column, 2 is the $y$ column, and so on
• using a number prefixed by #: this is a 0-based index, #0 is then the $x$ column
• by its name: x, y, z, y2, y3 and so on. y2 is equivalent to z
• no or none when you don’t want to specify a number at all, such as for disabling the display of error bars with dataset-options.

Some commands (like contract) take column lists, which are comma-separated lists of columns (just like above), with the addition of ranges: 2..6 are columns 2 to 6 inclusive.

## Regular expressions

Some commands, notably load and the related commands, make use of “regular expressions”. Regular expressions are a way to describe how a text looks like, such as “numbers”, “white spaces”, “anything that looks like a date”, etc. Here is how it works:

• A simple text just matches itself. For instance, using /separator=, for load-as-text means that the columns are separated by commas.
• {blank-line} matches a fully blank line.
• {blank} matches a series of blanks. This is the default separator for load-as-text.
• {text-line} matches a line that does not start by numbers (ignoring spaces).
• /regex/, which is taken as a Qt regular expression. For instance, /[;,]/ means “either ; or ,”. Please see the Qt documentation for more information.

## Commands producing several datasets

Many commands in QSoas will produce several datasets, for instance load, that loads several files at the same time, or split-monotonic, that splits a dataset into its monotonic parts. All these commands share a set of options:

• /style that can be used to display all the curves with gradual changes in color;
• /flags, that can be used to set flags to the newly generated datasets, see the flag command for more information.
• /set-meta, that can be used to set meta-data to the newly generated datasets, using a key=value syntax (so you have two = signs in row). This option can be used several times to add several meta-data.

For instance, try out:

QSoas> generate-dataset -1 1 /style=brown-green sin((10+number)*x) /number=11
QSoas> generate-dataset -1 1 /set-meta=a=2 /set-meta=b=3 

# General purpose commands

### quit – Quit

quit

Other name: q

Exits QSoas, losing the current session. The full log of the session is always available in the soas.log file created in the initial directory. This is indicated at startup in the terminal.

To avoid accumulating very large log files, the log file gets renamed as soas.log.1 when you start QSoas (and the older one as soas.log.2, and so on until soas.log.5).

If you want to save the entire state of QSoas before quitting so you can restart exactly from where you left, use save-stack.

### credits – Credits

credits /full=yes-no

• /full=yes-no: Full text of the licenses – values: a boolean: yes, on, true or no, off, false

This command displays credits, copyright and license information of QSoas and all the dependencies linked to or built in your version. You’ll get the full license text with /full=true.

It also lists publications whose findings/equations/algorithms were directly used in QSoas.

### version – Version

version /dump-sysinfo=yes-no /show-features=yes-no

• /dump-sysinfo=yes-no: If true, writes system specific information to standard output – values: a boolean: yes, on, true or no, off, false
• /show-features=yes-no: If true, show detailed informations about the capacities of QSoas (defaults to false) – values: a boolean: yes, on, true or no, off, false

Prints the version number of QSoas, including various build information.

If the option /show-features=true, then the output is much longer, and contains a list of all the features built in QSoas, including the fit engines, the available statistics, the time-dependent parameters and so on.

### save-history – Save history

save-history file

• file: Output file – values: name of a file

Saves all the commands that were launched since the beginning of the session, to the given (text) file.

This can be used for saving a series of command that should be applied repetitively as a script.

### cd – Change directory

cd directory /from-home=yes-no /from-script=yes-no

Other name: G

• directory: New directory – values: name of a directory
• /from-home=yes-no: If on, relative from the home directory – values: a boolean: yes, on, true or no, off, false
• /from-script=yes-no: If on, cd relative from the current script directory – values: a boolean: yes, on, true or no, off, false

Changes the current working directory. If /from-home is specified, the directory is assumed to be relative to the user’s home directory. If /from-script is specified, the directory is assumed to be relative to that of the command file currently being executed by a run command (or in a startup script).

### pwd – Working directory

pwd

Prints the full path of the current directory.

It is also indicated in the title of the QSoas window.

### temperature – Temperature

temperature /set=number

Other name: T

• /set=number (default option): Sets the temperature – values: a floating-point number

Shows or sets the current temperature, in Kelvins. The temperature is used in many places, mostly in fits to serve as the initial value for the temperature parameter. To set the temperature, pass its new value using the /set option (the /set= part is optional):

QSoas> temperature 310

### commands – Commands

commands

List all available commands, with a short help text. This also includes used-defined commands, such as custom fits loaded from a fit file and aliases.

### help – Help on…

help /command=command /synopsis=yes-no

Other name: ?

• /command=command (default option): The command on which to give help – values: the name of one of QSoas’s commands
• /synopsis=yes-no: Does not show the help, but print a brief synopsis – values: a boolean: yes, on, true or no, off, false

Gives all help available on the given command. By default, it spawns a browser to show the online help, unless you use /online=false.

### tips – Tips

tips /show-at-startup=yes-no

• /show-at-startup=yes-no: – values: a boolean: yes, on, true or no, off, false

Without any options, it shows the “startup tips” window. With the /show-at-startup option, you can control whether the tips will show at startup in the next run of QSoas or not.

### save-output – Save output

save-output file

• file: Output file – values: name of a file

Save all text in the terminal to a plain text file. Equivalent to copy-pasting the contents of the terminal to a plain text file using a text editor.

### print – Print

print /file=file /nominal-height=integer /overwrite=yes-no /page-size=text /title=text

Other name: p

• /file=file (default option): Save as file – values: name of a file
• /nominal-height=integer: Correspondance of the height of the page in terms of points – values: an integer
• /overwrite=yes-no: Overwrite the output file – values: a boolean: yes, on, true or no, off, false
• /page-size=text: Sets the page size, like 9×6 for 9cm by 6cm – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /title=text: Sets the title of the page as printed – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

Prints the current view, providing a usual print dialog. If you just want a PDF or PostScript file, just provide the file name as the /file option.

An optional title can be added using the /title option.

You can also use a .svg extension if you want to produce a SVG file that can later be modified, by, e.g. Inkscape.

Important note: QSoas is not a data plotting system, it is a data analysis program. Don’t expect miraculous plots !

### define-alias – Define alias

define-alias alias command /*=text

• alias: The name to give to the new alias – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• command: The command to give an alias for – values: the name of one of QSoas’s commands
• /*=text: All options – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

The define-alias commands allows one to defined a shortcut for a command one uses often with the same options. For instance, running:

QSoas> define-alias fit-2exp fit-exponential-decay /exponentials=2 /loss=true

creates a fit-2exp command that is equivalent to starting fit-exponential-decay with two exponentials by default and film loss on.

Alias can only be used to provide default values for options. It cannot provide default values for arguments.

### display-aliases – Display aliases

display-aliases

Shows a list of all the currently defined aliases.

### graphics-settings – Graphics settings

graphics-settings /antialias=yes-no /line-width=number /opengl=yes-no

• /antialias=yes-no: Turns on/off the use of antialised graphics – values: a boolean: yes, on, true or no, off, false
• /line-width=number: Sets the base line width for all lines/curves – values: a floating-point number
• /opengl=yes-no: Turns on/off the use of OpenGL acceleration – values: a boolean: yes, on, true or no, off, false

Gives the possibility to tweak a few settings concerning display. The settings are kept from one QSoas session to the next.

Turning on antialias (with /antialias=true) will make QSoas use antialiased drawings, which looks admittedly nicer, but requires much more computation time, to the point that drawing jagged curves may become particularly slow. Printing or exporting to PDF files through print always produces antialiased graphics, regardless of this option.

If you experience performance problems for displaying curves, use /opengl=true, as this will instruct QSoas to use hardware acceleration to display curves. It is off by default as some setups do not really benefit from that, and the OpenGL support is sometimes buggy and may result in crashes.

### ruby-run – Ruby load

ruby-run file

• file: Ruby file to load – values: name of a file

This command loads and executes a Ruby file. For the time being, the main interest of this command is to define complex functions in a separate file.

Imagine you have a file function.rb containing the text:

def mm(x,vmax,km)
return vmax/(1 + km/x)
end

After running

QSoas> ruby-run function.rb

You can use mm like any normal function for fitting:

QSoas> fit-arb mm(x,vmax,km)

or use it in eval:

QSoas> eval mm(1.0,2.0,3.0)
=> 0.5

You can find out more about ruby code below, but here is how one can define a function my_exp that is 0 before t0 and follows an exponential relaxation starting at val with a time constant tau afterwards:

def my_exp(t,t0,tau,val)
if t < t0
return 0
else
return val*exp(-(t-t0)/tau)
end
end

### break – Break

break

Exits from the current script. Has no effect if not inside a script.

### debug – Debug

debug /directory=directory /level=integer

• /directory=directory (default option): Directory in which the debug output is saved – values: name of a directory
• /level=integer: Sets the debug level – values: an integer

With this command, it is possible to collect a large amount of debugging information. You will essentially only need this to send information to the QSoas developers to help them track down problems.

The command:

QSoas> debug directory

sets up the automatic debug output in the directory directory.

The /level option correspond to the debug level. It defaults to 1, the higher this number the more detailed the output will be.

### system – System

system command… /shell=yes-no /timeout=integer

• command…: Arguments of the command – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /shell=yes-no: use shell (on by default on Linux/Mac, off in windows) – values: a boolean: yes, on, true or no, off, false
• /timeout=integer: timeout (in milliseconds) – values: an integer

The system command can be used to run external commands from QSoas. The output of the commands will be displayed in the terminal.

For the duration of the external command, QSoas will not respond to keyboard and mouse.

If /use-shell is on (the default on Linux and Mac, but off in Windows), the command will be processed by the shell before being run.

If a strictly positive /timeout is specified, the command will be killed if it takes longer than the timeout to execute.

### timer – Timer

timer /name=text

• /name=text: name for the timer – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

The first call starts a timer, and the second one stops it, showing the amount of time that has elapsed since the previous call to timer. This can be used to benchmark costly computations, for instance.

### mem – Memory

mem /cached-files=integer

• /cached-files=integer: – values: an integer

Displays information about the resource use of QSoas, including memory use, the number of cached files and the total CPU time used so far. The size of the file cache can be changed using the /cached-files option.

## Output file manipulation

Several commands (e.g. various data analysis commands and the fit commands) write data to the output file.

By default, the first time the output file is used, a output.dat file is created in the current directory. Another file can be used by providing its name to the output command.

### output – Change output file

output /file=file /meta=words /overwrite=yes-no /reopen=yes-no

• /file=file (default option): name of the new output file – values: name of a file
• /meta=words: when writing to output file, also prints the listed meta-data – values: several words, separated by ‘,’
• /overwrite=yes-no: if on, overwrites the file instead of appending (default: false) – values: a boolean: yes, on, true or no, off, false
• /reopen=yes-no: if on, forces reopening the file (default: false) – values: a boolean: yes, on, true or no, off, false

This command has several modes of operations. If file is provided (it is the default option, so you can omit /file=), then it opens file as the new output file. By default, if the file exists, new data are appended, and the old data are left untouched. You can force overwriting by specifiying /overwrite=true.

In the other mode, when only the /meta option is provided, it sets the list of meta-data that will automatically be added to the output file when outputting any data there. It is a comma-separated list of meta names. See more about meta-data there.

It is a bad idea to modify the output file while QSoas is still using it, as it messes up what QSoas think is in the output file. If you forgot you were using the output file and modified it, you can avoid problems by running:

QSoas> output /reopen=true

### comment – Write line to output

comment comment

• comment: Comment line added to output file – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

Writes the given line comment to the output file. Don’t forget to quote if you need to include spaces:

QSoas> comment 'Switching to sample 2'

The main command for loading data is load.

### load – Load

load file… /auto-split=yes-no /columns=integers /comments=pattern /decimal=text /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-cache=yes-no /ignore-empty=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

Other name: l

• file…: the files to load – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /auto-split=yes-no: if on, create a new dataset at every fully blank line (off by default) – values: a boolean: yes, on, true or no, off, false
• /columns=integers: columns loaded from the file – values: a comma-separated list of integers
• /comments=pattern: pattern for comment lines – values: plain text, or regular expressions enclosed within / / delimiters
• /decimal=text: decimal separator – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /expected=integer: Expected number of loaded datasets – values: an integer
• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /for-which=code: Select on formula – values: a piece of Ruby code
• /histogram=yes-no: whether to show as a histogram (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /ignore-cache=yes-no: if on, ignores cache (default off) – values: a boolean: yes, on, true or no, off, false
• /ignore-empty=yes-no: if on, skips empty files (default on) – values: a boolean: yes, on, true or no, off, false
• /separator=pattern: separator between columns – values: plain text, or regular expressions enclosed within / / delimiters
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /skip=integer: skip that many lines at beginning – values: an integer
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
• /yerrors=column: name of the column containing y errors – values: the number/name of a column in a dataset

Loads the given files and pushes them onto the data stack. QSoas features several backends for loading files (“backends” are roughly equivalent to “file formats”). In principle, QSoas is smart enough to figure out which one is correct, but you can force the use of a given backend by using the appropriate load-as- command. Using a backend directly also provides more control on the way files are loaded (this can also be done via the numerous options to load, which are forwarded to the appropriate backend). Currently available backends:

Look in their documentation for more information. In particular, the options /separator=, /decimal=, /skip=, /comments=, /columns= and /auto-split are documented in the load-as-text command.

QSoas tells you which backend it used for loading a given file:

QSoas> load 03.dat
Loading file: './03.dat' using backend text

The command load caches the loaded file. If for some reason, the cache gets in the way, use the direct load-as- commands, or alternatively use /ignore-cache=true.

load, like all the other commands that take several files as arguments, understand unix-like wildcards:

QSoas> load *.dat

This command loads all the files ending by .dat files from the current directory.

QSoas> load [0-4]*.dat

One can also set various dataset options while loading with load (and the load-as- commands), using the options /yerrors= and /histogram=. See the dataset-options, command for more information

The /style= option sets the color style when loading several curves:

QSoas> load *.dat /style=red-blue

This loads all the .dat files in the current directory, and displays them with a color gradient from red (for the first loaded file) to blue (for the last loaded file).

With the /flags= option, on can flag datasets as they get loaded. Using it has the same effect as running flag with the same option on loaded datasets.

The load command also provides dataset selection rules through the /for-which, option, more about that in the dedicated section.

By default, the load and related commands will not create a dataset if it were empty (i.e. a valid data file containing no data), you can force the creation of empty files using /ignore-empty=false.

Finally, it is possible to provide a number of datasets that should be loaded with the /expected= option. The command fails if the number of loaded datasets does not match the number given. This can be useful for scripts, to abort the script when a file is missing, see run to make use of this.

### load-as-text – Load files with backend ‘text’

load-as-text file… /auto-split=yes-no /columns=integers /comments=pattern /decimal=text /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-empty=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

• file…: the files to load – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /auto-split=yes-no: if on, create a new dataset at every fully blank line (off by default) – values: a boolean: yes, on, true or no, off, false
• /columns=integers: columns loaded from the file – values: a comma-separated list of integers
• /comments=pattern: pattern for comment lines – values: plain text, or regular expressions enclosed within / / delimiters
• /decimal=text: decimal separator – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /expected=integer: Expected number of loaded datasets – values: an integer
• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /for-which=code: Select on formula – values: a piece of Ruby code
• /histogram=yes-no: whether to show as a histogram (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /ignore-empty=yes-no: if on, skips empty files (default on) – values: a boolean: yes, on, true or no, off, false
• /separator=pattern: separator between columns – values: plain text, or regular expressions enclosed within / / delimiters
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /skip=integer: skip that many lines at beginning – values: an integer
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
• /yerrors=column: name of the column containing y errors – values: the number/name of a column in a dataset

Loads files using the backend text, bypassing cache and automatic backend detection. text recognizes space-separated data (which includes tab-separated data). Most “plain text” files will be read correctly by this backend. By default, it loads all the columns of the file, but only displays the second as a function of the first. If you want to work on other columns, have a look at expand. Alternatively, you can specify the columns to load using the /columns option, see below.

Apart from the options of dataset-options and the /style and /flags options documented in the load command, the text backend accepts several options controlling the way the text files are interpreted:

• /separator specifies the text that separates the columns (blank spaces by default). You can use regular expressions.
• /decimal specifies the decimal separator for loading (default is the dot). This is for loading only.
• /comments specifies a regular expression describing comment lines (ie lines that get ignored). By default, line that don’t start by a number are ignored.
• Give to /skip a number of text lines that should be ignored at the beginning of the text file.
• If /auto-split is true, then QSoas will create a new dataset everytime it hits a series of blank lines in the file.
• /columns is a series of numbers saying in which order the file columns will be used to make a dataset. For instance, /columns=2,1 will swap X and Y at load time.

### load-as-csv – Load files with backend ‘csv’

load-as-csv file… /auto-split=yes-no /columns=integers /comments=pattern /decimal=text /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-empty=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

• file…: the files to load – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /auto-split=yes-no: if on, create a new dataset at every fully blank line (off by default) – values: a boolean: yes, on, true or no, off, false
• /columns=integers: columns loaded from the file – values: a comma-separated list of integers
• /comments=pattern: pattern for comment lines – values: plain text, or regular expressions enclosed within / / delimiters
• /decimal=text: decimal separator – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /expected=integer: Expected number of loaded datasets – values: an integer
• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /for-which=code: Select on formula – values: a piece of Ruby code
• /histogram=yes-no: whether to show as a histogram (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /ignore-empty=yes-no: if on, skips empty files (default on) – values: a boolean: yes, on, true or no, off, false
• /separator=pattern: separator between columns – values: plain text, or regular expressions enclosed within / / delimiters
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /skip=integer: skip that many lines at beginning – values: an integer
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
• /yerrors=column: name of the column containing y errors – values: the number/name of a column in a dataset

The csv backend is essentially the same backend as the text one, but with the separators set by default to commas and semicolons, to parse CSV files. Hence, the options have the same meaning as for load-as-text.

### load-as-chi-txt – Load files with backend ‘chi-txt’

load-as-chi-txt file… /auto-split=yes-no /columns=integers /comments=pattern /decimal=text /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-empty=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

• file…: the files to load – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /auto-split=yes-no: if on, create a new dataset at every fully blank line (off by default) – values: a boolean: yes, on, true or no, off, false
• /columns=integers: columns loaded from the file – values: a comma-separated list of integers
• /comments=pattern: pattern for comment lines – values: plain text, or regular expressions enclosed within / / delimiters
• /decimal=text: decimal separator – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /expected=integer: Expected number of loaded datasets – values: an integer
• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /for-which=code: Select on formula – values: a piece of Ruby code
• /histogram=yes-no: whether to show as a histogram (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /ignore-empty=yes-no: if on, skips empty files (default on) – values: a boolean: yes, on, true or no, off, false
• /separator=pattern: separator between columns – values: plain text, or regular expressions enclosed within / / delimiters
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /skip=integer: skip that many lines at beginning – values: an integer
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
• /yerrors=column: name of the column containing y errors – values: the number/name of a column in a dataset

This is a slightly modified version of load-as-text that handles better text files from CH Instruments (and is in particular able to detect at least some of their meta-data).

### load-as-eclab-ascii – Load files with backend ‘eclab-ascii’

load-as-eclab-ascii file… /auto-split=yes-no /columns=integers /comments=pattern /decimal=text /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-empty=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

• file…: the files to load – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /auto-split=yes-no: if on, create a new dataset at every fully blank line (off by default) – values: a boolean: yes, on, true or no, off, false
• /columns=integers: columns loaded from the file – values: a comma-separated list of integers
• /comments=pattern: pattern for comment lines – values: plain text, or regular expressions enclosed within / / delimiters
• /decimal=text: decimal separator – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /expected=integer: Expected number of loaded datasets – values: an integer
• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /for-which=code: Select on formula – values: a piece of Ruby code
• /histogram=yes-no: whether to show as a histogram (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /ignore-empty=yes-no: if on, skips empty files (default on) – values: a boolean: yes, on, true or no, off, false
• /separator=pattern: separator between columns – values: plain text, or regular expressions enclosed within / / delimiters
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /skip=integer: skip that many lines at beginning – values: an integer
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
• /yerrors=column: name of the column containing y errors – values: the number/name of a column in a dataset

This is a slightly modified version of load-as-text that handles better ASCII files exported from Biologic potentiostats.

### load-as-parameters – Load files with backend ‘parameters’

load-as-parameters file… /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-empty=yes-no /set-meta=meta-data /style=style /yerrors=column

• file…: the files to load – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /expected=integer: Expected number of loaded datasets – values: an integer
• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /for-which=code: Select on formula – values: a piece of Ruby code
• /histogram=yes-no: whether to show as a histogram (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /ignore-empty=yes-no: if on, skips empty files (default on) – values: a boolean: yes, on, true or no, off, false
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
• /yerrors=column: name of the column containing y errors – values: the number/name of a column in a dataset

QSoas can also load the parameters from a “Save Parameters” file. The parameterse end up one per column, as a function of the perpendicular coordinate used during the fit (or just an index if there was no perpendicular coordinates). This works on the parameters “saved for reusing later”, the ones “exported” can be read using the standard load-as-text command, possibly by specifying the option /comments=# to avoid ignoring lines that start with text (dataset names).

### expand – Expand

expand /flags=words /group-columns=integer /perp-meta=text /set-meta=meta-data /style=style /x-every-nth=integer

• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /group-columns=integer: specifies the number of Y columns in the created datasets – values: an integer
• /perp-meta=text: defines meta-data from perpendicular coordinate – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
• /x-every-nth=integer: specifies the number of columns between successive X values – values: an integer

If a dataset contains several columns, QSoas only displays the second as a function of the first. expand splits the current dataset into as many datasets as there are Y columns, ie a X, Y1, Y2, Y3 dataset will be split into three datasets: X, Y1; X, Y2 and X, Y3.

If /perp-meta is specified, then the given meta-data will be defined for each dataset, based on the value of the perpendicular coordinates.

By default, expand assumes that the first column is the only X column. However, if you give a number to the /x-every-nth= option, then expand assumes that a X column is every that many columns. For instance, /x-every-nth=2 means that the layout of the dataset is X1 Y1 X2 Y2 X3 Y3…

By default, expand splits every Y column into its own dataset. However, it is possible to group them using the /group-columns option. For instance, splitting a X Y1 Y2 Y3 Y4 dataset with:

QSoas> expand /group-columns=2

will result in two datasets: X Y1 Y2 and X Y3 Y4.

### rename – Rename

rename new-name

Other name: a

• new-name: New name – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

Changes the name of the current dataset. To help track the operations applied to a dataset, its name is modified and gets longer after each modification. Use rename to give it a more meaningful (and shorter) name.

If you need to rename a large number of datasets, you probably want to try save-datasets with /mode=rename.

### save – Save

save file /mkpath=yes-no /overwrite=yes-no

Other name: s

• file: File name for saving – values: name of a file
• /mkpath=yes-no: If true, creates all necessary directories – values: a boolean: yes, on, true or no, off, false
• /overwrite=yes-no: If true, overwrite without prompting – values: a boolean: yes, on, true or no, off, false

Saves the current dataset to a file. This command will ask you before overwriting an existing file, unless /overwrite=true was specified.

It will also change the name of the file.

### save-datasets – Save

save-datasets datasets… /expression=text /format=text /mkpath=yes-no /mode=choice /overwrite=yes-no

Other name: save-buffers

• datasets…: datasets to save – values: comma-separated lists of datasets in the stack, see dataset lists
• /expression=text: a Ruby expression to make file names – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /format=text: overrides dataset names if present – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
• /mkpath=yes-no: if true, creates all necessary directories (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /mode=choice: if using /format or /expression, whether to just save, to just rename or both (defaults to ‘both’) – values: one of: both, rename, save
• /overwrite=yes-no: if false, will not overwrite existing files (default is true) – values: a boolean: yes, on, true or no, off, false

Saves the designated datasets to files.

Unlike the save command, this saves the datasets using their current names, and does not prompt for a file name. It is probably a good idea to use rename first, or use the possibilities below.

This command can rename the datasets before saving them, by using a printf-like format, as in the following case, which renames the first 101 datasets to Buffer-000.dat, Buffer-001.dat, and so on:

QSoas> save-datasets /format=Buffer-%03d.dat 0..100

It is also possible to use a full-blown Ruby expression (returning a string) that will be aware of the dataset’s meta-data:

QSoas> save-datasets '/expression="File-#{$meta.sr}.dat"' This requires careful quoting: outer single quotes (') for QSoas and inner double quotes for Ruby. See more information about the informations available from within the ruby code there. If you only need to rename the datasets without saving them, use /mode=rename. By default, save-datasets overwrites the files without asking, but using /overwrite=false keeps the original files in place. save-datasets does not by default create directories. However, using /mkpath=true makes it possible to save datasets in non-existing directories, that as created when needed. Try out: QSoas> save-datasets /format=non-existing-directory/buffer-%03d.dat 0..100 /mkpath=true ### browse – Browse files browse /for-which=code /pattern=text Other name: W • /for-which=code: Select on formula – values: a piece of Ruby code • /pattern=text (default option): Files to browse – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “ Browse all datafiles in the current directory (or those matching the wildcard pattern given to /pattern, see load for more information about wildcards). Very useful to find quickly the file you’re looking for. Using the /for-which option, one can display only a certain set of files based on their meta-data and/or statistics. See the dedicated section for more details. # Data display ### overlay-buffer – Overlay buffers overlay-buffer /buffers=datasets /for-which=code /style=style Other name: V • /buffers=datasets (default option): Buffers to overlay – values: comma-separated lists of datasets in the stack, see dataset lists • /for-which=code: Only act on datasets matching the code – values: a piece of Ruby code • /style=style: Style for curves display – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green Plots one or several datasets on top of the current dataset. See load for the description of the /style option. ### hide-buffer – Hide buffers hide-buffer buffers… Other name: H • buffers…: buffers to hide – values: comma-separated lists of datasets in the stack, see dataset lists This does the reverse of the overlay-buffer command. Pass it the datasets you want to remove from the current view. Don’t be afraid of passing it non-visible datasets, QSoas won’t shout at you if you do. ### overlay – Overlay overlay file… /auto-split=yes-no /columns=integers /comments=pattern /decimal=text /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-cache=yes-no /ignore-empty=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column Other name: v • file…: the files to load – values: one or more files. Can include wildcards such as *, [0-4], etc… • /auto-split=yes-no: if on, create a new dataset at every fully blank line (off by default) – values: a boolean: yes, on, true or no, off, false • /columns=integers: columns loaded from the file – values: a comma-separated list of integers • /comments=pattern: pattern for comment lines – values: plain text, or regular expressions enclosed within / / delimiters • /decimal=text: decimal separator – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “ • /expected=integer: Expected number of loaded datasets – values: an integer • /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’ • /for-which=code: Select on formula – values: a piece of Ruby code • /histogram=yes-no: whether to show as a histogram (defaults to false) – values: a boolean: yes, on, true or no, off, false • /ignore-cache=yes-no: if on, ignores cache (default off) – values: a boolean: yes, on, true or no, off, false • /ignore-empty=yes-no: if on, skips empty files (default on) – values: a boolean: yes, on, true or no, off, false • /separator=pattern: separator between columns – values: plain text, or regular expressions enclosed within / / delimiters • /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements • /skip=integer: skip that many lines at beginning – values: an integer • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green • /yerrors=column: name of the column containing y errors – values: the number/name of a column in a dataset This command combines overlay-buffer and load in one go: loads the files given as arguments and adds them to the current plot; it has the same options as those commands. ### clear – Clear view clear Removes all datasets except the current dataset from the display. Use to revert the effect of a previous overlay command, or can be useful if for some reason a command failed while not restoring the display (but that should not happen anyway). ### points – Show points points Other name: poi Shows datapoints (by default, datasets are plotted by connecting datapoints with a line). Beware that it may slow down display if you have a large number of data points. ### zoom – Zoom zoom (interactive) Other name: z Zooms on the current curve. Click to delimit a region. Hit x to zoom in on the X axis, X to zoom out, y and Y for the Y axis, and z/Z for both at the same time. Hit c to reset the zoom. Indepently of this function, you can use the mouse wheel at any moment to zoom in and out: • mouse wheel: zoom in and out vertically • Shift+mouse wheel: zoom in and out horizontally • Ctrl (or Cmd) + mouse wheel: zoom in and out (horizontally and vertically) • Shift+Ctrl + mouse wheel: reset zoom. If you know the coordinates around which you’d like to zoom, you may want to use limits instead. ### limits – Set limits limits left right bottom top • left: Left limit – values: a floating-point number • right: Right limit – values: a floating-point number • bottom: Bottom limit – values: a floating-point number • top: Top limit – values: a floating-point number This is the non-interactive version of zoom. You specify the left, right, bottom and top values of the currently displayed window directly on the command-line. There are two special values: • * means “auto”, or in other words the maximum needed to see all the curves for that specific side (left, right, bottom or top) • = means “don’t change” # Data stack manipulation Data files are loaded and manipulated in a stack. Every time a file is loaded or a dataset modified, the new dataset is pushed onto the top of the stack, and becomes the current dataset (numbered 0). Older datasets have increasing numbers (the previous dataset is 1, the one before 2, and so on). There is also a “redo” stack populated by the undo command. Stack can be manipulated in different ways: ### browse-stack – Browse stack browse-stack /buffers=datasets /for-which=code (interactive) Other name: K • /buffers=datasets (default option): Datasets to show – values: comma-separated lists of datasets in the stack, see dataset lists • /for-which=code: Only act on datasets matching the code – values: a piece of Ruby code Displays the contents of the stack using a dialog box that works similarly to the one of the browse command. It is possible to fine-tune the datasets to browse using: * the /buffers option, which takes a dataset list; * the /for-which option, that takes a condition, see the dedicated section for more information. If the option /meta= is specified, the command also lists the values of the given, comma-separated, meta data. ### show-stack – Show stack show-stack /meta=words /number=integer Other name: k • /meta=words: also lists the comma-separated meta-data – values: several words, separated by ‘,’ • /number=integer (default option): Display only that many datasets around 0 – values: an integer Shows a small text summary of what the stack is made of. If your stack is large and you just need to look at a few datasets, use /number=10 for instance (that will only show datasets -9 to 9). ### undo – Undo undo /number=integer Other name: u • /number=integer (default option): Number of operations to undo – values: an integer Returns to the previous dataset, and pushes the current to the redo stack. If /number= is specified, repeats that many times. ### redo – Redo redo /number=integer Other name: r • /number=integer (default option): Number of operations to redo – values: an integer Pops the last dataset from the redo stack and sets it as the current dataset. /number has the same meaning as for undo. ### save-stack – Save stack save-stack file • file: File name for saving stack – values: name of a file Saves the entire contents of the stack (all the datasets, their flags and their meta-data) for later use in a .qst file, which is in a binary format. This file is only meant to be loaded again with either the command load-stack, directly from the command-line using the --load-stack command-line option, or directly by double-clicking from your favorite file manager. If you’d rather save every file in the stack separately as a text file, use the save-datasets command: QSoas> save-datasets all Stack file format QSoas uses a simple binary format for saving the stack. It stores all the datasets of the stack, including their meta-data, perpendicular coordinates and flags. It does not save: • the currently displayed datasets (the datasets are saved but not the information that they are displayed; • user-defined Ruby functions/variables; • user-defined fits. ### load-stack – Load stack load-stack file /merge=yes-no • file: File name for saving stack – values: name of a file • /merge=yes-no: If true, merges into the current stack rather than overwriting – values: a boolean: yes, on, true or no, off, false Loads a saved stack, from a file that was created using save-stack. If /merge=true is used, then the previous datasets are kept, and the contents of the stack files are just merged into the stack. ### clear-stack – Clear stack clear-stack Other name: delstack Removes all the datasets from both normal and redo stack ### fetch – Fetch datasets from the stack fetch datasets… • datasets…: Datasets to fetch – values: comma-separated lists of datasets in the stack, see dataset lists Put back a copy of the given dataset on the top of the stack. Useful when you want to work again on a old dataset buried in the stack. ### drop – Drop dataset drop /buffers=datasets • /buffers=datasets (default option): Datasets to drop – values: comma-separated lists of datasets in the stack, see dataset lists Permanently deletes the current dataset (or the ones specified in the /buffers options) from the stack. QSoas> drop 3..16 drops all the datasets from 3 to 16 included. Important: it is not possible to recover a dataset once it has been dropped from the stack. undo won’t work. ### flag – Flag datasets flag /buffers=datasets /exclusive=yes-no /flags=words /for-which=code /set=yes-no • /buffers=datasets (default option): Buffers to flag/unflag – values: comma-separated lists of datasets in the stack, see dataset lists • /exclusive=yes-no: If on, clears the given flags on all the datasets but the ones specified – values: a boolean: yes, on, true or no, off, false • /flags=words: Flags to set/unset – values: several words, separated by ‘,’ • /for-which=code: Only act on datasets matching the code – values: a piece of Ruby code • /set=yes-no: If on, clears all the previous flags – values: a boolean: yes, on, true or no, off, false Flags the given dataset (or the current one if none is supplied) for later use. All currently flagged datasets can be specified using the flagged argument to, for instance, overlay-buffer. QSoas supports arbitrary text flags, by passing a comma-separated list of flags to the /flags= option. In the absence of that, the datasets are flagged with the flag name default. Datasets can hold an arbitrary number of flags. For instance: QSoas> flag 0..5 /flags=exp1,fit flags datasets 0 to 5 with the flags exp1 and fit. Datasets are flagged ‘in-place’: the current dataset is not changed. If the /for-which option is present, the flags are only applied to the datasets that match the specifications given. See more about that there. By default, flag does not touch already existing flags. However, if you use /exclusive=true, then all the flags that are not set explictly with the command are cleared. ### unflag – Unflag datasets unflag /buffers=datasets /flags=words /for-which=code • /buffers=datasets (default option): Buffers to flag/unflag – values: comma-separated lists of datasets in the stack, see dataset lists • /flags=words: Flags to set/unset – values: several words, separated by ‘,’ • /for-which=code: Only act on datasets matching the code – values: a piece of Ruby code Does the reverse of flag, that is removes all flags on the given datasets, or only those specified by the /flags option if the latter is present. The /for-which option words exactly in the same way as for flag. ### auto-flag – Auto flag auto-flag /flags=words • /flags=words (default option): Flags – values: several words, separated by ‘,’ Flags the datasets produced by all commands afterwards, until a call to auto-flag without options: QSoas> auto-flag /flags=stuff [ ... create new datasets. They will all be flagged stuff, until the following command ...] QSoas> auto-flag This can be used to flag all the datasets produced by a script, for instance. # Basic data manipulation at the dataset level ### apply-formula – Apply formula apply-formula formula /buffers=datasets /extra-columns=integer /flags=words /for-which=code /keep-on-error=yes-no /set-meta=meta-data /style=style /use-meta=yes-no /use-stats=yes-no Other name: F • formula: formula – values: a piece of Ruby code • /buffers=datasets (default option): Datasets to work on – values: comma-separated lists of datasets in the stack, see dataset lists • /extra-columns=integer: number of extra columns to create – values: an integer • /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’ • /for-which=code: Only act on datasets matching the code – values: a piece of Ruby code • /keep-on-error=yes-no: if on, the points where the Ruby expression returns a error are kept, as invalid numbers – values: a boolean: yes, on, true or no, off, false • /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green • /use-meta=yes-no: if on (by default), you can use $meta to refer to the dataset meta-data – values: a boolean: yes, on, true or no, off, false
• /use-stats=yes-no: if on (by default), you can use $stats to refer to statistics (off by default) – values: a boolean: yes, on, true or no, off, false Applies a formula to the current dataset. It should specify how the x and/or y values of the dataset are modified: QSoas> apply-formula x=x**2 QSoas> apply-formula y=sin(x**2) QSoas> apply-formula x,y=y,x The last bit swaps the $x$ and $y$ values of the dataset. The formula must be valid ruby code. In addition to x and y (note the lowercase !), the formula can refer to: • i, the index of the data point • seg, the number of the current segment (starting from 0) • x_0, the value of $x$ of the first point of the current segment • i_0, the index of the first point in the current segment • y2, y3, etc when there are more than 2 columns in the dataset i and seg cannot be modified, but y2 and so on can. Here is how you can use i to have even points draw a sine wave and odd points a cosine: QSoas> apply-formula y=(i%2==0?sin(x):cos(x)) % is the modulo operator. The construction with ? and : (called the ternary operator means: if i%2==0 is true, then the value is sin(x), else cos(x). You can use several instructions by separating them with ;: QSoas> apply-formula x=x**2;y=x**2 This results in x values that are the squares of the old values, and y values that are the square of the new x values. Extra columns initially filled with 0 can be created by using the /extra-columns option: QSoas> apply-formula /extra-columns=1 y2=y**2 This creates a third column (a second y column) containing the square of the values of the Y column. If /use-stats=true is used, a global variable $stats can be used in the Ruby expression. It contains all the statistics displayed by stats. For instance, to normalize the Y values by dividing by the median, one would use:

QSoas> apply-formula /use-stats=true y=y/$stats.y_med Note that you can make use of the special /= operator to shorten that into: QSoas> apply-formula /use-stats=true y/=$stats.y_med

Statistics by segments (see more about segments there) are available too, which means if you want to normalize by the medians of the first segment, you could do

QSoas> apply-formula /use-stats=true y/=$stats[0].y_med If /use-meta is true (the default), then a global variable $meta is defined that contains the value of the meta-data (what is shown by show). What you make of this will greatly depend of the meta-data QSoas has gathered from your file (and those you have set manually using set-meta).

Some results will give “invalid numbers”, such as sqrt(-1). By default, QSoas strips the points corresponding to the invalid results, but you can keep them (as invalid numbers) using /keep-on-error=true (but be aware that working with invalid numbers is a real pain !).

It is now possible to work with several datasets using the /buffers option, and control the resulting datasets using the commands described there.

### dx – DX

dx

Replaces the Y values by the values of delta X, i.e, y[i] = x[i+1] - x[i]. This is useful to see if the X values are equally spaced.

### dy – DY

dy

Same as dx but for Y values: replaces the Y values by the values of delta Y.

### zero – Makes 0

zero value /axis=axis

• value: – values: a floating-point number
• /axis=axis: which axis is zero-ed (default y) – values: one of: x, y

Given an X value, shifts the Y values so that the point the closest to the given X value has 0 as Y value.

If /axis is x, swap X and Y in the above description.

### shiftx – Shift X values

shiftx

Shift X values so that the first point has a X value of 0.

### norm – Normalize

norm /map-to=numbers /positive=yes-no

• /map-to=numbers (default option): Normalizes by mapping to the given segment – values: several floating-point numbers, separated by :
• /positive=yes-no: whether to normalize on positive or negative values (default true) – values: a boolean: yes, on, true or no, off, false

Normalizes the current dataset by dividing by its maximum value, or, if /positive=false by the absolute value of its most negative value.

If the /map-to option is specified, the original dataset is mapped linearly to the given interval:

norm /map-to=2:4

shifts and scales the original data so that the Y minimum is 2 and the Y maximum is 4.

### deldp – Deldp

deldp (interactive)

With this command, you can click on given data points to remove them. Useful to remove a few spikes from the data. Middle click or q to accept the modifications, hit escape to cancel them.

### edit – Edit dataset

edit

Opens a spreadsheet-like window where you can view and edit the individual values of the current dataset. If you want to save your modification, press the “push new” button.

### sort – Sort

sort

Sorts the dataset in increasing X values.

### reverse – Reverse

reverse

Reverses the order of all the data points: the last one now becomes the first one, and so on. Though this has no effect on the look of the data, this will impact commands that work with indices, such as cut and the multi-dataset processing commands (such as subtract, div) with /mode=indices.

### strip-if – Strip points

strip-if formula /threshold=integer /use-meta=yes-no /use-stats=yes-no

• formula: Ruby boolean expression – values: a piece of Ruby code
• /threshold=integer: If the stripping operation leaves less than that many points, do not create a new dataset – values: an integer
• /use-meta=yes-no: if on (by default), you can use $meta to refer to the dataset meta-data – values: a boolean: yes, on, true or no, off, false • /use-stats=yes-no: if on, you can use $stats to refer to statistics (off by default) – values: a boolean: yes, on, true or no, off, false

Removes all points for which the ruby expression returns true. This can be used for quite advanced data selection:

QSoas> strip-if x>2

This removes all points whose X value is greater than 2.

QSoas> strip-if x>2||x<4

This removes all points whose X value is greater than 2 or whose X value is lower than 4. The || bit means OR. In other terms, it keeps only the X values between 2 and 4.

QSoas> strip-if x*y<10&&x>2

This removes all the points for which both the X value is greater than 2 and the product of X and Y is lower than 10.

When reading data files that contain spurious data points (such as text lines containing no data within a file read with load-as-text), QSoas replaces the missing data by weird numbers called NaN (Not a Number). They can be useful at times, but mess up statistics and fits. To remove them, use:

QSoas> strip-if x.nan?||y.nan?

Like in apply-formula, you can use the statistics and the meta-data of the datasets if you use the options /use-meta (on by default) and /use-stats.

By default, strip-if creates a new dataset regardless of the number of points left (even if there are no points left). Giving a value to the /threshold option will prevent strip-if from creating a new dataset if it has less than that many points.

### integrate – Integrate

integrate /index=integer

• /index=integer: index of the point that should be used as y = 0 – values: an integer

Integrate just does the reverse of diff and integrates the current dataset. First data point is the one for which Y=0, unless an index is specified to the /index option, in which case the numbered point ends up being at 0.

### diff – Derive

diff /derivative=integer /order=integer

• /derivative=integer: the number of the derivative to take, only valid together with the order option – values: an integer
• /order=integer: total order of the computation – values: an integer

Computes the 4th order accurate derivative of the dataset.

This is efficient to compute the derivative of smooth data, but it gives very poor results on noisy data. In general, for derivation of real data, prefer filter-fft, filter-bsplines or auto-reglin, which will give much better results.

Starting from QSoas version 2.1, a second mode is available, in which you can choose an arbitrary order for the derivation (has to be less than the number of points of the dataset), via the option /order=, and an optional derivative via the /derivative option. For instance, you can reproduce the effect of diff2 using:

QSoas> diff /order=4 /derivative=2

### diff2 – Derive twice

diff2

Computes the 4th order accurate second derivative of the dataset.

The same warnings apply as for diff.

### dataset-options – Options

dataset-options /histogram=yes-no /yerrors=column

• /histogram=yes-no: whether to show as a histogram (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /yerrors=column: name of the column containing y errors – values: the number/name of a column in a dataset

Sets options for the current dataset:

• /yerrors sets the display of errors on Y values, see there for more information on how to specify the columns;
• /histogram sets wether or not the dataset should be displayed as a histogram.

### edit-errors – Edit errors

edit-errors (interactive)

Provides an interface for editing manually the errors attached to each point of the current dataset. This function will create a column containing errors if there is none yet.

Pick left and right bounds with the left and right mouse buttons and set the errors within the bounds with i and outside with o. This is typically used to crudely exclude some bits of the dataset from fitting, by setting much larger errors for the bits than for the rest.

## Splitting the dataset in bits (and back)

### cut – Cut

cut (interactive)

Other name: c

Interactively cuts bits out of the dataset. Left and right mouse clicks set the left and right limits. Middle click or q quits leaving only the part that is within the region, while u leaves only the outer part. r remove the part inside the region, but lets you keep on editing the dataset. Hit escape to cancel.

By default, the Y values are displayed as a function of the index; you can switch back to display Y values as a function of X by hitting x.

### chop – Chop dataset

chop lengths… /flags=words /mode=choice /set-meta=meta-data /set-segments=yes-no /style=style

• lengths…: Lengths of the subsets – values: several floating-point numbers, separated by ,
• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /mode=choice: Whether to cut on index or x values (default) – values: one of: deltax, index, indices, xvalues
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /set-segments=yes-no: Whether to actually cut the dataset, or just to set segments where the cuts would have been – values: a boolean: yes, on, true or no, off, false
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Cuts the dataset into several parts based on the numbers given as arguments, and save them as separate datasets. The intepretation of the numbers depends on the value of the /mode option:

• deltax (default): the numbers are the length (in terms of X) of the sub-datasets
• xvalues: the numbers are the X values at which to split
• index (or indices): the numbers are the indices of the points at which to split

If /set-segments is on, the X values are not used to create independent datasets but rather to set the position of the segments.

### splita – Split first

splita

Returns the first part of the dataset, until the first change of sign of $\Delta x$.

Useful to get the forward scan of a cyclic voltammogram.

### splitb – Split second

splitb

Returns the part of the dataset after the first change of sign of $\Delta x$.

Useful to get the backward scan of a cyclic voltammogram.

### split-monotonic – Split into monotonic parts

split-monotonic /flags=words /group=integer /keep-first=integer /keep-last=integer /set-meta=meta-data /style=style

• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /group=integer: Group that many segments into one dataset – values: an integer
• /keep-first=integer: Keep only the first n elements of the results – values: an integer
• /keep-last=integer: Keep only the last n elements of the results – values: an integer
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Splits the dataset into datasets where all parts have X values that increase or decrease monotonically.

With /group=2, each resulting dataset will contain two monotonic segments.

Using the /keep-first or /keep-last options make it possible to only keep a given number of the generated datasets.

### unwrap – Unwrap

unwrap /reverse=yes-no /scan-rate=number

• /reverse=yes-no: If true, reverses the effect of a previous unwrap command – values: a boolean: yes, on, true or no, off, false
• /scan-rate=number: Sets the scan rate – values: a floating-point number

This command makes the X values of the current dataset monotonic by ensuring that the value of $\Delta x$ always have the same sign, changing it if needed. The command places segments limits at the position of the changes in direction.

This is useful for instance to convert a cyclic voltammogram from $i = f(E)$ to $i = f(t)$; for that purpose, the scan rate can be provided using the /scan-rate= option, or can be guessed from the sr meta-data.

The unwrap operation can be reverted by calling unwrap with /reverse=true, which will use the scan rate information and the position of the segments to reconstruct the original data.

### cat – Concatenate

cat buffers… /add-segments=yes-no

Other name: i

• buffers…: Datasets to concatenate – values: comma-separated lists of datasets in the stack, see dataset lists
• /add-segments=yes-no: If on (default) segments are added between the old datasets – values: a boolean: yes, on, true or no, off, false

Concatenates the datasets given as arguments, adding segment stops inbetween (unless /add-segments=false is used). This can be used to reverse the effect of the previous commands.

This does not change the number of columns. If you want to gather several Y columns as a function of the same X, use contract instead.

## Dataset’s meta-data and perpendicular coordinates

QSoas’ datasets (or buffers) hold more than just columns of numbers. When a file is loaded, QSoas also gathers as much information as possible about that file, such as original file name, file date, and, for file formats supported by QSoas, details about the experimental conditions recorded in that file. These are known as “meta-data”, and can be displayed using the show command.

Here are some meta-data of particular signification available to all datasets loaded from files:

• file_date is the date of the file
• original_file is the file name of the loaded file
• age is the how old the file was in seconds when the current QSoas session was started.
• commands is the list of commands that have been applied to this dataset since its load/creation.

Upon saving using save all meta-data are saved as comments in the text file.

Perpendicular coordinates make sense when a dataset has several Y columns. For instance, when the dataset consists in spectra taken at different times, like in the tutorial (or at different solution potentials for a redox titration), then the X values will be the wavelength, and each Y column will correspond to a different time. Then the time is the perpendicular coordinate. One can set the perpendicular coordinate manually using set-perp.

Many commands use perpendicular coordinates, most notably transpose (that would convert columns of $y = f(\lambda)$ for different values of $t$ above into columns of $y = f(t)$ for different values of $\lambda$), and all the multi-fit commands, which show parameters as a function of the perpendicular coordinates when applicable.

Some of the meta-data has special meaning for QSoas, which uses them for specific functions:

## Selecting datasets and files based on meta-data

Some commands, namely flag, unflag and browse accept a /for-which option to select the datasets (or files) they work on based on their properties. The value of the /for-which is a ruby formula that uses the global variables $meta and $stats variables. For instance, the following command flags all the datasets that have a maximum value greater than 1e-4:

QSoas> flag all /for-which $stats.y_max>=1e-4 How to test for equality: in ruby, you need to use == to test whether two values are the same. For instance, to flag voltammograms in which the scan rate is 0.1 V/s, you have to use: QSoas> flag all /for-which$meta.sr==0.1

### ruby-run – Ruby load

ruby-run file (fit command)

• file: Ruby file to load – values: name of a file

Like the other ruby-run, loads and run a Ruby code file.

### save-history – Save history

save-history file (fit command)

• file: Output file – values: name of a file

Like the other save-history, saves all the commands typed into the fit window to the given file.

### run – Run commands

run file… /add-to-history=yes-no /cd-to-script=yes-no /error=choice /silent=yes-no (fit command)

Other name: @

• file…: First is the command files, following are arguments – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /add-to-history=yes-no: whether the commands run are added to the history (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /cd-to-script=yes-no: If on, automatically change the directory to that oof the script – values: a boolean: yes, on, true or no, off, false
• /error=choice: Behaviour to adopt on error – values: one of: abort, delete, except, ignore
• /silent=yes-no: whether or not to switch off display updates during the script (off by default) – values: a boolean: yes, on, true or no, off, false

Like the other run command, runs the given script. The options and arguments are interpreted the same way as the other run command.

### run-for-each – Runs a script for several arguments

run-for-each script arguments… /add-to-history=yes-no /arg2=file /arg3=file /arg4=file /arg5=file /arg6=file /error=choice /range-type=choice /silent=yes-no (fit command)

• script: The script file – values: name of a file
• arguments…: All the arguments for the script file to loop on – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /add-to-history=yes-no: whether the commands run are added to the history (defaults to false) – values: a boolean: yes, on, true or no, off, false
• /arg2=file: Second argument to the script – values: name of a file
• /arg3=file: Third argument to the script – values: name of a file
• /arg4=file: Fourth argument to the script – values: name of a file
• /arg5=file: Fifth argument to the script – values: name of a file
• /arg6=file: Sixth argument to the script – values: name of a file
• /error=choice: Behaviour to adopt on error – values: one of: abort, delete, except, ignore
• /range-type=choice: If on, transform arguments into ranged numbers – values: one of: lin, log
• /silent=yes-no: whether or not to switch off display updates during the script (off by default) – values: a boolean: yes, on, true or no, off, false

Like the other run-for-each, runs a script for several values of its first parameter.

### verify – Verify

verify expression (fit command)

• expression: the expression to evaluate – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

Does the same as the general verify command.

### fit – Fit

fit /iterations=integer (fit command)

• /iterations=integer: the maximum number of iterations of the fitting process – values: an integer

Runs the fit, optionally changing the number of maximum fit iterations through the /iterations option.

### commands – Commands

commands (fit command)

Like the other commands command, list the commands available from within the fit prompt.

### system – System

system command… /shell=yes-no /timeout=integer (fit command)

• command…: Arguments of the command – values: one or more files. Can include wildcards such as *, [0-4], etc…
• /shell=yes-no: use shell (on by default on Linux/Mac, off in windows) – values: a boolean: yes, on, true or no, off, false
• /timeout=integer: timeout (in milliseconds) – values: an integer

Like the other system command, runs an external program.

### push – Push to stack

push /flags=words /recompute=yes-no /residuals=yes-no /set-meta=meta-data /style=style /subfunctions=yes-no (fit command)

• /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’
• /recompute=yes-no: whether or not to recompute the fit (on by default) – values: a boolean: yes, on, true or no, off, false
• /residuals=yes-no: if true, push the residuals rather than the computed values – values: a boolean: yes, on, true or no, off, false
• /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements
• /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
• /subfunctions=yes-no: whether the subfunctions are also exported or not – values: a boolean: yes, on, true or no, off, false

Pushes the computed function to the stack, like the fit sim- command would do.

## Parameter space exploration

QSoas now provides facilities for parameter space exploration. The idea is that QSoas will attempt several (many!) fits with different starting parameters. There are different explorers that choose new starting parameters in a different way, but all explorers can be used this way:

QSoas.fit> monte-carlo-explorer A_inf:-10..10
Selected parameter space explorer: 'monte-carlo'
Setting up monte-carlo explorator with: 20 iterations and 50 fit iterations
* A_inf[#0]: -10 to 10 lin
QSoas.fit> iterate-explorer

The first command sets up the explorer, here the monte-carlo-explorer, and the second iterates the explorer, chosing new parameters and running the fits, until the number of iterations specified by the explorer is finished.

### monte-carlo-explorer – Monte Carlo

monte-carlo-explorer parameters… /fit-iterations=integer /iterations=integer /reset-frequency=integer (fit command)

• parameters…: Parameter specification – values: several words, separated by ‘’
• /fit-iterations=integer: Maximum number of fit iterations – values: an integer
• /iterations=integer: Number of monte-carlo iterations – values: an integer
• /reset-frequency=integer: If > 0 reset to the best parameters every that many iterations – values: an integer

Sets up a “Monte Carlo” exploration, i.e. an exploration in which the initial parameters are chosen uniformly within given segments.

QSoas.fit> monte-carlo-explorer A_inf:-10..10 tau_1:1e-2..1e2,log

This command sets up the exploration, with the parameter A_inf uniformly distributed between -10 and 10, and tau_1 with a log uniform distribution between 1e-2 and 1e2. The other parameters are left untouched from the previous fit iteration.

### linear-explorer – Linear ramp

linear-explorer parameters… /fit-iterations=integer /iterations=integer (fit command)

• parameters…: Parameter specification – values: several words, separated by ‘’
• /fit-iterations=integer: Maximum number of fit iterations – values: an integer
• /iterations=integer: Number of monte-carlo iterations – values: an integer

Linearly (or logarithmically) varies the parameter between the given range:

QSoas.fit> linear-explorer A_inf:-10..10

This command runs a number of fits with the initial value of A_inf ranging from -10 to +10. You can specify several parameters this way, they will be varied simultaneously (i.e. they will be linearly correlated). Adding ,log switches to an exponential progression.

### iterate-explorer – Iterate explorer

iterate-explorer /arg1=file /arg2=file /improved-script=file /just-pick=yes-no /pre-script=file /script=file (fit command)

• /arg1=file: First argument to the scripts – values: name of a file
• /arg2=file: Second argument to the scripts – values: name of a file
• /improved-script=file (default option): script file run whenever the best residuals have improved – values: name of a file
• /just-pick=yes-no: If true, then just picks the next initial parameters, don’t fit, don’t iterate – values: a boolean: yes, on, true or no, off, false
• /pre-script=file (default option): script file run after choosing the parameters and before choosing the file – values: name of a file
• /script=file (default option): script file run after the iteration – values: name of a file

Runs all the iterations of the previously setup explorer. If /just-pick=true is specified, then just picks the parameters once, do not run the iterations nor any fit.

The /pre-script, /script and /improved-script options specify the names of script files that will be run either after picking the parameters but before running the fit, after the fit, or every time the best residuals are improved. They can be given additional arguments through the /arg1 and /arg2 options.

# Computation/simulations functions

The commands in this section generate data “from scratch”, though most require a dataset as a starting point to provide X values. You can create a dataset for those commands using generate-dataset.

## Evaluation functions

QSoas provides various functions to evaluate the result of mathematical operations.

### eval – Ruby eval

eval code /buffers=datasets /for-which=code /modify-meta=yes-no /use-dataset=yes-no

• code: Any ruby code – values: a piece of Ruby code
• /buffers=datasets (default option): Datasets to run eval on – values: comma-separated lists of datasets in the stack, see dataset lists
• /for-which=code: Only act on datasets matching the code – values: a piece of Ruby code
• /modify-meta=yes-no: Reads backs the modifications made to the $meta hash (implies /use-dataset=true) – values: a boolean: yes, on, true or no, off, false • /use-dataset=yes-no: If on (the default) and if there is a current dataset, the$meta and $stats hashes are available – values: a boolean: yes, on, true or no, off, false Evaluates the given code as a Ruby expression: QSoas> eval 2*3 => 6 It runs in the same environment as the apply-formula and the custom fits (excepted, of course, that there are no x and y variables). It can be useful to check that a function has been correctly defined in a file loaded by ruby-run. Moreover, if /use-dataset is true (the default), it can also access the meta-data and statistics of the (as apply-formula with /use-meta=true and /use-stats=true) of the dataset: QSoas> generate-dataset 0 10 x**3 QSoas> eval '$stats["y_int"]'
=> 2500.002505007509

You can also use this command as a calculator.

### verify – Verify

verify code /buffers=datasets /for-which=code /use-dataset=yes-no

• code: Any ruby code – values: a piece of Ruby code
• /buffers=datasets (default option): Datasets to run verify on – values: comma-separated lists of datasets in the stack, see dataset lists
• /for-which=code: Only act on datasets matching the code – values: a piece of Ruby code
• /use-dataset=yes-no: If on (the default) and if there is a current dataset, the $meta and$stats hashes are available – values: a boolean: yes, on, true or no, off, false

Evaluates the given Ruby code. If its value is false, the command fails.

This function only makes sense in scripts, to abort a script before running long computations if one detects that something went wrong. If the data you load really should only have positive X values, then you can ensure that this way:

# X values are positive
verify $stats.x_min>0 ### find-root – Finds a root find-root formula seed /max=number • formula: An expression of 1 variable (not an equation !) – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “ • seed: Initial X value from which to search – values: a floating-point number • /max=number (default option): If present, uses dichotomy between seed and max – values: a floating-point number Find the root of the given x-dependent expression using an iterative algorithm, using seed as the initial value. If the /max option is specified, then the search proceeds using dichotomy between the two values (seed and max). QSoas> find-root 'x**2 - 3' 1 Found root at: 1.73205 Do not use a equal sign. The returned value is that for which the expression equates 0. ### integrate-formula – Integrate expression integrate-formula formula a b /integrator=choice /prec-absolute=number /prec-relative=number /subdivisions=integer • formula: An expression of 1 variable (not an equation !) – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “ • a: Left bound of the segment – values: a floating-point number • b: Right bound of the segment – values: a floating-point number • /integrator=choice: The algorithm used for integration – values: one of: gauss15, gauss21, gauss31, gauss41, gauss51, gauss61, qng • /prec-absolute=number: Absolute precision required for integration – values: a floating-point number • /prec-relative=number: Relative precision required for integration – values: a floating-point number • /subdivisions=integer: Maximum number of subdivisions in the integration algorithm – values: an integer Computes the integral of the given expression of x between bounds a and b: QSoas> integrate-formula x**2 10 22 Integral value: 3216 estimated error: 3.57048e-11 in 31 evaluations over 1 intervals  The available integrators are gaussi (with i ranging from 15 to 61), which correspond to adaptive Gauss-Kronrod integrators (starting with i evaluations), and qng, which is a non-adaptive Gauss-Kronrod integrator. See the documentation of the GNU Scientific Library for more information. ### mintegrate-formula – Integrate expression mintegrate-formula formula a b /integrator=choice /max-evaluations=integer /prec-absolute=number /prec-relative=number • formula: An expression of x and z – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “ • a: Lower Z value – values: a floating-point number • b: Upper Z value – values: a floating-point number • /integrator=choice: The algorithm used for integration – values: one of: akima, csplines, gk15, gk21, gk31, gk41, gk51, gk61, naive • /max-evaluations=integer: Maximum number of function evaluations – values: an integer • /prec-absolute=number: Absolute precision required for integration – values: a floating-point number • /prec-relative=number: Relative precision required for integration – values: a floating-point number This command takes a function of $x$ and $z$, two numbers, $a$ and $b$, and computes, for each value of $x$ of the current dataset, the integral: This command uses the same algorithms for integration as the fits created by define-distribution-fit. ### generate-dataset – Generate dataset generate-dataset start end /flags=words /formula=text /number=integer /samples=integer /set-meta=meta-data /style=style Other name: generate-buffer • start: The first X value – values: a floating-point number • end: The last X value – values: a floating-point number • /flags=words: Flags to set on the newly created datasets – values: several words, separated by ‘,’ • /formula=text (default option): Formula to generate the Y values – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “ • /number=integer: generates that many datasets – values: an integer • /samples=integer: number of data points – values: an integer • /set-meta=meta-data: Meta-data to add to the newly created datasets – values: one or more meta=value assignements • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green Generates a dataset with samples samples (by default 1000) uniformly spaced between start and end. If formula is provided, it sets Y values according to this formula (else Y is take equal to X). QSoas> generate-dataset -10 10 sin(x) ## Simulation functions ### kinetic-system – Kinetic system evolver kinetic-system reaction-file parameters /adaptive=yes-no /annotate=yes-no /dump=yes-no /min-step-size=number /prec-absolute=number /prec-relative=number /step-size=number /stepper=stepper /sub-steps=integer • reaction-file: File describing the kinetic system – values: name of a file • parameters: Parameters of the model – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “ • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false • /annotate=yes-no: If on, a last column will contain the number of function evaluation for each step (default false) – values: a boolean: yes, on, true or no, off, false • /dump=yes-no: if on, prints a description of the system rather than solving (default: false) – values: a boolean: yes, on, true or no, off, false • /min-step-size=number: minimum step size for the stepper – values: a floating-point number • /prec-absolute=number: absolute precision required – values: a floating-point number • /prec-relative=number: relative precision required – values: a floating-point number • /step-size=number: initial step size for the stepper – values: a floating-point number • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45 • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer Simulates the evolution over time of the kinetic system given in the reaction-file (see the section kinetic system for the syntax of the reaction files). This commands will use the current dataset as a source for X values. The result is a multi-column dataset containing the concentration of all the species in the different columns. parameters is a list of assignments evaluated at the beginning of the time evolution to set the parameters of the system. (all parameters not set this way default to 0). This list is evaluated as Ruby code, so you should separate the assignments with ;. For instance, if the reaction file (system.sys) contains: A <=>[ki][ka] I You can run the following commands to simulate the time evolution of the system with initial concentration of A equal to 1 (the parameter c0_A), of I equal to 0 (the parameter c0_I, here not specified so assumed to be 0) and with ki and ka equal to 1: QSoas> generate-dataset 0 10 QSoas> kinetic-system system.sys 'c0_A = 1;ka = 1; ki = 1' ### ode – ODE solver ode file /adaptive=yes-no /annotate=yes-no /dump=yes-no /min-step-size=number /parameters=text /prec-absolute=number /prec-relative=number /step-size=number /stepper=stepper /sub-steps=integer • file: File containing the system – values: name of a file • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false • /annotate=yes-no: If on, a last column will contain the number of function evaluation for each step – values: a boolean: yes, on, true or no, off, false • /dump=yes-no: If on, do not integrate, just dumps the parse contents of the ODE file – values: a boolean: yes, on, true or no, off, false • /min-step-size=number: minimum step size for the stepper – values: a floating-point number • /parameters=text (default option): Values of the parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “ • /prec-absolute=number: absolute precision required – values: a floating-point number • /prec-relative=number: relative precision required – values: a floating-point number • /step-size=number: initial step size for the stepper – values: a floating-point number • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45 • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer ode solves ordinary differential equations. The equation definition file is structured in three parts, separated by at least one fully blank line, the last one being optional. The first section defines the “initial conditions”; there are as many integrated variables as there are lines in this section. This section is only evaluated once at the beginning of the integration. The second section defines the derivatives; they are evaluated several times for each time step. The third is optional and is described further below. Here is the contents of the file (say sine.ode) one would use to obtain $\sin t$ and $\cos t$ as solutions. sin = 0 cos = 1 d_sin = cos d_cos = -sin Important Make sure that at least one fully blank line separates the definition of the initial values and the definition of the derivatives. Make sure also that to each variable defined in the first section corresponds a derivative in the second, starting with d_. After running the commands: QSoas> generate-dataset 0 10 QSoas> ode sine.ode One has a dataset with one X column (representing the $t$ values), and two Y columns, $\sin t$ and $\cos t$ (in the order in which they are given in the “initial conditions” section). The optional third section can be used to control the exact output of the program. The above example can be completed thus: sin = 0 cos = 1 d_sin = cos d_cos = -sin [sin, cos, sin**2 + cos**2] Using this gives 3 Y columns: $\sin t$, $\cos t$ and $\sin^2 t + \cos^2 t$. The latter should hopefully be very close to 1. Details of the integrations procedures can be tweaked using the parameters: • /stepper: the ODE stepper algorithm. You can find more about them in the GSL documentation. rkf45 is the standard Runge-Kutta-Feldberg integrator, and is the default choice. If QSoas complains that it has difficulties to integrate and that you should try implicit solvers (because your system is too stiff, then try rk4imp, bsimp, msadams or msbdf. • /prec-relative and /prec-absolute control the precision. A step will be deemed precise enough if the error estimate is smaller than either the relative precision or the absolute precision • /adaptive controls whether an adaptive step size is used (the values of $t$ in the resulting dataset are always those asked, but there may be more intermediate steps). You should seldom need to turn it off. If /annotate is on, a last column is added that contains the number of the evaluations of derivatives for each step (useful for understanding why an integration takes so long, for instance). The system of equations may contain undefined variables; one could have for instance used: d_sin = omega * cos d_cos = -omega * sin Their values are set to 0 by default. You can change their values using the /parameters option: QSoas> ode sine.ode /parameters="omega = 3" # Scripting facilities QSoas provides facilities for scripting, ie running commands unattended, for instance for preparing series of data files for fitting or further use. The following commands are useful only in this context. ## Scripting commands ### run – Run commands run file… /add-to-history=yes-no /cd-to-script=yes-no /error=choice /silent=yes-no Other name: @ • file…: First is the command files, following are arguments – values: one or more files. Can include wildcards such as *, [0-4], etc… • /add-to-history=yes-no: whether the commands run are added to the history (defaults to false) – values: a boolean: yes, on, true or no, off, false • /cd-to-script=yes-no: If on, automatically change the directory to that oof the script – values: a boolean: yes, on, true or no, off, false • /error=choice: Behaviour to adopt on error – values: one of: abort, delete, except, ignore • /silent=yes-no: whether or not to switch off display updates during the script (off by default) – values: a boolean: yes, on, true or no, off, false Run commands saved in a file. If a compulsory argument is missing, QSoas will prompt the user. Arguments following the name of the script are passed to the script as “special variables” ${1}, and ${2} etc. Imagine you are often doing the same processing a given type of data files, say, simply filtering them. You just have to write a script process.cmd containing: load${1}
auto-filter-fft 

And run it this way:

QSoas> run process.cmd data_file.dat

or

QSoas> @ process.cmd data_file.dat

If you use run regularly, you may be interested in the other scripting commands, such as run-for-each, run-for-datasets and startup-files

If you want to manipulate the arguments or provide defaut values for some of them, you can use the following syntax:

• ${2%%suffix} will be replaced by parameter 2 with the suffix “suffix” removed, or simply parameter 2 if it does not end with “suffix”. • ${2##prefix} will be replaced by parameter 2 with the prefix “prefix” removed, or simply parameter 2 if it does not start with “prefix”.
• ${2:-value}: this will be replaced by parameter 2 if it has been provided to the script, or by “value” if it has not been provided. • ${2:+value}: this will be replaced by “value” if parameter 2 has been provided to the script, or by nothing if that is not the case (the value of parameter 2 is not used).
• ${2?yes:no}: this will be replaced by “yes” if parameter 2 has been provided to the script, or by “no” if that is not the case. #### Error handling It is possible to change how the script handles errors using the /error option, which can take the following values: • abort (the default behaviour): when a command in the script fails, the script stops executing, and the control comes back to either the command-line or the calling script. In the latter case, this behaviour is not considered as an error (i.e. the calling script does not abort); • ignore: if a command in the script fails, the script keeps on running; • except: as in abort, but this is considered as an error, so this may also stop the calling script; • delete: as in abort, but all the datasets generated during the execution of this script are removed from the stack. ### startup-files – Startup files startup-files /add=file /rm=integer /run=yes-no • /add=file (default option): adds the given startup file – values: name of a file • /rm=integer: removes the numbered file – values: an integer • /run=yes-no: if on, runs all the startup files right now (off by default) – values: a boolean: yes, on, true or no, off, false This command instructs QSoas to execute command files at startup. Without options, it displays the list of command files that QSoas will read at the next startup. Files given to the /add options are added at the end of the list. To remove a file from the list, obtain its number by running startup-files without any option, then use startup-files again with the option /rm=. You can re-run all startup files by running: QSoas> startup-files /run=true ### run-for-each – Runs a script for several arguments run-for-each script arguments… /add-to-history=yes-no /arg2=file /arg3=file /arg4=file /arg5=file /arg6=file /error=choice /range-type=choice /silent=yes-no • script: The script file – values: name of a file • arguments…: All the arguments for the script file to loop on – values: one or more files. Can include wildcards such as *, [0-4], etc… • /add-to-history=yes-no: whether the commands run are added to the history (defaults to false) – values: a boolean: yes, on, true or no, off, false • /arg2=file: Second argument to the script – values: name of a file • /arg3=file: Third argument to the script – values: name of a file • /arg4=file: Fourth argument to the script – values: name of a file • /arg5=file: Fifth argument to the script – values: name of a file • /arg6=file: Sixth argument to the script – values: name of a file • /error=choice: Behaviour to adopt on error – values: one of: abort, delete, except, ignore • /range-type=choice: If on, transform arguments into ranged numbers – values: one of: lin, log • /silent=yes-no: whether or not to switch off display updates during the script (off by default) – values: a boolean: yes, on, true or no, off, false Runs the given script file successively for each argument given. For instance, running: QSoas> run-for-each process-my-file.cmds file1 file2 file3 Is equivalent to running successively QSoas> @ process-my-file.cmds file1 QSoas> @ process-my-file.cmds file2 QSoas> @ process-my-file.cmds file3 The arguments may not be file names, although automatic completion will only complete file names. If the script you want to run requires more than one argument, you can specify them (for all the runs) using the options /arg2, /arg3 and so on: QSoas> run-for-each process-my-file.cmds /arg2=other file1 file2  Is equivalent to running: QSoas> @ process-my-file.cmds file1 other QSoas> @ process-my-file.cmds file2 other If you specify either /range-type=lin or /range-type=log, the parameters are interpreted differently, and are expected to be of the type 1..10:20, which means 20 numbers between 1 and 10 (inclusive), that are spaced either linearly or logarithmically, depending on the value of the option. The /error= option controls how the scripts handle errors. See run for more information. ### run-for-datasets – Runs a script for several datasets run-for-datasets script datasets… /add-to-history=yes-no /arg1=file /arg2=file /arg3=file /arg4=file /arg5=file /arg6=file /error=choice /silent=yes-no • script: The script file – values: name of a file • datasets…: All the arguments for the script file to loop on – values: comma-separated lists of datasets in the stack, see dataset lists • /add-to-history=yes-no: whether the commands run are added to the history (defaults to false) – values: a boolean: yes, on, true or no, off, false • /arg1=file: First argument to the script – values: name of a file • /arg2=file: Second argument to the script – values: name of a file • /arg3=file: Third argument to the script – values: name of a file • /arg4=file: Fourth argument to the script – values: name of a file • /arg5=file: Fifth argument to the script – values: name of a file • /arg6=file: Sixth argument to the script – values: name of a file • /error=choice: Behaviour to adopt on error – values: one of: abort, delete, except, ignore • /silent=yes-no: whether or not to switch off display updates during the script (off by default) – values: a boolean: yes, on, true or no, off, false Runs the given script file for each of the datasets given. Before each invocation of the script, the dataset is pushed back to the top of the stack, as if by fetch. The /error= option controls how the scripts handle errors. See run for more information. ### noop – No op noop /*=words • /*=words (default option): Ignored options – values: several words, separated by ‘’ Does nothing. This command can be combined with the advanced argument uses described in run to conditionally execute some commands. ## Non-interactive commands In addition to purely scripting commands, many commands do not require user interaction, provided all their arguments are given. They are listed here: # Mathematical formulas using Ruby QSoas internally uses Ruby (or more precisely its embedded version, mruby) for the interpretation of all formulas. This means in particular that all formulas must be valid ruby code. Basically, the Ruby syntax ressembles that of other symbolic evaluation programs (it is quite close to the one from gnuplot), with the following restrictions: • Parameter names cannot start with an uppercase letter, as those have a special meaning to the Ruby interpreter: anything that starts with an uppercase letter is assumed to be a constant. • Don’t abbreviate floating point numbers: 2. and .4 are invalid, use 2.0 and 0.4 instead. • Case matters: Pi is $\pi$, while pi is nothing defined. • Exponentiation is done with the ** operator. The ^ operator is used for binary XOR. • Logical OR is done with the || operator and logical AND with the && operator. The single-letter versions, | and & are binary operators and will not work as you intend. ## Special variables Most ruby expressions can make use of dataset information, such as meta-data or statistics (see the documentation of the specific command for more information about how to make this available): • the special variable $stats allow access to the statistics, as given by stats.
• the special variable $meta gives access to the meta-data. For instance, to subtract the average to the y column: QSoas> apply-formula y-=$stats.y_average

To show the name of the original file of the current dataset.

QSoas> eval $meta.original_file Auto completion is able to complete the $stats or \$meta completions.

## Special functions

In addition to standard mathematical functions from the Math module (that contains, among others, the error function erf), the following special functions are available:

•  abs(x): $$x$$
• airy_ai(x): Airy Ai function $AiryAi(x)$. Precision to about $10^{-7}$. Other variants available: airy_ai_fast is faster, (precision $5\times10^{-4}$) and airy_ai_double slower, (precision $2\times10^{-16}$). (more information there)
• airy_ai_deriv(x): First derivative of Airy Ai function $\mathrm{d}AiryAi(x)/\mathrm{d}x$. Precision to about $10^{-7}$. Other variants available: airy_ai_deriv_fast is faster, (precision $5\times10^{-4}$) and airy_ai_deriv_double slower, (precision $2\times10^{-16}$). (more information there)
• airy_bi(x): Airy Bi function $AiryBi(x)$. Precision to about $10^{-7}$. Other variants available: airy_bi_fast is faster, (precision $5\times10^{-4}$) and airy_bi_double slower, (precision $2\times10^{-16}$). (more information there)
• airy_bi_deriv(x): First derivative of Airy Bi function $\mathrm{d}AiryBi(x)/\mathrm{d}x$. Precision to about $10^{-7}$. Other variants available: airy_bi_deriv_fast is faster, (precision $5\times10^{-4}$) and airy_bi_deriv_double slower, (precision $2\times10^{-16}$). (more information there)
• atanc(x): $\frac{\tan^{-1} x}{x}$
• atanhc(x): $\frac{\tanh^{-1} x}{x}$
• bessel_j0(x): Regular cylindrical Bessel function of 0th order, $J_0(x)$ (more information there)
• bessel_j1(x): Regular cylindrical Bessel function of first order, $J_1(x)$ (more information there)
• bessel_jn(x,n): Regular cylindrical Bessel function of n-th order, $J_n(x)$ (more information there)
• bessel_y0(x): Irregular cylindrical Bessel function of 0th order, $Y_0(x)$ (more information there)
• bessel_y1(x): Irregular cylindrical Bessel function of first order, $Y_1(x)$ (more information there)
• bessel_yn(x,n): Irregular cylindrical Bessel function of n-th order, $Y_n(x)$ (more information there)
• clausen(x): Clausen integral, $Cl_2(x) = -\int_0^x \mathrm{d}t \log(2\sin(t/2))$ (more information there)
• dawson(x): Dawson integral, $\exp(-x^2)\int_{0}^{x}\exp(t^2)\mathrm{d} t$
• debye_1(x): Debye function of order 1, $D_1 = (1/x) \int_0^x \mathrm{d}t (t/(e^t - 1))$ (more information there)
• debye_2(x): Debye function of order 2, $D_2 = (2/x^2) \int_0^x \mathrm{d}t (t^2/(e^t - 1))$ (more information there)
• debye_3(x): Debye function of order 3, $D_3 = (3/x^3) \int_0^x \mathrm{d}t (t^3/(e^t - 1))$ (more information there)
• debye_4(x): Debye function of order 4, $D_4 = (4/x^4) \int_0^x \mathrm{d}t (t^4/(e^t - 1))$ (more information there)
• debye_5(x): Debye function of order 5, $D_5 = (5/x^5) \int_0^x \mathrm{d}t (t^5/(e^t - 1))$ (more information there)
• debye_6(x): Debye function of order 6, $D_6 = (6/x^6) \int_0^x \mathrm{d}t (t^6/(e^t - 1))$ (more information there)
• dilog(x): The dilogarithm, $Li_2(x) = - \Re \left(\int_0^x \mathrm{d}s \log(1-s) / s\right)$ (more information there)
• expint_e1(x): Exponential integral $E_1(x) = \int_{x}^{\infty} \frac{\exp -t}{t} \mathrm{d} t$
• expint_e2(x): Exponential integral $E_2(x) = \int_{x}^{\infty} \frac{\exp -t}{t^2} \mathrm{d} t$
• expint_en(x,n): Exponential integral $E_n(x) = \int_{x}^{\infty} \frac{\exp -t}{t^n} \mathrm{d} t$
• fermi_dirac_0(x): Complete Fermi-Dirac integral (index 0), $F_0(x) = \ln(1 + e^x)$ (more information there)
• fermi_dirac_1(x): Complete Fermi-Dirac integral (index 1), $F_1(x) = \int_0^\infty \mathrm{d}t (t /(\exp(t-x)+1))$ (more information there)
• fermi_dirac_2(x): Complete Fermi-Dirac integral (index 2), $F_2(x) = (1/2) \int_0^\infty \mathrm{d}t (t^2 /(\exp(t-x)+1))$ (more information there)
• fermi_dirac_3half(x): Complete Fermi-Dirac integral (index 3/2) (more information there)
• fermi_dirac_half(x): Complete Fermi-Dirac integral (index 1/2) (more information there)
• fermi_dirac_m1(x): Complete Fermi-Dirac integral (index -1), $F_{-1}(x) = e^x / (1 + e^x)$ (more information there)
• fermi_dirac_mhalf(x): Complete Fermi-Dirac integral (index -1/2) (more information there)
• fermi_dirac_n(x,n): Complete Fermi-Dirac integral of index $n$, $F_n(x) = \frac{1}{\Gamma(n+1)} \int_0^\infty \mathrm{d} t \frac{t^n}{\exp(t-x) + 1}$ (more information there)
• gamma(x): The Gauss gamma function $\Gamma(x) = \int_0^{\infty} dt t^{x-1} \exp(-t)$ (more information there)
• gamma_inc(a,x): Incomplete gamma function $\Gamma(a,x) = \int_x^\infty dt t^{a-1} \exp(-t)$ (more information there)
• gamma_inc_p(a,x): Complementary normalized incomplete gamma function $\Gamma_P(a,x) = 1 - \Gamma_Q(a,x) = 1 - \frac{1}{\Gamma(a)}\int_x^\infty dt t^{a-1} \exp(-t)$ (more information there)
• gamma_inc_q(a,x): Normalized incomplete gamma function $\Gamma_Q(a,x) = \frac{1}{\Gamma(a)}\int_x^\infty dt t^{a-1} \exp(-t)$ (more information there)
• gaussian(x,sigma): Normalized gaussian: $p(x,\sigma) = \frac{1}{\sqrt{2 \pi \sigma^2}} \exp (-x^2 / 2\sigma^2)$
• gsl_erf(x): Error function $\mathrm{erf}(x) = \frac{2}{\sqrt{\pi}} \int_0^x \mathrm{d}t \exp(-t^2)$ – GSL version (more information there)
• gsl_erfc(x): Complementary error function $\mathrm{erfc}(x) = 1 - \mathrm{erf}(x)$ (more information there)
• hyperg_0F1(c,x): Hypergeometric function ${}_0F_1$ (more information there)
• hyperg_1F1(a,b,x): Hypergeometric function ${}_1F_1(a,b,x)$ (more information there)
• hyperg_U(a,b,x): Hypergeometric function $U(a,b,x)$ (more information there)
• k_mhc(lambda, eta): Marcus-Hush-Chidsey integral $k(\lambda, \eta) = \int_{-\infty}^{\infty} \exp\left(\frac{ - (x - \lambda + \eta)^2}{4\lambda}\right) \times \frac{1}{1 + \exp x}\,\mathrm{d}x$. Single precision, computed using the fast trapezoid method. (more information there)
• k_mhc_double(lambda, eta): Marcus-Hush-Chidsey integral $k(\lambda, \eta) = \int_{-\infty}^{\infty} \exp\left(\frac{ - (x - \lambda + \eta)^2}{4\lambda}\right) \times \frac{1}{1 + \exp x}\,\mathrm{d}x$. Double precision, computed using the series by Bieniasz, JEAC 2012. (more information there)
• k_mhc_n(lambda, eta): Approximation to the Marcus-Hush-Chidsey integral described in Nahir, JEAC 2002, $k(\lambda, \eta) \approx \int_{-\infty}^{\infty} \exp\left(\frac{ - (x - \lambda + \eta)^2}{4\lambda}\right) \times \frac{1}{1 + \exp x}\,\mathrm{d}x$ (more information there)
• k_mhc_z(lambda, eta): Approximation to the Marcus-Hush-Chidsey integral described in Zeng et al, JEAC 2014, $k(\lambda, \eta) \approx \int_{-\infty}^{\infty} \exp\left(\frac{ - (x - \lambda + \eta)^2}{4\lambda}\right) \times \frac{1}{1 + \exp x}\,\mathrm{d}x$ (more information there)
• lambert_W(x): Principal branch of the Lambert function $W_0(x)$ (more information there)
• lambert_Wm1(x): Secondary branch of the Lambert function $W_{-1}(x)$ (more information there)
• landau(x): Probability density of the Landau distribution, $p(x) = 1/\pi \int_0^x \mathrm{d}t \exp(-t\log(t) - xt)\sin(\pi t)$ (more information there)
• ln_erfc(x): Logarithm of the complementary error function $\log(\mathop{erfc}(x))$ (more information there)
• ln_gamma(x): The logarithm of the gamma function $\log (\Gamma(x))$ (more information there)
• log1p(x): $\ln (1 + x)$, but accurate for $x$ close to 0
• lorentzian(x,gamma): Normalized lorentzian: $p(x,\gamma) = \frac{1}{ \gamma \pi (1 + (x/\gamma)^2) }$
• pseudo_voigt(x, w, mu): Pseudo-Voigt function, defined by: $\frac{1-\mu}{\sqrt{2 \pi w^2}} \exp (-x^2 / 2w^2) + \frac{\mu}{ w \pi (1 + (x/w)^2) }$
• psi(x): Digamma function: $\psi(x) = \Gamma'(x)/\Gamma(x)$ (more information there)
• psi_1(x): Trigamma function: $\psi^{(1)} = \frac{\mathrm d \Gamma'(x)/\Gamma(x)}{\mathrm d x}$ (more information there)
• psi_n(x, n): Polygamma function: $\psi^{(n)} = \frac{\mathrm d^n \Gamma'(x)/\Gamma(x)}{\mathrm d x }$ (more information there)
• trumpet_bv(m, alpha, prec): Position of an oxidative adsorbed 1-electron peak. $m$ is the coefficient defined by Laviron, the value is returned in units of $RT/F$

## Physical constants

Some physical/mathematical constants are available; their name starts with an uppercase letter.

• Alpha: The fine structure constant, $\alpha$ – 0.00729735
• C: The speed of light in vacuum, $c$ – 2.99792e+08
• Eps_0: The permittivity of vacuum, $\epsilon_0$ – 8.85419e-12
• F: Faraday’s constant, $F$ – 96485.3
• H: The Planck constant, $h$ – 6.62607e-34
• Hbar: $\hbar = h/2\pi$ – 1.05457e-34
• Kb: Boltzmann’s constant – 1.38065e-23
• M_e: The mass of the electron, $m_e$ – 9.10938e-31
• M_mu: The mass of the mu, $m_\mu$ – 1.88353e-28
• M_n: The mass of the neutron, $m_n$ – 1.67493e-27
• M_p: The mass of the proton, $m_p$ – 1.67262e-27
• Mu_0: The permeability of vacuum, $\mu_0$ – 1.25664e-06
• Mu_B: The Bohr Magneton, $\mu_B$ – 9.27401e-24
• Na: The Avogadro number, $N_A$ – 6.02214e+23
• Pi, PI: $\pi$ – 3.14159
• Q_e: The absolute value of the charge of the electron, $e$ – 1.60218e-19
• R: Molar gas constant, $R$ – 8.31447
• Ry: The Rydberg constant, $Ry$ – 2.17987e-18
• Sigma: The Stefan-Boltzmann radiation constant – 5.6704e-08

The embedded version of Ruby, mruby, does not have a regular expression engine. We have added one, but it is not based on standard Ruby regular expressions, but on the ones from Qt. For most regular expressions, this should not matter, however.

# Running QSoas

QSoas can also be useful when run from the command-line.

## Command-line options

When starting QSoas from a terminal, you can use a number of command-line option to change its behaviour. Here are the most useful:

• --run command will run the command command after QSoas starts up.
• --exit-after-running will run the commands specified by --run, and then exit the program. This can be used to run scripts to automatically process data without user interaction.
• --no-startup-files disables the loading of startup scripts.
• --stdout makes the text written to the QSoas terminal also appear in the standard output (i.e. the terminal from which you started QSoas).
• --load-stack file loads the given file as a stack file just after QSoas starts up.

## Non-interactive running of QSoas

It is possible to run QSoas completely non-interactively. This can be useful for regenerating the results of fits, or massively subtracting baselines…

The simplest way to do so is to use the scripts/qs-run script included in the source code archive. Copy that script where you have the QSoas command file you want to run, open an operating system command-line terminal and run:

# ./qs-run my-command-script.txt

This file was written by Vincent Fourmond, and is copyright (c) 2012-2020 by CNRS/AMU.