Merge pull request #84 from ImperialCollegeLondon/add-input-validation

Major code refactoring and documentation improvements
ImperialCollegeLondon · Aug 2, 2024 · 45ee5ac · 45ee5ac
2 parents a3bbb61 + 7b49ea1
commit 45ee5ac
Show file tree

Hide file tree

Showing 135 changed files with 5,539 additions and 5,937,294 deletions.
diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml
@@ -22,10 +22,11 @@ jobs:
       run: |
         pip install -U pip
         pip install -r requirements-dev.txt
+        pip install ipykernel
     
     - name: Run sphinx-apidoc
       run: |
-        sphinx-apidoc -f -e -M -o docs/source/ pyprobe
+        sphinx-apidoc -f -e -M -o docs/source/api pyprobe
 
     - name: Add bibliographies
       run: |

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -28,3 +28,7 @@ repos:
     hooks:
       - id: markdownlint
         args: ["--disable", "MD013"]
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.7.1
+    hooks:
+      - id: nbstripout
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -32,8 +32,8 @@ Additions to the code should be made in accordance with the structure of PyProBE
 maximise compatibility and ensure it is a maintainable package. Guidance for writing
 code for PyProBE includes:
 1. DataFrame operations should only be done using polars expressions. Data should be kept by default in polars LazyFrame format and only converted to DataFrame if needed for a particular operation.
