Merged dev-5-0-0-rc branch

.github/workflows/test-package.yml

@@ -13,7 +13,7 @@ jobs:
       fail-fast: false
       matrix:
         os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
-        python-version: ['3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12']
 
     steps:
     - uses: actions/checkout@v4

.github/workflows/test-wheel.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12']
 
     steps:
     - uses: actions/checkout@v4

CHANGELOG.md

@@ -1,3 +1,163 @@
+# 5.0.0 (2024/08/29)
+
+**THIS UPDATE CONTAINS SEVERAL CHANGES THAT ARE NOT BACKWARDS COMPATIBLE WITH CODE WRITTEN USING VERSION 4.x!**
+**SOME OF THE ARGUMENTS IN THE COMMAND LINE INTERFACE HAVE ALSO CHANGED OR BEEN REMOVED!**
+
+
+### Linear Kramers-Kronig tests
+
+- Renamed the `TestResult` class to `KramersKronigResult`.
+- Renamed the `perform_test` function to `perform_kramers_kronig_test`.
+- Removed the `perform_exploratory_tests` function. The `pyimpspec.analysis.kramers_kronig.evaluate_log_F_ext` function should be used instead.
+- The `complex`, `real`, and `imaginary` tests now use`numpy.linalg.lstsq`. The previous implementations based on matrix inversion are now accessible by appending `-inv` (e.g., `complex-inv`).
+- Updated the `perform_test` and `perform_exploratory_tests` function signatures (e.g., `test='real'`, `add_capacitance=True`, and `add_inductance=True` are now the new defaults).
+- Replaced the `--add-capacitance` and `--add-inductance` CLI arguments with `--no-capacitance` and `--no-inductance`. They new arguments have the same abbreviated forms, which means that `-C` and `-L` now have the opposite effect compared to previously.
+- Added a variant of the mu-criterion algorithm that fits a logistic function to the mu-values (accessible via negative mu-criterion values).
+- Added a `suggest_num_RC` function for suggesting the optimum number of RC elements to use when performing linear Kramers-Kronig tests:
+    - Estimates the lower and upper limits for the range of numbers of RC elements to avoid under- and overfitting.
+    - Uses one or more methods/algorithms for suggesting the optimum number of RC elements:
+      - Method 1 (https://doi.org/10.1016/j.electacta.2014.01.034)
+      - Method 2 (https://doi.org/10.1109/IWIS57888.2022.9975131)
+      - Method 3 (https://doi.org/10.1109/IWIS57888.2022.9975131)
+      - Method 4 (https://doi.org/10.1109/IWIS57888.2022.9975131)
+      - Method 5 (https://doi.org/10.1016/j.electacta.2024.144951)
+      - Method 6 (https://doi.org/10.1016/j.electacta.2024.144951)
+    - Defaults to an approach that uses methods 4, 3, and 5 (in that order) to narrow the list of options.
+    - Multiple methods can be combined in different ways:
+      - mean of the suggested values
+      - sum of scores obtained based on rankings
+      - sum of relative scores
+- Added support for performing linear Kramers-Kronig tests on the admittance representation:
+  - Added `KramersKronigAdmittanceRC` element to represent the series RC element used in the equivalent circuit model.
+  - Added a boolean `admittance` attribute to the `TestResult` class.
+  - Added `get_parallel_resistance`, `get_parallel_capacitance`, and `get_parallel_inductance` methods to the `TestResult` class.
+  - Added a variant of the mu-criterion algorithm that uses capacitance values instead of resistance values when operating on the admittance representation.
+- Added `suggest_representation` function for suggesting either the impedance or admittance representation to use.
+- Added `evaluate_time_constant_extensions` function for optimizing the extension of the range of time constants.
+- Added the following arguments to the CLI:
+  - `--admittance` and `--impedance` to only perform tests on the admittance and impedance representation, respectively.
+  - `--suggestion-methods` to selecting one or more methods for suggesting the optimum number of RC elements.
+  - `--mean`, `--ranking`, and `--sum` to specify how to combine multiple methods for suggesting the optimum number of RC elements.
+  - `--num-F-ext-evaluations` to specify the number of evaluations to perform when optimizing the extension of the range of time constants.
+  - `--min-log-F-ext` and `--max-log-F-ext` to specify the lower and upper limits for the number of decades to extend the range of time constants when `--num-F-ext-evaluations` is set to something else than zero.
+  - `--log-F-ext` to specify the number of decades to extend the range of time constants when `--num-F-ext-evaluations` is set to zero.
+  - `--no-rapid-F-ext-evaluations` to evaluate the full range of the number of time constants at each sampled extension of the range of time constants.
+  - `--lower-limit`/`--upper-limit` to specify the lower/upper limit for the optimum number of RC elements to suggest.
+  - `--limit-delta` as an alternative way of specifying the limits of the range of optimum number of RC elements to suggest.
+  - `--plot-immittance` to automatically plot the corresponding immittance representation that was used when performing the linear Kramers-Kronig test.
+  - `--plot-pseudo-chi-squared` to override the plot when a single suggestion method has been chosen.
+  - `--plot-moving-average-width` to plot the moving averages of the residuals (the number of points must be provided).
+  - `--plot-estimated-noise` to include the estimated standard deviation of the noise.
+  - `--plot-log-F-ext-3d` and `--plot-log-F-ext-2d` to plot the pseudo chi-squared values as a function of the number of time constants and the extension of the range of time constants.
+  - `--plot-auto-limited-residuals` to automatically adjust the limits of the y-axes when plotting the relative residuals.
+- Added utility functions for subdividing frequency ranges and for calculating the curvatures of impedance spectra.
+- Updated the `perform_test` function to make use of the `perform_exploratory_tests`, `suggest_num_RC`, and `suggest_representation` functions.
+- Refactored the `perform_exploratory_tests` function to only perform tests with different numbers of RC elements.
+- Removed the `--automatic` argument from the CLI.
+- Updated the CLI to use similar plots both for exploratory results and when manually selecting a number of RC elements.
+- Removed the `mu` attribute from the `TestResult` class.
+- Fixed a bug in calculation of mu values that caused the series resistance to be included.
+- Some functions are no longer available the top level of the package and must instead be accessed via the `pyimpspec.analysis.kramers_kronig` module.
+
+
+### Z-HIT analysis
+
+- Added support for performing Z-HIT analysis on admittance data.
+- Added a CLI argument for performing analyses on admittance data (`--admittance` or `-A`).
+- Added two smoothing algorithms (https://doi.org/10.1021/acsmeasuresciau.1c00054):
+  - `whithend`: Whittaker-Henderson
+  - `modsinc`: modified sinc kernel with linear extrapolation
+- Updated the default smoothing algorithm to be `modsinc`.
+- Added title to plot by default when performing analyses via the CLI.
+- Changed `statsmodels` from a required dependency to an optional dependency.
+- Added support for showing a plot of the residuals when using the CLI.
+
+
+### Fitting
+
+- Added an optional `timeout` argument to the `fit_circuit` function that can be used to set a time limit. This can be used to force the fitting process to timeout if it is taking a very long time to finish.
+- Added `--timeout` argument to the CLI.
+- Added `--type` argument to the CLI so that fit results can optionally be plotted as, e.g., just a Nyquist plot.
+
+
+### Distribution of relaxation times
+
+- Updated the TR-RBF implementation to be based off of a newer version of pyDRTtools:
+  - `lambda_value` is now automatically determined using a cross-validation method unless the new `cross_validation` argument is an empty string (i.e., `cross_validation=""`).
+  - If one of the cross-validation methods is chosen, then `lambda_value` is used as the initial value.
+  - The currently supported cross-validation (CV) methods are:
+    - `"gcv"` - generalized cross-validation (GCV)
+    - `"mgcv"` - modified GCV
+    - `"rgcv"` - robust GCV
+    - `"re-im"` - real-imaginary CV
+    - `"lc"` - L-curve
+  - See https://doi.org/10.1149/1945-7111/acbca4 for more information about the CV methods.
+- Removed the `maximum_symmetry` argument from the TR-RBF implementation.
+- Changed how timeouts and progress updates are implemented when the TR-RBF method is called with `credible_intervals=True` and `timeout` is greater than zero.
+- Some functions and classes are no longer available the top level of the package and must instead be accessed via the `pyimpspec.analysis.drt` module.
+
+
+### Plotting
+
+- Added support for plotting admittance data:
+  - The affected plotting functions now have an optional, boolean `admittance` keyword argument.
+- Added a CLI argument for plotting admittance data (`--plot-admittance` or `-pY`).
+- Removed the `mpl.plot_mu_xps` function.
+- Added an `mpl.plot_pseudo_chisqr` function for plotting the pseudo chi-squared values of `TestResult` instances.
+- Updated the `mpl.plot_residuals` function to not use markers by default.
+- Fixed a bug that caused `mpl.plot_residuals` to have empty legend labels when no markers were used.
+- Updated how the limits are automatically determined by the `mpl.plot_residuals` function.
+- Updated how the ticks are determined in the y-axes of the `mpl.plot_residuals` function.
+- Added an `mpl.plot_suggestion` function that visualizes the suggested numbers of RC elements to use for linear Kramers-Kronig testing.
+- Added an `mpl.plot_suggestion_method` function that visualizes the data that is used to suggest the number of RC elements to use for linear Kramers-Kronig testing.
+- Removed support for colored axes from the `mpl.plot_nyquist` function.
+- Updated the `mpl.plot_nyquist` function to switch to using a marker when using `line=True` if all points are approximately the same.
+- Updated how the `--plot-type` CLI argument is handled when plotting, e.g., DRT results.
+- Added an `mpl.show` function that acts as a wrapper for `matplotlib.pyplot.show`.
+- Renamed the `plot_tests` function to `plot_kramers_kronig_tests`.
+- Renamed the `plot_complex` function to `plot_real_imaginary`.
+
+
+### Data parsing
+
+- Added support for parsing ZView/ZPlot `.z` files.
+- Added support for parsing PalmSens `.pssession` files.
+- Added support for two more variants of column headers to parsers that attempt to automatically identify columns.
+- Added support for using `pathlib.Path` in addition to `str` when passing paths to, e.g., the `parse_data` function.
+- Added `--output-indices` argument to the CLI to include zero-based indices in text output.
+- Added `--exclude-indices` argument to the CLI so that specific data points (e.g., outliers) can be excluded based on their zero-based indices.
+- Added `--nth-data-set` argument to the CLI so that one or more data sets can be chosen from a file.
+- Updated parsing of `.dta` files to support parsing the drift corrected impedances when it is available. The returned `List[DataSet]` is sorted so that the drift corrected impedance spectra have a lower index in the list than the uncorrected impedance spectra.
+- Fixed a bug that caused an exception to be raised when parsing a spreadsheet that also contained at least one empty sheet.
+- Fixed a bug that caused NumPy arrays in the dictionary returned by `DataSet.to_dict` to not be compatible with `json.dump` and `json.dumps` from the standard library.
+- Fixed a bug where `DataSet.from_dict` was unable to handle mask dictionaries where the keys were strings instead of integers.
+- Fixed a bug where the keyword arguments provided to `parse_data` were not being passed on to the different format parsers in a specific case.
+- Fixed a bug where detecting columns in files would fail if an otherwise valid column name started with whitespace.
+
+
+### Elements
+
+- Added the ZARC element, which is represented by `Zarc` in circuit description codes.
+- Added a `reset_default_parameter_values` function to reset the default parameter values of either all element types or specific element types.
+- Added `remove_elements` and `reset` functions to the `pyimpspec.circuit.registry` module that can be used to remove user-defined elements, or to remove user-defined elements and reset the default parameter values, respectively.
+- Added an optional `default_only` parameter to the `get_elements` function so that the function can return either all elements (including user-defined elements) or just the elements included in pyimpspec by default. The parameter is set to `False` by default, which means that all elements are returned.
+
+
+### Miscellaneous
+
+- Added `get` and `get_total` methods to the `Progress` class for obtaining the current step and the current total.
+- Added `register_default_handler` and `clear_default_handler_output` functions to the `progress` module.
+- Added mock data for circuit with negative differential resistance.
+- Added mock data for Randles circuit with diffusion.
+- Added noisy variants of mock data.
+- Added a `set_default_values` class method to circuit elements.
+- Refactored code.
+- Updated minimum versions of dependencies and removed support for Python 3.9.
+- Removed cvxpy from the list of supported optional dependencies.
+- Added `canvas` argument to `Circuit.to_drawing` method.
+- Changed some CLI argument names to improve consistency.
+
+
 # 4.1.1 (2024/03/14)
 
 - Maintenance release that updates the version requirements for dependencies.

COPYRIGHT

@@ -1,5 +1,5 @@
 # pyimpspec is licensed under the GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.html).
-# Copyright 2023 pyimpspec developers
+# Copyright 2024 pyimpspec developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by