QSoas

Manual

Important warning Some commands of QSoas may not be documented here. It means they are not supported in any way: their syntax may change without notice, they may disappear, they may turn out to do completely different things in the end. In short, use them at your own risks (and it would be a good idea to check out the code, in that case).

The most recent HTML version of this document can always be found there, together with the corresponding PDF version.

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

QSoas works by entering commands inside the command prompt.

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 replace by a space, so that the command above could 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.

Note about text files

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.

Buffer list (or dataset lists) arguments

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

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

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

Buffer columns

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

Some commands (like contract) take column lists, which are comma-separated lists of columns (just like above), with the addition of range: 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:

Commands producing several buffers

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

For instance, try out:

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

General purpose commands

quit - Quit

quit

Short 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

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 /show-features=yes-no

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

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

Short name: G

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

Short name: T

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 /online=yes-no

Short name: ?

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

save-output - Save output

save-output 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 /overwrite=yes-no /title=text

Short name: p

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

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

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

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

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

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

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.

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

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

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'

Data loading/saving

The main command for loading data is load.

load - Load

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

Short name: l

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

This loads only those that start with a digit from 0 to 4, etc.

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 buffers as they get loaded. Using it has the same effect as running flag with the same option on loaded datasets.

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

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

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:

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

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

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 /flags=words /histogram=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

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-parameters - Load files with backend ‘parameters’

load-as-parameters file… /flags=words /histogram=yes-no /set-meta=meta-data /style=style /yerrors=column

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 (buffer names).

expand - Expand

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

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

If /perp-meta is specified, then the given meta-data will be defined for each buffer, 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 buffer is X1 Y1 X2 Y2 X3 Y3…

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

QSoas> expand /group-columns=2

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

rename - Rename

rename new-name

Short name: a

Changes the name of the current buffer. To help track the operations applied to a buffer, 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 buffers, you probably want to try save-buffers with /mode=rename.

save - Save

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

Short name: s

Saves the current buffer 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-buffers - Save

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

Saves the designated buffers to files.

Unlike the save command, this saves the buffers 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 buffers before saving them, by using a [printf](http://www.cplusplus.com/reference/cstdio/printf/)-like format, as in the following case, which renames the first 101 buffers to Buffer-000.dat, Buffer-001.dat, and so on:

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

It is also possible to use a full-blown Ruby expression that will be aware of the buffer’s meta-data:

QSoas> save-buffers '/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 buffers without saving them, use /mode=rename.

By default, save-buffers overwrites the files without asking, but using /overwrite=false keeps the original files in place.

save-buffers does not by default create directories. However, using /mkpath=true makes it possible to save buffers in non-existing directories, that as created when needed. Try out:

QSoas> save-buffers /format=non-existing-directory/buffer-%03d.dat 0..100 /mkpath=true

browse - Browse files

browse /for-which=text /pattern=text

Short name: W

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… /style=style

Short name: V

Plots one or several buffers on top of the current buffer.

See load for the description of the /style option.

hide-buffer - Hide buffers

hide-buffer buffers…

Short name: H

This does the reverse of the overlay-buffer command. Pass it the buffers 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 /flags=words /histogram=yes-no /ignore-cache=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

Short name: v

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 buffer 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

Short 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)

Short 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

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:

Data stack manipulation

Data files are loaded and manipulated in a stack. Every time a file is loaded or a buffer modified, the new buffer is pushed onto the top of the stack, and becomes the current buffer (numbered 0). Older buffers have increasing numbers (the previous buffer 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 (interactive)

Short name: K

Displays the contents of the stack using a dialog box that works similarly to the one of the browse command.

show-stack - Show stack

show-stack /number=integer

Short name: k

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 buffers, use /number=10 for instance (that will only show buffers -9 to 9).

undo - Undo

undo /number=integer

Short name: u

Returns to the previous buffer, and pushes the current to the redo stack. If /number= is specified, repeats that many times.

redo - Redo

redo /number=integer

Short name: r

Pops the last buffer from the redo stack and sets it as the current buffer. /number has the same meaning as for undo.

save-stack - Save stack

save-stack file

Saves the entire contents of the stack (all the buffers, 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-buffers command:

QSoas> save-buffers all

load-stack - Load stack

load-stack file

Loads a saved stack, from a file that was created using save-stack.

clear-stack - Clear stack

clear-stack

Short name: delstack

Removes all the buffers from both normal and redo stack

fetch - Fetch an old buffer

fetch buffers…

Put back a copy of the given buffer on the top of the stack. Useful when you want to work again on a old buffer buried in the stack.

drop - Drop dataset

drop /buffers=buffers

Permanently deletes the current dataset (or the ones specified in the /buffers options) from the stack.

QSoas> drop 3..16

drops all the buffers from 3 to 16 included.

Important: it is not possible to recover a buffer once it has been dropped from the stack. undo won’t work.

flag - Flag datasets

flag /buffers=buffers /exclusive=yes-no /flags=words /for-which=text /set=yes-no

Flags the given buffer (or the current one if none is supplied) for later use. All currently flagged buffers 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 buffers are flagged with the flag name default. Buffers can hold an arbitrary number of flags. For instance:

QSoas> flag 0..5 /flags=exp1,fit

flags buffers 0 to 5 with the flags exp1 and fit. Buffers are flagged ‘in-place’: the current buffer 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=buffers /flags=words /for-which=text

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 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 buffer level

apply-formula - Apply formula

apply-formula formula /extra-columns=integer /use-meta=yes-no /use-stats=yes-no

Short name: F

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 and values of the buffer. The formula must be valid ruby code.

In addition to x and y (note the lowercase !), the formula can refer to:

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"]'

Beware of the quotes: the outer quotes ' are meant to make QSoas understand that the y = y/$stats["y_med"] is only one argument, while the inner quotes " are required because the keys to the statistics dictionnary are ruby strings, delimited by ".

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 = 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).

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

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

Normalizes the current buffer 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 buffer 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-buffer 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

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 * 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 != x) || (y != y)'

Like in apply-formula, you can use the statistics and the meta-data of the buffers 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 buffer if it has less than that many points.

integrate - Integrate

integrate /index=integer

Integrate just does the reverse of diff and integrates the current buffer. 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

Computes the 4th order accurate derivative of the buffer.

This is efficient to compute the derivative of smooth data, but it gives very poor results on noisy data. In general, for derivation, 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 more 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 buffer.

The same warnings apply as for diff.

dataset-options - Options

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

Sets options for the current dataset:

edit-errors - Edit errors

edit-errors (interactive)

Provides an interface for editing manually the errors attached to each point of the current buffer. 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)

Short name: c

Interactively cuts bits out of the buffer. 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 buffer. 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 Buffer

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

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

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

splita - Split first

splita

Returns the first part of the buffer, until the first change of sign of .

Useful to get the forward scan of a cyclic voltammogram.

splitb - Split second

splitb

Returns the part of the buffer after the first change of sign of .

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

Splits the buffer into buffers 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

This command makes the X values of the current buffer monotonic by ensuring that the value of 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)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

Short name: i

Concatenates the buffers 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.

Buffer’s meta-data and perpendicular coordinates

QSoas’ buffers (or datasets) 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 buffers loaded from files:

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

Perpendicular coordinates make sense when a buffer 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 for different values of above into columns of for different values of ), 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'

Be mindful of the quotes: the outer ' quotes are meant to protect the $stats["y_max"] >= 1e-4 bit that is passed on to ruby. The quotes around y_max are necessary, as $stats is a dictionnary whose keys are ruby strings, which are delimited by double quotes.

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'

Replacing the == by = in the code above leads to selecting all the buffers, because $meta["sr"] = 0.1 evaluates to true for ruby.

show - Show information

show buffers…

This command gives detailed information about the buffers given as arguments, such as the number of rows, columns, segments, but also the flags the buffer may have, and all its meta-data:

