DearEIS

A GUI program for analyzing, simulating, and visualizing impedance spectra.

Table of contents

• About
• Getting started
  • Requirements
  • Installing
  • Running
  • Settings and keybindings
• Features
  • Projects
  • Data sets
  • Data validation
  • Distribution of relaxation times
  • Circuit fitting and simulation
  • Visualization
  • Scripting
• Changelog
• Contributing
• License

About

DearEIS is a Python package that includes both a program with a graphical user interface (GUI) and an application programming interface (API) for working with impedance spectra. The target audience is researchers who use electrochemical impedance spectroscopy (EIS) though the program may also be useful in educational settings. The program implements:

• projects that can contain multiple experimental data sets
• reading experimental data from several different data formats
• validation of impedance spectra by checking if the data is Kramers-Kronig transformable
• construction of equivalent circuits either by parsing a circuit definition code or by using the included graphical editor
• equivalent circuit fitting
• simulation of impedance spectra
• composition of complex plots

GIFs showcasing parts of the GUI can be found here. See the Features section and pyimpspec for more details about, e.g., supported data formats and implementation details.

The API is built upon the API provided by pyimpspec and can be used to, e.g., perform batch processing. Documentation about the API can be found here. This Jupyter notebook contains some examples of how to use the API though the focus is on the additions available in the DearEIS API. API documentation and examples for pyimpspec can be found here.

If you encounter issues, then please open an issue on GitHub.

Getting started

Supported platforms

• Linux
• Windows
• MacOS

The package may also work on other platforms depending on whether or not those platforms are supported by DearEIS' dependencies.

Requirements

• Python
• The following Python packages
  • Dear PyGui: cross-platform GUI toolkit
  • pyimpspec: data parsing, data validation, circuits, and fitting
  • requests: checking the latest version of DearEIS available on PyPI
  • xdg: XDG Base Directory Specification compliant paths

These Python packages (and their dependencies) are installed automatically when DearEIS is installed using pip.

The following Python packages can be installed as optional dependencies for additional functionality:

• Alternatives to cvxopt (used by default by pyimpspec) in DRT calculations using the TR-RBF method
  • kvxopt: convex optimization
    • This fork of cvxopt may support additional platforms (e.g., Apple Silicon hardware like M1).
  • cvxpy: convex optimization
    • IMPORTANT! Windows and MacOS users must follow the steps described in the CVXPY documentation before installing this optional dependency!

Installing

Make sure that a recent version of Python (3.8+, 64-bit) and pip are installed first and then type the following command in a terminal of your choice (e.g., PowerShell in Windows):

pip install deareis

NOTE! You may wish use the --user option when installing with pip if you are not using a virtual environment. If you only intend to use DearEIS via the GUI, then you may wish to use, e.g., pipx to install DearEIS inside of a virtual environment.

If you wish to install the optional dependencies, then they must be specified explicitly when installing pyimpspec:

pip install deareis[cvxpy]

Alternatively, use the Windows installer available in the releases section. The installer will take care of installing DearEIS using pip and then create shortcuts in the start menu.

Newer versions of DearEIS can be installed at a later date by appending the --upgrade option to the command:

pip install --upgrade deareis

Running

Once installed, DearEIS can be started, e.g., from a terminal or the Windows start menu by searching for the command deareis. If the Windows installer was used, then there should be shortcuts in the start menu. The program may also show up in some application launchers. Check out these tutorials to find out how to use the program.

There is also a deareis-debug command that prints additional information to the terminal and can be useful when troubleshooting issues.

Settings and keybindings

DearEIS has several user-configurable settings. It is possible to configure the default values of the settings on the Kramers-Kronig, fitting, and simulation tabs as well as some aspects of the plots (e.g., colors and markers). Several keybindings, which are also user-configurable, are supported for more keyboard-centric navigation although a mouse or trackpad is required in some circumstances.

Features

Below is a brief overview of the main features of DearEIS. See the included tooltips and instructions in the program for more information.

Projects

