Add rescaling of reference scales in EchemdbEntry

doc/api.md

@@ -14,6 +14,7 @@ api/entry.md
 api/descriptor.md
 api/database/echemdb.md
 api/database/echemdb_entry.md
+api/electrochemistry/reference_electrode.md
 api/remote.md
 api/local.md
 api/baseloader.md

doc/api/electrochemistry/reference_electrode.md

@@ -0,0 +1,10 @@
+---
+github_url: https://github.com/echemdb/unitpackage/blob/master/unitpackage/electrochemistry/reference_electrode.py
+---
+
+# `unitpackage.electrochemistry.reference_electrode`
+
+```{eval-rst}
+.. automodule:: unitpackage.electrochemistry.reference_electrode
+   :members:
+```

doc/news/rescale-reference.rst

@@ -0,0 +1,5 @@
+**Added:**
+
+* Added `unitpackage.electrochemistry.reference_electrodes` which contains reference electrode data and a dataclass to interact with the data (`_reference_electrodes`), and a `ReferenceElectrode` object, which determining the shift of the potential between different reference scales.
+* Added `Entry.add_offset` which allows shifting the values of a specified column of the entry by a certain offset and tracking the information in the fields description.
+* Added `EchmdbEntry.rescale_reference` which allows shifting the potential scale onto another potential scale known to `unitpackage.electrochemistry._reference_electrodes`.

doc/usage/echemdb_usage.md

@@ -5,7 +5,7 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.17.2
+    jupytext_version: 1.18.1
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
@@ -80,17 +80,112 @@ entry.figureDescription.fields
 entry.figureDescription.scanRate
 ```
 
-An entry can be rescaled to these original units.
+### Changing column units
+
++++
+
+An entry can be rescaled to new units.
+
+```{code-cell} ipython3
+rescaled_entry = entry.rescale({'E': 'mV', 'j': 'A / m2' })
+rescaled_entry.df.head(5)
+```
+
+The information is updated in the field description of the mutable resource.
 
 ```{code-cell} ipython3
-original_entry = entry.rescale('original')
+rescaled_entry.mutable_resource.schema
+```
+
+An entry can be rescaled to its original units.
+
+```{code-cell} ipython3
+original_entry = rescaled_entry.rescale('original')
 original_entry.df.head(5)
 ```
 
+The information in the mutable resource is updated accordingly.
+
 ```{code-cell} ipython3
 original_entry.mutable_resource.schema
 ```
 
+### Shifting reference scales
+
+A key issue for comparing electrochemical current potential traces is that data can be recorded with different reference electrodes. Hence direct comparison of the potential data is not straight forward unless the data is shifted to a common reference scale. The shift to a different reference scale depends on how the value of that reference electrode vs the standard hydrogen electrode (SHE) is determined and sometimes depends on the source of the reported data. 
+
+#### Separate consideration
+
+To mitigate this issue, the `unitpackage.electrochemistry.reference_electrode` module, contains a collection of commonly used reference electrodes that can be accessed by its API.
+
+```{code-cell} ipython3
+from unitpackage.electrochemistry.reference_electrode import _reference_electrodes
+
+_reference_electrodes.keys()
+```
+
+A `ReferenceElectrode` object can be created by providing the corresponding acronym.
+
+```{code-cell} ipython3
+from unitpackage.electrochemistry.reference_electrode import ReferenceElectrode
+
+ref = ReferenceElectrode('CE-sat')
+ref
+```
+
+A certain `ReferenceElectrode` can contain multiple entries with values from different sources. For the echemdb standard data values were chosen based on the discussion of the specified reference electrodes in the literature.
+
+```{code-cell} ipython3
+ref.standard_data
+```
+
+The shift a certain reference electrode vs that of another known reference electrode can be inferrred. 
+The resulting value is always in `V`!
+
+```{code-cell} ipython3
+ref.shift(to='CE-1M')
+```
+
+The shift can also be calculated for a specific potential.
+
+```{code-cell} ipython3
+ref.shift(to='CE-1M', potential = 0.564)
+```
+
+For conversion to and from the RHE scale, the pH is required.
+
+```{code-cell} ipython3
+ref.shift(to='RHE', potential = 0.564, ph=13)
+```
+
+#### unitpackage implementation
+
+If the reference scale is given for a certain entry, the potentials can directly be shifted
+
+```{code-cell} ipython3
+entry_mse = entry.rescale_reference('MSE-sat')
+entry_mse.df.head()
+```
+
+If a pH value is provided in the metadata, conversion to RHE is straight forward. In other cases the pH must be provide as additional argument.
+
+```{code-cell} ipython3
+entry.system.electrolyte.ph
+```
+
+```{code-cell} ipython3
+entry.get_electrode('REF')
+```
+
+```{code-cell} ipython3
+entry.df.head()
+```
+
+```{code-cell} ipython3
+entry_rhe = entry.rescale_reference('SHE')
+entry_rhe.df.head()
+```
+
 ## Plotting
 
 The default plot to present the data is `j` vs. `E` (or `I` vs. `E`).

doc/usage/unitpackage_usage.md

@@ -5,7 +5,7 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.17.2
+    jupytext_version: 1.18.1
 kernelspec:
   name: python3
   display_name: Python 3 (ipykernel)
@@ -36,10 +36,35 @@ len(db)
 
 The identifiers can also be returned as a list.
 
++++
+
+### Slice the collection
+
 ```{code-cell} ipython3
 db.identifiers[0:3]
 ```
 
+A new collection from an existing collection can be created from a list of selected identifiers
+
+```{code-cell} ipython3
+ids_db = db['engstfeld_2018_polycrystalline_17743_f4b_1','alves_2011_electrochemistry_6010_f1a_solid']
+ids_db
+```
+
+a list of indices
+
+```{code-cell} ipython3
+ids_db = db[0,1]
+ids_db
+```
+
+or a slice.
+
+```{code-cell} ipython3
+sliced_db = db[:2]
+sliced_db
+```
+
 You can iterate over these entries
 
 ```{code-cell} ipython3
