docs: fix errors and typos in documentation

ImperialCollegeLondon · Jan 8, 2025 · 0b71340 · 0b71340
1 parent 97ee45f
commit 0b71340
Show file tree

Hide file tree

Showing 25 changed files with 104 additions and 48 deletions.
diff --git a/docs/source/api/pyprobe.cyclers.arbin.rst b/docs/source/api/pyprobe.cyclers.arbin.rst
@@ -0,0 +1,10 @@
+pyprobe.cyclers.arbin module
+============================
+
+.. automodule:: pyprobe.cyclers.arbin
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/api/pyprobe.cyclers.basytec.rst b/docs/source/api/pyprobe.cyclers.basytec.rst
@@ -0,0 +1,10 @@
+pyprobe.cyclers.basytec module
+==============================
+
+.. automodule:: pyprobe.cyclers.basytec
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/api/pyprobe.cyclers.maccor.rst b/docs/source/api/pyprobe.cyclers.maccor.rst
@@ -0,0 +1,10 @@
+pyprobe.cyclers.maccor module
+=============================
+
+.. automodule:: pyprobe.cyclers.maccor
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/api/pyprobe.cyclers.rst b/docs/source/api/pyprobe.cyclers.rst
@@ -12,8 +12,11 @@ Submodules
 .. toctree::
    :maxdepth: 4
 
+   pyprobe.cyclers.arbin
    pyprobe.cyclers.basecycler
+   pyprobe.cyclers.basytec
    pyprobe.cyclers.biologic
+   pyprobe.cyclers.maccor
    pyprobe.cyclers.neware
 
 

diff --git a/docs/source/api/pyprobe.typing.rst → docs/source/api/pyprobe.logger.rst b/docs/source/api/pyprobe.typing.rst → docs/source/api/pyprobe.logger.rst
@@ -1,7 +1,7 @@
-pyprobe.typing module
+pyprobe.logger module
 =====================
 
-.. automodule:: pyprobe.typing
+.. automodule:: pyprobe.logger
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/source/api/pyprobe.pyprobe_types.rst b/docs/source/api/pyprobe.pyprobe_types.rst
@@ -0,0 +1,10 @@
+pyprobe.pyprobe\_types module
+=============================
+
+.. automodule:: pyprobe.pyprobe_types
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/api/pyprobe.rst b/docs/source/api/pyprobe.rst
@@ -24,12 +24,14 @@ Submodules
    pyprobe.cell
    pyprobe.dashboard
    pyprobe.filters
+   pyprobe.logger
    pyprobe.plot
+   pyprobe.pyprobe_types
    pyprobe.rawdata
    pyprobe.readme_processor
    pyprobe.result
-   pyprobe.typing
    pyprobe.units
+   pyprobe.utils
 
 
 .. footbibliography::
diff --git a/docs/source/api/pyprobe.utils.rst b/docs/source/api/pyprobe.utils.rst
@@ -0,0 +1,10 @@
+pyprobe.utils module
+====================
+
+.. automodule:: pyprobe.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. footbibliography::
diff --git a/docs/source/developer_guide/adding_a_cycler.rst b/docs/source/developer_guide/adding_a_cycler.rst
@@ -28,11 +28,12 @@ allow PyProBE to work with your data.
    .. literalinclude:: ../../../pyprobe/cyclers/biologic.py
     :language: python
     :linenos:
-    :lines: 12-25
+    :lines: 12-26
 
 2. Add a method to read a file into a dataframe. 
 
-   The :func:`~pyprobe.cyclers.basecycler.BaseCycler.read_file` method works for the simplest
+   The :func:`~pyprobe.cyclers.basecycler.BaseCycler.read_file` method in the 
+   :class:`~pyprobe.cyclers.basecycler.BaseCycler` works for the simplest
    example, where the file contents are only the data under column headings. This may work
    for you, or may just require adding to its list of recognized file extensions.
 
@@ -55,8 +56,8 @@ allow PyProBE to work with your data.
 
    The :class:`~pyprobe.cyclers.basecycler.BaseCycler`
    includes properties for reading each column of the data. If any of these need adjusting,
-   re-define them in your new cycler class. For example, the :class:`~pyprobe.cyclers.biologic.Biologic` class
-   overrides the :attr:`~pyprobe.cyclers.biologic.Biologic.step` property, to add one
-   to the step number to change from 0-indexing to 1-indexing.
+   re-define them in your new cycler class. For example, the :class:`~pyprobe.cyclers.neware.Neware` class
+   overrides the :attr:`~pyprobe.cyclers.neware.Neware.time` property, to retrieve time
+   information from the date column if it is present.
 
 .. footbibliography::