QSoas> show 0
Dataset 08.oxw: 2 cols, 4975 rows, 1 segments
Flags: 
Meta-data:	delta_t_0 = 950	gpes_file = D:\Vincent\140428\08	original-file = /home/vincent/Data/140428/08.oxw
	age = 428907.581	steps = 1	title = 
	file-date = 2014-05-23T21:23:38	exp-time = 14:03:08	comments = 
	t_0 = 0	E_0 = -0.65	method = chronoamperometry

set-meta - Set meta-data

set-meta name value

Using set-meta, one can set the value of the named meta-data for the current buffer. name can have any value, it does not have to exist in the list of buffer’s meta-data.

set-perp - Set perpendicular

set-perp coords…

Sets the perpendicular coordinates for the Y columns, as comma-separated values. There must be as many perpendicular coordinates as there are Y columns.

transpose - Transpose

transpose

This command transposes the matrix of the Y columns, while paying attention to the perpendicular coordinates. In short, if one starts from a series of Y columns representing spectra as a function of (the X column) for different values of time (each column at at different value of ), then after transpose, the new dataset contains columns describing the time evolution of the absorbance for different values of (one for each column).

tweak-columns - Tweak columns

tweak-columns /flip=yes-no /flip-all=yes-no /remove=columns

tweak-columns provides basic modifications of columns. If a list of columns is given to the /remove option, then the given columns are removed. If /flip is on, then all Y columns are reversed. If /flip-all is on, then all columns, including the X column, are reversed.

split-on-values - Split on column values

split-on-values meta… columns… /flags=words /set-meta=meta-data /style=style

This command splits the current dataset into a number of datasets, based on the contents of the columns columns. Each newly created dataset correspond to points in the original dataset that had exactly the same values in the designated columns. These columns are remove from the newly created datasets and the values are used to set the meta-data meta. There must be as many comma-separated names in meta as there are colunm names in columns.

Data filtering/processing

QSoas provides different ways to process data to remove unwanted noise:

In addition, QSoas provides ways to remove calculated “baselines”:

filter-fft - FFT filter

filter-fft /derive=integer (interactive)

Filters data using FFT, ie the data is Fourier transformed, then a filter function is applied in the frequency domain and the result is backward transformed.

The cutoff can be changed using the mouse left/right buttons. The power spectrum can be displayed using the p key, and the derivative can be displayed with d (in which case you get the derivative of the signal when accepting the data).

Behind the scenes, a cubic baseline is computed and subtracted from the data to ensure that the data to which the FFT is applied has 0 value and 0 derivative on both sides. This greatly reduces artifacts at the extremities of the dataset. This baseline is computed using a small heuristic. You can display it using the b key.

filter-bsplines - B-Splines filter

filter-bsplines /weight-column=column (interactive)

Filters the data using B-splines: B-splines are polynomial functions of a given order defined over segments. The filtering process finds the linear combination of these spline functions that is the closest to the original data.

This approach amounts to taking the projection of the original data onto the subspace of the polynomial functions.

More information about the polynomial splines used can be found in the GSL documentation.

The result can be tuned by placing “nodes”, ie the X positions of the segments over which the splines are defined. Put more nodes in an area where the data is not described properly by the smoothed function. Increasing the order (using +) may help too.

Like for filter-fft, you can derive the data as well pushing the d key.

Hitting the o key optimizes the position of the segments in order to minimize the difference between the data and the approximation. (be careful as this function may fail at times).

auto-filter-bs - Auto B-splines

auto-filter-bs /derivatives=integer /number=integer /order=integer /weight-column=column

Short name: afbs

Filters the data using B-splines in a non-interactive fashion. Performs automatically an optimization step, like hitting o in filter-bsplines.

This is mostly useful in scripts.

auto-filter-fft - Auto FFT

auto-filter-fft /cutoff=integer /derive=integer /transform=yes-no

Short name: afft

Filters data using FFT in a non-interactive fashion. Useful in scripts.

With /transform=yes, pushes the Fourier transform of the data, in the format:

freq magnitude real imag

auto-reglin - Automatic linear regression

auto-reglin /window=integer

Performs a linear regression on a number of points around each point of the graph and creates a buffer from the resulting slopes, which results in a derivative buffer. This command is similar to but provides less noisy output than diff, and also similar to filtering with FFT (using filter-fft) and taking the derivative.

remove-spikes - Remove spikes

remove-spikes /factor=number /force-new=yes-no /number=integer

Short name: R

Removes spikes using a simple heuristic: a point is considered a “spike” if over the /number points, the difference between this point and the ones next to it are larger than /factor times the other differences in the interval. This command will not create a new buffer if not spikes were removed, unless you specify /force-new=true, in which case the buffer is duplicated; this is useful for scripting, when you need a reproducible number of created buffers, regardless of whether spikes are present or not.

downsample - Downsample

downsample /factor=integer

Creates a buffer with about factor times less points than the original buffer (default 10 times less) by averaging the original X and Y values in groups of factor. This command averages the other columns too.

baseline - Baseline

baseline (interactive)

Short name: b

Draw a baseline by placing markers on the curve using the mouse (or off the curve, after using key o). Baseline is computing using one of several interpolation algorithms: C-splines, linear or polynomial interpolation and Akima splines (the latter usually follows best the accidents on the curve). Cycle between the various schemes by hitting t.

It is possible to leave saving not the interpolated data, but just the interpolation ``nodes’’ (ie the big dots), by pushing the p key. This has two advantages: first, one can load nodes from a buffer by hitting the L key and providing the buffer number (or just their X value by hitting l). Second, if one has the nodes and just the X values, one can generate the interpolated data using interpolate.

The area between the baseline and the curve is displayed in the terminal. If the dataset has a meta-data named sr, it is taken as a scan rate (as in cyclic voltammetry), and the charge is displayed too.

interpolate - Interpolate

interpolate xvalues nodes /type=choice

Given a buffer containing xvalues and another one containing the X/Y position of interpolation nodes saved using p from within baseline, this command regenerates the interpolated values, for the given X values.

Through this approach, one can draw a baseline, save the points, generate the baseline-subtracted data using interpolate from within a script. This has the advantage that one can always have a close look at the quality of the baseline, and tweak it if need be.

catalytic-baseline - Catalytic baseline

catalytic-baseline (interactive)

Short name: B

Draws a so-called “catalytic” baseline. There are several types of baselines, but they all share the following features:

There are two baselines implemented for now:

solve - Solves an equation

solve formula /iterations=integer /max=text /min=text /prec-absolute=number /prec-relative=number

Solves an equation on on the current buffer. For instance,

QSoas> solve y**2-x

solves for the equation .

By default, the algorithm used is an iterative process starting from the current value of (i.e. the value before the command starts). You can use a dichotomy approch by specifying upper and lower bounds using the /min= and /max= options:

QSoas> solve y**2-x /min=0 /max=x

auto-correlation - Auto-correlation

auto-correlation

Short name: ac

Computes the auto-correlation function of the data, using FFT.

bin - Bin

bin /boxes=integer /column=column /log=yes-no /norm=yes-no /weight=column

Creates an histogram by binning the Y values (or the values of the column given by the /column option, see above) into various boxes (whose number can be controlled using the /boxes option). The new buffer has for X values the center of the boxes and as Y values the number of data points that were in the boxes.

By default, all original points have a weight of 1. You can specify a column number using the /weight= option that contains the weight of each point.

Segments

It is possible to split a buffer into logical segments without changing the contents of the buffer. The position of the segment boundaries are marked by a vertical line. They can be used for different purposes: for segment-by-segment operations, step-by-step film loss correction (using film-loss) or buffer splitting (using segments-chop).

Segments can be detected using find-steps, or set manually using set-segments or chop.

find-steps - Find steps

find-steps /average=integer /set-segments=yes-no /threshold=number

