echemdb

The electrochemical data shown on the echemdb.org website can be downloaded from the echemdb data repository and stored in a collection.

from unitpackage.database.echemdb import Echemdb
db = Echemdb.from_remote()
type(db)

unitpackage.database.echemdb.Echemdb

Collection

In contrast to the Collection object described in the usage section, Echemdb provides data specific functionality. All other functionalities of the base class are still applicable.

For example, statistics of the collection can be shown.

db.describe()

{'number of references': 44,
 'number of entries': 205,
 'materials': {'Ag', 'Au', 'Cu', 'Pt', 'Ru'}}

Metadata

The entries have properties which allow for more convenient filtering of the collection.

db_filtered = db.filter(lambda entry: entry.get_electrode('WE').material == 'Pt')
db_filtered.describe()

{'number of references': 19, 'number of entries': 130, 'materials': {'Pt'}}

Single entries can be selected by their identifier provided on echemdb.org/cv for each entry.

entry = db['engstfeld_2018_polycrystalline_17743_f4b_1']
type(entry)

unitpackage.database.echemdb_entry.EchemdbEntry

entry.metadata provides a full list of available descriptors.

For Echemdb entries, the top-level keys under entry.metadata['echemdb'] (such as source, system, figureDescription, etc.) are directly accessible as properties on the entry:

entry.source

{'citationKey': 'engstfeld_2018_polycrystalline_17743', 'url': 'https://doi.org/10.1002/chem.201803418', 'techniques': ['XPS', 'STM'], 'figure': '4b', 'curve': '1', 'bibdata': '@article{engstfeld_2018_polycrystalline_17743,\n    author = "Engstfeld, Albert K and Maagaard, Thomas and Horch, Sebastian and Chorkendorff, Ib and Stephens, Ifan EL",\n    title = "Polycrystalline and single-crystal Cu electrodes: influence of experimental conditions on the electrochemical properties in alkaline media",\n    journal = "Chem.-Eur. J",\n    volume = "24",\n    number = "67",\n    pages = "17743--17755",\n    year = "2018",\n    abstract = "Single and polycrystalline Cu electrodes serve as model systems for the study of the electroreduction of CO2, CO and nitrate, or for corrosion studies; even so, there are very few reports combining electrochemical measurements with structural characterization. Herein both the electrochemical properties of polycrystalline Cu and single crystal Cu(1 0 0) electrodes in alkaline solutions (0.1 m KOH and 0.1 m NaOH) are investigated. It is demonstrated that the pre-treatment of the electrodes plays a crucial role in determining their electrochemical properties. Scanning tunneling microscopy, X-ray photoelectron spectroscopy and cyclic voltammetry are performed on Cu(1 0 0) electrodes prepared under UHV conditions; it is shown that the electrochemical properties of these atomically well-defined electrodes are distinct from electrodes prepared by other methods. Also highlighted is the significant role of residual oxygen and electrolyte convection in influencing the electrochemical properties."\n}\n'}

entry.system.electrolyte

{'components': [{'name': 'water', 'proportion': {'unit': 'volume percent', 'value': 100}, 'source': {'quality': 'ultrapure water', 'refinement': 'Millipore MilliQ'}, 'type': 'solvent'}, {'concentration': {'unit': 'mol / l', 'value': 0.1}, 'name': 'KOH', 'source': {'supplier': 'Merck Suprapur'}, 'type': 'base'}], 'ph': {'value': 13}, 'temperature': {'unit': 'K', 'value': 298.15}, 'type': 'aqueous'}

Other metadata subsets that are not under the echemdb key must be accessed via entry.metadata, e.g., entry.metadata['other_key'].

As indicated above, electrodes used to record the data are listed in the system.electrodes descriptor and are accessible with

entry.get_electrode('WE')

{'name': 'WE', 'function': 'working electrode', 'crystallographicOrientation': '100', 'geometricElectrolyteContactArea': {'unit': '1 / cm2'}, 'material': 'Cu', 'preparationProcedure': {'description': ['Sputter and heating under UHV conditions.']}, 'shape': {'diameter': {'unit': 'mm', 'value': 4.4}, 'height': {'unit': 'mm', 'value': 2}, 'type': 'head shaped'}, 'source': {'manufacturer': 'Mateck'}}

