Merge pull request #37 from ImperialCollegeLondon/9-complete-docs

Add accessing data section to docs

.github/workflows/sphinx.yml

@@ -12,7 +12,6 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
 
     steps:
     - uses: actions/checkout@v4

docs/source/accessing_data.rst

@@ -0,0 +1,83 @@
+Accessing Data
+==============
+
+Filtering
+---------
+
+PyProBE is designed to have a simple interface for filtering data. The filtering methods
+use chained notation and natural language to be approachable for users who are less 
+familiar with Python. Procedure and experiment names are specified as strings by the
+user, either :ref:`when the data is imported <adding_data_to_cell>` or in the 
+:code:`README.yaml` :ref:`file <writing_a_readme_file>`.
+
+It is possible to filter data by a number of methods:
+
+* First **procedure**:
+
+   .. code-block:: python
+
+      cell.procedure['Procedure Name']
+
+* Then by **experiment**:
+
+   .. code-block:: python
+
+      cell.procedure['Procedure Name'].experiment('Experiment Name')
+
+* Then by the **numerical filter methods** in the :class:`pyprobe.filter.Filter` class:
+
+   .. code-block:: python
+
+      # Filter by cycle
+      cell.procedure['Procedure Name'].experiment('Experiment Name').cycle(1)
+
+      # Filter by step
+      cell.procedure['Procedure Name'].experiment('Experiment Name').step(3)
+
+      # Filter by cycle then step
+      cell.procedure['Procedure Name'].experiment('Experiment Name').cycle(1).step(1)
+
+      # Filter by step type
+      cell.procedure['Procedure Name'].experiment('Experiment Name').charge(2)
+      cell.procedure['Procedure Name'].experiment('Experiment Name').discharge(0)
+      cell.procedure['Procedure Name'].experiment('Experiment Name').rest(1)
+      cell.procedure['Procedure Name'].experiment('Experiment Name').chargeordischarge(1)
+
+      # Filter by cycle then step type
+      cell.procedure['Procedure Name'].experiment('Experiment Name').cycle(4).charge(2)
+      cell.procedure['Procedure Name'].experiment('Experiment Name').cycle(2).discharge(0)
+   
+   Indices are zero-based, so the first cycle is 0, the first step is 0, etc. The 
+   index count is reset after applying every filter, i.e. the first discharge of any 
+   cycle is accessed with :code:`discharge(0)`.
+
+RawData objects
+---------------
+Any filter applied to a cell returns a :class:`pyprobe.rawdata.RawData` object. This 
+holds:
+
+* :attr:`~pyprobe.rawdata.RawData.data` attribute
+   a `polars Dataframe <https://docs.pola.rs/py-polars/html/reference/dataframe/index.html>`_
+   containing the filtered data.
+* :attr:`~pyprobe.rawdata.RawData.info` attribute
+   the cell's :attr:`~pyprobe.cell.Cell.info` dictionary.
+
+To access the data, you can access the full polars Dataframe:
+
+.. code-block:: python
+
+   dataframe = cell.procedure['Procedure Name'].experiment('Experiment Name').cycle(1).step(1).data
+
+Or you can access individual columns as 1D numpy arrays by calling the 
+:class:`~pyprobe.rawdata.RawData` object:
+
+.. code-block:: python
+
+   voltage = cell.procedure['Procedure Name'].experiment('Experiment Name').cycle(1).step(1)("Voltage [V]")
+
+Accessing columns directly with this method is useful for converting data to units not
+stored in the :attr:`~pyprobe.rawdata.RawData.data` Dataframe:
+
+.. code-block:: python
+
+   current_mA = cell.procedure['Procedure Name'].experiment('Experiment Name')("Current [mA]")

docs/source/user_guide.rst

@@ -6,7 +6,7 @@ User Guide
 
    installation
    importing_data
-   using_data
+   accessing_data
    input_data_guidance
    writing_a_readme_file
    writing_an_experiment_record