Kramers-Kronig testing

deareis.perform_exploratory_tests(data, settings, num_procs=0)

Wrapper for the pyimpspec.perform_exploratory_tests function.

Performs a batch of linear Kramers-Kronig tests, which are then scored and sorted from best to worst before they are returned.

Parameters:

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

  • settings (TestSettings) – The settings that determine how the test is performed. Note that only Test.EXPLORATORY is supported by this function.

  • num_procs (int, optional) – See perform_test for details.

Return type:

List[TestResult]

deareis.perform_test(data, settings, num_procs=0)

Wrapper for the pyimpspec.perform_test function.

Performs a linear Kramers-Kronig test as described by Boukamp (1995). The results can be used to check the validity of an impedance spectrum before performing equivalent circuit fitting. If the number of (RC) circuits is less than two, then a suitable number of (RC) circuits is determined using the procedure described by Schönleber et al. (2014) based on a criterion for the calculated \({\rm \mu}\) (0.0 to 1.0). A \({\rm \mu}\) of 1.0 represents underfitting and a \({\rm \mu}\) of 0.0 represents overfitting.

References:

Parameters:

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

  • settings (TestSettings) – The settings that determine how the test is performed. Note that Test.EXPLORATORY is not supported by this function.

  • num_procs (int, optional) – The maximum number of parallel processes to use when performing a test. A value less than 1 will result in an attempt to automatically figure out a suitable value. Applies only to the TestMode.CNLS test.

Return type:

TestResult

Classes

class deareis.TestResult(uuid, timestamp, circuit, num_RC, mu, 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.

  • num_RC (int) – The final number of parallel RC circuits connected in series.

  • mu (float) – The \({\rm \mu}\) that was calculated for the result (eq. 21 in Schönleber et al., 2014).

  • 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 (TestSettings) – The settings that were used to perform the test.

calculate_score(mu_criterion)

Calculate a score based on the provided \({\rm \mu}\)-criterion and the statistics of the result. A result with a \({\rm \mu}\) greater than or equal to the \({\rm \mu}\)-criterion will get a score of -numpy.inf.

Parameters:

mu_criterion (float) – The \({\rm \mu}\)-criterion to apply. See perform_test for details.

Return type:

float

classmethod from_dict(dictionary, data=None)

Create an instance from a dictionary.

Parameters:

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

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

Return type:

TestResult

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_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_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_residuals_data()

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

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

to_dict(session)

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

Parameters:

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

Return type:

dict

to_statistics_dataframe()

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

Return type:

DataFrame

class deareis.TestSettings(test, mode, num_RC, mu_criterion, add_capacitance, add_inductance, method, max_nfev)

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

Parameters:

  • test (Test) – 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 (TestMode) – How to perform the test: automatic, exploratory, or manual. The automatic mode uses the procedure described by Schönleber et al. (2014) to determine a suitable number of parallel RC circuits connected in series. The exploratory mode is similar to the automatic mode except the user is allowed to choose which of the results to accept and the initial suggestion has additional weighting applied to it in an effort to reduce false negatives that would lead to the conclusion that the data is invalid. The manual mode requires the user to pick the number of parallel RC circuits connected in series.

  • num_RC (int) – The (maximum) number of parallel RC circuits connected in series.

  • mu_criterion (float) – The threshold value used in the procedure described by Schönleber et al. (2014).

  • add_capacitance (bool) – Add a capacitance in series to the Voigt circuit.

  • add_inductance (bool) – Add an inductance in series to the Voigt circuit.

  • 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.

classmethod from_dict(dictionary)

Create an instance from a dictionary.

Parameters:

dictionary (dict) –

Return type:

TestSettings

to_dict()

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

Return type:

dict

Enums

class deareis.CNLSMethod(value, names=None, *, 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.Test(value, names=None, *, 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

class deareis.TestMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Types of modes that determine how the number of Voigt elements (capacitor connected in parallel with resistor) is chosen:

  • AUTO: follow procedure described by Schönleber, Klotz, and Ivers-Tiffée (2014)

  • EXPLORATORY: same procedure as AUTO but present intermediate results to user and apply additional weighting to the initial suggestion

  • MANUAL: manually choose the number