This function detects “jumps” in the data (such as potential changes in a chronoamperometry experiment, for instance), and display them both to the terminal output and on the data display.

By default, this function only shows the segments it finds, but if the option /set-segments is on, the segments are set to that found by find-steps (removing the ones previously there).

set-segments - Set segments

set-segments (interactive)

Interactively prompts for the addition/removal of segments. A left click adds a segment where the mouse is, while a right click removes the closest segment.

segments-chop - Chop into segments

segments-chop /flags=words /set-meta=meta-data /style=style

Cuts the buffer into several ones based on the segments defined in the current buffer. This way, the effect of a chop /set-segment=true followed by segments-chop is the same as the chop without /set-segment=true.

film-loss - Film loss

film-loss (interactive)

Applies stepwise film loss correction (in the spirit of the experiments in Fourmond et al, Anal. Chem., 2009). For that, the current buffer must be separated into segments, using set-segments, for instance. QSoas then zooms on the first segment. Right and left clicking around the final linear decay will set the value of the film loss rate constant for this step. Push space to switch to the next step, and when you have done everything, push q to obtain the corrected data.

Operations involving several buffers

It is possible to combine several buffers into one by applying mathematical operations (subtraction, division and the like). Each of these processes involve matching a data point of a buffer to a data point of another one. There are two ways to do that, chosen by the /mode option:

In addition to that, the operations can make use of the segments defined on each buffer (see find-steps and set-segments). If segments are defined and /use-segments=true, then the operations are applied segment-by-segment, with the first point of each segment matching the corresponding point in the other buffer. This mode is suited to combine two buffers that are divided into logical bits (such as chronoamperograms with steps at different potentials) whose exact details (beginnings and duration of the steps) vary a a little.

subtract - Subtract

subtract first… second /mode=choice /use-segments=yes-no

Short name: S

Subtracts the last buffer from all the other ones (there can be more than one first buffer). Useful for standard baseline removal.

div - Divide

div first… second /mode=choice /use-segments=yes-no

Divides all buffers by the last one. Just as subtract is useful to remove one of a multicomponent response when they are additive, div can be used to remove one of the components when they are multiplicative, like film loss in protein film voltammetry experiments, see Fourmond et al, Anal. Chem. 2009 for more information.

add - Add

add buffers… /mode=choice /use-segments=yes-no

Adds all the given buffers and pushes the result (a single dataset).

multiply - Add

multiply buffers… /mode=choice /use-segments=yes-no

Short name: mul

Multiplies all the given buffers and pushes the result (a single dataset).

average - Average

average buffers… /count=yes-no /mode=choice /split=yes-no /use-segments=yes-no

In a manner similar to subtract and div, the average command averages all the buffers given into one, with the same segment-by-segment capacities.

An additional feature of average is its ability to first split the buffers into monotonic parts before averaging (when /split is on). That is the default when only one buffer is provided. This proves useful for averaging the forward and return scan in a cyclic voltammogram.

merge - Merge buffers on X values

merge first… second /mode=choice /use-segments=yes-no

Merges the second buffer with the first one, and keep Y of the second as a function of Y of the first. The algorithm for finding which point in the second corresponds to a given one in the first is the same as that of the other commands in this section (subtract, div…).

If more than two buffers are specified, the last one gets merged with each of those before.

contract - Group buffers on X values

contract buffers… /mode=choice /perp-meta=text /use-columns=columns /use-segments=yes-no

contract does the reverse of expand, ie it regroups in one buffer several values of Y that run against the same values of X. The result is a buffer that contains as many Y columns as the total of Y columns of all the arguments. X matching between the buffers is done as for the other commands in this section (div or subtract).

You can specify a column list using /use-columns (see above for more information about column lists), in which case the other columns from the buffers are ignored.

Data inspection facilities

Options for data output

The commands below are able to compute a number of quantities from the datasets they work on, such as various statistics, the position of peaks, and so on. QSoas provides several ways to store and work with these data.

Saving to the output file

The “traditional” way is to store the data in the output file. They end up as TAB-separated data, with an generally explicit header, and the name of the buffer the data is extracted from on the first column. When outputting to the output file, you can force the writing of extra columns containing some meta-data by listing them using the /meta-data= option.

Saving as meta-data

It is also possible to use the /set-meta= option to “decorate” the buffers with the results of the command, as meta-data. For instance: running

QSoas> stats /set-meta=y_min

sets the y_min meta-data to the minimum value of the column of the dataset. It is also possible to select several meta-data, separating them using commas, or even change their name, such as

QSoas> stats /set-meta=y_min->my_interesting_meta

which saves also the minimum of the column as meta-data, but this time under the name my_interesting_meta.

You can save all the data in one go under their original name using /set-meta=*.

Combining /accumulate= and pop to create new datasets on the fly

It is now possible to generate a data from scratch using the /accumulate= option. This option takes an ordered list of output values (and, possibly meta-data), and accumulates the values to a “hidden” buffer, until the command pop is called. For instance, running on different buffers the following command:

QSoas> 1 /output=false /accumulate=x,y,area

will populate a dataset with 3 columns, containing respectively the X position, Y position, and area of the major peak of the buffers (with possibly extra columns for meta-data).

This command is typically used to parse a whole series of buffers using run-for-each or run-for-datasets.

pop - Pop accumulator

pop /drop=yes-no

A number of commands can accumulate data to a “hidden” buffer using the /accumulate= options. The pop command takes that buffer, pushes it to the stack, and clears the “hidden” buffer.

With /drop=yes, the “hidden” buffer is just clear, it is not pushed onto the stack.

find-peaks - Find peaks

find-peaks /accumulate=words /include-borders=yes-no /meta=words /output=yes-no /peaks=integer /set-meta=words /which=choice /window=integer

Find all the peaks of the current dataset. Peaks are local extrema over a window of a number of points given by /window (8 by default). If /output is on, then the peak data is written to the output file. This function will find many peaks on noisy data, you can limit to the first n ones by using /peaks=n (peaks are ranked by amplitude with respect to the average of the buffer).

By default, if a point at either end of the dataset is an extremum, it is not included, unless you use /include-borders=true.

Peaks are indicated on the buffer using lines, and their position is written to the terminal. In addition, if /output is on (off by default), they are also written to the output file.

echem-peaks - Find peaks pairs

echem-peaks /accumulate=words /include-borders=yes-no /meta=words /output=yes-no /pairs=integer /set-meta=words /which=choice /window=integer

This function tries to find “pairs” of peaks that may be the anodic and cathodic peaks of a redox couple, and outputs useful information about those.

1 - Find peak

1 /accumulate=words /include-borders=yes-no /meta=words /output=yes-no /set-meta=words /which=choice /window=integer

Equivalent to

QSoas> find-peaks /peaks=1 /output=true

2 - Find two peaks

2 /accumulate=words /include-borders=yes-no /meta=words /output=yes-no /set-meta=words /which=choice /window=integer

Equivalent to

QSoas> find-peaks /peaks=2 /output=true

stats - Statistics

stats /accumulate=words /buffer=buffer /meta=words /output=yes-no /set-meta=words /stats=stats-names /use-segments=yes-no

stats displays various statistics about the current buffer (or the one specified by the /buffer option). The exact list of displayed statistics grows slowly with time and needs. It is currently, for each column:

Statistics can be written to the output file with /output=true. If you specify /use-segments=true, the statistics are also displayed segment-by-segment (and written to the output file if /output=true). If you want some meta-data to be written to the output file together with the statistics, provide them as a comma-separated list to the /meta option, or, alternatively, use the /meta option of the output command. See more about that above.

cursor - Cursor

cursor (interactive)

Short name: cu

Starts an interative mode (which you can end by pression q or Escape), in which you can position a cursor by left-clicking on the curve, to know its exact X and Y positions.