Note

Usually measurements are performed in a three electrode configuration, with a working electrode WE, a counter electrode CE, and a reference electrode REF.

Data

In a freshly created collection all values of in the dataframe are in SI units.

entry.df.head(5)
t E j
0 0.00 -0.198005 0.036712
1 0.02 -0.197005 0.045084
2 0.04 -0.196005 0.050082
3 0.06 -0.195005 0.054618
4 0.08 -0.194005 0.058966

The original units in the published figure are stored as metadata. For data digitized with svgdigitizer a time axis is only present, when a scan rate was given in the SVG.

entry.figureDescription.fields

[{'name': 'E', 'type': 'number', 'unit': 'V', 'orientation': 'horizontal', 'reference': 'RHE'},
 {'name': 'j', 'type': 'number', 'unit': 'uA / cm2', 'orientation': 'vertical'}]

entry.figureDescription.scanRate

50.0 mV / s

Changing column units

An entry can be rescaled to new units.

rescaled_entry = entry.rescale({'E': 'mV', 'j': 'A / m2' })
rescaled_entry.df.head(5)
t E j
0 0.00 -198.005384 0.036712
1 0.02 -197.005384 0.045084
2 0.04 -196.005384 0.050082
3 0.06 -195.005384 0.054618
4 0.08 -194.005384 0.058966

The information is updated in the field descriptions.

rescaled_entry.fields

[{'name': 't', 'type': 'number', 'unit': 's'},
 {'name': 'E', 'type': 'number', 'unit': 'mV', 'reference': 'RHE'},
 {'name': 'j', 'type': 'number', 'unit': 'A / m2'}]

An entry can be rescaled to its original units.

original_entry = rescaled_entry.rescale('original')
original_entry.df.head(5)
t E j
0 0.00 -0.198005 3.671208
1 0.02 -0.197005 4.508403
2 0.04 -0.196005 5.008222
3 0.06 -0.195005 5.461767
4 0.08 -0.194005 5.896625

The field descriptions are updated accordingly.

original_entry.fields

[{'name': 't', 'type': 'number', 'unit': 's'},
 {'name': 'E', 'type': 'number', 'unit': 'V', 'reference': 'RHE'},
 {'name': 'j', 'type': 'number', 'unit': 'uA / cm2'}]

Scan rate

The scan rate used to record the data is accessible as an astropy quantity.

entry.scan_rate
\[50 \; \mathrm{\frac{mV}{s}}\]

Rescaling the scan rate

CVs are often recorded with different scan rate. The rescale_scan_rate method rescales the j (or I) axis by the ratio of a given scan rate to the original one, for better comparison of the data, which provides information on transport and kinetic effects. Essentially this applies a scaling factor to the j (or I), which is tracked in the field metadata.

rescaled_sr = entry.rescale_scan_rate(value=100, unit='mV / s')
rescaled_sr.df.head()
t E j
0 0.00 -0.198005 0.073424
1 0.02 -0.197005 0.090168
2 0.04 -0.196005 0.100164
3 0.06 -0.195005 0.109235
4 0.08 -0.194005 0.117933

The scaling factor is stored in the field description.

rescaled_sr.resource.schema.get_field('j')

{'name': 'j',
 'type': 'number',
 'unit': 'A / m2',
 'scalingFactor': {'value': 2.0}}

A custom field name can be provided if the current axis has a different name.

rescaled_sr_custom = entry.rescale_scan_rate('j', value=0.1, unit='V / s')
rescaled_sr_custom.df.head()
t E j
0 0.00 -0.198005 0.073424
1 0.02 -0.197005 0.090168
2 0.04 -0.196005 0.100164
3 0.06 -0.195005 0.109235
4 0.08 -0.194005 0.117933

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.

from unitpackage.electrochemistry.reference_electrode import _reference_electrodes

_reference_electrodes.keys()

