Add posterior diagnostics and ECM vectorization tools

doc/_basic_usage.md

@@ -27,6 +27,59 @@ for i, row in circuits.iterrows():
 ae.visualization.print_inference_results(circuits)
 ```
 
+## Posterior quality diagnostics
+
+After Bayesian inference, AutoEIS can score each posterior parameter
+distribution for Gaussian-like behavior. The diagnostic combines Q-Q plot
+linearity, skewness, and KDE mode count, then labels each parameter as
+`Normal`, `Multi-Peak`, `Left-Skewed`, `Right-Skewed`, `Touch-Bound`, or
+`Invalid`.
+
+```python
+result = results[0]
+
+# Return one row per inferred parameter.
+quality = result.assess_posterior_quality(threshold=79)
+print(quality[["parameter", "score", "shape", "status"]])
+
+# The same API is also available as a module-level function.
+quality = ae.diagnostics.assess_posterior_quality(result.mcmc, threshold=79)
+
+# Optional: save KDE + histogram plots for each parameter.
+quality = result.assess_posterior_quality(
+    threshold=79,
+    save_plots=True,
+    save_dir="posterior_quality",
+)
+
+# Add posterior scores back to a circuits dataframe and rank models.
+circuits = ae.diagnostics.add_posterior_quality(circuits, results, threshold=79)
+```
+
+## ECM topology vectors
+
+ECM topology utilities are available from `ae.ecm`. They operate on the same
+AutoEIS circuit strings, but produce normalized topology trees and compact
+vectors for tracking or comparing model structure.
+
+```python
+circuit = "R1-[P2,R3]-C4"
+
+# Simplify mergeable R/C/L branches without changing the existing parser API.
+simplified = ae.ecm.simplify_ecm("R1-R2-[C1-C2,R3]-R4")
+
+# Convert ECM topology to an integer vector and back.
+ecm_vector = ae.ecm.ecm_to_vector(circuit)
+roundtrip = ae.ecm.vector_to_ecm(ecm_vector)
+
+# Convert numeric EIS values with matching series/parallel syntax.
+eis_vector = ae.ecm.eis_to_vector("10-[2.5,30]-1e-6")
+values = ae.ecm.extract_eis_values(eis_vector)
+
+# Add vectors to a circuits dataframe.
+circuits = ae.ecm.add_ecm_vectors(circuits)
+```
+
 :::{seealso}
 While the above example should work out of the box, it is recommended to use AutoEIS in a step by step fashion to have more control over the analysis process. Furthermore, you'll learn more about the inner workings of AutoEIS this way. An example notebook that demonstrates how to use AutoEIS in more details can be found [here](https://github.com/AUTODIAL/AutoEIS/blob/develop/examples/autoeis_demo.ipynb).
 :::

doc/modules.rst

@@ -3,7 +3,9 @@
 API Reference
 #############
 
-AutoEIS contains five modules: ``io`` for reading and writing data, ``core`` for finding the best fit and performing the analysis, ``visualization`` for plotting, ``utils`` for helper functions used in ``core``, and ``parser`` for parsing circuit strings.
+AutoEIS contains modules for reading and writing data, finding the best fit
+and performing the analysis, posterior diagnostics, ECM topology tools,
+plotting, helper utilities, and parsing circuit strings.
 
 .. automodule:: autoeis
 
@@ -13,6 +15,8 @@ AutoEIS contains five modules: ``io`` for reading and writing data, ``core`` for
 
       autoeis.io
       autoeis.core
+      autoeis.diagnostics
+      autoeis.ecm
       autoeis.visualization
       autoeis.utils
       autoeis.parser

pyproject.toml

@@ -46,6 +46,7 @@ dependencies = [
     "pyparsing>=3",
     "rich",
     "scikit-learn>=1.4",
+    "scipy",
     "seaborn",
     "tqdm",
     "numexpr",

src/autoeis/__init__.py

@@ -26,7 +26,16 @@ def _setup_logger():
 config = _Settings()
 _setup_logger()
 
-from . import core, io, metrics, parser, utils, visualization  # noqa: F401, E402
+from . import (  # noqa: F401, E402
+    core,
+    diagnostics,
+    ecm,
+    io,
+    metrics,
+    parser,
+    utils,
+    visualization,
+)
 from .core import *  # noqa: E402
 from .version import __equivalent_circuits_jl_version__, __version__  # noqa: F401, E402
 from .visualization import rich_print  # noqa: F401, E402