diff --git a/docs/source/developer_guide/contributing_to_the_analysis_module.rst b/docs/source/developer_guide/contributing_to_the_analysis_module.rst
@@ -31,7 +31,7 @@ The steps to write a method are as follows:
 2. Check that inputs to the method are valid with the 
    :class:`~pyprobe.analysis.utils.AnalysisValidator` class. Provide the class the 
    input data to the method, the columns that are required for the computation to 
-   be performed and the required data type for `input_data``.
+   be performed and the required data type for :code:`input_data`.
 3. If needed, you can retrieve the columns specified in the `required_columns` field
    as numpy arrays by accessing the :attr:`~pyprobe.analysis.utils.AnalysisValidator.variables`
    attribute of the instance of :class:`~pyprobe.analysis.utils.AnalysisValidator`.
@@ -58,7 +58,7 @@ Base
 The :mod:`pyprobe.analysis.base` module exists as a repository for functions to work in
 the rest of the analysis module. Often with data analysis code, it is tempting to include
 data manipulation (forming arrays, dataframes etc. from your standard data format) 
-alongside calculations. By keeping the data manipulation inside the methods of classes
+alongside calculations. By keeping the data manipulation inside the methods 
 in the :mod:`pyprobe.analysis` and calculations in the :mod:`~pyprobe.analysis.base`
 submodule, these functions remain more readable, testable and portable.
 

diff --git a/docs/source/developer_guide/developer_installation.rst b/docs/source/developer_guide/developer_installation.rst
@@ -1,9 +1,6 @@
 Installation
 ============
 
-To install PyProBE you must be running Python 3.11 or later. It is recommended to use a 
-virtual environment to install PyProBE, for example venv or conda.
-
 The steps to install PyProBE with developer settings are as follows:
 
 **Clone the repository**
@@ -25,15 +22,15 @@ The steps to install PyProBE with developer settings are as follows:
 **Installation with uv (recommended)**
 
 To guarantee a safe installation with compatible packages, it is recommended to use
-the `uv <https://uv.readthedocs.io/en/latest/>`_ tool.
+the `uv <https://docs.astral.sh/uv/>`_ tool.
 
 First, follow the steps in the 
 `uv installation guide <https://docs.astral.sh/uv/getting-started/installation/>`_ 
 to install uv onto your system. Note: while uv can be installed into a virtual 
 environment with pip, it is recommended to install system-wide.
 
 Once uv is installed we can continue with the PyProBE installation. With a single
-command uv installs PyProBE, alongside python and all of its dependencies in a 
+command, uv installs PyProBE alongside Python and all of its dependencies in a 
 virtual environment:
 
 .. code-block:: bash

diff --git a/docs/source/examples/comparing-pyprobe-performance.ipynb b/docs/source/examples/comparing-pyprobe-performance.ipynb
@@ -473,7 +473,7 @@
     "        cycler=\"neware\",\n",
     "        folder_path=data_directory,\n",
     "        input_filename=\"sample_data_neware.xlsx\",\n",
-    "        output_filename=\"sample_data_neware.parquet\",\n",
+    "        output_filename=\"sample_data_neware_test.parquet\",\n",
     "        overwrite_existing=True,\n",
     "        compression_priority=priority,\n",
     "    )\n",
@@ -506,7 +506,9 @@
     "    file_sizes / 10**6,\n",
     ")\n",
     "plt.ylabel(\"File size (mb)\")\n",
-    "plt.show()"
+    "plt.show()\n",
+    "\n",
+    "os.remove(data_directory + \"/sample_data_neware_test.parquet\")"
    ]
   }
  ],

diff --git a/docs/source/examples/differentiating-voltage-data.ipynb b/docs/source/examples/differentiating-voltage-data.ipynb
@@ -85,7 +85,7 @@
     "    final_cycle.discharge(0), \"Capacity [Ah]\", \"Voltage [V]\"\n",
     ")\n",
     "print(raw_data_dVdQ.column_list)\n",
