Distribution of relaxation times analysis

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

Wrapper for the pyimpspec.calculate_drt function.

Calculates the distribution of relaxation times (DRT) for a given data set.

References:

Parameters:

  • data (DataSet) – The data set to use in the calculations.

  • settings (DRTSettings) – The settings to use.

  • num_procs (int, optional) – The maximum number of processes to use. 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.

Return type:

DRTResult

Classes

class deareis.DRTResult(uuid, timestamp, time_constants, real_gammas, imaginary_gammas, frequencies, impedances, residuals, mean_gammas, lower_bounds, upper_bounds, scores, pseudo_chisqr, lambda_value, mask, settings)

An object representing the results of calculating the distribution of relaxation times in a data set.

Parameters:

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

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

  • time_constants (TimeConstants) – The time constants (in seconds).

  • real_gammas (Gammas) – The corresponding gamma values (in ohms).

  • imaginary_gammas (Gammas) – The gamma values calculated based the imaginary part of the impedance data. Only non-empty when the BHT method has been used.

  • frequencies (Frequencies) – The frequencies of the analyzed data set.

  • impedances (ComplexImpedances) – The modeled impedances.

  • residuals (ComplexResiduals) – The residuals for the real and imaginary parts of the modeled impedances.

  • mean_gammas (Gammas) – The mean values for gamma(tau). Only non-empty when the TR-RBF method has been used and the Bayesian credible intervals have been calculated.

  • lower_bounds (Gammas) – The lower bound for the gamma(tau) values. Only non-empty when the TR-RBF method has been used and the Bayesian credible intervals have been calculated.

  • upper_bounds (Gammas) – The upper bound for the gamma(tau) values. Only non-empty when the TR-RBF method has been used and the Bayesian credible intervals have been calculated.

  • scores (Dict[str, complex]) – The scores calculated for the analyzed data set. Only non-empty when the BHT method has been used.

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

  • lambda_value (float) – The regularization parameter used as part of the Tikhonov regularization. Only valid (i.e., positive) when the TR-NNLS or TR-RBF methods have been used.

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

  • settings (DRTSettings) – The settings used to perform this analysis.

classmethod from_dict(dictionary, data=None)

Create an instance from a dictionary.

Parameters:

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

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

Return type:

DRTResult

get_bode_data()

Get the data necessary to plot this DataSet 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_drt_credible_intervals_data()

Get the data necessary to plot the Bayesian credible intervals for this DRTResult: the time constants, the mean gamma values, the lower bound gamma values, and the upper bound gamma values.

Return type:

Tuple[TimeConstants, Gammas, Gammas, Gammas]

get_drt_data()

Get the data necessary to plot this DRTResult as a DRT plot: the time constants and the corresponding gamma values.

Return type:

Tuple[TimeConstants, Gammas, Gammas]

get_frequencies()

Get the frequencies (in hertz) of the data set.

Return type:

Frequencies

get_gammas()

Get the gamma values.

Return type:

Tuple[Gammas, Gammas]

get_impedances()

Get the complex impedance of the model.

Return type:

ComplexImpedances

get_label()

Generate a label for the result.

Return type:

str

get_nyquist_data()

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

Return type:

Tuple[Impedances, Impedances]

get_peaks(threshold=0.0)

Get the time constants (in seconds) and gamma (in ohms) of peaks with magnitudes greater than the threshold. The threshold and the magnitudes are all relative to the magnitude of the highest peak.

Parameters:

threshold (float, optional) – The threshold for the relative magnitude (0.0 to 1.0).

Return type:

Tuple[TimeConstants, Gammas, TimeConstants, Gammas]

get_residuals_data()

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

Return type:

Tuple[Frequencies, Residuals, Residuals]

get_scores()

Get the scores for the data set. The scores are represented as complex values where the real and imaginary parts have magnitudes ranging from 0.0 to 1.0. A consistent impedance spectrum should score high. BHT method only.

Return type:

Dict[str, complex]

get_time_constants()

Get the time constants.

Return type:

TimeConstants

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_peaks_dataframe(threshold=0.0, columns=None)

