version 07-05-2024, release 5.1.81.3
YAPPARI stands for Yet Another Program for Analysis and Research in Impedance, it can be referenced in publications as Materials Lab, 2023, 2, 230031, you can download a paper describing this program at https://doi.org/10.54227/mlab.20230031.
This document applies to version 5.1.77 or after. For prior releases see the /help folder.
About this program
This program can perform several mathematical operations of interest in impedance spectroscopy: non-linear parametric fits for one or multiple datasets, DRT, Hilbert transform, spectra simulations etc. For a single dataset and non-linear optimization you may use an old and simpler program Yappari 4.2. This single dataset program is not developed further and it has limited features so it might be better to start with this version. No support will be provided for the previous versions.
Some theoretical notions are given in the theory file in this repository.
You are encouraged to contribute to this help file or write tutorials. If you want to contribute to the help file or tutorials, send them to me and I will add them to this repository. As much as I like programming, writing documentation is boring. The most updated description of the program is always here on this page.
Note to users
There is no warrantee whatsoever for using this program. Use it if you want, see CC-BY-NC-ND licence, but you will probably not receive much help from me as everything is in this documentation file. If you don't want to use it... don't use it. There are many other programs, some commercial and some free... and likely some are better than this one. If you find an error (reproducible) you can post the details in Releases/Join discussion forum so I can check. I will answer if there is a bug or if the issue is not covered by this Help file (I will not answer any email messages related to Yappari, basically read the doc file, think, and if something is wrong go to Join discussion).
Tutorials
Changes
- July 7, 2024 : Changed some routines to "clone in memory". Should be a little faster than previous version. Release 5.1.81.3.
- May 7, 2024 : Cosmetics on message boxes. Release 5.1.81.2.
- May 4, 2024 : Annotations on multiple plots at the same time. Release 5.1.81.1.
- May 3, 2024 : Notes can be added to Nyquist plots. Changed the structure of yappari_configuration.xml file. Release 5.1.81.
- April 28, 2024 : Added |Z|^2 as weighting scheme. The weighted and reduced chi^2 parameters are now reported. The structure of xml project file has changed. Release 5.1.80.
- April 28, 2024 : The reduced chi^2 parameter is now reported, instead of chi^2. Release 5.1.79.3.
- April 26, 2024 : The weight factor can be selected on the Parameters page. Release 5.1.79.2.
- April 26, 2024 : Changed the auto zoom behavior on Nyquist plot, it can be disabled. Resease 5.1.79.1.
- April 25, 2024 : Added a Nelder-Mead optimization method. Changed the weighting factor for the minimization process to 1/abs(Z). Configuration and XML project files have new entries therefore old projects files cannot be read with this version and later. Release 5.1.79.
- April 6, 2024 : Dynamically enable or disable options in the menus. Release 5.1.78.
- April 4, 2024 : More cosmetics. Release 5.1.77.
- April 2, 2024 : Cosmetics. Release 5.1.76.
- March 31, 2024 : Added a Global fit function. Grouped Advanced commands in a list. Release 5.1.75
- March 29, 2024 : Added a "Mask" function to disable plotting of spurious points (these points will not be used in the fit). Release 5.1.74.1. (Major upgrade, corrected a bug in XML files)
- February 19, 2024 : Custom data format is now defined with xml files. Configuration file is saved and read from /config. Default parameters and limits of the circuits can be changed by editing the /config/*.xml files or by using an additional program. Release 5.1.71.1
- February 14, 2024 : Project files (all data, parameters, models) can be saved to or read from xml file. Release 5.1.71.
- February 10, 2024 : Order of datasets can be changed by drag and drop. Release 5.1.70.6.
- February 7, 2024 : Corrected an error in the "Report" function. Release 5.1.70.5.
- February 4, 2024 : Changed the name of a function to drt_explore. Added a confirmation window to prevent accidental erase of datasets. Compiled on a Windwos 11 version (it should also work on Windows 10). 5.1.70.4.
- December 21, 2023 : Added a multiplication factor for conversitng Ohm in Ohm cm or Ohm cm^2. Release 5.1.70.2.
- September 20, 2023 : Fisk algorithm improvement; stop fitting if the changes in the solution are less than 0.25% than the norm of the vector u(k). Release 5.1.70.1.
- September 19, 2023 : Changes in the Advanced commands (drt_search, drt_explore). Gold and Fisk DRT calculations are now included in the Action menu. Release 5.1.70.
- September 14, 2023 : Minor changes in Advanced commands. Release 5.1.69.3.
- September 13, 2023 : Added a Gold optimisation algorithm for DRT calculations. Tikhonov regularization parameter can be optimized based on the mean square error between experimental and reconstructed impedance. Release 5.1.69.2
- September 12, 2023 : Calculating re-im cross-validation parameters. Release 5.1.69.1
- September 11, 2023 : Memory optimizations for large arrays. Release 5.1.69
- September 1st, 2023 : Added the command explore_lambda (will plot all DRT calculations for a range of lambda and the user can save all these data).
- August 30, 2023 : Added a config file; you can edit it to start with your own defaults. Removed hdf5 reading file, some errors appeared, problems with DLL linking (conflicts with python hdf5 dll's on some systems). Release 5.1.68.3
- August 29, 2023 : The existing parameters are copied to the new datasets for Smooth and Spline functions. Release 5.1.68.3
- August 28, 2023 : More efficient 3D Plots. Active datasets can be removed with "Delete" key. Corrected an error in labelling Z-Hit datasets. Release tag 5.1.68.2
- August 26, 2023 : Changed the editing of parameters. Release tag 5.1.68.1
- August 25, 2023 : For cases of simple RC circuits, their values are estimated directly from the DRT plots (see Tips and Documentation in the DRT graph). Added a 2-Zarcs element. This release is named 5.1.68.
- August 23, 2023 : Changed the way Max plots is used. In the past, the first max_plots datasets were plotted; now the active datasets are decimated to the number max_plots.
- August 22, 2023 : Added the function DRT search lambda in the main Action menu.
- August 21, 2023 : Added a cursor on the lambda graph, it can be dragged to modify the value proposed by the program (see search_lambda in Advanced commands).
- August 20, 2023 : Show the criteria used in "Search lambda" procedure in a graph. Changed the way the data are saved.
- August 19, 2023 : Changed the Report procedure. Added a simulate spectrum function. Release 5.1.67.4
- August 18, 2023 : Updated the documentation and files.
- August 17, 2023 : Added a spline interpolation function in "Developer commands", can upscale in log spaced frequency. Moved to version 5-1-65 as a new release.
- August 16, 2023 : Added a "Max plots" parameter on the Parameters panel.
- August 15, 2023 : DRT : plot only the first active dataset.
- August 14, 2023 : The method of NNLS for DRT was changed to that of Altenbach. This version is much faster in DRT calculations.
- August 12, 2023 : Implemented a full DRT calculation for ore or more datasets (with a Tikhonov-type constrained non-negative parameters least-squares procedure, see the documentation for reference to the method used). Added the possibility to change the X-scale in DRT graph (sometimes is convenient to check the time constants). Added a debug/developper command to test things.
- August 10, 2023 : Cosmetics; DRT graph changed as a function of 1/ω
- August 9, 2023 : A rather simple calculation of DRT (Distribution of Relaxation Times) with unconstrained Tikhonov parametrisation has been added. The help command directs now to this page. In addition, an error in naming Z-Hit transformed files has been found and corrected. This is a major upgrade, please use this version or later.
- August 7, 2023 : Change in the error management in the fit process.
- August 6, 2023 : Small cosmetic changes, main font is the user system 15pt. Experimental points can now be removed from Nyquist, Zr, Zi and lnR plots.
- August 4, 2023 : Can copy parameters (aka clone) to active datasets. The number of iterations and stop limit are now adjustable parameters.
- August 2, 2023 : read impedance data from HDF5 data files. Some points can now be deleted from the Nyquist plot (see the Action menu).
- August 1st, 2023 : added an indication of the fitting progress.
- July 31, 2023 : increased he number of iterations to 10000 and decreased the limit step, erased an error that appeared when plotting more than 20 datasets
- July 29, 2023 : added the possibility to select which column to read if the data files have more columns or if the frequency is not in the first column
- July 28, 2023 : added the possibility to read custom definition files.
- July 16, 2023 : after loading a datafile, the first dataset is selected automatically.
- July 15, 2023 : the user can select the separator used for MFLI CSV and 3 columns file. The same separator (space, comma or TAB) will be used for saving files.
- July 14, 2023 : added user selected boundaries for TRDL and constrained LM fit.
- June 12, 2023 : added a fourth term in the Z-hit calculations (the one with the pi^7/604800).
- June 10, 2023 : added Z-hit calculation.
Author
This program can be used freely and distributed according to CC-BY-NC-ND 4.0. It was written in Labview 2023, National Instruments and it includes the JKI toolkits for Labview, © 2023, JKI and NI. All rights reserved.
For questions or comments see Note to users:
Nita DRAGOE, Université Paris-Saclay, ICMMO/SP2M, 91400 Orsay, France
Index
- How to install
- Get started
- Read data
- Action
- Mask points active datasets
- Unmask active datasets
- Delete points active datasets
- Delete active datasets
- Apply correction to active
- Simulate spectrum
- Z-Hit active datasets
- DRT active datasets
- DRT search
- Clone the parameters to all
- Clone the parameters to active
- Report active datasets
- Save active parameters
- Save data
- Save project, xml
- Help
- Exit
- Advanced
- Panels
- Parameters
- About
- Datasets
- Fit selected
The recommended and easiest way to install it is to use the full package which can be downloaded from Releases. Make sure you download the Volume.zip file and not what is labelled as source file archives. Several versions are available, in general the last one is the best choice. In case of bugs please report them and grab an earlier version.
There is another way to install it, if you want to complicate things. Yappari 5.1 is compiled with Labview 2023 for Windows. As such it will require a Labview run-time engine which is installed, if needed, by the full installer. So, if you already have the run-time engine (either because you have peviously installed Yappari or you have installed another program compiled with Labview 2023) you can just download all the files from the green button Code as a zip file. If you do not have the run-time engine but still want to go the hard way, you can download the LV 2023 engine freely from ni.com then get the zip file from Code. The files in Code are always the latest version. For previous ones, look in Releases.
After installing the program in a directory of your choice, some other subdirectories will be created : /config, /drt, /files, /help and /models. The /models directory contains png files with images for showing circuits. The /config holds xml configuration files, /files directory contains some examples of data files and custom definitions. The /help directory holds some images for this document and some help files. You can remove /drt, /files and /help but you must keep the /models and /config folders.
This program will work on Windows 10 64 bits or Win 11 with regular screen resolutions.
To use this program requires to give it some data, in general, or you can generate some data. Be aware of the numeric separator of your system: in most cases is a dot, in some others is a period, see the Read data part. There are three main commands in this program: Read data, Action and Advanced.
This command opens a menu with several options indicating the type of file to read.
Warning : A number can be represented as 1.25 or 1,25 (in some countries, like in France). So if your Windows separator setting is set to "," the program expects a number as 1,25 and not 1.25. You can still use this program with "," but you cannot read the files given as examples in /files, which were formated with "."
Reading a new file will just add more data at the beginning of the list wihtout losing the previous ones. You will need to select one or more datasets in order to perform operations like fit, save, plot.. etc. A selected dataset is coloured differently, it is named in this document and in the program as active. _Note : the files given as examples in the /files directory have a decimal separator . (a dot). When saving data there is a character separation between the numerical values (usually a TAB), this should be adjusted in Yappari, see the Parameters page.
This option reads a single dataset from a three-column ASCII file, which should be separated by the character selected in the Parameters page, and it should contain frequency in Hz, Zr, and Zi. The data separator can be "TAB", "space", ",", ";". The file may contain a description line (like parameters or type of the sample), if the description does not contain numbers which might be interpreted as data values by the program. The best option is to have only 3 columns and no text or empty lines in the file. If you want to keep one or more description lines in the file, it is better to use the "Custom" format and prepare an XML template file, see below. If you have multiple datasets in a single file (other than Z_MFLI and MFLI_Zview files) they must be read with the Custom option.
If the reading is successful, the dataset will be inserted in the first position with a name taken from the filename. This name can be changed by the user. Only one dataset can be read with this command.
Note : You should select the proper separator string in the Parameters page prior to use of this function.
This is a ';' or ',' separated values file as obtained from MFLI/MFIA, a Zurich Instruments impedance analyzer. As in the MFLI, Zview text, multiple data sets can be read from this file. In the /files folder that is provided with the installer you can find such a file containing 34 measurements of the same sample. It would be boring and useless to fit all these 34 datasets one by one. Yappari-5 can handle such multiple data sets. The dataseset are labeled with a name taken from the file name and a suffix indicating the position in the file : the first datasets in the file will have 0, then 1, .. and so on.
Note : You should select the proper separator string in the Parameters page prior to of use this function.
This is a MFLI text file, an ASCII type, that can hold multiple data sets. Yappari will read all datasets it finds in this file and insert them in the datasets listing, with a name taken from the file name and a suffix indicating the position in the file : the first datasets will have 0, then 1, and so on.
Note : Data separator from the Parameters page is ignored for this file.
This type of file contains data delimited by and >/Segments>. I did not extensively checked this type of file, an example is given in the /files folder. If you encounter errors, feel free to drop me a line with examples of datafile saved by this system.
Note : Data separator from the Parameters page is ignored for this file.
This is a custom text file, that can hold multiple data sets, which is obtained by the programs I wrote in my lab. An exemple of such file is given in the /files directory but it has probably little interest for other users except that a Custom definition file is provided for this file, so you may understand how to define such a file for reading custom formats.
Note : Data separator from the Parameters page is ignored for this file.
Expand for details
If your data file is of text type and has a format that is not usual you may define a _Custom_ format in an XML configuration file. In this case the program will ask the user to select two files: first the datafile then the XML file that describes the format used. Several exemples of such files are given in the **/files** directory, you can manually edit the xml file definitions or use an additional program, see __Advanced__ below.The XML parameters that are required for a definition file are
header
a text separating datasets, required in order to separate the data blocks
label_length
a numeric value indicating how many characters after the header should be kept for naming a dataset, this value can be set to 0. If the label exists it must be located on the same line and after the header.
data_separator
the string that separates data fields (can be "tab", ",", ";" or " " space).
ignore_first
the number of lines to ignore before the start of the data (it can be 0)
column_freq_Hz
in which column the fequency is located
column_Z_real
in which column Z_real is located
column_Z_imag
in which column Z_imag is located
ignore_last
the number of lines to ignore after the end of the data (it can be 0)
For example, the Z-MFLI program saves a file like this:
Temp /K before measurement : 449.810
measure started : 26/07/2023 18:33:58
T34B descente
temp /K : 0.000
frequency /Hz, Real Z /Ohm, Im Z /Ohm
1.000000E+6 9.414706E+5 -2.383074E+5
8.154407E+5 1.130474E+5 -6.121182E+4
.....
1.844263E-1 1.124571E+5 -5.840550E+2
1.503887E-1 1.129925E+5 -7.342464E+2
1.226330E-1 1.130371E+5 9.631194E+2
1.000000E-1 1.137720E+5 9.809898E+0
end of measure : 26/07/2023 18:35:34
Temp /K after measurement : 449.670 K
----------
Temp /K before measurement : 449.660
measure started : 26/07/2023 18:36:07
T34B descente
temp /K : 0.000
frequency /Hz, Real Z /Ohm, Im Z /Ohm
1.000000E+6 9.664908E+5 -2.747448E+5
8.154407E+5 1.126409E+5 -6.080259E+4
6.649436E+5 9.169096E+4 -5.206284E+4
....
In order to read this file we can observe that the datasets are separated by a string Temp /K before measurement : The label I use is the temperature shown in this line, just after the header. Next, there are 4 text lines that I can ignore. Four additional lines are at the end of the data which are separated by "tab". One can use an xml definition like this :
<Version>23.1f276</Version>
<Cluster>
<Name>cluster</Name>
<NumElts>8</NumElts>
<String>
<Name>header</Name>
<Val>Temp /K before measurement : </Val>
</String>
<U8>
<Name>label length</Name>
<Val>6</Val>
</U8>
<EW>
<Name>data_separator</Name>
<Choice>space</Choice>
<Choice>comma</Choice>
<Choice>semicolon</Choice>
<Choice>tab</Choice>
<Val>3</Val>
</EW>
<U8>
<Name>ignore first</Name>
<Val>4</Val>
</U8>
<U8>
<Name>column_freq</Name>
<Val>1</Val>
</U8>
<U8>
<Name>column_Zr</Name>
<Val>2</Val>
</U8>
<U8>
<Name>column_Zi</Name>
<Val>3</Val>
</U8>
<U8>
<Name>ignore last</Name>
<Val>4</Val>
</U8>
</Cluster>undefined</LVData>The command header will split the datafile (an example of this ZMFLI file is located in /files/ZMFLI_datafile_example.dat) in as many datasets it can find. The datasets are separated by the header read from the XML file (some repetitive text value). The program will find all the measurements (446 measurements for this case), then label each data set with the text following the header, ignore the following 4 lines then read the data found in the three columns separated by the delimiter specified in data_separator (here, it is TAB, it is the index nr 3 of the list, the list start at index 0). After the data is read, an additional 4 lines are skipped.
Note that even if you don't use a label, i.e. label_length is 0, the dataset will have an index indicating the position of the data in the file : 0 is for the first dataset, 1 the second, and so on.
The custom file allows to read other columns from a data file. For instance, the file example_custom_5_columns.dat was saved with yappari and contains 4 datasets with experimental and fitted data. It has a form like this :
dev3221_imps_34, freq /Hz, Zr , Zi, Zr calc, Zi calc
5.000000E+6;2.308040E+3;-4.358320E+3;2.656137E+3;-6.062695E+3
4.304039E+6;2.506840E+3;-5.120760E+3;3.017911E+3;-6.767093E+3
3.704951E+6;2.749520E+3;-5.969060E+3;3.432446E+3;-7.547331E+3
3.189251E+6;3.044990E+3;-6.912400E+3;3.907999E+3;-8.409863E+3
...
5.200320E-3;6.779950E+5;-1.059500E+6;6.713365E+5;-1.051917E+6
4.476419E-3;7.530980E+5;-1.175940E+6;7.440566E+5;-1.164143E+6
dev3221_imps_33, freq /Hz, Zr , Zi, Zr calc, Zi calc
5.000000E+6;2.302790E+3;-4.372530E+3;2.825870E+3;-6.215076E+3
4.304039E+6;2.499580E+3;-5.137940E+3;3.203636E+3;-6.927116E+3
3.704951E+6;2.739930E+3;-5.990360E+3;3.635279E+3;-7.714612E+3
3.189251E+6;3.033540E+3;-6.938630E+3;4.129017E+3;-8.583845E+3
...
If we want to read the calculated impedances, located in the columns 4 and 5 with a definition file (given in example_custom_5_columns_template.xml) the definition will look like this:
<LVData
xmlns="http://www.ni.com/LVData">
<Version>23.1f276</Version>
<Cluster>
<Name>cluster</Name>
<NumElts>8</NumElts>
<String>
<Name>header</Name>
<Val>dev3221_imps_</Val>
</String>
<U8>
<Name>label length</Name>
<Val>2</Val>
</U8>
<EW>
<Name>data_separator</Name>
<Choice>space</Choice>
<Choice>comma</Choice>
<Choice>semicolon</Choice>
<Choice>tab</Choice>
<Val>2</Val>
</EW>
<U8>
<Name>ignore first</Name>
<Val>0</Val>
</U8>
<U8>
<Name>column_freq</Name>
<Val>1</Val>
</U8>
<U8>
<Name>column_Zr</Name>
<Val>4</Val>
</U8>
<U8>
<Name>column_Zi</Name>
<Val>5</Val>
</U8>
<U8>
<Name>ignore last</Name>
<Val>0</Val>
</U8>
</Cluster>
</LVData>This instructs the program to read the fourth column as Zr and the fifth as Zi. Make sure you have the separator set as ";" which is the one used in this file, it is index 2 in the data_separator list.
In the /files folder and in /drt you will find some other files, experimental or simulated with other impedance programs and exemples of configurations for XML templates (or definition files). Be aware that the separator character is defined in the definition file only if you use a Custom file, otherwise the separator is defined in the Parameters page.
This command will read an xml file saved with Yappari. It can read all data, models and parameters obtained. This is an xml file so it can be seen in a browser, but reading it is slow, very slow, it requires parsing all ASCII fields.
This button can trigger several commands.
This function will hide all points from the active datasets, that are in the range shown in the graph. So, before applying this command you need to zoom in the graph to the region which you want to hide. You can "Unmask" them, see the next command. This is useful if you want to exclude some points from the fit, if they are bad, or if you want to separately fit regions of the spectra. All points, from all selected datasets, that are in the area defined by the graph (Nyquist, Zr, Zi or R, but not 3D) will be hidden and not plotted nor used in calculations aftewards. This command applies to all selected (named active) datasets even when they are not plotted : if the Max plots parameter is smaller than the number of active datasets, some of the datasets are not shown... but this command applies to all selected datasets. It is the same case for the Delete points command.
Cancel the mask function for all selected datasets.
You can delete experimental points from selected datasets in the Nyquist, Zr, Zi or lnR plots: just zoom in the region to show only the points you want to delete then select this command (this is irreversible). Be aware that all the points having values in the range shown on the plots are removed from all selected datasets irrespective if they are actually seen on the plots or not. The datasets visible on the graph depends on the Max plot value. Be careful : there is no warning.
Irreversible action removing one or more datasets and all related parameters from memory (by active one should understand “selected”). Datasets can be deleted also with the Key "Delete".
Apply a correction factor to the experimental Zr and Zi for all selected datasets. The impedance values will be multiplied with the factor you input here. Be careful: this will change the units, it is actually its purpose. For ionic conductivity multiply with S/L will give resistivity (in Ohm cm or Ohm m, depending on what unit you used for the S/L correction factor) instead of Ohm. For reactions at electrode surface you need to multiply with the electrode surface to get Ohm cm^2 or Ohm m^2. The already calculated impedances will not be affected by this command.
This option will calculate an impedance spectrum based on the model and the values of the parameters of the model, in the frequency range that are on Parameters page. It will create a new dataset (called "sim_" but you can change its name).
This option will provide a Z-HIT simulation (which is a Hilbert transform of the phase into the real part of the impedance) for one or more datasets. The procedure, when and why to use it, is described here. In this implementation I am using the corrections including the 5th derivative of the phase as described in the link given previously. This is a procedure similar to the better known Kramers-Kronig test. The data will be interpolated, if needed, to log scale and duplicate frequencies will be removed.
This performs a calculation of Distribution of Relaxation Times for one or more datasets for the case of serial RC circuits. The methods used and theory is detailed here.
Data should be acquired with log spacing and with a decent number of points per decade (otherwise you may try to rearrange data with the command spline). For the fit, the optimal regularization parameter is decided by the user (there is no universal value for this, it can be estimated with a procedure known as L-curve). If the Tikhonov parameter, noted Lambda in this program, is too small some spurious peaks will appear while a parameter too large will just squash the information.
Criteria for selecting the optimal value are included in this program. You can either use DRT search command or see other options in Advanced commands. The function drt_explore allows you to see and save all data. The procedure I use here is to provide an indication of the frequencies of the relaxations. More advanced free DRT programs are available, see for instance Ciucci et al and his papers and there are some others. The DRT procedure may help in detecting a proper electrical circuit for serial RC circuits and to some extent to serial RQ cirrcuits. If you want to use it, I suggest to read first some publications describing the procedure and the limitations. There is no need for a circuit model for the DRT calculations. The usefulness of DRT depends much on the quality of the data and in particular the first and the last points of the data. Three different algorithm are now used : Tikhonov regularization (the default one used today), an iterative variant of Tikhonov proposed by Fisk and the Gold decomposition. The latter seems more useful for RQ circuits but the number of iterations is large and it is up to the user to select this. On the DRT graph, the experimental Zr and Zi are plotted together with the recalculated impedances from the DRT data and a probability of distribution function. Calculations are made in real time if you change the Tikhonov parameter, so if you have multiple datasets and many iterations, it may be slow. Some files to test are in the /drt folder. An example of a DRT fit is shown below :
Red dots are experimental Zr and the red line is calculated Zr based on the distribution function as RC (blue dots and line are experimental and calculated Zi values). The green spikes are calculated relaxation times. The fit is very good and corresponds well with the simulated values calculated only from the "experimental" imaginary impedance.
Only the first selected dataset will be shown on the DRT graph, if the DRT calculation was performed for that dataset.
If you hold the mouse on the graph a Tip with an estimation of RC values will be shown (or you can right click on the graph and look for Description and Tips). These parameters are calculated based on the Rpol and the surface of the peaks and can be used as starting points for fitting a model.
This command performs a search of optimal regularization parameter for the first active (aka selected) dataset.
A window with an indication of the optimal parameter will appear. The plot shows the mean squared error (MSE) between the experimental Zr and Zr calculated from DRT data as well as the variance (this is based on the method proposed here).
It should look like this
The optimal regularization parameter is the minimum of the MSE (or just at the change of the variance). You can zoom this image to check the selection made. The program proposes the optimum as the value of lambda where there is a minimum in MSE and show a red cursor position. You can drag this cusor to another position to impose another value for lambda or the number of iterations if you are using Gold. You can select the number of parameters to search. Similar to this function there is drt_explore which can be accesed in Advanced.
Copy the listed parameters to all datasets. Useful for bulk fitting in order to set proper starting point for all the sets.
Copy the listed parameters to selected datasets. Note that the listed parameters are those of the first selected dataset.
This command generates an HTML report containing information about the model used, the parameters used, the fitted parameters, and their standard deviation. It also includes images of the fit. The report is saved in your temporary directory and automatically opened in a browser. Beware that for each datasets you'll get 5 images and text with the obtained results, therefore if you fit 3700 datasets may get a 10000 pages pdf file. A warning is issued if the report will be too large.
Saves a file with the parameters for all selected datasets. Useful for multiple datasets, for a small number of datasets you may use also Report. Note that if the dataset was not fitted the parameter line corresponding to that dataset will be empty.
This option saves the active datasets, as selected by the user, to a single file with data separated by the character you have on the Parameters page, in multiple columns format. All active datasets will be saved in a single file, each dataset subsequently added, with its name, to the same file.
Save all data, model and parameters, including calculated and DRT data, if any, into an xml file. This file can be read in Yappari. Note : With the release 5.1.74, there is a change in the format of the project xml file. Project xml files that were saved with previous versions of the program can not be read with the latest version.
This will open this website, hopefully the address will not change; while the program file may have some tutorial help files, the most recent help is always on this github page.
Close the program and Exit.
These can be used for manual control or advanced functions. Some commands are not very common so I didn't want to have too many entries in the Action menu).
read_config
will update the default parameters (method, iterations...) from values saved in /config/_yappari_configuration.xml
save_config
will save the default parameters (method, iterations...) listed on the parameters page, in the file /config/_yappari_configuration.xml
read_project
Will read an xml file containing all data and parameters (this works only for files saved with Yappari 5.1.74 or after).
save_project
Will save an xml file containing all data and parameters.
save_custom_definition_file
Will save a definition file, in an xml format, for reading custom datafiles.
change_parameters_default_values
Change the default values and the limits for electrical parameters of the model. Adapt these values for your use cases (can be used only as administrator).
drt_search
will calculate a number of DRTs in the range defined by the user and reconstruct all the impedance sets. The best lambda parameter based on the minim squared error between the calculated and experimental sets will be shown. The interval of lambda will be scaned in log spacing over the interval specified by the user (for Gold optimization, the adjusting parameter is the number of iterations). The window that appears allow you to set the DRT value (you may need to resize the window, depending on your screen resolution)
drt_explore
This will calculate and plot a 3D graph with all DRTs as a function of lambda (or iterations), like this graph. Be patient, it takes time.
For Tikhonov or Fisk the parameter changed is Lambda while for Gold optimization you need to specify the number of iterations.
fit_selected_datasets
Equivalent to the Fit selected command.
global_fit_selected_datasets
Perform a fit for a unique set of parameters for the selected datasets. The parameters of the first selected dataset will be taken as starting point. All selected datasets will be taken as input data and all selected datasets will have the same parameters.
add noise to z
Add random noise up to X percent, X being a value defined by the user. Noise can also be added to frequency (for testing purposes, there is no point in adding errors in frequencies), Z, Zr and Zi.
negate_zi
To change the sign of Zi after reading a file that has -Zi (I always wondered why some softwares request -Zi in the datafile).
spline
will get a number of points interpolated from your data, in a log scale. It might not be good to increase too much the number of points from he original ones, nor to use this function on noisy data. This command will create new datasets for every selected dataset, so you can play around to see how it is working. The log scale is important for DRT and Z-hit.
smooth
To make a Savitzky-Golay smooth of the active datasets, with parameters defined by the user. This will create new smoothed datasets with the same name and the prefix sm_.
average
will calculate the mean of Zr and Zi for the selected datasets. This function has a sense if the selected datasets measured at the same frequencies. Not very useful, for fitting several datasets it is better to use Global fit.
tweak Nyquist plots
Can add cursor notes on Nyquist plots, for indicating frequency for instance (since 5.1.81). A short tutorial on this matter can be found in here. You can edit multiple datasets simultaneously (up to 24) but I dot recommend it other than searching automatically a frequence for all plots. Changing other parameters will change all parameters for all datasets. You can get something like this:
The program has several panels and a parameter list with several commands grouped on the right side of the window. When you start the program, if everything is normal, you should see something like this
This panel shows a Nyquist plot, which is a standard way to visualize impedance data. The scale on the graph will adjust automatically based on the data, with the same axis range for the imaginary part and real part. However, if you want to manually set a specific range, you need to disable the Auto-axis feature by right clicking on the graph and directly change the ranges. Some other standard graphic functions are available in the top left "palette" such as zoom in, zoom out... etc. All graphic panels will plot experimental and simulated data (if any) of selected datasets. You can change the plot colors, style, etc.... by clicking on the label; the changes in this graph will affect all the other graphs, except for DRT. You can mask or delete some outlier points by zooming in and use the commands Action/Mask points active datasets or Action/Delete points active datasets. Points that are in that range are removed from all active datasets. When masking some points they will not appear in graphs and not be used in calculations. Unlike the Delete points you can Unmask points. The number of plots can be selected by the user, see Max Plots on Parameters page. Note that, because of space limitations, only the first 24 plots will have legends. But you can plot as many datasets as you want (I tried 3700 datasets, see the tutorials, it is possible but slow to plot them and I wonder why you'd want to plot that many). You can select among the 24 legends which plot to show or hide (this is independent of the Max Plots parameter).
These panels will show the dependency of impedances (real, imaginary, modulus or phase) as a function of frequency and the differences between the calculated and experimental values, something like this
Note that points that are masked will not be shown, nor the difference with the calculations, it's like they don't exist.
This panel will show a 3D plot of selected datasets or a part of them, either in Nyquist, Zr or Zi or their differences, as selected by the user. This is useful for many datasets, more than 20 I guess, it will allow the user to see tendencies or check systematic errors in the fits. You can right click on the graph to adjust plotting properties to your liking (3D Plot Properties) or change the size of the graph. If you have many datasets, it will take some time to plot all data so to limit the waiting time, you may want to "decimate" the data for plotting). The number of plots shown is defined by the smallest value between the number of selected datasets and the "Max plots" value, see --Parameters__. Depending on your computer, a few hunderth datasets can be plotted easily. If you try more than 1000 you'll have to wait, the program will appear irresponsive.
The 3D plot might be useful to look for tendencies, a plot looks like this :
In this panel a model can be created by the user, by selecting element circuits. Up to ten elements can be added in the circuit (obviously it is not realistic to fit such a circuit, unless you want to fit an elephant). Only the first 18 parameters -more than enough- will be shown in the right side of the program.
When you click on one of the ten available cases, a new window will appear where you can select the element you want to add. Simply click on the picture of the element you want to add to the model. The available circuit elements include resistors, capacitors, inductors, and more complex elements such as constant phase elements or Warburg elements (see below).
You can edit the png image files to your liking (just for aesthetics, the calculations will not be affected), they are in the subdirectory /models. The ideal size of the png files is 150x100 pixels.
The elements used are rather common: Resistor, Capacitor, Inductor, CPE, Zarc, simple Randles circuit, Randles with kinetic and diffusion, Warburg (semi-infinite linear diffusion), Warburg short, Warburg Long, Gerischer, Havriliak-Negami and several compositions of these.
Equations are described in the theory file.
When you create a model using the editor, the circuit is not valid unless a flow of current can be calculated (but not a short-circuit). Once the circuit is valid, a LED labeled valid will light up on the model panel, indicating that the circuit is ready for use and you can see a list of all the parameters for each element of the circuit.
Note : the parameters will be listed only if your model is valid.
To see the experimental data and the simulation you need to select one or several datasets and the calculations will be made based on the model and the values of parameters for each dataset. If you select several datasets, the parameters of the first selected dataset are shown. If you modify a parameter while several datasets are selected, that parameter will be changed for all selected datasets.
Calculations of impedances are made whenever the parameter values are changed... if the model is valid and if you have some data loaded or simulated. You can use the wheel of the mouse to evaluate the change in the output impedance with the change in the value of a parameter.
Each parameter listed on the right side of the page, is labeled with a decimal, which indicates which element it belongs to. For example, the first element of the circuit will have parameters labeled as 0.x, the second element as 1.x, and so on. For this circuit composed of two zarcs we need to close the circuit and make "electrical contacts" in other elements (elements 0 and 6) for the circuit to be valid. The parameters that will be listed for this circuit will be 4something and 5something (since the two elements are located on positions 4 and 5).
As the circuit is valid, with a Zarc in element 4 position and a Zarc in element 5 position, six parameters will appear in the tab of the right side of the panel: 4ZARR, 4ZARQ and 4ZARN and 5ZARR, 5ZARQ and 5ZARN; the names are rather self-explaining for the parameters describing a Zarc located in the position 4 of the circuit and a Zarc in the position 5. You can use a RQ element and fix the N to 1 to obtain the equivalent RC circuit. The equivalent capacitance for a RQ circuit is C=((RQ)1/n)/R, if n is close to 1.
For a more complex circuit, you can find on the right side of the screen names such as 2MR1D, 2MQ2D, 2MN2D, 2MR3D, 2MR4D, 2MR5D, and 2MW6D. The first number, "2", indicates which element case the device is in. The letters "M" and "D" are internal notations that are used by the program to identify the device type, but they are not important for the user. The type of device is listed after the "M" notation, such as "R" for resistor or "W" for Warburg. The numbering of the devices goes from left to right and top to bottom.
Overall, the notation is quite straightforward once you become familiar with the conventions used.
On this page you can adjust some parameters of the program. The basic parameters (but not the parameters related to electrical model) are loaded from a configuration file named _yappari_configuration.xml that is located in /config folder. You can edit or save a different default configuration file. The default circuit parameters are loaded from model definitions in /config xml files. You can edit all these xml to adapt the default values to your liking by directly editing the xml files (be careful with these changes, the XML format shoud be respected or the program will not work) or you can use Advanced/save_custom_xml
For reading and saving data, depending on the format you use, the datafile separator should be selected here. When reading a MFLI csv file you have probably a , or ; separator. You need to inspect the data file then select the proper string here. For 3 columns, tabs are typically used. Note that the separator used here for reading will also be used for exporting the data files. This data separator will not be used when reading files which have a defined configuration, see below (in this case the definition file sets the separator to be used).
There are four fitting methods implemented: Trusted Region Dog-Led, Nelder Mead, Constrained Levenberg-Marquardt and unconstrained Levenberg-Marquardt. The TRDL fitting algorithm is the default and the parameters bounds can be constrained to certain intervals that are listed on this page. Initial limits are rather large, for example, resistors are limited to the range of 1 mOhm to 1 GOhm, capacitors are between 10^-4 and 10^-15, and so on. You may want to adjust these parameters limits either on this page for the session in process or edit the default values that are located in the /config/*.xml files. You can edit the files manually or use Advanced commands/change_default_limits The fitting results will depend on the starting parameters since this is a non-linear system. You should probably manually adjust the starting parameters then use the fitting procedure you want (TRDL seems to be quite robust). For Levenberg-Marquardt method, the initial parameters should be rather close to good values. Note that esd's of the fitted parameters are properly calculated for unconstrained LM fit. You need to fit all parameters to get proper esds and chi squared values.
This value selects the weighting method. User can select from |Z|, Z_real, Z_imag, equal (no weight) or |Z|^2. In my opinion the best is way the "absolute Z". The applied weight will be the inverse of this parameter. Use of |Z|^2 will force the fit to give more power to larger Z, sometimes the system is not stable with this parameter.
The fit termination parameters can be adjusted here : by default they are set to 2500 iterations and a stop limit at 10E-18. The default values are in the program /config/.xml configuration file which can be edited manually or by using an Advanced function. The same value listed as the maximum iteration number in this panel is also used for DRT calculated with Gold or Fisk algorithms.
This is used only for Simulate function, it will calculate a spectrum in this range of frequencies having a number of points defined here. Useful for testing and simulation.
This is the maximum number of plots to show on the graphs (excluding DRT which will show only the first selected dataset). It should be small (up to about 100) if you are dealing with many datasets. The number of plots is determined by the number of selected datasets or this number, whichever is smaller. The program will "decimate" the available data for plots but all selected datasets (aka active datasets) are considered for mathematical operations. So, if you have 300 datasets and show only 100 on the graph, when perfoming "Delete points", the points of all 300 datasets will be deleted. The 3D plot is very slow if you have more than 200-300 datasets. Suppose you have 500 datasets selected (you can perform calculations on all of them), for plotting them it may be better to show only a part, let's say 100. The program will "decimate" the 500 datasets and show only 100, equally distributed among the 500. The tendencies will still be visible on the graphs, no need to plot all of them. If you want, you can, but for more than 500 datasets it will be very slow (on my desktop computer slow means a few seconds for 500 datasets plotted on 3D graph, and several minutes for 3000 datasets on 3D graph).
Select the method and the source for DRT calculations. See help/theory.md for details.
Brief help listing the version of the program, this is also the landing page of the program.
This list box shows all the datasets in memory. You can select one or more datasets, edit the label or drag and drop them to rearrange them (you can use common Windows shortcut like Ctrl+A, Delete...). The parameters listed are those of the dataset selected (or the first selected dataset if you have more than one selection).
This command is used to fit the set of parameters that describes the circuit, if the circuit is valid (i.e., there are parameters to fit on the right side of the window) and if you have data. The user can select which parameters to fit and it is recommended to start with a few parameters first, ensuring that the initial values are close to the expected values. The simulated spectrum will be updated with every change in the parameters, and the user can perform manual adjustments as necessary. The data can be selected by standard click, ctrl+click,.. or if you want you can select all by using Ctrl+A. For many datasets, the data are described by the same model circuit, I suggest to select one measurement, adjust the parameters manually to be close to solution, then fit. You may want to take a look at this tutorial. After fit you can “Clone” these parameters to all other datasets and select all datasets, then Fit all selected in a go.
The fitting can be performed using different methods, which are discussed before, although there is not much difference in the output of these methods (except for the esd, see below). The fitting process involves a number of cycles, selected by the user, and it will stop a limit is reached. These termination parameters can be adjusted on the Parameters page or in configuration file. Multiple iterations may be necessary, particularly if the initial values are far from the actual values.
The quality of the fit is evaluated using the R2 statistical parameter and the chi2 value. However, the use of the chi2 value as a statistical parameter for non-linear fit is debatable, as discussed in the paper "Dos and don'ts of reduced chi-squared" by Andrae et al, see the /help/theory/md file.
In Yappari chi2 which, is the weighted value it should be called something like SSE -sum of weighted squared errors-, is the term that is minimized by least-squares and is calculated with the formula
With w=weight, which ideally should be 1/variance. In this case, for an ideal fit chi^2 should be equal to 1, smaller values indicating "overfitting". Since we don't know the variance for each data point, the weight is selected by the user, which is typically 1/Z to balance the influence of larger Z values compared to small ones. This norming scheme (with the weigth decided by the user) might not be a good statistical indication of the fit. The weighting scheme will change the influence of Z values in the fit. In some programs the squared Z is used, I include this as well, but for large values of impedance the fit might not be very stable with this scheme. If you want to get the unweighted chi^2, use "equal" as weighting parameter which means w=1. The reduced_chi2 is reported and is calculated as
With the degree of freedom (DOF) taken as Nr_of_points - nr_of_fitted_parameters.
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script> <script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>