Using the right mouse button, it is also possible to position a reference point. After that, the command also shows the difference and the ratios in X,Y coordinates between the cursor and the reference point.

Cursor positions can be saved to the output file by pressing the space bar.

Hitting u subtracts the Y value of the current point to the Y values of the buffer and returns. Hitting v divides by the current Y value.

reglin - Linear regression

reglin (interactive)

Short name: reg

Linear regression. Using the left and right mouse buttons, select a region whose slope is of interest. The terminal shows the and parameters (the equation is ), and also the effective first order rate constant, ie the parameter of the equation

whose first-order expansion gives the same linear approximation, ie:

Using the space bar it is possible to save the values displayed in the terminal to the output file.

Fits

QSoas was designed with a particular emphasis on fitting data. It allows complex fits, and in particular multi-buffer fits, when functions with shared parameters are fit to different buffers. Fits fall into two different categories:

Fits can be used through several commands: for all fits there are a mfit-fit and a sim-fit command, and for mono-buffer fits, there is a fit-fit in addition.

All fits commands share the following options:

The sim- commands additionally take the following options:

In addition to these commands, QSoas provides commands to combine fits together, to fit derivatives of the signals, and to define fits with distributions of parameters.

Fit engines

QSoas provides a number of fit engines with different strengths and weaknesses. Most are based on a Levenberg-Marquardt solver, with a few variants that make some of them more useful in certain situations. The rule is, if you are unhappy with how a particular fit engine converges, try another one !

Subfunctions

Some fits support displaying “sub-functions”: for instance, “peak fits” like fit-gaussian display each individual component in color if there are more than one. They are documented in each individual fitting function when applicable. They are not always displayed by default, as in some cases, such as fit-exponential-decay , it generally makes the display less clear.

To show/hide subfunctions, use “Toggle subfunction display” from within the “Data…” submenu in the fit dialog. If that item is absent, then the fit does not support subfunctions.

You can also push the individual components to the stack for further manipulation using “Data…”/”Push all subfunctions”.

Parameters restrictions

Some fits implement restrictions on the values that can be taken by parameters. For instance, the time constants for the exponential-decay cannot be negative, neither for the starting parameters, nor for any intermediate (iteration, computation of derivatives).

This is done so that the fit algorithm does not go into directions which are assured not to give relevant parameters.

Fit manipulations

QSoas provide a series of commands to create new fits from other fits:

combine-fits - Combine fits

combine-fits name formula fits… /redefine=yes-no

Creates a new fit named name based on other fits, combined through a formula. The formula use y1, y2 and so on to refer to the fits. You specify the fit names by removing the fit- or mfit- prefix. For instance, to fit a sum of lorentzians and gaussians, one just has to do:

QSoas> combine-fits lg 'y1 + y2' lorentzian gaussian

This creates a new fit, lg, and hence three new commands, fit-lg, mfit-lg and sim-lg. The fit is a sum of a lorentzian fit (y1) and a gaussian fit (y2). The new fit shares the options of all the original fits.

The newly-defined fit only lasts for the current session, if you need something more persistent, consider setting up a startup file using startup-files.

If you try to redefine an existing fit, the command will stop, unless you use /redefine=true (not by default), in which case existing (custom) fits are silently redefined. You cannot redefine built-in fits.

define-derived-fit - Create a derived fit

define-derived-fit existing-fit /mode=choice /redefine=yes-no

Defines new fit commands based on existing-fit (without the fit- prefix). It fits:

This function is explained in more details in the tutorial.

define-distribution-fit - Define fit with distribution

define-distribution-fit name existing-fit parameter /distribution=choice /redefine=yes-no

Defines a new fit called name based on the fit fit in which the data is the result of the integration of the original fit over a distribution of parameter.

You can choose the default distribution with the /distribution= option. It is one of:

Of course, even for theoretically infinite distributions (gaussian and lorentzian distributions above), QSoas does not integrate over the whole real axis, which is why these distributions get an extra parameter, fixed by default, which indicates the extent of the integration interval in dimensionless units (independent of the value of the parameter). In principle, these values are chosen as a good compromise between accuracy and computing time, but they can be tuned should you need it.

The created fit commands also take a /distribution option with the same meaning.

Like for combine-fits, you cannot redefine existing fits with this command unless /redefine=true is specified.

reparametrize-fit - Reparametrize fit

reparametrize-fit name fit new-parameters redefinitions… /conditions=words /redefine=yes-no

This command makes it possible to reparametrize a fit: add new parameters, and express old parameters as a function of other old parameters and new ones.

For instance, to reparametrize a mono-exponential fit in terms of rate constant rather than time constant, one can use:

QSoas> reparametrize-fit my-exp exponential-decay k_1 tau_1=1/k_1

This creates a new fit named my-exp (hence it creates the commands fit-my-exp, mfit-my-exp and sim-my-exp), in which the parameter tau_1 of the exponential-decay fit has been replaced by k_1 (its reciprocal).

Exponential fits

There are several ways to fit exponentials to data. The simplest is fit-exponential-decay, which fits a decay with an arbitrary number of exponentials to the data.

fit-exponential-decay - Fit: Multi-exponential fits

fit-exponential-decay /absolute=yes-no /debug=integer /engine=engine /exponentials=integer /extra-parameters=text /loss=yes-no /parameters=file /set-from-meta=words /slow=yes-no (interactive)

Fits the formula below to the current dataset:

is only present if the /slow option is on, and is not 0 only if /loss is on. If /relative is on, the parameter of the fit is (defined by ) rather than . /relative=true should not be used to fit data that tend to 0.

Subfunctions

Each individual exponential, with as asymptotic value. The subfunctions are not displayed by default.

Parameters restrictions

The values of cannot be negative, nor can .

mfit-exponential-decay - Multi fit: Multi-exponential fits

mfit-exponential-decay datasets… /absolute=yes-no /debug=integer /engine=engine /exponentials=integer /extra-parameters=text /loss=yes-no /parameters=file /perp-meta=text /set-from-meta=words /slow=yes-no /weight-buffers=yes-no (interactive)

Multi-buffer version of the fit-exponential-decay fit.

sim-exponential-decay - Simulation: Multi-exponential fits

sim-exponential-decay parameters datasets… /absolute=yes-no /debug=integer /engine=engine /exponentials=integer /extra-parameters=text /flags=words /loss=yes-no /operation=choice /override=overrides /set-meta=meta-data /slow=yes-no /style=style

Simulation command for the fit-exponential-decay fit.

fit-multiexp-multistep - Fit: Multi-step and multi-exponential

fit-multiexp-multistep /debug=integer /engine=engine /exponentials=integer /extra-parameters=text /independent=yes-no /parameters=file /set-from-meta=words /steps=integers (interactive)

This fit is an extension of the exponential-decay fit when the experiment consists in several steps in which the time constants are expected to change, but some may be common to different steps. The steps are specified using the /steps option. Specifying /steps=0,1,0 means that there are three steps, but there are only two distinct sets of time constants, a first one (0, used for step 1 and 3), and a second one (1, used only for step 2).

In each of the steps, the formula fitted to the data is:

Where is the step number, is the number of the corresponding time constants, is the beginning of the step , the are the relative amplitudes of the exponential phases, the are the asymptotic values of on each step (in the absence of film loss) and is defined recursively by and $$\alpha_j = \alpha{j-1} \exp (- k^{k(j-1)}{loss}(t^j0 - t^{j-1}0))$$. This is done so as to keep track of film loss over the whole experiment.

Parameters restrictions

Like in the exponential-decay fit, the values of cannot be negative, nor can the values of .

mfit-multiexp-multistep - Multi fit: Multi-step and multi-exponential

mfit-multiexp-multistep datasets… /debug=integer /engine=engine /exponentials=integer /extra-parameters=text /independent=yes-no /parameters=file /perp-meta=text /set-from-meta=words /steps=integers /weight-buffers=yes-no (interactive)

