Z-HIT analysis

deareis.perform_zhit(data, settings, num_procs=-1)

Wrapper for the pyimpspec.perform_zhit function.

Performs a reconstruction of the modulus data of an impedance spectrum based on the phase data of that impedance spectrum using the Z-HIT algorithm described by Ehm et al. (2000). The results can be used to, e.g., check the validity of an impedance spectrum by detecting non-steady state issues like drift at low frequencies. See the references below for more information about the algorithm and its applications. The algorithm involves an offset adjustment of the reconstructed modulus data, which is done by fitting the reconstructed modulus data to the experimental modulus data in a frequency range that is unaffected (or minimally affected) by artifacts. This frequency range is typically around 1 Hz to 1000 Hz, which is why the default window function is a “boxcar” window that is centered around \(\log{f} = 1.5\) and has a width of 3.0. Multiple window functions are supported and a custom array of weights can also be used.

References:

    1. Ehm, H. Göhr, R. Kaus, B. Röseler, and C.A. Schiller, 2000, Acta Chimica Hungarica, 137 (2-3), 145-157.

    1. Ehm, R. Kaus, C.A. Schiller, and W. Strunz, 2001, in “New Trends in Electrochemical Impedance Spectroscopy and Electrochemical Noise Analysis”.

  • C.A. Schiller, F. Richter, E. Gülzow, and N. Wagner, 2001, 3, 374-378 (https://doi.org/10.1039/B007678N)

Parameters:

  • data (DataSet) – The data to be tested.

  • settings (ZHITSettings) – The settings that determine how the Z-HIT computation is performed.

  • num_procs (int, optional) – The maximum number of parallel processes to use when performing the computations. A value less than 1 will result in an attempt to automatically figure out a suitable value. Negative values are used as offsets relative to the number of cores detected. Applies only when there are multiple possible options for smoothing, interpolation, or window function.

Return type:

ZHITResult

Classes

class deareis.ZHITResult(uuid, timestamp, frequencies, impedances, residuals, mask, pseudo_chisqr, smoothing, interpolation, window, settings)

A class containing the result of a Z-HIT analysis.

Parameters:

  • uuid (str) – The universally unique identifier assigned to this result.

  • timestamp (float) – The Unix time (in seconds) for when the test was performed.

  • frequencies (Frequencies) – The frequencies used to perform the analysis.

  • impedances (ComplexImpedances) – The reconstructed impedances.

  • residuals (ComplexResiduals) – The residuals of the reconstructed impedances and the original impedances.

  • mask (Dict[int, bool]) – The mask that was applied to the original data set.

  • pseudo_chisqr (float) – The calculated \(\chi^2_{ps.}\) (eq. 14 in Boukamp, 1995).

  • smoothing (str) – The smoothing algorithm that was used (relevant if this setting was set to ‘auto’).

  • interpolation (str) – The spline that was used to interpolate the data (relevant if this setting was set to ‘auto’).

  • window (str) – The window function that was used to generate weights for the offset adjustment (relevant if this setting was set to ‘auto’).

  • settings (ZHITSettings) – The settings that were used to perform the analysis.

classmethod from_dict(dictionary, data=None)

Create an instance from a dictionary.

Parameters:

  • dictionary (dict) – The dictionary to turn into a FitResult object.

  • data (Optional[DataSet], optional) – The DataSet object that this result is for.

Return type:

ZHITResult

get_bode_data()

Get the data required to plot the results as a Bode plot (Mod(Z) and -Phase(Z) vs f).

Return type:

Tuple[Frequencies, Impedancesy, Phases]

get_frequencies()

Get an array of frequencies within the range of frequencies in the data set.

Return type:

Frequencies

get_impedances()

Get the complex impedances produced by the fitted circuit within the range of frequencies in the data set.

Return type:

ComplexImpedances

get_nyquist_data()

Get the data required to plot the results as a Nyquist plot (-Im(Z) vs Re(Z)).

Return type:

Tuple[Impedances, Impedances]

get_residuals_data()

Get the data required to plot the residuals (real and imaginary vs f).

Return type:

Tuple[Frequencies, Residuals, Residuals]

to_dict(session=True)

Return a dictionary that can be used to recreate an instance.

Parameters:

session (bool, optional) – If False, then a minimal dictionary is generated to reduce file size.

Return type:

dict

to_statistics_dataframe()

Get the statistics related to the modulus reconstruction as a pandas.DataFrame object.

Return type:

DataFrame

class deareis.ZHITSettings(smoothing, num_points, polynomial_order, num_iterations, interpolation, window, window_center, window_width, representation)

A class to store the settings used to perform a Z-HIT analysis.

Parameters:

  • smoothing (ZHITSmoothing) – The smoothing algorithm to use.

  • num_points (int) – The number of points to consider when smoothing a point.

  • polynomial_order (int) – The order of the polynomial to use in the Savitzky-Golay algorithm.

  • num_iterations (int) – The number of iterations to use in the LOWESS algorithm.

  • interpolation (ZHITInterpolation) – The spline to use when interpolating the phase data.

  • window (ZHITWindow) – The window function to use when generating weights for the offset adjustment.

  • window_center (float) – The center of the window function on the logarithmic frequency scale (e.g., 100 Hz -> 2.0).

  • window_width (float) – The width of the window function on the logarithmic frequency scale (e.g., 2.0 means 1 decade on each side of the window center).

  • representation (ZHITRepresentation) – Which immittance representation to operate on.

classmethod from_dict(dictionary)

Create an instance from a dictionary.

Parameters:

dictionary (dict) – The dictionary to turn into a ZHITSettings object.

Return type:

ZHITSettings

to_dict()

Return a dictionary that can be used to recreate an instance.

Return type:

dict

Enums

class deareis.ZHITInterpolation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

The spline to use for interpolating the smoothed phase data:

class deareis.ZHITSmoothing(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

The algorithm to use when smoothing the phase data:

class deareis.ZHITWindow(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

The window functions to use for determining the weights when adjusting the Mod(Z) offset:

  • AUTO: try all of the options

  • BARTHANN

  • BARTLETT

  • BLACKMAN

  • BLACKMANHARRIS

  • BOHMAN

  • BOXCAR

  • COSINE

  • FLATTOP

  • HAMMING

  • HANN

  • LANCZOS

  • NUTTALL

  • PARZEN

  • TRIANG

See scipy.signal.windows for information about these.