Kramers-Kronig testing

Classes

class deareis.KramersKronigResult(uuid, timestamp, circuit, pseudo_chisqr, frequencies, impedances, residuals, mask, settings)

A class containing the result of a Kramers-Kronig test.

Parameters:

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

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

  • circuit (Circuit) – The final, fitted circuit.

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

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

  • impedances (ComplexImpedances) – The complex impedances of the fitted circuit at each of the frequencies.

  • residuals (ComplexResiduals) – The residuals of the real and the imaginary parts of the fit.

  • mask (Dict[int, bool]) – The mask that was applied to the DataSet that was tested.

  • settings (KramersKronigSettings) – The settings that were used to perform the test.

classmethod from_dict(dictionary, data=None)

Create an instance from a dictionary.

Parameters:

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

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

Return type:

KramersKronigResult

get_bode_data(num_per_decade=-1)

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

Parameters:

num_per_decade (int, optional) – If the value is greater than zero, then logarithmically distributed frequencies will be generated within the range of tested frequencies and used to calculate the impedance produced by the fitted circuit.

Return type:

Tuple[Frequencies, Impedances, Phases]

get_estimated_percent_noise()

Estimate the standard deviation of the noise (as a percentage of \(|Z|\)) using the approximation \({\rm SD}_{\rm est} \approx \sqrt{\chi^2_{\rm ps} \times 5000 / N_\omega}\) where \(\chi^2_{\rm ps}\) is the pseudo chi-squared value of the fit and \(N_\omega\) is the number of excitation frequencies. This approximation assumes that the error is spread evenly across the real and imaginary parts of the immittance spectrum.

References:

Return type:

float

get_frequencies(num_per_decade=-1)

Get an array of frequencies within the range of tested frequencies.

Parameters:

num_per_decade (int, optional) – If the value is greater than zero, then logarithmically distributed frequencies will be generated within the range of tested frequencies.

Return type:

Frequencies

get_impedances(num_per_decade=-1)

Get the complex impedances produced by the fitted circuit within the range of tested frequencies.

Parameters:

num_per_decade (int, optional) – If the value is greater than zero, then logarithmically distributed frequencies will be generated within the range of tested frequencies and used to calculate the impedance produced by the fitted circuit.

Return type:

Frequencies

get_label()

Generate a label for the result.

Return type:

str

get_log_F_ext()

Get the value of \(\log{F_{\rm ext}}\), which affects the range of time constants.

Return type:

float

get_nyquist_data(num_per_decade=-1)

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

Parameters:

num_per_decade (int, optional) – If the value is greater than zero, then logarithmically distributed frequencies will be generated within the range of tested frequencies and used to calculate the impedance produced by the fitted circuit.

Return type:

Tuple[Impedances, Impedances]

get_parallel_capacitance()

Get the value of the parallel capacitance (or numpy.nan if not included in the circuit).

Return type:

float

get_parallel_inductance()

Get the value of the parallel inductance (or numpy.nan if not included in the circuit).

Return type:

float

get_parallel_resistance()

Get the value of the parallel resistance.

Return type:

float

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]

get_series_capacitance()

Get the value of the series capacitance (or numpy.nan if not included in the circuit).

Return type:

float

get_series_inductance()

Get the value of the series inductance (or numpy.nan if not included in the circuit).

Return type:

float

get_series_resistance()

Get the value of the series resistance.

Return type:

float

get_time_constants()

Get the time constants that were used during fitting.

Return type:

TimeConstants

perform_kolmogorov_smirnov_test(standard_deviation=0.0)

Perform one-sample Kolmogorov-Smirnov test on the residuals of the real and imaginary parts. The residuals are tested against a normal distribution with a mean that is assumed to be zero and a standard deviation that can either be provided or estimated automatically.

Parameters:

standard_deviation (float, optional) – If greater than zero, then the provided value is used. Otherwise, the standard deviation estimated based on the pseudo chi-squared and the number of frequencies is used.

Returns:

The p-values for the tests performed on the residuals of the real and imaginary parts. The null hypothesis is that the distributions of the residuals are identical to the normal distribution with a mean of zero and the provided (or estimated) standard deviation.

Return type:

Tuple[float, float]

perform_lilliefors_test()

Perform the Lilliefors test for normality on the residuals of the real and imaginary parts.

Returns:

The p-values for the tests performed on the residuals of the real and imaginary parts. The null hypothesis is that the residuals come from a normal distribution.

Return type:

Tuple[float, float]

perform_shapiro_wilk_test()

Perform the Shapiro-Wilk test for normality on the residuals of the real and imaginary parts.

Returns:

The p-values for the tests performed on the residuals of the real and imaginary parts. The null hypothesis is that the residuals come from a normal distribution.

Return type:

Tuple[float, float]

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(extended_statistics=3)

Get the statistics related to the test as a `pandas.DataFrame`_ object.

Parameters:

extended_statistics (int, optional) –

Include different amounts of additional statistics depending on the chosen level. Level 1 includes:

  • The estimated equivalent standard deviation of a Gaussian noise calculated based on the pseudo chi-squared value assuming that the noise in the real and imaginary parts of the impedance are independent, have a Gaussian distribution, a mean of zero, and the same standard deviation.

  • The means of the real and imaginary residuals.

  • The sample standard deviations of the real and imaginary residuals.

  • The percentage of points found within 1, 2, or 3 standard deviations.

Level 2 includes:

  • The p-values of normality tests performed on the real or imaginary residuals. These tests include: Lilliefors and Shapiro-Wilk.