This is the multibuffer version of the multiexp-multistep fit.

sim-multiexp-multistep - Simulation: Multi-step and multi-exponential

sim-multiexp-multistep parameters datasets… /debug=integer /engine=engine /exponentials=integer /extra-parameters=text /flags=words /independent=yes-no /operation=choice /override=overrides /set-meta=meta-data /steps=integers /style=style

This is the simulation command for the multiexp-multistep fit.

fit-linear-kinetic-system - Fit: Several steps with a kinetic evolution

fit-linear-kinetic-system /additional-loss=yes-no /debug=integer /engine=engine /extra-parameters=text /offset=yes-no /parameters=file /set-from-meta=words /species=integer /steps=words (interactive)

This is an extension to the multiexp-multistep fit. This fit models the evolution of a system of chemical species that interconvert with first-order reactions. For instance, is the rate of production of species 2 from species 1.

Like in multiexp-multistep, the time is divided into steps, during which the values of the rate constants are constant. The concentration of the species is assumed to be continuous at step change. The fit engine solves the following differential equations over each step (the result is a sum of exponential decays):

The step specification is just a like of “names” (numbers, letters…), separated by commas. For each name corresponds a set of rate constants in the equation above. For instance, with the specification /steps=1,2,1, there are three steps, but only two sets of rate constants, 1, and 2, the first one being reused.

This fit was used for many of the publications of the team, such as Fourmond et al, Nat. Chem., 2014 or Jacques et al, BBA, 2014.

mfit-linear-kinetic-system - Multi fit: Several steps with a kinetic evolution

mfit-linear-kinetic-system datasets… /additional-loss=yes-no /debug=integer /engine=engine /extra-parameters=text /offset=yes-no /parameters=file /perp-meta=text /set-from-meta=words /species=integer /steps=words /weight-buffers=yes-no (interactive)

This is the multibuffer version of the linear-kinetic-system fit.

sim-linear-kinetic-system - Simulation: Several steps with a kinetic evolution

sim-linear-kinetic-system parameters datasets… /additional-loss=yes-no /debug=integer /engine=engine /extra-parameters=text /flags=words /offset=yes-no /operation=choice /override=overrides /set-meta=meta-data /species=integer /steps=words /style=style

This is the simulation command for the linear-kinetic-system fit.

Polynomial fits

fit-polynomial - Fit: Fit to a polynomial function

fit-polynomial /debug=integer /engine=engine /extra-parameters=text /monotonic=yes-no /number=integer /order=integers /parameters=file /prefactor=yes-no /set-from-meta=words /without-inflexions=yes-no (interactive)

Fits a sum of polynomials to the data:

The number of polynomial functions is given by the /number= option (defaults to 1), and the order of the polynomials is chosen using the /order= option. By default, the order is the same for all polynomials, to specify different ones, give a comma-separated list of orders, one for each polynomial, and don’t use /number=.

The prefactors , are present by default when there are more than one polynomial, and off if not. You can override that using the /prefactor option.

Parameters restrictions

By default, there are no restrictions on parameters, but using /monotonic=true will discard parameter combinations that give non-monotonic polynomials (each of the , not the sum), and with /without-inflexions=true, it will discard parameter combinations that give inflexion points.

mfit-polynomial - Multi fit: Fit to a polynomial function

mfit-polynomial datasets… /debug=integer /engine=engine /extra-parameters=text /monotonic=yes-no /number=integer /order=integers /parameters=file /perp-meta=text /prefactor=yes-no /set-from-meta=words /weight-buffers=yes-no /without-inflexions=yes-no (interactive)

This is the multibuffer version of the polynomial fit.

sim-polynomial - Simulation: Fit to a polynomial function

sim-polynomial parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /monotonic=yes-no /number=integer /operation=choice /order=integers /override=overrides /prefactor=yes-no /set-meta=meta-data /style=style /without-inflexions=yes-no

This is the simulation command for the polynomial fit.

Arbitrary fits

QSoas provides ways to fit arbitrary formulas (written in Ruby) to data. While it is possible to do that on a case-by-case basis using fit-arb, it is also possible to store formulas in a plain text file and load them using load-fits or define a new one using custom-fit.

fit-arb - Fit: Arbitrary fit

fit-arb formulas /debug=integer /engine=engine /extra-parameters=text /parameters=file /set-from-meta=words /with=time-dependent parameters (interactive)

Fits formula (a piece of Ruby code) to the current buffer.

Parameters are auto-detected. Some parameters are treated specifically:

If you often use the same formula for fit-arb, you should consider using custom-fit or writing it in a file and loading that file with load-fits.

Starting from QSoas version 2.0, you can use the /with= option to make some of the parameters dependent on time in a flexible fashion. See time dependent parameters below for more information.

mfit-arb - Multi fit: Arbitrary fit

mfit-arb formulas datasets… /debug=integer /engine=engine /extra-parameters=text /parameters=file /perp-meta=text /set-from-meta=words /weight-buffers=yes-no /with=time-dependent parameters (interactive)

Same as fit-arb, but for multiple buffers.

Using mfit-arb, it is possible to specify several formulas, separated by |.

If only one formula is specified, the same formula is applied to all buffers (with, as usual, the possibility to select which parameters are global or buffer-local).

If more than one formula is specified, the exact same number of buffers should be supplied; the first formula applies to the first buffer, the second formula to the second buffer, and so on… For instance, if you run:

QSoas> mfit-arb a*x+b|a*x+c|a*x+d 0 1 2

This command fits a*x+b to buffer 0, a*x+c to buffer 1 and a*x+d to buffer 2.

In this specific case, though, you could also have run

QSoas> mfit-arb a*x+b 0 1 2

and have a common to all buffer, but b buffer-specific.

load-fits - Load fits

load-fits file /redefine=yes-no

Load fits of arbitrary functions from a plain text file, and create the corresponding fit-, mfit- and sim- functions, that can be used with define-derived-fit or combine-fits for instance. Files should look like this:

# Comments are allowed
michaelis: vmax/(1 + km/x)
sigm-log: log((exp(a_red*log(10.0)) +exp(a_ox*log(10.0)) * \
          exp(-fara*(x-e0)))/ \
          (1 + exp(-fara*(x-e0))))

Comments are allowed, as are line continuations with \.

Like for combine-fits, you cannot redefine existing fits with this command unless /redefine=true is specified.

custom-fit - Define fit

custom-fit name formula /redefine=yes-no

Directly defines a custom fit with the given name and formula. Equivalent to having a line

name: formula

in a file loaded by load-fits.

Like for combine-fits, you cannot redefine existing fits with this command unless /redefine=true is specified.

Peak fits

The fits in this section can be used to fit various “peaks” obeying to different distributions, such as the

For all these fits, you can specify the number of “peaks” using a common /number option. For each peak, there is a position, an amplitude and a width parameter. If you are more interested in the total surface under the peak rather than the amplitude of the peak, the fits provide a /use-surface argument that changes the amplitude parameter into a surface one.

fit-gaussian - Fit: One or several gaussians

fit-gaussian /debug=integer /engine=engine /extra-parameters=text /number=integer /parameters=file /set-from-meta=words /use-surface=yes-no (interactive)

Fits a number of gaussians (and an offset), given by:

More information in the GSL documentation.

The /number option controls the number of different peaks, while using /use-surface=true fits the surface of the peak instead of the amplitude.

Subfunctions

Each individual peak, with the offset . Displayed by default.

mfit-gaussian - Multi fit: One or several gaussians

mfit-gaussian datasets… /debug=integer /engine=engine /extra-parameters=text /number=integer /parameters=file /perp-meta=text /set-from-meta=words /use-surface=yes-no /weight-buffers=yes-no (interactive)

Multi-buffer variant of the fit-gaussian fit.

sim-gaussian - Simulation: One or several gaussians