dict_keys(['SHE', 'Ag/AgCl', 'Ag/AgCl-sat', 'Ag/AgCl-1M', 'CE-sat', 'CE-1M', 'CE-0.1M', 'Hg/HgO-0.1M-NaOH', 'Hg/HgO-0.5M-NaOH', 'Hg/HgO-1M-NaOH', 'Hg/HgO-0.1M-KOH', 'Hg/HgO-0.5M-KOH', 'Hg/HgO-1M-KOH', 'MSE-sat', 'MSE-0.5M', 'RHE'])

A ReferenceElectrode object can be created by providing the corresponding acronym.

from unitpackage.electrochemistry.reference_electrode import ReferenceElectrode

ref = ReferenceElectrode('CE-sat')
ref

{'name': 'CE-sat', 'full_name': 'Saturated calomel electrode', 'alias': 'SCE', 'entries': [{'value': 0.26796, 'standard': 'ECHEMDB-2026', 'approach': 'experimental', 'unit': 'V', 'vs': 'SHE', 'source': {'doi': 'https://doi.org/10.1007/978-3-642-36188-3', 'title': 'Handbook of Reference Electrodes'}, 'choice': 'Recommended value in Handbook of Reference Electrodes (DOI: https://doi.org/10.1007/978-3-642-36188-3).', 'uncertainty': None}], 'temperature_dependence': []}

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.

ref.standard_data

{'value': 0.26796, 'standard': 'ECHEMDB-2026', 'approach': 'experimental', 'unit': 'V', 'vs': 'SHE', 'source': {'doi': 'https://doi.org/10.1007/978-3-642-36188-3', 'title': 'Handbook of Reference Electrodes'}, 'choice': 'Recommended value in Handbook of Reference Electrodes (DOI: https://doi.org/10.1007/978-3-642-36188-3).', 'uncertainty': None}

The shift a certain reference electrode vs that of another known reference electrode can be inferrred.

Note

The resulting value is always in V!

ref.shift(to='CE-1M')

0.01214000000000004

The shift can also be calculated for a specific potential.

ref.shift(to='CE-1M', potential = 0.564)

0.57614

For conversion to and from the RHE scale, the pH is required.

ref.shift(to='RHE', potential = 0.564, ph=13)

-0.47226

unitpackage implementation

If the reference scale is given for a certain entry, the potentials can directly be shifted

entry_mse = entry.rescale_reference('MSE-sat')
entry_mse.df.head()

Reference MSE-sat is of type 'generic', i.e., the value is not based on experimental or theoretical values. Consult the details for MSE-sat with `ReferenceElectrode.data`.
t E j
0 0.00 1.224295 0.036712
1 0.02 1.225295 0.045084
2 0.04 1.226295 0.050082
3 0.06 1.227295 0.054618
4 0.08 1.228295 0.058966

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.

entry.system.electrolyte.ph

{'value': 13}

entry.get_electrode('REF')

{'name': 'REF', 'function': 'reference electrode', 'source': {'manufacturer': 'homemade'}, 'type': 'RHE'}

entry.df.head()
t E j
0 0.00 -0.198005 0.036712
1 0.02 -0.197005 0.045084
2 0.04 -0.196005 0.050082
3 0.06 -0.195005 0.054618
4 0.08 -0.194005 0.058966 
entry_rhe = entry.rescale_reference('SHE')
entry_rhe.df.head()
t E j
0 0.00 0.570295 0.036712
1 0.02 0.571295 0.045084
2 0.04 0.572295 0.050082
3 0.06 0.573295 0.054618
4 0.08 0.574295 0.058966

Plotting

The default plot to present the data is j vs. E (or I vs. E). The curve label consists of the figure number in the original publication followed by a unique identifier.

entry.plot()

The dimensions of the axis can still be specified explicitly.

entry.plot(x_label='t', y_label='j')

Bibliography

All entries within the Echemdb collection are referenced and included in a bibtex bibliography.

len(db.bibliography.entries)

44

Each entry in the Echemdb collection can be cited.

entry = db['engstfeld_2018_polycrystalline_17743_f4b_1']
entry.citation(backend='text') # other available backends: 'latex' or 'markdown'. 'text' is default.

'A. K. Engstfeld et al. Polycrystalline and single-crystal Cu electrodes: influence of experimental conditions on the electrochemical properties in alkaline media. Chem.-Eur. J, 24(67):17743–17755, 2018.'