DearEIS has a project-based workflow and multiple projects can be open at the same time. Each project has a user-definable label and a section for keeping notes. Multiple projects can also be merged to form a single project.

Data sets

The experimentally obtained impedance spectra are referred to as data sets. Each project can contain multiple data sets. Multiple noisy data sets can be averaged to produce a single data set. Individual data points can be masked to exclude outliers or to focus on a part of the spectrum. Corrections can be made by subtracting either a constant complex value, the impedance of an equivalent circuit, or another spectrum. See pyimpspec's documentation for information about which data formats are currently supported.

Data validation

Data sets can be validated by checking if they are Kramers-Kronig transformable. A few different implementations are included.

See pyimpspec for more details regarding the implementation of the tests.

Distribution of relaxation times

The distribution of relaxation times can be calculated using a few different methods (TR-NNLS, TR-RBF, and BHT).

See pyimpspec for more details regarding the implementation of the calculations.

Circuit fitting and simulation

Equivalent circuits can be constructed either by means of inputting a circuit description code (CDC) or by using the graphical, node-based circuit editor. More information about the CDC syntax can be found in the program. The circuits can be fitted to the experimental data to obtain values for the element parameters. Initial values as well as upper and lower limits can be defined for each element parameter. Element parameters can also be fixed at a constant value. The impedance spectra produced by the circuits can also be simulated in a wide frequency range. Various aspects of the circuits and the fitting results can be copied to the clipboard in different formats. For example, a table of fitted element parameters can be obtained in the form of a Markdown or LaTeX table. The mathematical expression for a circuit's impedance as a function of the applied frequency can also be obtained as, e.g., a SymPy expression.

Visualization

Data sets and their corresponding results (Kramers-Kronig tests and equivalent circuit fits) are visualized using simple Nyquist plots, Bode plots, and residual plots. More complex plots containing multiple data sets, Kramers-Kronig test results, equivalent circuit fitting results, and/or simulation results can also be created. These complex plots can be used to overlay and compare results. The plots can also be exported using matplotlib to render them as either bitmap graphics or vector graphics. However, they can also be used to compose plots that can be turned into publication-ready figures with the help of a Python script (see the Scripting section for more details) or by copying the plot's data to another program.

Scripting

DearEIS projects can also be used in Python scripts for the purposes of batch processing results. This capability could be used to:

• generate project files from large numbers of measurements in an automated fashion
• export the processed data to another format
• generate tables that can be included in a document written in, e.g., LaTeX or Markdown
• plot publication-ready figures using, e.g., matplotlib

See the Jupyter notebook for some examples. Documentation about the API can be found here. See this other Jupyter notebook and pyimpspec's API for examples and documentation, respectively, regarding the API that DearEIS extends.

Changelog

See CHANGELOG.md for details.

Contributing

If you wish to contribute to the further development of DearEIS, then there are several options available to you depending on your ability and the amount of time that you can spare.

If you find bugs, wish some feature was added, or find the documentation to be lacking, then please open an issue on GitHub.

If you wish to contribute code, then start by cloning the repository:

git clone --recurse-submodules https://github.com/vyrjana/DearEIS.git

The development dependencies can be installed from within the repository directory:

pip install -r ./dev-requirements.txt

Create a new branch based on either the main branch or the most recent development branch (e.g., dev-*), and submit your changes as a pull request.

Note that some of the core functionality of DearEIS is based on pyimpspec and thus certain changes (e.g., parsers for data formats) should be contributed to that project instead.

Code contributions should, if it is applicable, also include unit tests, which should be implemented in files placed in the tests folder found in the root of the repository along with any assets required by the tests. It should be possible to run the tests by executing the run_tests.sh script, which uses the test discovery built into the unittest module that is included with Python.

See CONTRIBUTORS for a list of people who have contributed to the DearEIS project.

License

Copyright 2022 DearEIS developers

DearEIS is licensed under the GPLv3 or later.

The licenses of DearEIS' dependencies and/or sources of portions of code are included in the LICENSES folder.