sim-gaussian parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /number=integer /operation=choice /override=overrides /set-meta=meta-data /style=style /use-surface=yes-no

Simulation command for the fit-gaussian fit.

fit-lorentzian - Fit: A Lorentzian (also named Cauchy distribution)

fit-lorentzian /debug=integer /engine=engine /extra-parameters=text /number=integer /parameters=file /set-from-meta=words /use-surface=yes-no (interactive)

Fits a number of lorentzians (and an offset), given by:

More information in the GSL documentation.

The /number option controls the number of different peaks, while using /use-surface=true fits the surface of the peak instead of the amplitude.

Subfunctions

Each individual peak, with the offset . Displayed by default.

mfit-lorentzian - Multi fit: A Lorentzian (also named Cauchy distribution)

mfit-lorentzian datasets… /debug=integer /engine=engine /extra-parameters=text /number=integer /parameters=file /perp-meta=text /set-from-meta=words /use-surface=yes-no /weight-buffers=yes-no (interactive)

Multi-buffer variant of the fit-lorentzian fit.

sim-lorentzian - Simulation: A Lorentzian (also named Cauchy distribution)

sim-lorentzian parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /number=integer /operation=choice /override=overrides /set-meta=meta-data /style=style /use-surface=yes-no

Simulation command for the fit-lorentzian fit.

fit-pseudo-voigt - Fit: A pseudo-voigt distribution (linear combination of a gaussian and a lorentzian)

fit-pseudo-voigt /debug=integer /engine=engine /extra-parameters=text /number=integer /parameters=file /set-from-meta=words /use-surface=yes-no (interactive)

Fits a number of pseudo-Voigt peaks, according to the following formula:

Subfunctions

Each individual peak, with the offset . Displayed by default.

mfit-pseudo-voigt - Multi fit: A pseudo-voigt distribution (linear combination of a gaussian and a lorentzian)

mfit-pseudo-voigt datasets… /debug=integer /engine=engine /extra-parameters=text /number=integer /parameters=file /perp-meta=text /set-from-meta=words /use-surface=yes-no /weight-buffers=yes-no (interactive)

Multi-buffer variant of the fit-pseudo-voigt fit.

sim-pseudo-voigt - Simulation: A pseudo-voigt distribution (linear combination of a gaussian and a lorentzian)

sim-pseudo-voigt parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /number=integer /operation=choice /override=overrides /set-meta=meta-data /style=style /use-surface=yes-no

Simulation command for the fit-pseudo-voigt fit.

Redox titration fits

fit-nernst - Fit: Nerstian behaviour

fit-nernst /debug=integer /engine=engine /extra-parameters=text /parameters=file /set-from-meta=words /species=integer /states=integers (interactive)

Fits the Nernst equation for a number of chemical species present under several redox states to the buffer, that represents absorbance (or something else) as a function of potential. The number of species is given to the /species option, while the number of redox states for each species is given to the /states option. Alternatively, if you need distinct species with a different number of redox states, you can specify a comma-separated list of number of states to /states, in which case /species is ignored. For instance, to fit the Nersnt equation for two species, one present in 4 redox states and the other in two redox states, one can use:

QSoas> fit-nernst /states=4,2

The species are designated using a lowercase letter suffix, while the redox state is designated using red, int or ox when there are 3 states or less, or with a number for more than three states.

Note: be aware that if there is more than one species, the system is intrinsically overdetermined, which is why QSoas automatically fixes the absorbance of the reduced species of all but the first one to 0 (but you can change that).

This fit is useful to fit the results of a the redox titration at a single wavelength. If several wavelength are available, separate them into several buffers as a function of the potential and fit them using mfit-nernst, while keeping the redox potentials (and electron numbers) global and only the absorbances as buffer-local.

mfit-nernst - Multi fit: Nerstian behaviour

mfit-nernst datasets… /debug=integer /engine=engine /extra-parameters=text /parameters=file /perp-meta=text /set-from-meta=words /species=integer /states=integers /weight-buffers=yes-no (interactive)

Multi-buffer version of fit-nernst. To be used for fitting multi-wavelength redox titrations.

sim-nernst - Simulation: Nerstian behaviour

sim-nernst parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /operation=choice /override=overrides /set-meta=meta-data /species=integer /states=integers /style=style

Simulation command for fit-nernst

Adsorbed redox species

fit-adsorbed - Fit: Adsorbed species

fit-adsorbed /2el=integer /debug=integer /distinct=yes-no /engine=engine /extra-parameters=text /parameters=file /set-from-meta=words /species=integer (interactive)

Fits the theoretical current given by a series of species adsorbed to an electrode in electrochemically reversible conditions to the current buffer (see for instance Laviron, J. Electroanal. Chem., 1979 for more details). The actual formula is the following:

The number of 1-electron peaks is given by the /species option (defaults to 1) and that of the 2-electrons peaks is given by the /2el option (defaults to 0).

The current for 1-electron peaks is given by:

with , with the potential of the couple and the apparent number of electrons. The latter only affects the width of the peaks, the stoechiometry is always 1 electron.

The current for the 2-electrons peaks is given by Pilchon and Laviron, J. Electronanal. Chem., 1976:

With , being the 2-electrons reduction potential (i.e. the average of those of the 1-electron couples) and , being the difference in the reduction potentials of the 1-electron couples (it is positive if the intermediate species is thermodynamically stable).

The parameters are the number of moles of the molecules adsorbed on the electrode. If the option /distinct=false is used, the same value of is used for all couples, while in the other case (the default), each couple has its own value of (this situation corresponds to unrelated species). is the voltammetric scan rate (in volts per second).

mfit-adsorbed - Multi fit: Adsorbed species

mfit-adsorbed datasets… /2el=integer /debug=integer /distinct=yes-no /engine=engine /extra-parameters=text /parameters=file /perp-meta=text /set-from-meta=words /species=integer /weight-buffers=yes-no (interactive)

Multi-buffer version of the adsorbed fit.

sim-adsorbed - Simulation: Adsorbed species

sim-adsorbed parameters datasets… /2el=integer /debug=integer /distinct=yes-no /engine=engine /extra-parameters=text /flags=words /operation=choice /override=overrides /set-meta=meta-data /species=integer /style=style

Simulation command for the adsorbed fit.

Differential equations fits

fit-ode - Fit: Fit an ODE system

fit-ode system /adaptive=yes-no /choose-t0=yes-no /debug=integer /engine=engine /extra-parameters=text /min-step-size=number /parameters=file /prec-absolute=number /prec-relative=number /set-from-meta=words /step-size=number /stepper=choice /sub-steps=integer /with=time-dependent parameters (interactive)

Using this command, one can fit the results of integrating a system of differential equations to a dataset. The system is a file given as the system argument. For more details about how to specify the system of equations, please refer to the documentation of the ode command. The parameters whose values are not defined in the system file become the fit parameters. If there is no optional third section in the system file, the value of the function is by default a linear combination of the variables of the system.

As with the kinetic-system fit, some of the parameters of the system can be varied automatically as a function of time, using the /with= option. See time dependent parameters below for more information.

mfit-ode - Multi fit: Fit an ODE system

mfit-ode system datasets… /adaptive=yes-no /choose-t0=yes-no /debug=integer /engine=engine /extra-parameters=text /min-step-size=number /parameters=file /perp-meta=text /prec-absolute=number /prec-relative=number /set-from-meta=words /step-size=number /stepper=choice /sub-steps=integer /weight-buffers=yes-no /with=time-dependent parameters (interactive)

Multibuffer version of the ode fit.

sim-ode - Simulation: Fit an ODE system

sim-ode system parameters datasets… /adaptive=yes-no /choose-t0=yes-no /debug=integer /engine=engine /extra-parameters=text /flags=words /min-step-size=number /operation=choice /override=overrides /prec-absolute=number /prec-relative=number /set-meta=meta-data /step-size=number /stepper=choice /style=style /sub-steps=integer /with=time-dependent parameters

