Dynamique réactionnelle des enzymes rédox multicentres, cinétique électrochimique

Reaction dynamics of multicenter redox enzymes, electrochemical kinetics

Commande reference

QSoas command reference

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

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

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

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

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

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

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

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

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

QSoas> load file1 file2 file3

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

QSoas> temperature /set=300

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

QSoas> temperature 300

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

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

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

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

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

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:

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

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

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

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

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:

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

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

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

Commands producing several 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:

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

For instance, try out:

QSoas> generate-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

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

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

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

version – Version

version /show-features=yes-no

  • /show-features=yes-no: If true, show detailed informations about the capacities of QSoas (defaults to false) – values: a boolean: yes, on, true or no, off, false

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

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

save-history – Save history

save-history file

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

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

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

cd – Change directory

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

Short name: G

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

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

pwd – Working directory

pwd

Prints the full path of the current directory.

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

temperature – Temperature

temperature /set=number

Short name: T

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

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

QSoas> temperature 310

commands – Commands

commands

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

help – Help on…

help command /online=yes-no

Short name: ?

  • command: The command on which to give help – values: the name of one of QSoas’s commands
  • /online=yes-no: Show the online documentation in a browser – values: a boolean: yes, on, true or no, off, false

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

save-output – Save output

save-output file

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

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

print – Print

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

Short name: p

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

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

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

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

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

define-alias – Define alias