-    "raw_data_dVdQ.plot(x=\"Capacity [Ah]\", y=\"Voltage [V]\")"
+    "raw_data_dVdQ.plot(x=\"Capacity [Ah]\", y=\"d(Voltage [V])/d(Capacity [Ah])\")"
    ]
   },
   {

diff --git a/docs/source/examples/getting-started.ipynb b/docs/source/examples/getting-started.ipynb
@@ -310,7 +310,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As the procedure that we imported with the `quick_add_procedure` method does not contain experiment information, that filter will not work on it:"
+    "As the procedure that we imported with the `quick_add_procedure` method does not contain experiment information, the `Break-in Cycles` will not work on it:"
    ]
   },
   {

diff --git a/docs/source/examples/plotting.ipynb b/docs/source/examples/plotting.ipynb
@@ -194,7 +194,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Built-in unit conversion is also present:"
+    "As for all the plotting methods demonstrated, built-in unit conversion is also present:"
    ]
   },
   {

diff --git a/docs/source/examples/sharing-data.ipynb b/docs/source/examples/sharing-data.ipynb
@@ -20,6 +20,9 @@
     "import pyprobe\n",
     "import os\n",
     "import shutil\n",
+    "from pprint import pprint\n",
+    "\n",
+    "%matplotlib inline\n",
     "\n",
     "# Describe the cell. Required fields are 'Name'.\n",
     "info_dictionary = {\n",
@@ -90,7 +93,7 @@
    "outputs": [],
    "source": [
     "saved_cell = pyprobe.load_archive(\"sample_archive.zip\")\n",
-    "print(saved_cell.info)"
+    "pprint(saved_cell.info)"
    ]
   },
   {

diff --git a/docs/source/user_guide/accessing_data.rst b/docs/source/user_guide/accessing_data.rst
@@ -87,7 +87,6 @@ variants:
    current_mA = cell.procedure['Procedure Name'].experiment('Experiment Name').get("Current [mA]")
 
 To retrieve more than one column, simply pass multiple column names to 
-:func:`~pyprobe.result.Result.get` or use :func:`~pyprobe.result.Result.array` to
-return an N-dimensional array of the selected columns.
+:func:`~pyprobe.result.Result.get`.
 
 .. footbibliography::
diff --git a/docs/source/user_guide/analysis.rst b/docs/source/user_guide/analysis.rst
@@ -20,7 +20,7 @@ Most analysis functions are available at the module-level. In general:
 
 .. code-block:: python
 
-   result = analysis_modue.method(method_parameters)
+   result = analysis_module.method(method_parameters)
 
 or for the performing differentiation using the :func:`pyprobe.analysis.differentiation.gradient` function:
 

diff --git a/docs/source/user_guide/images/Result_flowchart.jpg b/docs/source/user_guide/images/Result_flowchart.jpg
diff --git a/docs/source/user_guide/importing_data.rst b/docs/source/user_guide/importing_data.rst
@@ -85,7 +85,7 @@ The Biologic Modulo Bat format has its own reader ``'biologic_MB'``:
 
 Adding data to a cell object
 ----------------------------
-For data to be imported into PyProBE, there must be a corresponding :code:`README.yaml`
+For data to be imported into PyProBE, there should be a corresponding :code:`README.yaml`
 file in the same directory as the data file. This file contains details of the 
 experimental procedure that generated the data. See the :ref:`writing_a_readme_file`
 section for guidance.

diff --git a/docs/source/user_guide/input_data_guidance.rst b/docs/source/user_guide/input_data_guidance.rst
@@ -39,11 +39,12 @@ Once converted into the standard PyProBE format, the data columns stored in
    Date and time the measurement was taken
 
 - 'Time [s]' (`polars.datatypes.Float64 <https://docs.pola.rs/py-polars/html/reference/api/polars.datatypes.Float64.html#polars.datatypes.Float64>`_): elapsed time 
-   From the start of the filtered data section
+   From the start of the procedure
 - 'Step' (`polars.datatypes.Int64 <https://docs.pola.rs/py-polars/html/reference/api/polars.datatypes.Int64.html#polars.datatypes.Int64>`_): the unique step number 
    Corresponds to a single instruction in the cycling program. Step numbers repeat when instructions are cycled, i.e. the column might look like [1, 1, 1…, 2, 2, 2…, 1, 1, 1…, 2,2,2…, 3, 3, 3…] if steps 1 and 2 were cycled twice
 - 'Cycle' (`polars.datatypes.Int64 <https://docs.pola.rs/py-polars/html/reference/api/polars.datatypes.Int64.html#polars.datatypes.Int64>`_): the cycle number
-   Automatically identified when Step decreases
+   Automatically identified when Step decreases, or when detailed cycle information is 
+   provided in the :doc:`README <writing_a_readme_file>` file
 - 'Event' (`polars.datatypes.Int64 <https://docs.pola.rs/py-polars/html/reference/api/polars.datatypes.Int64.html#polars.datatypes.Int64>`_): the event number
    Automatically identified when Step changes
 - 'Current [A]' (`polars.datatypes.Float64 <https://docs.pola.rs/py-polars/html/reference/api/polars.datatypes.Float64.html#polars.datatypes.Float64>`_): the current in Amperes

diff --git a/docs/source/user_guide/installation.rst b/docs/source/user_guide/installation.rst
@@ -34,24 +34,24 @@ The steps to install PyProBE are as follows:
 
 1. Create and activate a virtual environment.
 
-  .. tabs::
-      .. tab:: venv
+.. tabs::
+   .. tab:: venv
 
-         In your working directory:
+      In your working directory:
 
-         .. code-block:: bash
+      .. code-block:: bash
 
-            python -m venv venv
-            source .venv/bin/activate
+         python -m venv venv
+         source .venv/bin/activate
 
-      .. tab:: conda
-            
-         In any directory:
+   .. tab:: conda
+
+      In any directory:
 
-         .. code-block:: bash
+      .. code-block:: bash
 
-            conda create -n pyprobe python=3.12
-            conda activate pyprobe
+         conda create -n pyprobe python=3.12
+         conda activate pyprobe
 
 2. Install PyProBE with pip:
 
@@ -66,7 +66,7 @@ The steps to install PyProBE are as follows:
       pip install 'PyProBE-Data[hvplot]'
 
    If a method uses an optional dependency, it will be detailed in the 
-   :doc:`api documentation <pyprobe>`. If these methods is run without their dependencies
+   :doc:`api documentation <pyprobe>`. If these methods are run without their dependencies
    installed, they will return an error. 
 
 3. You can create a new python script or jupyter notebook to 

diff --git a/docs/source/user_guide/introduction.rst b/docs/source/user_guide/introduction.rst
@@ -16,8 +16,7 @@ procedures run on the cell. These can be further filtered as described in the
 
 Once the data is filtered, it can be processed further with a 
 method in the :mod:`~pyprobe.analysis` module or displayed using the built-in 
-:mod:`~pyprobe.plot` module. All filters produce objects that are compatible with the 
-plotting module, making it easy to visualise the data at any stage of the analysis. Additionally, 
+:func:`~pyprobe.result.Result.plot` method. Additionally, 
 all methods in the analysis module produce a :class:`~pyprobe.result.Result` which can 
 be an input to further methods. This is summarised in the flowchart below:
 

diff --git a/docs/source/user_guide/plotting.rst b/docs/source/user_guide/plotting.rst
@@ -17,7 +17,7 @@ This enables the :func:`~pyprobe.result.Result.hvplot` method which creates inte
 visual inspection.
 
 The :func:`~pyprobe.result.Result.plot` and :func:`~pyprobe.result.Result.hvplot` 
-interfaces are very similar. For example, creation of a simple plot might look like:
+interfaces are very similar. For example, the creation of a simple plot might look like:
 
 .. code-block:: python
 
@@ -49,7 +49,7 @@ Seaborn must be installed as an optional dependency:
 
 All of these methods are light wrappers, meaning you can refer to the original package 
 documentation for details on methods to customise your plots further. To get started with
-plotting view the :doc:`example <../examples/plotting>`.
+plotting, view the :doc:`example <../examples/plotting>`.
 
 
 .. footbibliography::
diff --git a/docs/source/user_guide/writing_a_readme_file.rst b/docs/source/user_guide/writing_a_readme_file.rst
@@ -29,15 +29,14 @@ The :code:`README.yaml` contains the following information:
    PyBaMM Experiment strings separated by a comma, one for the CC part and one for the
    CV part.
 
-   Each step should be given a step number. For a single README file, this should count
-   upwards from 1. These numbers should increase in line with the real step numbers 
-   defined by the cycler, i.e. Neware cyclers treat a repeat instruction as its own
+   Each step should be given a step number. These numbers should increase in line with the real step numbers 
+   defined by the cycler, i.e. Neware cyclers treat a `repeat` instruction as its own
    step. Therefore, where there is a repeat instruction in the cycler procedure, the 
    corresponding step number should be skipped.
 
 * Cycle:
    This is a section that provides details on repeats of the provided steps. PyProBE 
-   looks for any title containing the string `"cycle"`, so you can choose any name that 
+   looks for any title containing the string :code:`"cycle"`, so you can choose any name that 
    includes this or add multiple cycles with different names.
 
    Cycle details must include the keywords "Start", "End" and "Count". These identify