Simulation command for the ode fit.

Kinetic systems

It is possible with QSoas to fit kinetic traces that follow the concentration of one or more species that are part of a full kinetic system. For that, you need to write a simple text file of the following form:

A <=>[k_i][k_a] I1
I1 ->[k_i2 * o2] I2

This describes a kinetic system with three species, A, I1 and I2, with a reversible reaction from A to I1 with a forward rate of k_i and a backward rate of k_a, and an irreversible reaction from I1 to I2 with a rate of k_i2 * o2.

QSoas automatically detects the parameters from the fit, here k_i, k_a, k_i2 and o2, and the initial concentrations of A, I1 and I2, namely c0_A, c0_I1 and c0_I2. As for arbitrary fits (fit-arb), do not use parameters that start with a capital letter. There is no such restriction on the name of species.

It is also possible to specify bimolecular reactions (or any molecularity):

A + B <=>[k_1][km_1] C

The rate is deduced from the rate constants as if it were an elementary reaction, but you can use arbitrary functions of the concentrations as rate constants (by prefixing the species name with c_). For Michaelis-Menten kinetics, use for instance:

S ->[k/(1 + km/c_S)] P

The files can contain comment lines starting with a #, and can contain an arbitrary large number of reactions.

It is possible to assign special time dependence to any of the parameters by using the /with option:

QSoas> fit-kinetic-system /with=o2:3,exp kinetic-file.txt

This gives to o2 the value of the sum of three exponential decays shifted in time (see formula below); this possibility is documented in greater detail below.

To define a new fit one could combine with others using combine-fits, use define-kinetic-system-fit.

fit-kinetic-system - Fit: Full kinetic system

fit-kinetic-system system /adaptive=yes-no /choose-t0=yes-no /debug=integer /engine=engine /extra-parameters=text /min-step-size=number /parameters=file /prec-absolute=number /prec-relative=number /set-from-meta=words /step-size=number /stepper=choice /sub-steps=integer /with=time-dependent parameters (interactive)

Fits a full kinetic system. The fitted value is a linear combination of all the concentrations, with the coefficients given by parameters of name y_A (for the coefficient for the concentration of species A, for instance).

Parameters restrictions

A rate constant cannot be negative.

mfit-kinetic-system - Multi fit: Full kinetic system

mfit-kinetic-system system datasets… /adaptive=yes-no /choose-t0=yes-no /debug=integer /engine=engine /extra-parameters=text /min-step-size=number /parameters=file /perp-meta=text /prec-absolute=number /prec-relative=number /set-from-meta=words /step-size=number /stepper=choice /sub-steps=integer /weight-buffers=yes-no /with=time-dependent parameters (interactive)

Multi-buffer variant of the kinetic-system fit.

sim-kinetic-system - Simulation: Full kinetic system

sim-kinetic-system system parameters datasets… /adaptive=yes-no /choose-t0=yes-no /debug=integer /engine=engine /extra-parameters=text /flags=words /min-step-size=number /operation=choice /override=overrides /prec-absolute=number /prec-relative=number /set-meta=meta-data /step-size=number /stepper=choice /style=style /sub-steps=integer /with=time-dependent parameters

Simulation command for the kinetic-system fit.

define-kinetic-system-fit - Define a fit based on a kinetic mode

define-kinetic-system-fit file name /redefine=yes-no

In the fit-kinetic-system fit, one has to provide systematically the name of the file that contains the kinetic system. This prevents the use of kinetic system fits with combine-fits or define-derived-fit.

The define-kinetic-system-fit command defines a new fit for the kinetic system contained in file. The kinetic system is read only once, if you make modifications to the kinetic system file, they will not be taken into account.

Like for combine-fits, you cannot redefine existing fits with this command unless /redefine=true is specified.

Time-dependent parameters

Some fits, namely arb, ode and kinetic-system (and all the custom fits defined using custom-fit or define-kinetic-system-fit) have a built-in possibility to have some parameters depend on time (instead of being constant). This can be used in kinetic systems to impose an external dependence on various parameters. It makes it possible to separate the chemistry of the system (defined in the kinetic system file), and the experimental procedure by which you vary the conditions (governed by the time-dependent parameters).

The time-dependent parameters are defined using the /with= option to the fits. This option takes a ;-separated list of specifications of the form: parameter:number,type,options… where parameter is the name of the parameter that will depend on time, type is the type of the dependence (see below), number (not always needed) is the number of “features” in the dependence (very type-dependent), and options can additionnally be used for some types.

QSoas recognizes the following time-dependences:

where is the heavyside step function (1 for positive argument, 0 else) and is the number given just after : (in command below, that means you will have three different steps). You may wish to have all values common, which you do by adding ,common in the spec:

QSoas> fit-kinetic-system /with=o2:3,exp,common kinetic-file.txt

This kind of functions were used to analyse the inhibition of NiFe hydrogenase by CO and O2, see for instance Liebgott et al, Nat. Chem. Biol., 2010.

As for exp, the time constant can be chosen to be common to all the segments by adding ,common after the spec.

You can specify several independant parameters, if you separate their description by ;

QSoas> fit-kinetic-system /with=o2:3,exp;o3:2,rexp kinetic-file.txt

This defines the dependence over time of two parameters: o2, like above, and o3, that follows two exponentials relaxations.

Another way to look at the different types of time-dependent parameters available in your version of QSoas is to run the file make-all.cmds from the tests/time-dependent-parameters directory of the source code archive.

Slow scans fits

These specific fits were used in the context of the interpretation of cyclic voltammograms of adorbed nickel-iron hydrogenase that undergo inactivations under oxidizing conditions. For more information, refer to Abou-Hamdam et al, PNAS 2012.

fit-slow-scan-hp - Fit: Slow scan test

fit-slow-scan-hp /bi-exp=yes-no /debug=integer /engine=engine /extra-parameters=text /parameters=file /scaling=yes-no /set-from-meta=words (interactive)

Fit for the “high-potential” part of a slow voltammetric scan where inactivation occurs with rate constants that do not depend on time. The current for the active form is assumed to depend linearly on potential.

Formula:

where is the vertex potential, is the initial potential, the rate constant of decrease, the amount of initially active enzyme, the equilibrium concentration of active species and the scan rate.

fit-slow-scan-lp - Fit: Slow scan test

fit-slow-scan-lp /debug=integer /engine=engine /explicit-rate=yes-no /extra-parameters=text /parameters=file /set-from-meta=words (interactive)

Fit for the “low-potential” part of a slow voltammetric scan where the enzyme reactivates with a rate constant that depends exponentially on the potential:

The overall formula is:

is the initial potential, the scan rate

mfit-slow-scan-hp - Multi fit: Slow scan test

mfit-slow-scan-hp datasets… /bi-exp=yes-no /debug=integer /engine=engine /extra-parameters=text /parameters=file /perp-meta=text /scaling=yes-no /set-from-meta=words /weight-buffers=yes-no (interactive)

Multi-buffer variant of the fit-slow-scan-hp fit.

mfit-slow-scan-lp - Multi fit: Slow scan test

mfit-slow-scan-lp datasets… /debug=integer /engine=engine /explicit-rate=yes-no /extra-parameters=text /parameters=file /perp-meta=text /set-from-meta=words /weight-buffers=yes-no (interactive)

Multi-buffer variant of the fit-slow-scan-lp fit.

sim-slow-scan-lp - Simulation: Slow scan test

sim-slow-scan-lp parameters datasets… /debug=integer /engine=engine /explicit-rate=yes-no /extra-parameters=text /flags=words /operation=choice /override=overrides /set-meta=meta-data /style=style

Simulation command for the slow-scan-lp fit.

sim-slow-scan-hp - Simulation: Slow scan test