define-alias alias command /*=text

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

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

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

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

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

display-aliases – Display aliases

display-aliases

Shows a list of all the currently defined aliases.

graphics-settings – Graphics settings

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

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

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

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

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

ruby-run – Ruby load

ruby-run file

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

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

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

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

After running

QSoas> ruby-run function.rb

You can use mm like any normal function for fitting:

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

or use it in eval:

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

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

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

break – Break

break

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

debug – Debug

debug /directory=directory /level=integer

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

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

The command:

QSoas> debug directory

sets up the automatic debug output in the directory directory.

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

system – System

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

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

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

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

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

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

timer – Timer

timer

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

mem – Memory

mem /cached-files=integer

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

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

Output file manipulation

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

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

output – Change output file

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

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

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

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

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

QSoas> output /reopen=true

comment – Write line to output

comment comment

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

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

QSoas> comment 'Switching to sample 2'

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 /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-cache=yes-no /ignore-empty=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

Short name: l

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

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:

  • text for plain space-separated text
  • csv for CSV data
  • chi-txt for file from CH Instruments potentiostats
  • eclab-ascii for ASCII files exported from Biologic potentiostats
  • parameters for fit parameters (“saved for reusing later”)

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

If a 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

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

Changes the name of the current 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

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

Saves the current 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

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

Saves the designated 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/){: class='external'}-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=code /pattern=text

Short name: W

  • /for-which=code: Select on formula – values: a piece of Ruby code
  • /pattern=text (default option): Files to browse – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

Browse all datafiles in the current directory (or those matching the wildcard pattern given to /pattern, see load for more information about wildcards). Very useful to find quickly the file you’re looking for.

Using the /for-which option, one can display only a certain set of files based on their meta-data and/or statistics. See the dedicated section for more details.

Data display

overlay-buffer – Overlay buffers

overlay-buffer /buffers=buffers /for-which=code /style=style

Short name: V

  • /buffers=buffers (default option): Buffers to overlay – values: comma-separated lists of buffers in the stack, see buffers lists
  • /for-which=code: Only act on buffers matching the code – values: a piece of Ruby code
  • /style=style: Style for curves display – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Plots one or several 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

  • buffers…: buffers to hide – values: comma-separated lists of buffers in the stack, see buffers lists

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 /expected=integer /flags=words /for-which=code /histogram=yes-no /ignore-cache=yes-no /ignore-empty=yes-no /separator=pattern /set-meta=meta-data /skip=integer /style=style /yerrors=column

Short name: v

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

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

  • left: Left limit – values: a floating-point number
  • right: Right limit – values: a floating-point number
  • bottom: Bottom limit – values: a floating-point number
  • top: Top limit – values: a floating-point number

This is the non-interactive version of zoom. You specify the left, right, bottom and top values of the currently displayed window directly on the command-line. There are two special values:

  • * means “auto”, or in other words the maximum needed to see all the curves for that specific side (left, right, bottom or top)
  • = means “don’t change”

Data stack manipulation

Data files are loaded and manipulated in a stack. Every time a file is loaded or a 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:

  • the current buffer can be changed using undo/redo;
  • buffers can be permanently removed from the stack using drop;
  • the whole stack can be saved for later use with save-stack and restored using load-stack, or dropped altogether using clear-stack;
  • contents of the stack can be displayed in the terminal using show-stack or in a dialog bog with browse-stack.
  • an old buffer can be put back on the top of the stack with fetch.
  • buffers can be flagged (flag) or unflagged (unflag) to be used later using the flagged buffer selector.

browse-stack – Browse stack

browse-stack /buffers=buffers /for-which=code (interactive)

Short name: K

  • /buffers=buffers (default option): Buffers to show – values: comma-separated lists of buffers in the stack, see buffers lists
  • /for-which=code: Only act on buffers matching the code – values: a piece of Ruby code

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

It is possible to fine-tune the datasets to browse using: * the /buffers option, which takes a buffer list; * the /for-which option, that takes a condition, see the dedicated section for more information.

If the option /meta= is specified, the command also lists the values of the given, comma-separated, meta data.

show-stack – Show stack

show-stack /meta=words /number=integer

Short name: k

  • /meta=words: also lists the comma-separated meta-data – values: several words, separated by ‘,’
  • /number=integer (default option): Display only that many buffers around 0 – values: an integer

Shows a small text summary of what the stack is made of. If your stack is large and you just need to look at a few buffers, use /number=10 for instance (that will only show buffers -9 to 9).

undo – Undo

undo /number=integer

Short name: u

  • /number=integer (default option): Number of operations to undo – values: an integer

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

  • /number=integer (default option): Number of operations to redo – values: an integer

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

  • file: File name for saving stack – values: name of a 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 /merge=yes-no

  • file: File name for saving stack – values: name of a file
  • /merge=yes-no: If true, merges into the current stack rather than overwriting – values: a boolean: yes, on, true or no, off, false

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

If /merge=true is used, then the previous buffers are kept, and the contents of the stack files are just merged into the 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…

  • buffers…: Buffers to fetch – values: comma-separated lists of buffers in the stack, see buffers lists

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

  • /buffers=buffers (default option): Buffers to drop – values: comma-separated lists of buffers in the stack, see buffers lists

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

  • /buffers=buffers (default option): Buffers to flag/unflag – values: comma-separated lists of buffers in the stack, see buffers lists
  • /exclusive=yes-no: If on, clears the given flags on all the buffers but the ones specified – values: a boolean: yes, on, true or no, off, false
  • /flags=words: Buffers to flag/unflag – values: several words, separated by ‘,’
  • /for-which=code: Only act on buffers matching the code – values: a piece of Ruby code
  • /set=yes-no: If on, clears all the previous flags – values: a boolean: yes, on, true or no, off, false

Flags the given 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=code

  • /buffers=buffers (default option): Buffers to flag/unflag – values: comma-separated lists of buffers in the stack, see buffers lists
  • /flags=words: Buffers to flag/unflag – values: several words, separated by ‘,’
  • /for-which=code: Only act on buffers matching the code – values: a piece of Ruby code

Does the reverse of flag, that is removes all flags on the given datasets, or only those specified by the /flags option if the latter is present. The /for-which option words exactly in the same way as for flag.

auto-flag – Auto flag

auto-flag /flags=words

  • /flags=words (default option): Flags – values: several words, separated by ‘,’

Flags the datasets produced by all commands afterwards, until a call to auto-flag without options:

QSoas> auto-flag /flags=stuff
 [ ... create new datasets. They will all be flagged stuff,
 until the following command ...]
QSoas> auto-flag

This can be used to flag all the datasets produced by a script, for instance.

Basic data manipulation at the buffer level

apply-formula – Apply formula

apply-formula formula /buffers=buffers /extra-columns=integer /flags=words /for-which=code /keep-on-error=yes-no /set-meta=meta-data /style=style /use-meta=yes-no /use-stats=yes-no

Short name: F

  • formula: formula – values: a piece of Ruby code
  • /buffers=buffers (default option): Buffers to work on – values: comma-separated lists of buffers in the stack, see buffers lists
  • /extra-columns=integer: number of extra columns to create – values: an integer
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /for-which=code: Only act on buffers matching the code – values: a piece of Ruby code
  • /keep-on-error=yes-no: if on, the points where the Ruby expression returns a error are kept, as invalid numbers – values: a boolean: yes, on, true or no, off, false
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /use-meta=yes-no: if on (by default), you can use $meta to refer to the dataset meta-data – values: a boolean: yes, on, true or no, off, false
  • /use-stats=yes-no: if on (by default), you can use $stats to refer to statistics (off by default) – values: a boolean: yes, on, true or no, off, false

Applies a formula to the current dataset. It should specify how the x and/or y values of the dataset are modified:

QSoas> apply-formula x=x**2
QSoas> apply-formula y=sin(x**2)
QSoas> apply-formula x,y=y,x

The last bit swaps the 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, the index of the data point
  • seg, the number of the current segment (starting from 0)
  • x_0, the value of of the first point of the current segment
  • i_0, the index of the first point in the current segment
  • y2, y3, etc when there are more than 2 columns in the dataset

i and seg cannot be modified, but y2 and so on can. Here is how you can use i to have even points draw a sine wave and odd points a cosine:

QSoas> apply-formula y=(i%2==0?sin(x):cos(x))

% is the modulo operator. The construction with ? and : (called the ternary operator means: if i%2==0 is true, then the value is sin(x), else cos(x).

You can use several instructions by separating them with ;:

QSoas> apply-formula x=x**2;y=x**2

This results in x values that are the squares of the old values, and y values that are the square of the new x values.

Extra columns initially filled with 0 can be created by using the /extra-columns option:

QSoas> apply-formula /extra-columns=1 y2=y**2

This creates a third column (a second y column) containing the square of the values of the Y column.

If /use-stats=true is used, a global variable $stats can be used in the Ruby expression. It contains all the statistics displayed by stats. For instance, to normalize the Y values by dividing by the median, one would use:

QSoas> apply-formula /use-stats=true y=y/$stats.y_med

Note that you can make use of the special /= operator to shorten that into:

QSoas> apply-formula /use-stats=true y/=$stats.y_med

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

QSoas> apply-formula /use-stats=true y/=$stats[0].y_med

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

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

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

dx – DX

dx

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

dy – DY

dy

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

zero – Makes 0

zero value /axis=axis

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

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

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

shiftx – Shift X values

shiftx

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

norm – Normalize

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

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

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

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

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

QSoas> strip-if x>2

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

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

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

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

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

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

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

Like in apply-formula, you can use the statistics and the meta-data of the 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

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

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

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

Computes the 4th order accurate derivative of the buffer.

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

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

QSoas> diff /order=4 /derivative=2

diff2 – Derive twice

diff2

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

The same warnings apply as for diff.

dataset-options – Options

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

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

Sets options for the current dataset:

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

edit-errors – Edit errors

edit-errors (interactive)

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

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

Cuts the 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:

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

If /set-segments is on, the X values are not used to create independent 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

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

Splits the 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

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

This command makes the X values of the current 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 to ; 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

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

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:

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

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

Perpendicular coordinates make sense when a 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:

  • sr is taken to be the scan rate of a voltammogram. This information is used by baseline and fit-adsorbed.

Selecting datasets and files based on meta-data

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

QSoas> flag all /for-which $stats.y_max>=1e-4

How to test for equality: in ruby, you need to use == to test whether two values are the same. For instance, to flag voltammograms in which the scan rate is 0.1 V/s, you have to use:

QSoas> flag all /for-which $meta.sr==0.1

Replacing the == by = in the code above leads to selecting all the buffers, because $meta.sr=0.1 is always true (see more about the ruby expressions there).

show – Show information

show buffers…

  • buffers…: Buffers to show – values: comma-separated lists of buffers in the stack, see buffers lists

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 /also-record=yes-no /type=choice

  • name: name of the meta-data – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • value: value of the meta-data – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /also-record=yes-no: also record the meta-data as if one had used record-meta on the original file – values: a boolean: yes, on, true or no, off, false
  • /type=choice: type of the meta-data – values: one of: number, number-list, text

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.

The actual type of the meta-data can be specified using the /type option. For now, it is mostly useful to specify lists of numbers:

QSoas> set-meta injection-times 100,200,300 /type=number-list

This specifies that the meta-data injection times is a list of numbers (and not a text).

Meta-data are not permament, and will be forgotten from a QSoas session to another. To store permanently the meta-data so that it is set again the next time QSoas loads this file, either use the record-meta, or use /also-record=true, which has the same effect as running record-meta on the original file.

record-meta – Set meta-data

record-meta name value files… /exclude=files /type=choice

  • name: name of the meta-data – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • value: value of the meta-data – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • files…: files on which to set the meta-data – values: one or more files. Can include wildcards such as *, [0-4], etc…
  • /exclude=files: exclude files – values: one or more files. Can include wildcards such as *, [0-4], etc…
  • /type=choice: type of the meta-data – values: one of: number, number-list, text

record-meta is the “permanent” version of set-meta. It sets meta-data permanently for a series of files (and not buffers as in the case of set-meta). For instance, after running

QSoas> record-meta pH 7 experiment.dat another.dat

The next time QSoas loads either experiment.dat or another.dat, they will automatically have a meta-data called pH with a value 7.

Behind the scenes The meta-data are stored in special files, one for each of the data files. They are almost plain text files (more precisely, JSON files). The have the names of the original files with a .qsm suffix appended. If you move data files around, you need to also move these files if you want the meta-data to follow.

set-perp – Set perpendicular

set-perp coords…

  • coords…: The values of the coordinates (one for each Y column) – values: several floating-point numbers, separated by ,

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

  • /flip=yes-no: If true, flips all the Y columns – values: a boolean: yes, on, true or no, off, false
  • /flip-all=yes-no: If true, flips all the columns, including the X column – values: a boolean: yes, on, true or no, off, false
  • /remove=columns: the columns to remove – values: a comma-separated list of columns names

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

  • meta…: Names of the meta to be created – values: several words, separated by ‘,’
  • columns…: Columns whose values one should split on – values: a comma-separated list of columns names
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

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

  • baselines interpolated from datapoints with baseline
  • baselines interpolated between two segments using either a cubic function or an exponential function with catalytic-baseline

filter-fft – FFT filter

filter-fft /derive=integer (interactive)

  • /derive=integer: The starting order of derivation – values: an integer

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.

If you want to do that non-interactively, look at auto-filter-fft.

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

If you want to do that non-interactively, look at auto-filter-bsplines.

auto-filter-bs – Auto B-splines

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

Short name: afbs

  • /derivatives=integer: computes derivatives up to this number – values: an integer
  • /number=integer: number of segments – values: an integer
  • /optimize=integer: number of iterations to optimize the position of the nodes (defaults to 15, set to 0 or less to disable) – values: an integer
  • /order=integer: order of the splines – values: an integer
  • /weight-column=column: uses the weights in the given column – values: the number/name of a column in a buffer

Filters the data using B-splines in a non-interactive fashion. Performs automatically an optimization step, like hitting o in filter-bsplines, with a number of iterations that is configurable using the /optimize= option (0 disables that altogether).

This is mostly useful in scripts.

auto-filter-fft – Auto FFT

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

Short name: afft

  • /cutoff=integer: value of the cutoff – values: an integer
  • /derive=integer: differentiate to the given order – values: an integer
  • /transform=yes-no: if on, pushes the transform (off by default) – values: a boolean: yes, on, true or no, off, false

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

  • /window=integer: Number of points (after and before) over which to perform regression – values: an 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

  • /factor=number: threshold factor – values: a floating-point number
  • /force-new=yes-no: creates a new buffer even if no spikes were removed (default: false) – values: a boolean: yes, on, true or no, off, false
  • /number=integer: looks at that many points – values: an integer

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

  • /factor=integer: Downsampling factor – values: an 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

  • xvalues: Buffer serving as base for X values – values: the number of a buffer in the stack
  • nodes: Buffer containing the nodes X/Y values – values: the number of a buffer in the stack
  • /type=choice: Interpolation type – values: one of: akima, linear, polynomial, spline

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:

  • they are defined by 4 points
  • the first two points correspond to points where the baseline sticks to the data
  • the last two points give a “direction”

There are two baselines implemented for now:

  • a cubic baseline, that goes through the first two points and is parallel to the slope of the last two
  • an exponential baseline, that goes through the first two points and has the same ratio as the data for the last two points

solve – Solves an equation

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

  • formula: An expression of the y variable – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /iterations=integer: Maximum number of iterations before giving up – values: an integer
  • /max=text: An expression giving the upper boundary for dichotomy approaches – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /min=text: An expression giving the lower boundary for dichotomy approaches – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number

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

  • /boxes=integer: – values: an integer
  • /column=column: – values: the number/name of a column in a buffer
  • /log=yes-no: – values: a boolean: yes, on, true or no, off, false
  • /norm=yes-no: – values: a boolean: yes, on, true or no, off, false
  • /weight=column: – values: the number/name of a column in a buffer

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

  • /average=integer: Average over that many points – values: an integer
  • /set-segments=yes-no: Whether or not to set the dataset segments – values: a boolean: yes, on, true or no, off, false
  • /threshold=number: Detection threshold – values: a floating-point 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

  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

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:

  • with /mode=xvalues, the default, uses the values of X (ie the closest X value is picked). Warning this will work properly for buffers with several times the same X values, like cyclic voltammograms.
  • with /mode=indices, points are matched on a one-to-one basis, ie point 1 of buffer 1 to point 1 of buffer 2, irrespective of the X values.

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 buffers… /mode=choice /use-segments=yes-no

Short name: S

  • buffers…: All buffers – values: comma-separated lists of buffers in the stack, see buffers lists
  • /mode=choice: Whether operations try to match x values or indices – values: one of: indices, xvalues
  • /use-segments=yes-no: If on, operations are performed segment-by-segment – values: a boolean: yes, on, true or no, off, false

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 buffers… /mode=choice /use-segments=yes-no

  • buffers…: All buffers – values: comma-separated lists of buffers in the stack, see buffers lists
  • /mode=choice: Whether operations try to match x values or indices – values: one of: indices, xvalues
  • /use-segments=yes-no: If on, operations are performed segment-by-segment – values: a boolean: yes, on, true or no, off, false

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

  • buffers…: Buffers – values: comma-separated lists of buffers in the stack, see buffers lists
  • /mode=choice: Whether operations try to match x values or indices – values: one of: indices, xvalues
  • /use-segments=yes-no: If on, operations are performed segment-by-segment – values: a boolean: yes, on, true or no, off, false

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

multiply – Multiply

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

Short name: mul

  • buffers…: Buffers – values: comma-separated lists of buffers in the stack, see buffers lists
  • /mode=choice: Whether operations try to match x values or indices – values: one of: indices, xvalues
  • /use-segments=yes-no: If on, operations are performed segment-by-segment – values: a boolean: yes, on, true or no, off, false

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

  • buffers…: Buffers – values: comma-separated lists of buffers in the stack, see buffers lists
  • /count=yes-no: If on, a last column contains the number of averaged points for each value – values: a boolean: yes, on, true or no, off, false
  • /mode=choice: Whether operations try to match x values or indices – values: one of: indices, xvalues
  • /split=yes-no: If on, buffers are automatically split into monotonic parts before averaging. – values: a boolean: yes, on, true or no, off, false
  • /use-segments=yes-no: If on, operations are performed segment-by-segment – values: a boolean: yes, on, true or no, off, false

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 buffers… /mode=choice /use-segments=yes-no

  • buffers…: All buffers – values: comma-separated lists of buffers in the stack, see buffers lists
  • /mode=choice: Whether operations try to match x values or indices – values: one of: indices, xvalues
  • /use-segments=yes-no: If on, operations are performed segment-by-segment – values: a boolean: yes, on, true or no, off, false

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

  • buffers…: Buffers to contract – values: comma-separated lists of buffers in the stack, see buffers lists
  • /mode=choice: Whether operations try to match x values or indices – values: one of: indices, xvalues
  • /perp-meta=text: defines the perpendicular coordinate from meta-data – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /use-columns=columns: if specified, uses only the given columns for the contraction – values: a comma-separated list of columns names
  • /use-segments=yes-no: If on, operations are performed segment-by-segment – values: a boolean: yes, on, true or no, off, false

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

  • /drop=yes-no: Drop the accumulator instead of pushing it on the stack – values: a boolean: yes, on, true or no, off, false

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

  • /accumulate=words: accumulate the given data into a dataset – values: several words, separated by ‘,’
  • /include-borders=yes-no: whether or not to include borders – values: a boolean: yes, on, true or no, off, false
  • /meta=words: when writing to output file, also prints the listed meta-data – values: several words, separated by ‘,’
  • /output=yes-no: whether to write data to output file (defaults to false) – values: a boolean: yes, on, true or no, off, false
  • /peaks=integer: Display only that many peaks (by order of intensity) – values: an integer
  • /set-meta=words: saves the results of the command as meta-data rather than/in addition to saving to the output file – values: several words, separated by ‘,’
  • /which=choice: selects which of minima and/or maxima to find – values: one of: both, max, min
  • /window=integer: width of the window – values: an 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

  • /accumulate=words: accumulate the given data into a dataset – values: several words, separated by ‘,’
  • /include-borders=yes-no: whether or not to include borders – values: a boolean: yes, on, true or no, off, false
  • /meta=words: when writing to output file, also prints the listed meta-data – values: several words, separated by ‘,’
  • /output=yes-no: whether to write data to output file (defaults to false) – values: a boolean: yes, on, true or no, off, false
  • /pairs=integer: Display (and output) only that many peak pairs (by order of intensity) – values: an integer
  • /set-meta=words: saves the results of the command as meta-data rather than/in addition to saving to the output file – values: several words, separated by ‘,’
  • /which=choice: selects which of minima and/or maxima to find – values: one of: both, max, min
  • /window=integer: width of the window – values: an 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

  • /accumulate=words: accumulate the given data into a dataset – values: several words, separated by ‘,’
  • /include-borders=yes-no: whether or not to include borders – values: a boolean: yes, on, true or no, off, false
  • /meta=words: when writing to output file, also prints the listed meta-data – values: several words, separated by ‘,’
  • /output=yes-no: whether to write data to output file (defaults to true) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=words: saves the results of the command as meta-data rather than/in addition to saving to the output file – values: several words, separated by ‘,’
  • /which=choice: selects which of minima and/or maxima to find – values: one of: both, max, min
  • /window=integer: width of the window – values: an 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

  • /accumulate=words: accumulate the given data into a dataset – values: several words, separated by ‘,’
  • /include-borders=yes-no: whether or not to include borders – values: a boolean: yes, on, true or no, off, false
  • /meta=words: when writing to output file, also prints the listed meta-data – values: several words, separated by ‘,’
  • /output=yes-no: whether to write data to output file (defaults to true) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=words: saves the results of the command as meta-data rather than/in addition to saving to the output file – values: several words, separated by ‘,’
  • /which=choice: selects which of minima and/or maxima to find – values: one of: both, max, min
  • /window=integer: width of the window – values: an integer

Equivalent to

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

stats – Statistics

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

  • /accumulate=words: accumulate the given data into a dataset – values: several words, separated by ‘,’
  • /buffers=buffers (default option): buffers to work on – values: comma-separated lists of buffers in the stack, see buffers lists
  • /meta=words: when writing to output file, also prints the listed meta-data – values: several words, separated by ‘,’
  • /output=yes-no: whether to write data to output file (defaults to false) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=words: saves the results of the command as meta-data rather than/in addition to saving to the output file – values: several words, separated by ‘,’
  • /stats=stats-names: writes only the given stats – values: one or more name of statistics (as displayed by stats), separated by ,.
  • /use-segments=yes-no: makes statistics segment by segment (defaults to false) – values: a boolean: yes, on, true or no, off, false

stats displays various statistics about the current buffer (or the one specified by the /buffer option). The following statistics are available:

  • buffer, rows, columns, segments: the buffer name, and the row, column and segment counts.
  • _sum, _average, _var, _stddev: the sum, the average, the variance and the standard deviation of the values of the column.
  • _first, _last: the first and last values of the column.
  • _min, _max: the minimum and maximum values of the column.
  • _norm: the norm of the column, that is .
  • y_int: the integral of the Y values over the X values.
  • _med, _q10, _q25, _q75, _q90: the median, and the 10th, 25th, 75th and 90th percentiles.
  • _delta_min, _delta_max: the min and max values of the difference between two successive values.
  • y_a, y_b: the linear regression coefficients of the Y column over X: a is the slope and b the value at 0.

In this list, the statistics that start with _ are available for all columns (for instance x_min, y_min, y2_min, etc…), the ones that start with y_ are only available for Y columns (such as y_int, y2_int, etc…), and the other ones are global (buffer, rows, etc.).

These statistics are also available in Ruby code with the name $stats, such as $stats.x_min.

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.

It is possible to run stats on several buffers by using the /buffers= option.

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:

  • mono-buffer fits, ie fits that apply to one buffer, but that can be applied to several buffers at the same time with shared parameters
  • multi-buffer fits, ie fits that need at least two buffers to work

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.

  • The fit- command fits a single buffer, when the fit allows that. It takes no argument
  • The mfit- command fits several buffers at the same time. It takes the numbers of the buffers it will work on.
  • The sim- command takes a saved parameters file and a series of buffers, and pushes the data computed from the parameters on the stack using the X values of the buffers given as arguments (their Y values are not used).

All fits commands share the following options:

  • With the /extra-parameters option, on defines additional parameters to the fit, that can be used to define parameters by formulas
  • Passing the name of a saved parameters file to the /parameters option preloads the given parameters at the beginning of the fit.
  • The /set-from-meta option makes it possible to set a value of parameters from meta-data. For instance, running a fit with /set-from-meta=v=sr will set the value of the parameter v to the value of the meta-data sr (if present). Specify more of those by separating them with commas.
  • The /debug option is for debugging fits or fit engines. It takes a debug level: 0 (no debug info), 1 and 2.
  • Using the /engine, one can pre-select the fit engine for fitting (exactly like choosing it in the dialog box)
  • The /window-title= option makes it possible to select the title of the fit window, which can be useful if you’re running several fits at the same time on the same computer.

The sim- commands additionally take the following options:

  • /operation= which tells sim- which operation to make: compute for just computing the fit function (the default operation), reexport, to reexport the values of the fit parameters with the options to the output file, jacobian to push the jacobian of the fit to the stack, and annotate, that just annotates the buffers by adding the values of the fit parameters as meta-data.
  • /override=, which provides a possibility to change the values of the parameters with respect to the values read from the parameter file. The syntax is a comma or colon-separated list of assignments of the form parameter=value or parameter[#buffer]=value.

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.

The fit engines now feature an “expert”, command-line, mode, which makes it possible to run fits automatically, to set parameters using expressions, to save “trajectories”, i.e. series of starting parameters -> ending parameters, and to explore the parameter space using various explorers. These features are accessible through the following options of the fit- and mfit- commands:

  • /expert=true activates the expert mode and allows typing commands;
  • /script= makes it possible to run a script file at fit startup time;
  • /arg1=, /arg2= and /arg3= can be used to give arguments to the script specified by /script=.

The commands for the command-line interface are described below.

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 !

  • odrpack is a very good Levenberg-Marquardt fit engine based on the ODRPACK netlib package. It is the default (and most often the best) for fitting a small number of buffers.
  • lmder and lmsder are the Levenberg-Marquardt fit engines built into the GNU Scientific Library.
  • qsoas and multi are the own Levenberg-Marquardt solvers of QSoas, they are in general significantly faster than the other ones, and the multi fit engine is optimized for massively multi-buffer fits. Don’t use anything else than multi if you have more than 20 buffers with some parameters (but not all) global.
  • simplex is a naive implementation of the “Simplex” minimization problem. It is much faster than all the other ones, but its convergence is sometimes not very good. You may want to refine the fit using one of the Levenberg-Marquardt engines once you have found a suitable minimum using this engine.
  • pso is a naive implementation of the “Particle Swarm” optimizer.

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:

  • to combine several fits together using a mathematical formula, use combine-fits
  • to fit the derivative of a fit function (possibly together with the original function), use define-derived-fit
  • to fit a function with a distribution of one of the parameters, use define-distribution-fit
  • to change the parameters of a fit and impose additional restrictions on them, use reparametrize-fit

combine-fits – Combine fits

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

  • name: name of the new fit – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • formula: how to combine the various fits – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • fits…: the fits to combine together – values: a series of names of a fit (without the fit- prefix), separated by spaces
  • /redefine=yes-no: If the new fit already exists, redefines it – values: a boolean: yes, on, true or no, off, false

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

  • existing-fit: name of the fit to make a derived fit of – values: the name of a fit (without the fit- prefix)
  • /mode=choice: Whether one fits only the derivative, both the derivative and the original data together or separated – values: one of: combined, deriv-only, separated
  • /redefine=yes-no: Does not error out if the fit already exists – values: a boolean: yes, on, true or no, off, false

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

  • only the derivative if /mode=deriv-only, in which case is is named fit-deriv-only-existing-fit;
  • a multibuffer fit for the original function in one buffer and the derivative in the second if /mode=separated (the default mode), in which case the fit is named mfit-deriv-existing-fit;
  • both the original function and the derivative in a single buffer (the derivative is assumed to be the data after the first discontinuity in the X values) if /mode=combined, in which case the new fit is named fit-deriv-combined-existing-fit;

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

  • name: name of the new fit – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • existing-fit: name of fit to make a derived fit from – values: the name of a fit (without the fit- prefix)
  • parameter: the parameter over which to integrate – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /distribution=choice: The default distribution – values: one of: gaussian, log-uniform, lorentzian, uniform
  • /redefine=yes-no: If the new fit already exists, redefines it – values: a boolean: yes, on, true or no, off, false

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:

  • gaussian: gaussian distribution of the parameter
  • lorentzian: lorentzian distribution of the parameter
  • log-uniform: uniform probability between two values for the logarithm of the parameter
  • uniform: for a uniform probability between two values

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

  • name: name of the new fit – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • fit: the fit to modify – values: the name of a fit (without the fit- prefix)
  • new-parameters: Comma-separated list of new parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • redefinitions…: a list of redefinitions, separated by ;; – values: several words, separated by ‘;;’
  • /conditions=words: Additional conditions that must be fullfilled by the parameters (Ruby code) – values: several words, separated by ‘’
  • /redefine=yes-no: If the new fit already exists, redefines it – values: a boolean: yes, on, true or no, off, false

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /exponentials=integer /extra-parameters=text /loss=yes-no /parameters=file /script=file /set-from-meta=words /slow=yes-no /window-title=text (interactive)

  • /absolute=yes-no: whether the amplitude is absolute or relative to the asymptote (defaults to true) – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /exponentials=integer: Number of exponentials – values: an integer
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /loss=yes-no: wether the sum of exponentials should be multiplied by an exp(-kt) function (default: false) – values: a boolean: yes, on, true or no, off, false
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /slow=yes-no: whether there is a very slow phase (that shows up as a linear change in Y against time, defaults: false) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /exponentials=integer /extra-parameters=text /loss=yes-no /parameters=file /perp-meta=text /script=file /set-from-meta=words /slow=yes-no /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /absolute=yes-no: whether the amplitude is absolute or relative to the asymptote (defaults to true) – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /exponentials=integer: Number of exponentials – values: an integer
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /loss=yes-no: wether the sum of exponentials should be multiplied by an exp(-kt) function (default: false) – values: a boolean: yes, on, true or no, off, false
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /slow=yes-no: whether there is a very slow phase (that shows up as a linear change in Y against time, defaults: false) – values: a boolean: yes, on, true or no, off, false
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /absolute=yes-no: whether the amplitude is absolute or relative to the asymptote (defaults to true) – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /exponentials=integer: Number of exponentials – values: an integer
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /loss=yes-no: wether the sum of exponentials should be multiplied by an exp(-kt) function (default: false) – values: a boolean: yes, on, true or no, off, false
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /slow=yes-no: whether there is a very slow phase (that shows up as a linear change in Y against time, defaults: false) – values: a boolean: yes, on, true or no, off, false
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Simulation command for the fit-exponential-decay fit.

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

fit-multiexp-multistep /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /exponentials=integer /extra-parameters=text /independent=yes-no /parameters=file /script=file /set-from-meta=words /steps=integers /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /exponentials=integer: Number of exponentials – values: an integer
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /independent=yes-no: Whether irreversible loss is independent on each step – values: a boolean: yes, on, true or no, off, false
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /steps=integers: Step list with numbered conditions – values: a comma-separated list of integers
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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 . 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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /exponentials=integer /extra-parameters=text /independent=yes-no /parameters=file /perp-meta=text /script=file /set-from-meta=words /steps=integers /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /exponentials=integer: Number of exponentials – values: an integer
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /independent=yes-no: Whether irreversible loss is independent on each step – values: a boolean: yes, on, true or no, off, false
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /steps=integers: Step list with numbered conditions – values: a comma-separated list of integers
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /exponentials=integer: Number of exponentials – values: an integer
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /independent=yes-no: Whether irreversible loss is independent on each step – values: a boolean: yes, on, true or no, off, false
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /steps=integers: Step list with numbered conditions – values: a comma-separated list of integers
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /offset=yes-no /parameters=file /script=file /set-from-meta=words /species=integer /steps=words /window-title=text (interactive)

  • /additional-loss=yes-no: Additional unconstrained ‘irreversible loss’ rate constants – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /offset=yes-no: If on, allow for a constant offset to be added – values: a boolean: yes, on, true or no, off, false
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /species=integer: Number of species – values: an integer
  • /steps=words: Step list with numbered conditions – values: several words, separated by ‘,’
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /offset=yes-no /parameters=file /perp-meta=text /script=file /set-from-meta=words /species=integer /steps=words /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /additional-loss=yes-no: Additional unconstrained ‘irreversible loss’ rate constants – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /offset=yes-no: If on, allow for a constant offset to be added – values: a boolean: yes, on, true or no, off, false
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /species=integer: Number of species – values: an integer
  • /steps=words: Step list with numbered conditions – values: several words, separated by ‘,’
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /additional-loss=yes-no: Additional unconstrained ‘irreversible loss’ rate constants – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /offset=yes-no: If on, allow for a constant offset to be added – values: a boolean: yes, on, true or no, off, false
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /species=integer: Number of species – values: an integer
  • /steps=words: Step list with numbered conditions – values: several words, separated by ‘,’
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

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

Polynomial fits

fit-polynomial – Fit: Fit to a polynomial function

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

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /monotonic=yes-no: With this on, only monotonic polynomials are solutions – values: a boolean: yes, on, true or no, off, false
  • /number=integer: Number of distinct polynomial functions – values: an integer
  • /order=integers: Order of the polynomial functions – values: a comma-separated list of integers
  • /parameters=file: pre-loads parameters – values: name of a file
  • /prefactor=yes-no: Whether there is a prefactor for each polynomial (on by default for multiple polynomials) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /without-inflexions=yes-no: If this is on, there are no inflexion points in the polynomials – values: a boolean: yes, on, true or no, off, false

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /monotonic=yes-no /number=integer /order=integers /parameters=file /perp-meta=text /prefactor=yes-no /script=file /set-from-meta=words /weight-buffers=yes-no /window-title=text /without-inflexions=yes-no (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /monotonic=yes-no: With this on, only monotonic polynomials are solutions – values: a boolean: yes, on, true or no, off, false
  • /number=integer: Number of distinct polynomial functions – values: an integer
  • /order=integers: Order of the polynomial functions – values: a comma-separated list of integers
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /prefactor=yes-no: Whether there is a prefactor for each polynomial (on by default for multiple polynomials) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /without-inflexions=yes-no: If this is on, there are no inflexion points in the polynomials – values: a boolean: yes, on, true or no, off, false

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /monotonic=yes-no: With this on, only monotonic polynomials are solutions – values: a boolean: yes, on, true or no, off, false
  • /number=integer: Number of distinct polynomial functions – values: an integer
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /order=integers: Order of the polynomial functions – values: a comma-separated list of integers
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /prefactor=yes-no: Whether there is a prefactor for each polynomial (on by default for multiple polynomials) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /without-inflexions=yes-no: If this is on, there are no inflexion points in the polynomials – values: a boolean: yes, on, true or no, off, false

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /script=file /set-from-meta=words /window-title=text /with=time-dependent parameters (interactive)

  • formulas: |-separated formulas for the fit – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /with=time-dependent parameters: Make certain parameters depend upon time – values: several specifications of time dependent parameters (like co:2,exp), seperated by ‘;’. Available types: exp, ramps, rexp, steps

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

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

  • x_0 and y_0 are fixed by default and initialized to the first X or Y value of the buffer the fit applies to;
  • temperature is also fixed and set to the current temperature
  • Using fara counts as using temperature excepted that its value is . You never get fara as a fit parameter.
  • dx is fixed by default to the difference in the values of two consecutive points
  • x_i and y_i with i a strictly positive integer are initially assumed to be evenly spread among the or range.

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /perp-meta=text /script=file /set-from-meta=words /weight-buffers=yes-no /window-title=text /with=time-dependent parameters (interactive)

  • formulas: |-separated formulas for the fit – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • datasets…: datasets that will be fitted to – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /with=time-dependent parameters: Make certain parameters depend upon time – values: several specifications of time dependent parameters (like co:2,exp), seperated by ‘;’. Available types: exp, ramps, rexp, steps

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

  • file: File containing the fits to load – values: name of a file
  • /redefine=yes-no: If a fit already exists, redefines it – values: a boolean: yes, on, true or no, off, false

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

  • name: Name for the new fit – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • formula: Mathematical expression for the fit – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /redefine=yes-no: If the fit already exists, redefines it – values: a boolean: yes, on, true or no, off, false

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /number=integer /parameters=file /script=file /set-from-meta=words /use-surface=yes-no /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /number=integer /parameters=file /perp-meta=text /script=file /set-from-meta=words /use-surface=yes-no /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false

Simulation command for the fit-gaussian fit.

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

fit-lorentzian /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /number=integer /parameters=file /script=file /set-from-meta=words /use-surface=yes-no /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /number=integer /parameters=file /perp-meta=text /script=file /set-from-meta=words /use-surface=yes-no /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /number=integer /parameters=file /script=file /set-from-meta=words /use-surface=yes-no /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /number=integer /parameters=file /perp-meta=text /script=file /set-from-meta=words /use-surface=yes-no /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /number=integer: number of distinct peaks (default 1) – values: an integer
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /use-surface=yes-no: whether to use a surface or an amplitude parameter (default false) – values: a boolean: yes, on, true or no, off, false

Simulation command for the fit-pseudo-voigt fit.

Redox titration fits

fit-nernst – Fit: Nerstian behaviour

fit-nernst /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /script=file /set-from-meta=words /species=integer /states=integers /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /species=integer: Number of distinct species (regardless of their redox state) – values: an integer
  • /states=integers: Number of redox states for each species – values: a comma-separated list of integers
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /perp-meta=text /script=file /set-from-meta=words /species=integer /states=integers /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /species=integer: Number of distinct species (regardless of their redox state) – values: an integer
  • /states=integers: Number of redox states for each species – values: a comma-separated list of integers
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /species=integer: Number of distinct species (regardless of their redox state) – values: an integer
  • /states=integers: Number of redox states for each species – values: a comma-separated list of integers
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Simulation command for fit-nernst

Adsorbed redox species

fit-adsorbed – Fit: Adsorbed species

fit-adsorbed /2el=integer /arg1=file /arg2=file /arg3=file /debug=integer /distinct=yes-no /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /script=file /set-from-meta=words /species=integer /window-title=text (interactive)

  • /2el=integer: Number of true 2-electron species – values: an integer
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /distinct=yes-no: If true (default) then all species have their own surface concentrations – values: a boolean: yes, on, true or no, off, false
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /species=integer: Number of 1-electron species – values: an integer
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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 /arg1=file /arg2=file /arg3=file /debug=integer /distinct=yes-no /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /perp-meta=text /script=file /set-from-meta=words /species=integer /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /2el=integer: Number of true 2-electron species – values: an integer
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /distinct=yes-no: If true (default) then all species have their own surface concentrations – values: a boolean: yes, on, true or no, off, false
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /species=integer: Number of 1-electron species – values: an integer
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /2el=integer: Number of true 2-electron species – values: an integer
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /distinct=yes-no: If true (default) then all species have their own surface concentrations – values: a boolean: yes, on, true or no, off, false
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /species=integer: Number of 1-electron species – values: an integer
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Simulation command for the adsorbed fit.

Differential equations fits

fit-ode – Fit: Fit an ODE system

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

  • system: Path to the file describing the ODE system – values: name of a file
  • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /choose-t0=yes-no: If on, one can choose the initial time – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /min-step-size=number: minimum step size for the stepper – values: a floating-point number
  • /parameters=file: pre-loads parameters – values: name of a file
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /step-size=number: initial step size for the stepper – values: a floating-point number
  • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45
  • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /with=time-dependent parameters: Make certain parameters depend upon time – values: several specifications of time dependent parameters (like co:2,exp), seperated by ‘;’. Available types: exp, ramps, rexp, steps

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 /arg1=file /arg2=file /arg3=file /choose-t0=yes-no /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /min-step-size=number /parameters=file /perp-meta=text /prec-absolute=number /prec-relative=number /script=file /set-from-meta=words /step-size=number /stepper=stepper /sub-steps=integer /weight-buffers=yes-no /window-title=text /with=time-dependent parameters (interactive)

  • system: Path to the file describing the ODE system – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /choose-t0=yes-no: If on, one can choose the initial time – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /min-step-size=number: minimum step size for the stepper – values: a floating-point number
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /step-size=number: initial step size for the stepper – values: a floating-point number
  • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45
  • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /with=time-dependent parameters: Make certain parameters depend upon time – values: several specifications of time dependent parameters (like co:2,exp), seperated by ‘;’. Available types: exp, ramps, rexp, steps

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=stepper /style=style /sub-steps=integer /with=time-dependent parameters

  • system: Path to the file describing the ODE system – values: name of a file
  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false
  • /choose-t0=yes-no: If on, one can choose the initial time – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /min-step-size=number: minimum step size for the stepper – values: a floating-point number
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /step-size=number: initial step size for the stepper – values: a floating-point number
  • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer
  • /with=time-dependent parameters: Make certain parameters depend upon time – values: several specifications of time dependent parameters (like co:2,exp), seperated by ‘;’. Available types: exp, ramps, rexp, steps

Simulation command for the ode fit.

ODE steppers

The fits and commands that perform ordinary differential equations (ODE) integrations, such as the kinetic-system or ode fits, have a /stepper= option that controls the stepper used, that is the algorithm that integrates the ODE.

Steppers are divided in two main categories: the explicit steppers, which are fast, and the implicit steppers, which are slower, but handle much better stiff problems, when the values of the derivatives are large (typically when using very large kinetic constants for kinetic-system for instance).

The explicit steppers are rk2, rk4, rk8pd, rkck and rkf45. We recommend the use of rkf45 when it is possible.

The implicit steppers are bsimp, msadams, msbdf, rk1imp, rk2imp and rk4imp. We recommend the use of bsimp for stiff problems.

We refer the reader to the stepper documentation of the GSL for more information.

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.

By default, 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).

However, it is possible to include in the kinetic system file a line starting with y = to define a formula to be fitted. For instance, in the file

A + B <=>[k_1][km_1] C
y = c_C**2

the function fitted is the square of the concentration of C. The formula can contain any arbitrary function, just like the arbitrary fits, and can contain new parameters, and refer to the time t and to any of the concentrations.

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 /arg1=file /arg2=file /arg3=file /choose-t0=yes-no /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /min-step-size=number /parameters=file /prec-absolute=number /prec-relative=number /script=file /set-from-meta=words /step-size=number /stepper=stepper /sub-steps=integer /window-title=text /with=time-dependent parameters (interactive)

  • system: file describing the system – values: name of a file
  • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /choose-t0=yes-no: If on, one can choose the initial time – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /min-step-size=number: minimum step size for the stepper – values: a floating-point number
  • /parameters=file: pre-loads parameters – values: name of a file
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /step-size=number: initial step size for the stepper – values: a floating-point number
  • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45
  • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /with=time-dependent parameters: Make certain parameters depend upon time – values: several specifications of time dependent parameters (like co:2,exp), seperated by ‘;’. Available types: exp, ramps, rexp, steps

Fits a full kinetic system.

Parameters restrictions

A rate constant cannot be negative.

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

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

  • system: file describing the system – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /choose-t0=yes-no: If on, one can choose the initial time – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /min-step-size=number: minimum step size for the stepper – values: a floating-point number
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /step-size=number: initial step size for the stepper – values: a floating-point number
  • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45
  • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /with=time-dependent parameters: Make certain parameters depend upon time – values: several specifications of time dependent parameters (like co:2,exp), seperated by ‘;’. Available types: exp, ramps, rexp, steps

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=stepper /style=style /sub-steps=integer /with=time-dependent parameters

  • system: file describing the system – values: name of a file
  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false
  • /choose-t0=yes-no: If on, one can choose the initial time – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /min-step-size=number: minimum step size for the stepper – values: a floating-point number
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /step-size=number: initial step size for the stepper – values: a floating-point number
  • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer
  • /with=time-dependent parameters: Make certain parameters depend upon time – values: several specifications of time dependent parameters (like co:2,exp), seperated by ‘;’. Available types: exp, ramps, rexp, steps

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

  • file: System to load – values: name of a file
  • name: Name of the newly created fit – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /redefine=yes-no: If the fit already exists, redefines it – values: a boolean: yes, on, true or no, off, false

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:

  • exp, where the given parameter, is given by:

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.

  • steps, where the given parameter, takes a series of values (1 more than the number given) at the given times.
  • rexp, that combines the steps and exp: the time is divided in number segments (preceded by an initial segment in which the parameter is fixed) in which the parameter is given by:

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 /arg1=file /arg2=file /arg3=file /bi-exp=yes-no /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /scaling=yes-no /script=file /set-from-meta=words /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /bi-exp=yes-no: whether the relaxation is bi-exponential or mono-exponential (false by default) – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /scaling=yes-no: if on, use an additional scaling factor (off by default) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /explicit-rate=yes-no /extra-parameters=text /parameters=file /script=file /set-from-meta=words /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /explicit-rate=yes-no: whether the scan rate is an explicit parameter of the fit (default false) – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /bi-exp=yes-no /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /perp-meta=text /scaling=yes-no /script=file /set-from-meta=words /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /bi-exp=yes-no: whether the relaxation is bi-exponential or mono-exponential (false by default) – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /scaling=yes-no: if on, use an additional scaling factor (off by default) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

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

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

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /explicit-rate=yes-no: whether the scan rate is an explicit parameter of the fit (default false) – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /explicit-rate=yes-no: whether the scan rate is an explicit parameter of the fit (default false) – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /bi-exp=yes-no: whether the relaxation is bi-exponential or mono-exponential (false by default) – values: a boolean: yes, on, true or no, off, false
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /scaling=yes-no: if on, use an additional scaling factor (off by default) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

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 Léger, Curr Op Electrochemistry 2017. There are 5 different fits:

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

  • /model describes the approximation used: with nersnt, the electron transfers are at equilibrium, with slow-et, slow electron transfer is taken into account using Butler-Volmer type of kinetics, disp-k0 is with slow electron transfer and a dispersion of values of as described in Léger et al, J. Phys. Chem. B 2002, and bd0-inf is the special case of the former when the limiting value of the current at extreme potentials is not reached.
  • /reduction, for irreversible models, describe the oxidative direction (by default) or the reductive direction (/reduction=true). For reversible models, it defines the reference direction (is the limiting current an oxidation or a reduction current).

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

  • /use-eoc. The open circuit potential (for which the current is 0) is entirely determined by the potentials of the active site and the ratio of the catalytic rates in the two directions. Therefore, instead of using the latter ratio as a parameter, it is equivalent to use the open circuit potential. /use-eoc=true does that. See more about that in Fourmond et al, JACS 2013.

The equations for the fits differ depending on the model:

  • for nernst:
  • for slow-et:
  • for disp-k0:
  • for bd0-inf:

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 /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /model=choice /parameters=file /reduction=yes-no /script=file /set-from-meta=words /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /parameters=file: pre-loads parameters – values: name of a file
  • /reduction=yes-no: if on, models a reductive wave (default: off, hence oxidative wave) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /model=choice /parameters=file /perp-meta=text /reduction=yes-no /script=file /set-from-meta=words /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /reduction=yes-no: if on, models a reductive wave (default: off, hence oxidative wave) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /reduction=yes-no: if on, models a reductive wave (default: off, hence oxidative wave) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Simulation command for the eci-wave fit.

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

fit-ecr-wave /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /model=choice /parameters=file /reduction=yes-no /script=file /set-from-meta=words /use-eoc=yes-no /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /parameters=file: pre-loads parameters – values: name of a file
  • /reduction=yes-no: if on, use the reductive direction as reference (default: oxidative direction as reference) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-eoc=yes-no: whether to use explicitly the bias or compute it using the open circuit potential (default: false) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /model=choice /parameters=file /perp-meta=text /reduction=yes-no /script=file /set-from-meta=words /use-eoc=yes-no /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /reduction=yes-no: if on, use the reductive direction as reference (default: oxidative direction as reference) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-eoc=yes-no: whether to use explicitly the bias or compute it using the open circuit potential (default: false) – values: a boolean: yes, on, true or no, off, false
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /reduction=yes-no: if on, use the reductive direction as reference (default: oxidative direction as reference) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /use-eoc=yes-no: whether to use explicitly the bias or compute it using the open circuit potential (default: false) – values: a boolean: yes, on, true or no, off, false

Simulation command for the ecr-wave fit.

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

fit-eeci-wave /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /model=choice /parameters=file /reduction=yes-no /script=file /set-from-meta=words /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /parameters=file: pre-loads parameters – values: name of a file
  • /reduction=yes-no: if on, models a reductive wave (default: off, hence oxidative wave) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /model=choice /parameters=file /perp-meta=text /reduction=yes-no /script=file /set-from-meta=words /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /reduction=yes-no: if on, models a reductive wave (default: off, hence oxidative wave) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /reduction=yes-no: if on, models a reductive wave (default: off, hence oxidative wave) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Simulation command for the eeci-wave fit.

fit-eecr-wave – Fit: Fit of an EEC reversible catalytic wave

fit-eecr-wave /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /model=choice /parameters=file /reduction=yes-no /script=file /set-from-meta=words /use-eoc=yes-no /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /parameters=file: pre-loads parameters – values: name of a file
  • /reduction=yes-no: if on, use the reductive direction as reference (default: oxidative direction as reference) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-eoc=yes-no: whether to use explicitly the bias or compute it using the open circuit potential (default: false) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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 EEC reversible catalytic wave

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

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /reduction=yes-no: if on, use the reductive direction as reference (default: oxidative direction as reference) – values: a boolean: yes, on, true or no, off, false
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-eoc=yes-no: whether to use explicitly the bias or compute it using the open circuit potential (default: false) – values: a boolean: yes, on, true or no, off, false
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

Multi-buffer variant of fit-eecr-wave.

sim-eecr-wave – Simulation: Fit of an EEC 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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /model=choice: the kind of model used for the computation (default: dispersion) – values: one of: nernst, slow-et, bd0-inf, disp-k0
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /reduction=yes-no: if on, use the reductive direction as reference (default: oxidative direction as reference) – values: a boolean: yes, on, true or no, off, false
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /use-eoc=yes-no: whether to use explicitly the bias or compute it using the open circuit potential (default: false) – values: a boolean: yes, on, true or no, off, false

Simulation for the eecr-wave fit.

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

fit-eecr-relay-wave /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /script=file /set-from-meta=words /use-potentials=yes-no /window-title=text (interactive)

  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-potentials=yes-no: if on, use the potentials of the active site electronic transitions rather than the equilibrium constants – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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… /arg1=file /arg2=file /arg3=file /debug=integer /engine=engine /expert=yes-no /extra-parameters=text /parameters=file /perp-meta=text /script=file /set-from-meta=words /use-potentials=yes-no /weight-buffers=yes-no /window-title=text (interactive)

  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /arg1=file: first argument of the script file – values: name of a file
  • /arg2=file: second argument of the script file – values: name of a file
  • /arg3=file: third argument of the script file – values: name of a file
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /expert=yes-no: runs the fit in expert mode – values: a boolean: yes, on, true or no, off, false
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /parameters=file: pre-loads parameters – values: name of a file
  • /perp-meta=text: if specified, it is the name of a meta-data that holds the perpendicular coordinates – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /script=file: runs a script file – values: name of a file
  • /set-from-meta=words: sets parameter values from meta-data – values: several words, separated by ‘,’
  • /use-potentials=yes-no: if on, use the potentials of the active site electronic transitions rather than the equilibrium constants – values: a boolean: yes, on, true or no, off, false
  • /weight-buffers=yes-no: whether or not to weight buffers (off by default) – values: a boolean: yes, on, true or no, off, false
  • /window-title=text: defines the title of the fit window – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “

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

  • parameters: file to load parameters from – values: name of a file
  • datasets…: the buffers whose X values will be used for simulations – values: comma-separated lists of buffers in the stack, see buffers lists
  • /debug=integer: Debug level: 0 means no debug output, increasing values mean increasing details – values: an integer
  • /engine=engine: The startup fit engine – values: Fit engine, one of: gsl-simplex, lmder, lmniel, lmsder, multi, odrpack, pso, qsoas, simplex
  • /extra-parameters=text: defines supplementary parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /operation=choice: Whether to just compute the function, the full jacobian, reexport parameters with errors or just annotate datasets – values: one of: annotate, compute, jacobian, reexport, residuals, subfunctions
  • /override=overrides: a comma-separated list of parameters to override – values: several parameter=value assignments, separated by , or ;
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green
  • /use-potentials=yes-no: if on, use the potentials of the active site electronic transitions rather than the equilibrium constants – values: a boolean: yes, on, true or no, off, false

Simulation command for the eecr-relay-wave fit.

Commands available in the fit command-line interface

All the commands here become available by using the /expert=true option to fit- or mfit- commands.

Fit engine selection

The fit command features means to select fit engines and tune their parameters.

qsoas-engine – qsoas

qsoas-engine /end-threshold=number /lambda=number /relative-min=number /residuals-threshold=number /scale=number /scaling=yes-no /trial-steps=integer (fit command)

  • /end-threshold=number: – values: a floating-point number
  • /lambda=number: – values: a floating-point number
  • /relative-min=number: – values: a floating-point number
  • /residuals-threshold=number: – values: a floating-point number
  • /scale=number: – values: a floating-point number
  • /scaling=yes-no: – values: a boolean: yes, on, true or no, off, false
  • /trial-steps=integer: – values: an integer

This command selects the qsoas fit engine, QSoas’s own implementation of the Levenberg-Marquardt algorithm.

odrpack-engine – odrpack

odrpack-engine (fit command)

Selects the ODRPACK fit engine

multi-engine – multi

multi-engine /end-threshold=number /global-scaling-order=number /lambda=number /relative-min=number /residuals-threshold=number /scale=number /scaling=yes-no /trial-steps=integer (fit command)

  • /end-threshold=number: – values: a floating-point number
  • /global-scaling-order=number: – values: a floating-point number
  • /lambda=number: – values: a floating-point number
  • /relative-min=number: – values: a floating-point number
  • /residuals-threshold=number: – values: a floating-point number
  • /scale=number: – values: a floating-point number
  • /scaling=yes-no: – values: a boolean: yes, on, true or no, off, false
  • /trial-steps=integer: – values: an integer

This command selects the multi fit engine, the variant of the qsoas fit engine that is adapted for massive multibuffer fits.

simplex-engine – simplex

simplex-engine /alpha=number /beta=number /delta=number /end-threshold=number /gamma=number (fit command)

  • /alpha=number: – values: a floating-point number
  • /beta=number: – values: a floating-point number
  • /delta=number: – values: a floating-point number
  • /end-threshold=number: – values: a floating-point number
  • /gamma=number: – values: a floating-point number

This command selects the Simplex fit engine.

gsl-simplex-engine – gsl-simplex

gsl-simplex-engine (fit command)

This command selects the fit engine based on the GSL version of the simplex, which may or may not be better than the Simplex depending on the function used for fitting.

pso-engine – pso

pso-engine /delta=number /min-inertia=number /particles=integer /starting-inertia=number (fit command)

  • /delta=number: – values: a floating-point number
  • /min-inertia=number: – values: a floating-point number
  • /particles=integer: – values: an integer
  • /starting-inertia=number: – values: a floating-point number

This command selects the Particle Swarm Optimizer fit engine.

Fit parameters manipulation

Here are a series of commands to manipulate the value and state of parameters.

Parameter name specification

Several commands work with parameter names. In single-buffer fits, the situation is simple, since the name just designates the corresponding parameter. For multi-buffer fits, one can also use name[#0] to only designate the parameter name for the first buffer (the numbering starts at 0). The number of the buffer is given in the box on the first line under the fit data, and as the column number in the parameters spreadsheet.

fix – Fix parameter

fix parameter (fit command)

  • parameter: the parameters to fix/unfix – values: …

Fix the parameters, given by their names:

QSoas.fit> fix a
QSoas.fit> fix b[#3]

This fixes parameter a everywher and b only for buffer #3 (i.e. the fourth one).

unfix – Unfix parameter

unfix parameter (fit command)

  • parameter: the parameters to fix/unfix – values: …

Same as fix but sets the parameter free.

set – Set parameter

set parameter value /expression=yes-no /fix=yes-no /unfix=yes-no (fit command)

  • parameter: the parameters of the fit – values: …
  • value: the value – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /expression=yes-no: whether the value is evaluated as an expression – values: a boolean: yes, on, true or no, off, false
  • /fix=yes-no: if true, also fixes the parameters – values: a boolean: yes, on, true or no, off, false
  • /unfix=yes-no: if true, also unfixes the parameters – values: a boolean: yes, on, true or no, off, false

Sets the value of the given parameter. With /expression=true, the value is interpreted as an expression that is evaluated immediately in the context of each fit dataset, as in eval or apply-formula. The /fix=true and /unfix=true can be used to fix or free the parameter at the same time as setting its value.

local – Local parameter

local parameter (fit command)

  • parameter: the parameters whose global/local status to change – values: …

Makes the given parameter local to the buffers.

global – Global parameter

global parameter (fit command)

  • parameter: the parameters whose global/local status to change – values: …

Makes the given parameter global.

save – Save

save file /rotate=integer (fit command)

  • file: name of the file for saving the parameters – values: name of a file
  • /rotate=integer: if not zero, performs a file rotation before saving – values: an integer

Saves the current parameters to the given file, as one would with Ctrl+S.

load – Load

load file /mode=choice (fit command)

  • file: name of the file to load the parameters from – values: name of a file
  • /mode=choice: – values: one of: buffer-name, closest-Z, normal

Loads the parameters from the given file.

show-parameters – Show parameters

show-parameters (fit command)

Displays a dialog box with a graphical display of the fit parameters with their respective errors.

parameters-spreadsheet – Parameters spreadsheet

parameters-spreadsheet (fit command)

Spawns the “parameters spreadsheet” dialog box to easily survey/edit parameters for a large number of datasets.

export – Export parameters

export /errors=yes-no /file=file (fit command)

  • /errors=yes-no: whether the errors are exported too – values: a boolean: yes, on, true or no, off, false
  • /file=file (default option): name of the file for saving the parameters – values: name of a file

Exports the parameters to either to the file given to the /file= option or to the output file if it is not specified.

reset – Reset

reset /source=choice (fit command)

  • /source=choice: – values: one of: backup, initial

Resets all the parameters, either to the “backup” values (i.e. the values at the start of the last fit) or to the initial guess.

Fit trajectories

When running a fit, QSoas keeps track of all the attemps of fits since the opening of the fit dialog. A pair “starting parameters” -> “ending parameters” is called a “fit trajectory”. Here are a collection of functions to work on fit trajectories.

flag-trajectories – Flag trajectories

flag-trajectories /flags=words (fit command)

  • /flags=words: Flags to set on the new trajectories – values: several words, separated by ‘,’

All the subsequent fit trajectories are flagged with the flags given as the /flags= option, until the next call to flag-trajectories. Calling flag-trajectories without the /flags option clears the flags to add to the new trajectories.

trim-trajectories – Trim trajectories

trim-trajectories threshold /at-most=integer (fit command)

  • threshold: threshold for trimming – values: a floating-point number
  • /at-most=integer: keep at most that many trajectories – values: an integer

Removes from the list of trajectories all the trajectories whose final residuals are more than threshold greater than the best final residuals.

save-trajectories – Save trajectories

save-trajectories file /flag=choice /mode=choice (fit command)

  • file: name of the file for saving the trajectories – values: name of a file
  • /flag=choice: – values: one of: « 
  • /mode=choice: – values: one of: fail, overwrite, update

Saves the trajectories into a file.

load-trajectories – Load trajectories

load-trajectories file /mode=choice (fit command)

  • file: name of the file for saving the trajectories – values: name of a file
  • /mode=choice: – values: one of: drop, ignore, update

Loads the trajectories from a previously saved fit trajectory file (see save-trajectories).

browse-trajectories – Browse trajectories

browse-trajectories (fit command)

Shows a dialog box with a spreadsheet to browse all the trajectories with initial and final parameters.

list-trajectories – List trajectories

list-trajectories /flag=choice (fit command)

  • /flag=choice: – values: one of: « 

Shows a list of all the trajectories in the terminal.

drop-trajectories – Drop trajectories

drop-trajectories trajectories (fit command)

  • trajectories: trajectories to remove – values: fit Trajectories

Deletes the trajectories whose flags are given as argument.

run-for-trajectories – Run commands

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

  • file: the script to run – values: name of a file
  • trajectories: trajectories to run – values: fit Trajectories
  • /add-to-history=yes-no: whether the commands run are added to the history (defaults to false) – values: a boolean: yes, on, true or no, off, false
  • /cd-to-script=yes-no: If on, automatically change the directory to that oof the script – values: a boolean: yes, on, true or no, off, false
  • /error=choice: Behaviour to adopt on error – values: one of: abort, delete, except, ignore
  • /parameters=choice: which parameters to use – values: one of: final, initial
  • /silent=yes-no: whether or not to switch off display updates during the script (off by default) – values: a boolean: yes, on, true or no, off, false

Loops through the specified trajectories, restore their final (or initial parameters, depending on the /parameters option), and runs the given script. See run for more information about the options.

Miscellaneous commands

quit – Quit

quit (fit command)

Quits the fit window.

mem – Memory

mem (fit command)

Like the other mem command, gives some information about the memory and other resources usage of QSoas.

select – Select

select dataset (fit command)

  • dataset: the number of the dataset in the fit (not in the stack) – values: an integer

Views the numbered dataset in the fit window. The number corresponds to the number inside the fit dialog box, not the number in QSoas’s stack.

eval – Evaluate

eval expression (fit command)

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

Evaluates a ruby expression. The meta-data of the current buffer are available through the $meta variable, and the parameters of the current buffers are available through their usual name (including those with special characters and those starting with an uppercase letter).

ruby-run – Ruby load

ruby-run file (fit command)

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

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

save-history – Save history

save-history file (fit command)

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

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

run – Run commands

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

Short name: @

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

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

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

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

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

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

verify – Verify

verify expression (fit command)

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

Does the same as the general verify command.

fit – Fit

fit /iterations=integer (fit command)

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

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

commands – Commands

commands (fit command)

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

system – System

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

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

Like the other system command, runs an external program.

push – Push to stack

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

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

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

Parameter space exploration

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

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

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

monte-carlo-explorer – Monte Carlo

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

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

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

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

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

linear-explorer – Linear ramp

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

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

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

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

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

iterate-explorer – Iterate explorer

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

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

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

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

Computation/simulations functions

The commands in this section generate data “from scratch”, though most require a buffer as a starting point 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 /buffers=buffers /for-which=code /modify-meta=yes-no /use-dataset=yes-no

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

Evaluates the given code as a Ruby expression:

QSoas> eval 2*3
 => 6

It runs in the same environment as the apply-formula and the custom fits (excepted, of course, that there are no x and y variables). It can be useful to check that a function has been correctly defined in a file loaded by ruby-run.

Moreover, if /use-dataset is true (the default), it can also access the meta-data and statistics of the (as apply-formula with /use-meta=true and /use-stats=true) of the buffer:

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

You can also use this command as a calculator.

verify – Verify

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

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

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

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

# X values are positive
verify $stats.x_min>0

find-root – Finds a root

find-root formula seed /max=number

  • formula: An expression of 1 variable (not an equation !) – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • seed: Initial X value from which to search – values: a floating-point number
  • /max=number (default option): If present, uses dichotomy between seed and max – values: a floating-point number

Find the root of the given x-dependent expression using an iterative algorithm, using seed as the initial value. If the /max option is specified, then the search proceeds using dichotomy between the two values (seed and max).

QSoas> find-root 'x**2 - 3' 1
Found root at: 1.73205

Do not use a equal sign. The returned value is that for which the expression equates 0.

integrate-formula – Integrate expression

integrate-formula formula a b /integrator=choice /prec-absolute=number /prec-relative=number /subdivisions=integer

  • formula: An expression of 1 variable (not an equation !) – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • a: Left bound of the segment – values: a floating-point number
  • b: Right bound of the segment – values: a floating-point number
  • /integrator=choice: The algorithm used for integration – values: one of: gauss15, gauss21, gauss31, gauss41, gauss51, gauss61, qng
  • /prec-absolute=number: Absolute precision required for integration – values: a floating-point number
  • /prec-relative=number: Relative precision required for integration – values: a floating-point number
  • /subdivisions=integer: Maximum number of subdivisions in the integration algorithm – values: an integer

Computes the integral of the given expression of x between bounds a and b:

QSoas> integrate-formula x**2 10 22
Integral value: 3216	estimated error: 3.57048e-11	 in 31 evaluations over 1 intervals 

The available integrators are gaussi (with i ranging from 15 to 61), which correspond to adaptive Gauss-Kronrod integrators (starting with i evaluations), and qng, which is a non-adaptive Gauss-Kronrod integrator. See the documentation of the GNU Scientific Library for more information.

mintegrate-formula – Integrate expression

mintegrate-formula formula a b /integrator=choice /max-evaluations=integer /prec-absolute=number /prec-relative=number

  • formula: An expression of x and z – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • a: Lower Z value – values: a floating-point number
  • b: Upper Z value – values: a floating-point number
  • /integrator=choice: The algorithm used for integration – values: one of: akima, csplines, gk15, gk21, gk31, gk41, gk51, gk61, naive
  • /max-evaluations=integer: Maximum number of function evaluations – values: an integer
  • /prec-absolute=number: Absolute precision required for integration – values: a floating-point number
  • /prec-relative=number: Relative precision required for integration – values: a floating-point number

This command takes a function of 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

  • start: The first X value – values: a floating-point number
  • end: The last X value – values: a floating-point number
  • /flags=words: Flags to set on the new buffers – values: several words, separated by ‘,’
  • /formula=text (default option): Formula to generate the Y values – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /number=integer: generates that many datasets – values: an integer
  • /samples=integer: number of data points – values: an integer
  • /set-meta=meta-data: Meta-data to add to the newly created buffers – values: one or more meta=value assignements
  • /style=style: Style for the displayed curves – values: one of: brown-green, red-blue, red-green, red-to-blue, red-yellow-green

Generates a 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=stepper /sub-steps=integer

  • reaction-file: File describing the kinetic system – values: name of a file
  • parameters: Parameters of the model – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false
  • /annotate=yes-no: If on, a last column will contain the number of function evaluation for each step (default false) – values: a boolean: yes, on, true or no, off, false
  • /dump=yes-no: if on, prints a description of the system rather than solving (default: false) – values: a boolean: yes, on, true or no, off, false
  • /min-step-size=number: minimum step size for the stepper – values: a floating-point number
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number
  • /step-size=number: initial step size for the stepper – values: a floating-point number
  • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45
  • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer

Simulates the evolution over time of the kinetic system given in the reaction-file (see the section kinetic system for the syntax of the reaction files).

This commands will use the current 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=stepper /sub-steps=integer

  • file: File containing the system – values: name of a file
  • /adaptive=yes-no: whether or not to use an adaptive stepper (on by default) – values: a boolean: yes, on, true or no, off, false
  • /annotate=yes-no: If on, a last column will contain the number of function evaluation for each step – values: a boolean: yes, on, true or no, off, false
  • /dump=yes-no: If on, do not integrate, just dumps the parse contents of the ODE file – values: a boolean: yes, on, true or no, off, false
  • /min-step-size=number: minimum step size for the stepper – values: a floating-point number
  • /parameters=text (default option): Values of the parameters – values: arbitrary text. If you need spaces, do not forget to quote them with ‘ or “
  • /prec-absolute=number: absolute precision required – values: a floating-point number
  • /prec-relative=number: relative precision required – values: a floating-point number
  • /step-size=number: initial step size for the stepper – values: a floating-point number
  • /stepper=stepper: algorithm used for integration (default: rkf45) – values: ODE stepper algorithm, one of: bsimp, msadams, msbdf, rk1imp, rk2, rk2imp, rk4, rk4imp, rk8pd, rkck, rkf45
  • /sub-steps=integer: If this is not 0, then the smallest step size is that many times smaller than the minimum delta t – values: an integer

ode solves ordinary differential equations. The equation definition file is structured in three parts, separated by at least one fully blank line, the last one being optional.

The first section defines the “initial conditions”; there are as many integrated variables as there are lines in this section. This section is only evaluated once at the beginning of the integration.

The second section defines the derivatives; they are evaluated several times for each time step.

The third is optional and is described further below.

Here is the contents of the file (say sine.ode) one would use to obtain 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:

  • /stepper: the ODE stepper algorithm. You can find more about them in the GSL documentation. rkf45 is the standard Runge-Kutta-Feldberg integrator, and is the default choice. If QSoas complains that it has difficulties to integrate and that you should try implicit solvers (because your system is too stiff, then try rk4imp, bsimp, msadams or msbdf.
  • /prec-relative and /prec-absolute control the precision. A step will be deemed precise enough if the error estimate is smaller than either the relative precision or the absolute precision
  • /adaptive controls whether an adaptive step size is used (the values of in the resulting buffer are always those asked, but there may be more intermediate steps). You should seldom need to turn it off.

If /annotate is on, a last column is added that contains the number of the evaluations of derivatives for each step (useful for understanding why an integration takes so long, for instance).

The system of equations may contain undefined variables; one could have for instance used:

d_sin = omega * cos
d_cos = -omega * sin

Their values are set to 0 by default. You can change their values using the /parameters option:

QSoas> ode sine.ode /parameters="omega = 3"

Scripting facilities

QSoas provides facilities for scripting, ie running commands unattended, for instance for preparing series of data files for fitting or further use. The following commands are useful only in this context.

Scripting commands

run – Run commands

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

Short name: @

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

Run commands saved in a file. If a compulsory argument is missing, QSoas will prompt the user.

Arguments following the name of the script are passed to the script as “special variables” ${1}, and ${2} etc.

Imagine you are often doing the same processing a given type of data files, say, simply filtering them. You just have to write a script process.cmd containing:

load ${1}
auto-filter-fft 

And run it this way:

QSoas> run process.cmd data_file.dat

or

QSoas> @ process.cmd data_file.dat

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

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

  • ${2%%suffix} will be replaced by parameter 2 with the suffix “suffix” removed, or simply parameter 2 if it does not end with “suffix”.
  • ${2##prefix} will be replaced by parameter 2 with the prefix “prefix” removed, or simply parameter 2 if it does not start with “prefix”.
  • ${2:-value}: this will be replaced by parameter 2 if it has been provided to the script, or by “value” if it has not been provided.
  • ${2:+value}: this will be replaced by “value” if parameter 2 has been provided to the script, or by nothing if that is not the case (the value of parameter 2 is not used).
  • ${2?yes:no}: this will be replaced by “yes” if parameter 2 has been provided to the script, or by “no” if that is not the case.

Error handling

It is possible to change how the script handles errors using the /error option, which can take the following values:

  • abort (the default behaviour): when a command in the script fails, the script stops executing, and the control comes back to either the command-line or the calling script. In the latter case, this behaviour is not considered as an error (i.e. the calling script does not abort);
  • ignore: if a command in the script fails, the script keeps on running;
  • except: as in abort, but this is considered as an error, so this may also stop the calling script;
  • delete: as in abort, but all the datasets generated during the execution of this script are removed from the stack.

startup-files – Startup files

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

  • /add=file (default option): adds the given startup file – values: name of a file
  • /rm=integer: removes the numbered file – values: an integer
  • /run=yes-no: if on, runs all the startup files right now (off by default) – values: a boolean: yes, on, true or no, off, false

This command instructs QSoas to execute command files at startup. Without options, it displays the list of command files that QSoas will read at the next startup.

Files given to the /add options are added at the end of the list.

To remove a file from the list, obtain its number by running startup-files without any option, then use startup-files again with the option /rm=.

You can re-run all startup files by running:

QSoas> startup-files /run=true

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

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

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

Runs the given script file successively for each argument given. For instance, running:

QSoas> run-for-each process-my-file.cmds file1 file2 file3

Is equivalent to running successively

QSoas> @ process-my-file.cmds file1 
QSoas> @ process-my-file.cmds file2
QSoas> @ process-my-file.cmds file3

The arguments may not be file names, although automatic completion will only complete file names. If the script you want to run requires more than one argument, you can specify them (for all the runs) using the options /arg2, /arg3 and so on:

QSoas> run-for-each process-my-file.cmds /arg2=other file1 file2 

Is equivalent to running:

QSoas> @ process-my-file.cmds file1 other
QSoas> @ process-my-file.cmds file2 other

If you specify either /range-type=lin or /range-type=log, the parameters are interpreted differently, and are expected to be of the type 1..10:20, which means 20 numbers between 1 and 10 (inclusive), that are spaced either linearly or logarithmically, depending on the value of the option.

The /error= option controls how the scripts handle errors. See run for more information.

run-for-datasets – Runs a script for several datasets

run-for-datasets script datasets… /add-to-history=yes-no /arg1=file /arg2=file /arg3=file /arg4=file /arg5=file /arg6=file /error=choice /silent=yes-no

  • script: The script file – values: name of a file
  • datasets…: All the arguments for the script file to loop on – values: comma-separated lists of buffers in the stack, see buffers lists
  • /add-to-history=yes-no: whether the commands run are added to the history (defaults to false) – values: a boolean: yes, on, true or no, off, false
  • /arg1=file: First argument to the script – values: name of a file
  • /arg2=file: Second argument to the script – values: name of a file
  • /arg3=file: Third argument to the script – values: name of a file
  • /arg4=file: Fourth argument to the script – values: name of a file
  • /arg5=file: Fifth argument to the script – values: name of a file
  • /arg6=file: Sixth argument to the script – values: name of a file
  • /error=choice: Behaviour to adopt on error – values: one of: abort, delete, except, ignore
  • /silent=yes-no: whether or not to switch off display updates during the script (off by default) – values: a boolean: yes, on, true or no, off, false

Runs the given script file for each of the datasets given. Before each invocation of the script, the dataset is pushed back to the top of the stack, as if by fetch.

The /error= option controls how the scripts handle errors. See run for more information.

noop – No op

noop /*=words

  • /*=words (default option): Ignored options – values: several words, separated by ‘’

Does nothing.

This command can be combined with the advanced argument uses described in run to conditionally execute some commands.

Non-interactive commands

In addition to purely scripting commands, many commands do not require user interaction, provided all their arguments are given. They are listed here:

Mathematical formulas using Ruby

QSoas internally uses Ruby (or more precisely its embedded version, mruby) for the interpretation of all formulas. This means in particular that all formulas must be valid ruby code.

Basically, the Ruby syntax ressembles that of other symbolic evaluation programs (it is quite close to the one from gnuplot), with the following restrictions:

  • Parameter names cannot start with an uppercase letter, as those have a special meaning to the Ruby interpreter: anything that starts with an uppercase letter is assumed to be a constant.
  • Don’t abbreviate floating point numbers: 2. and .4 are invalid, use 2.0 and 0.4 instead.
  • Case matters: Pi is , while pi is nothing defined.
  • Exponentiation is done with the ** operator. The ^ operator is used for binary XOR.
  • Logical OR is done with the || operator and logical AND with the && operator. The single-letter versions, | and & are binary operators and will not work as you intend.

Special variables

Most ruby expressions can make use of dataset information, such as meta-data or statistics (see the documentation of the specific command for more information about how to make this available):

  • the special variable $stats allow access to the statistics, as given by stats.
  • the special variable $meta gives access to the meta-data.

For instance, to subtract the average to the y column:

QSoas> apply-formula y-=$stats.y_average

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

QSoas> eval $meta.original_file

Auto completion is able to complete the $stats or $meta completions.

Special functions

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

  • abs(x):
  • airy_ai(x): Airy Ai function . Precision to about . Other variants available: airy_ai_fast is faster, (precision ) and airy_ai_double slower, (precision ). (more information there)
  • airy_ai_deriv(x): First derivative of Airy Ai function . Precision to about . Other variants available: airy_ai_deriv_fast is faster, (precision ) and airy_ai_deriv_double slower, (precision ). (more information there)
  • airy_bi(x): Airy Bi function . Precision to about . Other variants available: airy_bi_fast is faster, (precision ) and airy_bi_double slower, (precision ). (more information there)
  • airy_bi_deriv(x): First derivative of Airy Bi function . Precision to about . Other variants available: airy_bi_deriv_fast is faster, (precision ) and airy_bi_deriv_double slower, (precision ). (more information there)
  • atanc(x):
  • atanhc(x):
  • bessel_j0(x): Regular cylindrical Bessel function of 0th order, (more information there)
  • bessel_j1(x): Regular cylindrical Bessel function of first order, (more information there)
  • bessel_jn(x,n): Regular cylindrical Bessel function of n-th order, (more information there)
  • bessel_y0(x): Irregular cylindrical Bessel function of 0th order, (more information there)
  • bessel_y1(x): Irregular cylindrical Bessel function of first order, (more information there)
  • bessel_yn(x,n): Irregular cylindrical Bessel function of n-th order, (more information there)
  • clausen(x): Clausen integral, (more information there)
  • dawson(x): Dawson integral,
  • debye_1(x): Debye function of order 1, (more information there)
  • debye_2(x): Debye function of order 2, (more information there)
  • debye_3(x): Debye function of order 3, (more information there)
  • debye_4(x): Debye function of order 4, (more information there)
  • debye_5(x): Debye function of order 5, (more information there)
  • debye_6(x): Debye function of order 6, (more information there)
  • dilog(x): The dilogarithm, (more information there)
  • expint_e1(x): Exponential integral
  • expint_e2(x): Exponential integral
  • expint_en(x,n): Exponential integral
  • fermi_dirac_0(x): Complete Fermi-Dirac integral (index 0), (more information there)
  • fermi_dirac_1(x): Complete Fermi-Dirac integral (index 1), (more information there)
  • fermi_dirac_2(x): Complete Fermi-Dirac integral (index 2), (more information there)
  • fermi_dirac_3half(x): Complete Fermi-Dirac integral (index 3/2) (more information there)
  • fermi_dirac_half(x): Complete Fermi-Dirac integral (index 1/2) (more information there)
  • fermi_dirac_m1(x): Complete Fermi-Dirac integral (index -1), (more information there)
  • fermi_dirac_mhalf(x): Complete Fermi-Dirac integral (index -1/2) (more information there)
  • fermi_dirac_n(x,n): Complete Fermi-Dirac integral of index , (more information there)
  • gamma(x): The Gauss gamma function (more information there)
  • gamma_inc(a,x): Incomplete gamma function (more information there)
  • gamma_inc_p(a,x): Complementary normalized incomplete gamma function (more information there)
  • gamma_inc_q(a,x): Normalized incomplete gamma function (more information there)
  • gaussian(x,sigma): Normalized gaussian:
  • gsl_erf(x): Error function – GSL version (more information there)
  • gsl_erfc(x): Complementary error function (more information there)
  • hyperg_0F1(c,x): Hypergeometric function (more information there)
  • hyperg_1F1(a,b,x): Hypergeometric function (more information there)
  • hyperg_U(a,b,x): Hypergeometric function (more information there)
  • k_mhc(lambda, eta): Marcus-Hush-Chidsey integral
  • k_mhc_z(lambda, eta): Approximation to the Marcus-Hush-Chidsey integral described in Zeng et al, JEAC 2014, (more information there)
  • lambert_W(x): Principal branch of the Lambert function (more information there)
  • lambert_Wm1(x): Secondary branch of the Lambert function (more information there)
  • landau(x): Probability density of the Landau distribution, (more information there)
  • log1p(x): , but accurate for close to 0
  • lorentzian(x,gamma): Normalized gaussian:
  • pseudo_voigt(x, w, mu): Pseudo-Voigt function, defined by:
  • psi(x): Digamma function: (more information there)
  • psi_1(x): Trigamma function: (more information there)
  • psi_n(x, n): Polygamma function: (more information there)
  • trumpet_bv(m, alpha, prec): Position of an oxidative adsorbed 1-electron peak. is the coefficient defined by Laviron, the value is returned in units of

Physical constants

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

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

Other additions to Ruby

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

Running QSoas

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

Command-line options

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

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

Non-interactive running of QSoas

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

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

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

Latest version of the documentation

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

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