Z-HIT analysis

A collection of functions and classes for performing reconstruction of the modulus data of complex impedances using the Z-HIT algorithm.

Function

pyimpspec.perform_zhit(data, smoothing='modsinc', interpolation='makima', window='auto', num_points=3, polynomial_order=2, num_iterations=3, center=1.5, width=3.0, weights=None, admittance=False, num_procs=-1)

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:

Parameters:

  • data (DataSet) – The data set for which the modulus of the impedance should be reconstructed.

  • smoothing (str, optional) – The type of smoothing to apply: “none”, “lowess” (Locally Weighted Scatterplot Smoothing), “modsinc” (modified sinc kernel), “savgol” (Savitzky-Golay), “whithend” (Whittaker-Henderson) or “auto”.

  • interpolation (str, optional) – The type of interpolation to apply: “akima” (Akima spline), “cubic” (cubic spline), “pchip” (Piecewise Cubic Hermite Interpolating Polynomial), or “auto”.

  • window (str, optional) – The name of the window function. See scipy.signal.windows for window functions with only two parameters (M and sym). For example, “boxcar”, “cosine”, and “triang” are valid values for this parameter. All of these window functions can also be tested by using the value “auto”.

  • num_points (int, optional) – The number of points to take into account while smoothing any given point.

  • polynomial_order (int, optional) – The order of the polynomial used when smoothing (Savitzky-Golay and Whittaker-Henderson only).

  • num_iterations (int, optional) – The number of iterations to perform while smoothing (LOWESS only).

  • center (float, optional) – The center of the window on a logarithmic frequency scale (e.g., centered between 1 Hz and 1000 Hz would mean a value of (log(1000) - log(1)) / 2 = 1.5).

  • width (float, optional) – The width of the window on a logarithmic frequency scale. For example, 3.0 to cover the range from 1 Hz (log(1) = 0) to 1000 Hz (log(1000) = 3) when centered at log f = 1.5.

  • weights (Optional[NDArray[float64]], optional) – If the desired weights can not be implemented using the window, center, and width parameters, then this parameter can be used to provide custom weights.

  • admittance (bool, optional) – Use the admittance representation of the data instead of the impedance representation.

  • num_procs (int, optional) – The maximum number of parallel processes to use when smoothing algorithm, interpolation spline, and/or window function are set to “auto”. A value less than 1 results in an attempt to figure out a suitable value based on, e.g., the number of cores detected. Additionally, a negative value can be used to reduce the number of processes by that much (e.g., to leave one core for a GUI thread).

Return type:

ZHITResult

Class

class pyimpspec.ZHITResult(frequencies, impedances, residuals, pseudo_chisqr, smoothing, interpolation, window)

An object representing the results of reconstructing the modulus of the impedance using the Z-HIT algorithm.

Parameters:

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

  • impedances (ComplexImpedances) – The reconstructed impedances.

  • residuals (ComplexResiduals) – The residuals for the real (eq. 15 in Schönleber et al., 2014) and imaginary (eq. 16 in Schönleber et al., 2014) parts of the reconstruction.

  • pseudo_chisqr (float) – The pseudo chi-squared value (\(\chi^2_{\rm ps}\), eq. 14 in Boukamp, 1995).

  • smoothing (str) – The smoothing algorithm that was used.

  • interpolation (str) – The spline that was used for interpolation.

  • window (str) – The window function that was used.

get_bode_data()

Get the data necessary to plot this FitResult as a Bode plot: the frequencies, the absolute magnitudes of the impedances, and the negative phase angles/shifts of the impedances in degrees.

Return type:

Tuple[Frequencies, Impedances, Phases]

get_frequencies()

Get the frequencies in the fitted frequency range.

Return type:

Frequencies

get_impedances()

Get the impedance response of the fitted circuit.

Return type:

ComplexImpedances

get_label()

Get the label for this result.

Return type:

str

get_nyquist_data()

Get the data necessary to plot this FitResult as a Nyquist plot: the real and the negative imaginary parts of the impedances.

Return type:

Tuple[Impedances, Impedances]

get_residuals_data()

Get the data necessary to plot the relative residuals for this result: the frequencies, the relative residuals for the real parts of the impedances in percents, and the relative residuals for the imaginary parts of the impedances in percents.

Return type:

Tuple[Frequencies, Residuals, Residuals]

to_statistics_dataframe()

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

Return type:

pandas.DataFrame