sim-slow-scan-hp parameters datasets… /bi-exp=yes-no /debug=integer /engine=engine /extra-parameters=text /flags=words /operation=choice /override=overrides /scaling=yes-no /set-meta=meta-data /style=style

Simulation command for the slow-scan-hp fit.

Wave shape fits

These fits model the catalytic wave shape of active sites with either 2 or 3 redox states, and one catalytic reaction that can be reversible. The equations for these models were initially described in Fourmond et al, JACS 2013, and were reviewed and reparametrized in Fourmond and Lger, Curr Op Electrochemistry 2017. There are 5 different fits:

All these fits (but the eecr-relay-wave fit) share common options:

The fits of reversible models also have the following extra option:

The equations for the fits differ depending on the model:

In the formulas below, we use the shortcut , and is the catalytic rate in the “reference” direction, while is that in the other direction (for reversible fits).

fit-eci-wave - Fit: Fit of an EC irreversible catalytic wave

fit-eci-wave /debug=integer /engine=engine /extra-parameters=text /model=choice /parameters=file /reduction=yes-no /set-from-meta=words (interactive)

Fits the wave shape of an irreversible 1-electron catalytic cycle to the current dataset.

For the oxidative direction:

For the reductive direction:

mfit-eci-wave - Multi fit: Fit of an EC irreversible catalytic wave

mfit-eci-wave datasets… /debug=integer /engine=engine /extra-parameters=text /model=choice /parameters=file /perp-meta=text /reduction=yes-no /set-from-meta=words /weight-buffers=yes-no (interactive)

Multi-buffer version of the eci-wave fit.

sim-eci-wave - Simulation: Fit of an EC irreversible catalytic wave

sim-eci-wave parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /model=choice /operation=choice /override=overrides /reduction=yes-no /set-meta=meta-data /style=style

Simulation command for the eci-wave fit.

fit-ecr-wave - Fit: Fit of an EC reversible catalytic wave

fit-ecr-wave /debug=integer /engine=engine /extra-parameters=text /model=choice /parameters=file /reduction=yes-no /set-from-meta=words /use-eoc=yes-no (interactive)

Fits the wave shape of a reversible 1-electron catalytic cycle to the current dataset.

For the oxidative direction:

For the reductive direction:

mfit-ecr-wave - Multi fit: Fit of an EC reversible catalytic wave

mfit-ecr-wave datasets… /debug=integer /engine=engine /extra-parameters=text /model=choice /parameters=file /perp-meta=text /reduction=yes-no /set-from-meta=words /use-eoc=yes-no /weight-buffers=yes-no (interactive)

Multi-buffer version of the ecr-wave fit.

sim-ecr-wave - Simulation: Fit of an EC reversible catalytic wave

sim-ecr-wave parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /model=choice /operation=choice /override=overrides /reduction=yes-no /set-meta=meta-data /style=style /use-eoc=yes-no

Simulation command for the ecr-wave fit.

fit-eeci-wave - Fit: Fit of an EC irreversible catalytic wave

fit-eeci-wave /debug=integer /engine=engine /extra-parameters=text /model=choice /parameters=file /reduction=yes-no /set-from-meta=words (interactive)

Fits the wave shape of an irreversible 2-electron catalytic cycle to the current dataset.

For the oxidative direction:

For the reductive direction:

mfit-eeci-wave - Multi fit: Fit of an EC irreversible catalytic wave

mfit-eeci-wave datasets… /debug=integer /engine=engine /extra-parameters=text /model=choice /parameters=file /perp-meta=text /reduction=yes-no /set-from-meta=words /weight-buffers=yes-no (interactive)

Multibuffer version of the eeci-wave fit.

sim-eeci-wave - Simulation: Fit of an EC irreversible catalytic wave

sim-eeci-wave parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /model=choice /operation=choice /override=overrides /reduction=yes-no /set-meta=meta-data /style=style

Simulation command for the eeci-wave fit.

fit-eecr-wave - Fit: Fit of an EC reversible catalytic wave

fit-eecr-wave /debug=integer /engine=engine /extra-parameters=text /model=choice /parameters=file /reduction=yes-no /set-from-meta=words /use-eoc=yes-no (interactive)

Fits the wave shape of an reversible 2-electron catalytic cycle to the current dataset.

For the oxidative direction:

For the reductive direction:

mfit-eecr-wave - Multi fit: Fit of an EC reversible catalytic wave

mfit-eecr-wave datasets… /debug=integer /engine=engine /extra-parameters=text /model=choice /parameters=file /perp-meta=text /reduction=yes-no /set-from-meta=words /use-eoc=yes-no /weight-buffers=yes-no (interactive)

Multi-buffer variant of fit-eecr-wave.

sim-eecr-wave - Simulation: Fit of an EC reversible catalytic wave

sim-eecr-wave parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /model=choice /operation=choice /override=overrides /reduction=yes-no /set-meta=meta-data /style=style /use-eoc=yes-no

Simulation for the eecr-wave fit.

fit-eecr-relay-wave - Fit: Fit of an EECR+relay catalytic wave

fit-eecr-relay-wave /debug=integer /engine=engine /extra-parameters=text /parameters=file /set-from-meta=words /use-potentials=yes-no (interactive)

Fits the so-called EEC with relay model in Fourmond et al, JACS 2013 to the data.

mfit-eecr-relay-wave - Multi fit: Fit of an EECR+relay catalytic wave

mfit-eecr-relay-wave datasets… /debug=integer /engine=engine /extra-parameters=text /parameters=file /perp-meta=text /set-from-meta=words /use-potentials=yes-no /weight-buffers=yes-no (interactive)

Multi-buffer version of the eecr-relay-wave fit.

sim-eecr-relay-wave - Simulation: Fit of an EECR+relay catalytic wave

sim-eecr-relay-wave parameters datasets… /debug=integer /engine=engine /extra-parameters=text /flags=words /operation=choice /override=overrides /set-meta=meta-data /style=style /use-potentials=yes-no

Simulation command for the eecr-relay-wave fit.

Computation/simulations functions

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

Evaluation functions

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

eval - Ruby eval

eval code /modify-meta=yes-no /use-dataset=yes-no

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 buffer:

QSoas> generate-buffer 0 10 x**3
QSoas> eval '$stats["y_int"]'
 => 2500.002505007509

You can also use this command as a calculator.

find-root - Finds a root

find-root formula seed /max=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

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 /prec-absolute=number /prec-relative=number

This command takes a function of and , two numbers, and , and computes, for each value of of the current buffer, the integral:

This command uses the same algorithms for integration as the fits created by define-distribution-fit.

generate-buffer - Generate buffer

generate-buffer start end /flags=words /formula=text /number=integer /samples=integer /set-meta=meta-data /style=style

Generates a buffer 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-buffer -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=choice /sub-steps=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 buffer as a source for X values.

The result is a multi-column buffer 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-buffer 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=choice /sub-steps=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 and as solutions.

sin = 0
cos = 1

d_sin = cos
d_cos = -sin

After running the commands

QSoas> generate-buffer 0 10
QSoas> ode sine.ode

One has a buffer with one X column (representing the values), and two Y columns, and (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: , and , that should hopefully be very close to 1.

Details of the integrations procedures can be tweaked using the parameters:

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 /silent=yes-no

Short name: @

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 start to 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:

startup-files - Startup files

startup-files /add=file /rm=integer /run=yes-no

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 /range-type=choice /silent=yes-no

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.

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 /silent=yes-no

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.

noop - No op

noop ignored… /*=text

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:

Ruby code

QSoas internally uses Ruby for the interpretation of all formulas, or more precisely its embedded version, mruby. 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:

Specific additions/modifications to Ruby

Regular expressions

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.

Special functions

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

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

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:


Site info: © 2007-2017 C. Léger | Generated by webgen | Design original de Andreas Viklund.