@@ -49,6 +74,10 @@ next(iter(db))
 The collection can be filtered for specific descriptors,
 whereby a new collection is created.
 
++++
+
+### Filter the collection
+
 ```{code-cell} ipython3
 filtered_db = db.filter(lambda entry: entry.experimental.tags == ['BCV','HER'])
 len(filtered_db)
@@ -67,27 +96,6 @@ filtered_db = db.filter(custom_filter)
 len(filtered_db)
 ```
 
-A new collection from an existing collection can be created from a list of selected identifiers
-
-```{code-cell} ipython3
-ids_db = db['engstfeld_2018_polycrystalline_17743_f4b_1','alves_2011_electrochemistry_6010_f1a_solid']
-ids_db
-```
-
-a list of indices
-
-```{code-cell} ipython3
-ids_db = db[0,1]
-ids_db
-```
-
-or a slice.
-
-```{code-cell} ipython3
-sliced_db = db[:2]
-sliced_db
-```
-
 ## Entry
 
 Each entry consists of descriptors describing the data in the resource of the datapackage. Packages describing literature data can also contain a bibliography reference (see [Bibliography](#bibliography)).
@@ -174,7 +182,11 @@ The description of the fields (column names) including units and/or other inform
 entry.resource.schema
 ```
 
-The units of the dataframe can be rescaled.
+### Data manipulation
+
++++
+
+The units of the dataframe can be rescaled to different convertible units.
 
 ```{code-cell} ipython3
 rescaled_entry = entry.rescale({'t' : 'h', 'E': 'mV', 'j' : 'uA / cm2'})
@@ -187,6 +199,56 @@ The units are updated in the schema of the 'MutableResource'.
 rescaled_entry.mutable_resource
 ```
 
+An offset can be applied to a certain axis.
+
+```{code-cell} ipython3
+offset_entry = entry.add_offset('E', 0.32, 'V')
+offset_entry.df.head()
+```
+
+The offset is indicated in the mutable_resource. For subsequent offsets, the value is updated.
+
+```{code-cell} ipython3
+offset_entry.mutable_resource
+```
+
+In principle all pandas operations can be applied to the dataframe, including for example multiplying the columns
+
+```{code-cell} ipython3
+entry.df['P/A'] = entry.df['E'] * entry.df['j']
+entry.df.head()
+```
+
+However, the information is currently not updated in the field description. Here the field 'P/A' is missing after its creation above. Also the information on the units of the new axis is missing.
+
+```{code-cell} ipython3
+entry.mutable_resource
+```
+
+Let's remove it and try a different approach.
+
+```{code-cell} ipython3
+del entry.df['P/A']
+```
+
+The workaround is currently to add a new column to the entries dataframe with the unitpackage interface, which allows parsin information about the newly created field.
+
+```{code-cell} ipython3
+import pandas as pd
+import astropy.units as u
+
+df = pd.DataFrame()
+df['P/A'] = entry.df['E'] * entry.df['j']
+
+new_field_unit = u.Unit(entry.field_unit('E')) * u.Unit(entry.field_unit('j'))
+new_entry = entry.add_columns(df['P/A'], new_fields=[{'name':'P/A', 'unit': new_field_unit}])
+new_entry.df.head()
+```
+
+### Column information
+
++++
+
 The units of a specific field can be retrieved.
 
 ```{code-cell} ipython3
@@ -213,6 +275,22 @@ A plot with rescaled axis is obtained by rescaling the entry first.
 entry.rescale({'E':'mV', 'j':'uA / cm2'}).plot(x_label='t', y_label='j')
 ```
 
+We can also use the matplotlib interface.
+
+```{code-cell} ipython3
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots(1,1)
+
+x = 'E'
+y = 'j'
+
+entry.df.plot(x, y, ax=ax)
+plt.title(entry.identifier)
+ax.set_xlabel(f"{x} [{entry.field_unit(x)}]")
+ax.set_ylabel(f"{y} [{entry.field_unit(y)}]")
+```
+
 ## Bibliography
 
 An entry can be associated with bibliography data. The bibliography must must be prvided as abibtex string nested in source.bib_data. The bibliography to all entries is stored as a [pybtex database](https://docs.pybtex.org/api) `db.bibliography`,