Level 3 includes:

  • The p-values for one-sample Kolmogorov-Smirnov tests comparing the real or imaginary residuals against a normal distribution with a mean of zero and a standard deviation (as a percentage of \(|Z|\)) equal to the approximation obtained with \({\rm SD}_{\rm est} \approx \sqrt{\chi^2_{\rm ps} \times 5000 / N_\omega}\) where \(\chi^2_{\rm ps}\) is the pseudo chi-squared value of the fit and \(N_\omega\) is the number of excitation frequencies. This approximation assumes that the error is spread evenly across the real and imaginary parts of the immittance spectrum.

Return type:

`pandas.DataFrame`_

class deareis.KramersKronigSettings(test, mode, representation, add_capacitance, add_inductance, num_RC, min_log_F_ext, max_log_F_ext, log_F_ext, num_F_ext_evaluations, rapid_F_ext_evaluations, cnls_method, max_nfev, timeout, suggestion_settings)

A class to store the settings used to perform a Kramers-Kronig test.

Parameters:

  • test (KramersKronigTest) – The type of test to perform: complex, real, imaginary, or CNLS. See pyimpspec and its documentation for details about the different types of tests.

  • mode (KramersKronigMode) – How to perform the test: automatic, exploratory, or manual. The automatic mode uses one or more methods to determine a suitable number of RC circuits. The exploratory mode is similar to the automatic mode except the user is allowed to choose which of the results to accept, which can help with avoiding false positives or false negatives. The manual mode requires the user to pick the number of RC circuits.

  • representation (KramersKronigRepresentation) – Use a specific representation of the immittance data for validation or automatically select one.

  • add_capacitance (bool) – Add a capacitance in series or in parallel when validating impedance or admittance data, respectively.

  • add_inductance (bool) – Add an inductance in series or in parallel when validating impedance or admittance data, respectively.

  • num_RC (int) – The (maximum) number of RC circuits.

  • min_log_F_ext (float) – The lower limit for log Fext values to evaluate during optimization.

  • max_log_F_ext (float) – The upper limit for log Fext values to evaluate during optimization.

  • log_F_ext (float) – The log Fext value to use if the number of Fext evluations is set to zero.

  • num_F_ext_evaluations (int) – The number of evaluations to perform when automatically determining the number of decades to extend the range of time constants in both directions.

  • rapid_F_ext_evaluations (bool) – Reduce the time spent optimizing Fext by evaluating a narrower range of RC elements.

  • cnls_method (CNLSMethod) – The iterative method to use if the CNLS test is chosen.

  • max_nfev (int) – The maximum number of function evaluations to use if the CNLS test is chosen.

  • timeout (int) – The number of seconds to wait for a single fit to be performed.

  • suggestion_settings (KramersKronigSuggestionSettings) – The settings used to define how to suggest the optimum number of RC elements.

classmethod from_dict(dictionary)

Create an instance from a dictionary.

Parameters:

dictionary (dict)

Return type:

KramersKronigSettings

to_dict()

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

Return type:

dict

class deareis.KramersKronigSuggestionSettings(methods, use_mean, use_ranking, use_sum, lower_limit, upper_limit, limit_delta, m1_mu_criterion, m1_beta)

Singleton that is used to maintain the exploratory window’s settings while DearEIS is running.

methods: List[int]

The 1-based identifiers of suggestion methods: - 1: mu-criterion (modified) - 2: norm of fitted variables - 3: norm of curvatures - 4: number of sign changes in curvatures - 5: mean distance between sign changes in curvatures - 6: log(sum(tau_k/var_k)) inflection point

use_mean: bool

Use the mean of the number of RC elements suggested by different methods.

use_ranking: bool

Let the different methods rank the number of RC elements, assign scores, and pick the highest-scoring number of RC elements.

use_sum: bool

Add the score from each method together and pick the highest-scoring number of RC elements.

lower_limit: int

If greater than zero, then this value is used as the lower limit instead of trying to estimate the lower limit algorithmically.

upper_limit: int

If greater than zero, then this value is used as the upper limit instead of trying to estimate the upper limit algorithmically.

limit_delta: int

The upper limit can also be defined as the lower limit plus some delta.

m1_mu_criterion: float

The threshold value used in the method described by Schönleber et al. (2014).

m1_beta: float

The exponent that affects the penalty imposed based on the distance between \({\rm \mu}\)-criterion and \({\rm \mu}\) in the score calculated as part of the modified \({\rm \mu}\)-criterion method.

Parameters:

  • methods (List[int])

  • use_mean (bool)

  • use_ranking (bool)

  • use_sum (bool)

  • lower_limit (int)

  • upper_limit (int)

  • limit_delta (int)

  • m1_mu_criterion (float)

  • m1_beta (float)

Enums

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

Iterative methods used during complex non-linear least-squares fitting:

  • AUTO: try each method

  • BFGS

  • CG

  • LBFGSB

  • LEASTSQ

  • LEAST_SQUARES

  • NELDER

  • POWELL

  • SLSQP

  • TNC

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

Types of modes that determine how the number of RC elements is chosen:

  • AUTO: automatically suggest the number of using the selected method(s)

  • EXPLORATORY: same procedure as AUTO but present intermediate results to user

  • MANUAL: manually choose the number

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

  • AUTO: Automatically suggest the most suitable immittance representation

  • IMPEDANCE

  • ADMITTANCE

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

Types of Kramers-Kronig tests:

  • CNLS: complex non-linear least-squares fit of circuit (fig. 1, Boukamp, 1995) with a distribution of fixed time constants

  • COMPLEX: eqs. 11 and 12, Boukamp, 1995

  • IMAGINARY: eqs. 4, 6, and 7, Boukamp, 1995

  • REAL: eqs. 5, 8, 9, and 10, Boukamp, 1995

The _LEASTSQ variants use numpy.linalg.lstsq instead of pseudo-inverse matrices.