-2. Method classes should be written in the format described in the [documentation](
-    https://congenial-adventure-mz797n5.pages.github.io/creating_a_new_method.html
+2. Analysis classes should be written in the format described in the [documentation](
+    https://congenial-adventure-mz797n5.pages.github.io/contributing_to_the_analysis_module.html
 ).
 
 ## Viewing the API documentation

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ PyProBE is designed to:
 - Host a library of post-processing methods
 
 ## Installing PyProBE
-Please follow the [user installation guide](https://congenial-adventure-mz797n5.pages.github.io/installation.html) to install PyProBE.
+Please follow the [user installation guide](https://congenial-adventure-mz797n5.pages.github.io/user_guide/installation.html) to install PyProBE.
 
 ## Getting Started with PyProBE
 PyProBE should be imported as a package into an external post-processing script or jupyter notebook.
@@ -35,29 +35,29 @@ cell.procedure['Reference Test'].experiment('Discharge Pulses').cycle(3).dischar
 ```
 
 The PyProBE Dashboard can be launched on a list of ```Cell``` objects to allow rapid data exploration and plotting:
-![PyProBE Dashboard](./docs/source/images/Dashboard.png)
+![PyProBE Dashboard](./docs/source/user_guide/images/Dashboard.png)
 
 See the [documentation](https://congenial-adventure-mz797n5.pages.github.io) for a detailed user guide. Start with the following pages to get PyProBE set up with your data:
-- [Importing data](https://congenial-adventure-mz797n5.pages.github.io/importing_data.html)
-- [Accessing data](https://congenial-adventure-mz797n5.pages.github.io/accessing_data.html)
-- [Plotting](https://congenial-adventure-mz797n5.pages.github.io/plotting.html)
+- [Importing data](https://congenial-adventure-mz797n5.pages.github.io/user_guide/importing_data.html)
+- [Accessing data](https://congenial-adventure-mz797n5.pages.github.io/user_guide/accessing_data.html)
+- [Plotting](https://congenial-adventure-mz797n5.pages.github.io/user_guide/plotting.html)
 
-You can find example notebooks in the [examples folder](examples/).
+You can find example notebooks in the [examples folder](docs/source/examples/).
 
 ## Input data guidelines
-PyProBE works with numerous cyclers. For guidance on how to export your data to work with PyProBE see the [Input Data Guidance](https://congenial-adventure-mz797n5.pages.github.io/input_data_guidance.html).
+PyProBE works with numerous cyclers. For guidance on how to export your data to work with PyProBE see the [Input Data Guidance](https://congenial-adventure-mz797n5.pages.github.io/user_guide/input_data_guidance.html).
 
 The PyProBE workflow encourages thorough documentation of experimental data. For guidance please see:
-- [README file guidelines](https://congenial-adventure-mz797n5.pages.github.io/writing_a_readme_file.html)
-- [Experiment record guidelines](https://congenial-adventure-mz797n5.pages.github.io/writing_an_experiment_record.html#)
+- [README file guidelines](https://congenial-adventure-mz797n5.pages.github.io/user_guide/writing_a_readme_file.html)
+- [Experiment record guidelines](https://congenial-adventure-mz797n5.pages.github.io/user_guide/writing_an_experiment_record.html)
 
 ## Data Analysis Tools
 PyProBE provides easy access to tools for further analysis of battery data, including:
 - Capacity loss calculation during cycling
 - dQ/dV on OCV data
 - OCV fitting and Degradation Mode Analysis (DMA)
 
-PyProBE's [Method](https://congenial-adventure-mz797n5.pages.github.io/creating_a_new_method.html) framework allows new data analysis tools to be added quickly and easily.
+PyProBE's [analysis](https://congenial-adventure-mz797n5.pages.github.io/developer_guide/contributing_to_the_analysis_module.html) framework allows new data analysis tools to be added quickly and easily.
 
 ## Contributing to PyProBE
 

diff --git a/docs/source/modules.rst → docs/source/api/modules.rst b/docs/source/modules.rst → docs/source/api/modules.rst
diff --git a/docs/source/api/pyprobe.analysis.base.degradation_mode_analysis_functions.rst b/docs/source/api/pyprobe.analysis.base.degradation_mode_analysis_functions.rst
@@ -0,0 +1,10 @@
+pyprobe.analysis.base.degradation\_mode\_analysis\_functions module
+===================================================================
+
+.. automodule:: pyprobe.analysis.base.degradation_mode_analysis_functions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/api/pyprobe.analysis.base.differentiation_functions.rst b/docs/source/api/pyprobe.analysis.base.differentiation_functions.rst
@@ -0,0 +1,10 @@
+pyprobe.analysis.base.differentiation\_functions module
+=======================================================
+
+.. automodule:: pyprobe.analysis.base.differentiation_functions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/api/pyprobe.analysis.base.rst b/docs/source/api/pyprobe.analysis.base.rst
@@ -0,0 +1,19 @@
+pyprobe.analysis.base package
+=============================
+
+.. automodule:: pyprobe.analysis.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pyprobe.analysis.base.degradation_mode_analysis_functions
+   pyprobe.analysis.base.differentiation_functions
+
+
+.. footbibliography::
diff --git a/docs/source/pyprobe.experiments.pOCV.rst → docs/source/api/pyprobe.analysis.cycling.rst b/docs/source/pyprobe.experiments.pOCV.rst → docs/source/api/pyprobe.analysis.cycling.rst
@@ -1,7 +1,7 @@
-pyprobe.experiments.pOCV module
+pyprobe.analysis.cycling module
 ===============================
 
-.. automodule:: pyprobe.experiments.pOCV
+.. automodule:: pyprobe.analysis.cycling
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/source/api/pyprobe.analysis.degradation_mode_analysis.rst b/docs/source/api/pyprobe.analysis.degradation_mode_analysis.rst
@@ -0,0 +1,10 @@
+pyprobe.analysis.degradation\_mode\_analysis module
+===================================================
+
+.. automodule:: pyprobe.analysis.degradation_mode_analysis
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/...ource/pyprobe.methods.ocv_fitting.DMA.rst → .../api/pyprobe.analysis.differentiation.rst b/...ource/pyprobe.methods.ocv_fitting.DMA.rst → .../api/pyprobe.analysis.differentiation.rst
@@ -1,7 +1,7 @@
-pyprobe.methods.ocv\_fitting.DMA module
+pyprobe.analysis.differentiation module
 =======================================
 
-.. automodule:: pyprobe.methods.ocv_fitting.DMA
+.. automodule:: pyprobe.analysis.differentiation
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/source/api/pyprobe.analysis.pulsing.rst b/docs/source/api/pyprobe.analysis.pulsing.rst
@@ -0,0 +1,10 @@
+pyprobe.analysis.pulsing module
+===============================
+
+.. automodule:: pyprobe.analysis.pulsing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/api/pyprobe.analysis.rst b/docs/source/api/pyprobe.analysis.rst
@@ -0,0 +1,31 @@
+pyprobe.analysis package
+========================
+
+.. automodule:: pyprobe.analysis
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pyprobe.analysis.base
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pyprobe.analysis.cycling
+   pyprobe.analysis.degradation_mode_analysis
+   pyprobe.analysis.differentiation
+   pyprobe.analysis.pulsing
+   pyprobe.analysis.smoothing
+   pyprobe.analysis.utils
+
+
+.. footbibliography::
diff --git a/docs/source/pyprobe.methods.basemethod.rst → ...source/api/pyprobe.analysis.smoothing.rst b/docs/source/pyprobe.methods.basemethod.rst → ...source/api/pyprobe.analysis.smoothing.rst
@@ -1,7 +1,7 @@
-pyprobe.methods.basemethod module
+pyprobe.analysis.smoothing module
 =================================
 
-.. automodule:: pyprobe.methods.basemethod
+.. automodule:: pyprobe.analysis.smoothing
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/source/api/pyprobe.analysis.utils.rst b/docs/source/api/pyprobe.analysis.utils.rst
@@ -0,0 +1,10 @@
+pyprobe.analysis.utils module
+=============================
+
+.. automodule:: pyprobe.analysis.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/pyprobe.cell.rst → docs/source/api/pyprobe.cell.rst b/docs/source/pyprobe.cell.rst → docs/source/api/pyprobe.cell.rst
diff --git a/docs/source/pyprobe.cyclers.basecycler.rst → ...source/api/pyprobe.cyclers.basecycler.rst b/docs/source/pyprobe.cyclers.basecycler.rst → ...source/api/pyprobe.cyclers.basecycler.rst
diff --git a/docs/source/pyprobe.cyclers.biologic.rst → docs/source/api/pyprobe.cyclers.biologic.rst b/docs/source/pyprobe.cyclers.biologic.rst → docs/source/api/pyprobe.cyclers.biologic.rst
diff --git a/docs/source/pyprobe.cyclers.neware.rst → docs/source/api/pyprobe.cyclers.neware.rst b/docs/source/pyprobe.cyclers.neware.rst → docs/source/api/pyprobe.cyclers.neware.rst
diff --git a/docs/source/pyprobe.cyclers.rst → docs/source/api/pyprobe.cyclers.rst b/docs/source/pyprobe.cyclers.rst → docs/source/api/pyprobe.cyclers.rst
diff --git a/docs/source/pyprobe.dashboard.rst → docs/source/api/pyprobe.dashboard.rst b/docs/source/pyprobe.dashboard.rst → docs/source/api/pyprobe.dashboard.rst
diff --git a/docs/source/api/pyprobe.filters.rst b/docs/source/api/pyprobe.filters.rst
@@ -0,0 +1,10 @@
+pyprobe.filters module
+======================
+
+.. automodule:: pyprobe.filters
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/pyprobe.plot.rst → docs/source/api/pyprobe.plot.rst b/docs/source/pyprobe.plot.rst → docs/source/api/pyprobe.plot.rst
diff --git a/docs/source/pyprobe.rawdata.rst → docs/source/api/pyprobe.rawdata.rst b/docs/source/pyprobe.rawdata.rst → docs/source/api/pyprobe.rawdata.rst
diff --git a/docs/source/pyprobe.result.rst → docs/source/api/pyprobe.result.rst b/docs/source/pyprobe.result.rst → docs/source/api/pyprobe.result.rst
diff --git a/docs/source/pyprobe.rst → docs/source/api/pyprobe.rst b/docs/source/pyprobe.rst → docs/source/api/pyprobe.rst
@@ -12,9 +12,8 @@ Subpackages
 .. toctree::
    :maxdepth: 4
 
+   pyprobe.analysis
    pyprobe.cyclers
-   pyprobe.experiments
-   pyprobe.methods
 
 Submodules
 ----------
@@ -24,12 +23,12 @@ Submodules
 
    pyprobe.cell
    pyprobe.dashboard
-   pyprobe.filter
+   pyprobe.filters
    pyprobe.plot
-   pyprobe.procedure
    pyprobe.rawdata
    pyprobe.result
-   pyprobe.unitconverter
+   pyprobe.typing
+   pyprobe.units
 
 
 .. footbibliography::
diff --git a/docs/source/pyprobe.filter.rst → docs/source/api/pyprobe.typing.rst b/docs/source/pyprobe.filter.rst → docs/source/api/pyprobe.typing.rst
@@ -1,7 +1,7 @@
-pyprobe.filter module
+pyprobe.typing module
 =====================
 
-.. automodule:: pyprobe.filter
+.. automodule:: pyprobe.typing
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/source/api/pyprobe.units.rst b/docs/source/api/pyprobe.units.rst
@@ -0,0 +1,10 @@
+pyprobe.units module
+====================
+
+.. automodule:: pyprobe.units
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -24,16 +24,27 @@
     "sphinx_tabs.tabs",
     "sphinxcontrib.bibtex",
     "sphinx_design",
+    "nbsphinx",
 ]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 html_theme = "pydata_sphinx_theme"
 html_theme_options = {"collapse_navigation": True, "show_nav_level": 4}
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_default_options = {
+    "exclude-members": "model_computed_fields, model_config, model_fields, Config",
+}
 
 # -- sphinxcontrib-bibtex configuration --------------------------------------
 bibtex_bibfiles = ["../../CITATIONS.bib"]
 bibtex_style = "unsrt"
 bibtex_footbibliography_header = """.. rubric:: References"""
 bibtex_reference_style = "author_year"
 bibtex_tooltips = True
+
+# -- nbsphinx configuration --------------------------------------------------
+autosummary_generate = True
+nbsphinx_execute = "always"  # Always execute notebooks
+nbsphinx_allow_errors = True  # Raise exceptions when notebooks raise errors
diff --git a/docs/source/creating_a_new_method.rst b/docs/source/creating_a_new_method.rst