Get the peaks as a pandas.DataFrame object that can be used to generate, e.g., a Markdown table.

Parameters:

  • threshold (float, optional) – The minimum peak height threshold (relative to the height of the tallest peak) for a peak to be included.

  • columns (Optional[List[str]], optional) – The labels to use as the column headers for real time constants, real gammas, imaginary time constants, and imaginary gammas.

Return type:

DataFrame

to_scores_dataframe(columns=None, rows=None)

Get the scores for the data set as a pandas.DataFrame object that can be used to generate, e.g., a Markdown table. BHT method only.

Parameters:

  • columns (Optional[List[str]], optional) – The labels for the column headers.

  • rows (Optional[List[str]], optional) – The labels for the rows.

Return type:

Optional[pandas.DataFrame]

class deareis.DRTSettings(method, mode, lambda_value, rbf_type, derivative_order, rbf_shape, shape_coeff, inductance, credible_intervals, timeout, num_samples, num_attempts, maximum_symmetry, fit, gaussian_width, num_per_decade, cross_validation_method, tr_nnls_lambda_method)

The settings to use when performing a DRT analysis.

Parameters:

  • method (DRTMethod) – The method to use to perform the analysis.

  • mode (DRTMode) – The mode or type of data (i.e., complex, real, or imaginary) to use. TR-NNLS and TR-RBF methods only.

  • lambda_value (float) – The Tikhonov regularization parameter to use. TR-NNLS and TR-RBF methods only.

  • rbf_type (RBFType) – The radial basis function to use for discretization. BHT and TR-RBF methods only.

  • derivative_order (int) – The derivative order to use when calculating the penalty in the Tikhonov regularization. BHT and TR-RBF methods only.

  • rbf_shape (RBFShape) – The shape to use with the radial basis function discretization. BHT and TR-RBF methods only.

  • shape_coeff (float) – The shape coefficient. BHT and TR-RBF methods only.

  • inductance (bool) – Whether or not to include an inductive term in the calculations. TR-RBF method only.

  • credible_intervals (bool) – Whether or not to calculate Bayesian credible intervals. TR-RBF method only.

  • timeout (int) – The number of seconds to wait for the calculation of credible intervals to complete. TR-RBF method only.

  • num_samples (int) – The number of samples to use when calculating: - the Bayesian credible intervals (TR-RBF method) - the Jensen-Shannon distance (BHT method)

  • num_attempts (int) – The number of attempts to make to find a solution. BHT method only.

  • maximum_symmetry (float) – The maximum vertical peak-to-peak symmetry allowed. Used to discard results with strong oscillations. Smaller values provide stricter conditions. BHT method only.

  • fit (Optional[FitResult]) – The FitResult for a circuit that contains one or more “(RQ)” or “(RC)” elements connected in series. An optional series resistance may also be included. For example, a circuit with a CDC representation of “R(RQ)(RQ)(RC)” would be a valid circuit. m(RQ)fit method only.

  • gaussian_width (float) – The width of the Gaussian curve that is used to approximate the DRT of an “(RC)” element. m(RQ)fit method only.

  • num_per_decade (int) – The number of points per decade to use when calculating a DRT. m(RQ)fit method only.

  • cross_validation_method (CrossValidationMethod) – The cross-validation method used by the TR-RBF method to automatically determine a suitable value for lambda.

  • tr_nnls_lambda_method (TRNNLSLambdaMethod) – The method used by the TR-NNLS method to automatically pick a lambda value

Enums

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

The method to use for calculating the DRT:

  • TR_NNLS

  • TR_RBF

  • BHT

  • MRQ_FIT

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

The parts of the impedance data to use:

  • COMPLEX

  • REAL

  • IMAGINARY

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

The shape to use with the radial basis function discretization:

  • FWHM

  • FACTOR

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

The radial basis function to use for discretization (or piecewise linear discretization):

  • C0_MATERN

  • C2_MATERN

  • C4_MATERN

  • C6_MATERN

  • CAUCHY

  • GAUSSIAN

  • INVERSE_QUADRATIC

  • INVERSE_QUADRIC

  • PIECEWISE_LINEAR