`unitpackage.database.echemdb`

A Collection of data from the echemdb data repository displayed on the echemdb website. It provides additional functionalities compared to the Collection specific to the data in the echemdb repository.

EXAMPLES:

Create a collection from the Data Packages published in the echemdb data repository displayed on the echemdb website.:

>>> collection = Echemdb.from_remote()

Search the collection for entries from a single publication:

>>> collection.filter(lambda entry: entry.source.url == 'https://doi.org/10.1039/C0CP01001D')
[Echemdb('alves_2011_electrochemistry_6010_f1a_solid'), ...

class unitpackage.database.echemdb.Echemdb(package=None)

A collection of frictionless Data Packages.

Essentially this is just a list of data packages with some additional convenience wrap for use in the echemdb data repository displayed on the echemdb website.

EXAMPLES:

An example collection:

>>> collection = Collection.create_example()
>>> collection.package.resource_names
['alves_2011_electrochemistry_6010_f1a_solid',
'engstfeld_2018_polycrystalline_17743_f4b_1',
'no_bibliography']

class EchemdbEntry(resource)

A frictionless Data Package describing a CV.

EXAMPLES:

Entries are normally obtained by opening a Echemdb of entries:

>>> from unitpackage.database.echemdb import Echemdb
>>> collection = Echemdb.create_example()
>>> entry = next(iter(collection))

property bibliography

Return a pybtex bibliography object associated with this entry.

EXAMPLES:

>>> entry = EchemdbEntry.create_example()
>>> entry.bibliography
Entry('article',
fields=[
    ('title', ...
    ...

>>> entry_no_bib = EchemdbEntry.create_example(name="no_bibliography")
>>> entry_no_bib.bibliography
''

citation(backend='text')

Return a formatted reference for the entry’s bibliography such as:

Doe, et al., Journal Name, volume (YEAR) page, “Title”

Rendering default is plain text ‘text’, but can be changed to any format supported by pybtex, such as markdown ‘md’, ‘latex’ or ‘html’.

EXAMPLES:

>>> entry = EchemdbEntry.create_example()
>>> entry.citation(backend='text')
'O. B. Alves et al. Electrochemistry at Ru(0001) in a flowing CO-saturated electrolyte—reactive and inert adlayer phases. Physical Chemistry Chemical Physics, 13(13):6010–6021, 2011.'
>>> print(entry.citation(backend='md'))
O\. B\. Alves *et al\.*
*Electrochemistry at Ru\(0001\) in a flowing CO\-saturated electrolyte—reactive and inert adlayer phases*\.
*Physical Chemistry Chemical Physics*, 13\(13\):6010–6021, 2011\.

default_metadata_key = 'echemdb': Use ‘echemdb’ key to access descriptor metadata.

classmethod from_mpt(csvname, encoding=None)

Return an EchemdbEntry from a BioLogic EC-Lab MPT file.

The file is parsed with the ECLabLoader. Fields are updated with units from biologic_fields and renamed according to biologic_fields_alt_names (both defined in unitpackage.loaders.eclab_fields). The original field names are preserved as originalName.

Only columns whose original names appear in biologic_fields_alt_names are kept; all other columns are removed.

EXAMPLES:

>>> entry = EchemdbEntry.from_mpt('test/loader_data/eclab_cv.mpt')
>>> entry
Echemdb('eclab_cv')

>>> entry.df.head()
            t         E         I  cycle
0  86.761598  0.849737  0.001722    1.0
1  86.772598  0.849149 -0.003851    1.0
...

Fields have units and the original BioLogic column names:

>>> [f for f in entry.fields if f.name == 'E']
[{'name': 'E', 'type': 'number', 'description': 'WE potential versus REF.',
'unit': 'V', 'dimension': 'E', 'originalName': 'Ewe/V'}]

>>> [f for f in entry.fields if f.name == 't']
[{'name': 't', 'type': 'number', 'description': 'Time.',
'unit': 's', 'dimension': 't', 'originalName': 'time/s'}]

>>> [f for f in entry.fields if f.name == 'I']
[{'name': 'I', 'type': 'number', 'description': ...,
'unit': 'mA', 'dimension': 'I', 'originalName': '<I>/mA'}]

The loader metadata is stored in the entry’s metadata:

>>> entry.metadata['dsvDescription']['loader']
'ECLabLoader'

>>> entry.metadata['dsvDescription']['header']
'EC-Lab ASCII FILE\nNb header lines : 62...'

get_electrode(name)

Returns an electrode with the specified name.

EXAMPLES:

>>> entry = EchemdbEntry.create_example()
>>> entry.get_electrode('WE')
{'name': 'WE', 'function': 'workingElectrode', 'type': 'single crystal',
'crystallographicOrientation': '0001', 'material': 'Ru',
'preparationProcedure': 'Sputtering and flash annealing under UHV
conditions with repeated cycles of oxygen adsorption and desorption.',
'shape': {'height': {'unit': 'mm', 'value': 2}, 'type': 'hat shaped'},
'source': {'supplier': 'Mateck'}}

TESTS:

>>> entry.get_electrode('foo')
Traceback (most recent call last):
...
KeyError: "Electrode with name 'foo' does not exist"

plot(x_label='E', y_label='j', name=None)

Return a plot of this entry. The default plot is a Cyclic Voltammogram (‘j vs E’). When j is not present in the data, I is used instead.

EXAMPLES:

>>> entry = EchemdbEntry.create_example()
>>> entry.plot()
Figure(...)

The plot can also be returned with custom axis dimensions (field names) available in the resource:

>>> entry.plot(x_label='t', y_label='E')
Figure(...)

A plot resembling the original figure can be obtained by first rescaling:

>>> rescaled_entry = entry.rescale('original')
>>> rescaled_entry.plot()
Figure(...)

rescale(units)

Return a rescaled EchemdbEntry with axes in the specified units.

Usage is essentially the same as for rescale(), i.e., new units are expected as dict, where the key is the axis name and the value the new unit, such as {'j': 'uA / cm2', 't': 'h'}.

Additionally, the entry can be rescaled to the axes’ units of the original data. These units must be defined in the metadata of the resource, within the key figureDescription.fields:

>>> entry = EchemdbEntry.create_example()
>>> rescaled_entry = entry.rescale(units='original')
>>> rescaled_entry.fields
[{'name': 't', 'type': 'number', 'unit': 's'},
{'name': 'E', 'type': 'number', 'unit': 'V', 'reference': 'RHE'},
{'name': 'j', 'type': 'number', 'unit': 'mA / cm2'}]

rescale_reference(new_reference=None, field_name=None, ph=None)

Return a rescaled EchemdbEntry with potentials referenced to new_reference scale.

Warning

This is an experimental feature working for standard aqueous reference electrodes and electrolytes. We do not include temperature effects or other non-idealities at this point.

If a reference is not available, the axis can still be rescaled by adding an offset using the add_offset().

EXAMPLES:

>>> entry = EchemdbEntry.create_example()
>>> entry.resource.schema.get_field('E')
{'name': 'E', 'type': 'number', 'unit': 'V', 'reference': 'RHE'}

>>> entry.df.head()
      t         E         j
0  0.00 -0.103158 -0.998277
1  0.02 -0.102158 -0.981762
...

>>> rescaled_entry = entry.rescale_reference(new_reference='Ag/AgCl-sat')
>>> rescaled_entry.resource.schema.get_field('E')
{'name': 'E', 'type': 'number', 'unit': 'V', 'reference': 'Ag/AgCl-sat'}

>>> rescaled_entry.df.head()
      t         E         j
0  0.00  0.152942 -0.998277
1  0.02  0.153942 -0.981762
...

rescale_scan_rate(field_name=None, *, value, unit)

Return a rescaled EchemdbEntry where the current (I) or current density (j) axis is rescaled according to the ratio of the provided scan rate to the original scan rate.

Since current (density) scales linearly with scan rate in cyclic voltammetry, this method multiplies the j (or I) column by new_scan_rate / original_scan_rate. The scaling factor is tracked in the field metadata.

By default the j (or I) field is rescaled. A custom field_name can be provided if the current axis has a different name.

EXAMPLES:

>>> entry = EchemdbEntry.create_example()
>>> entry.scan_rate
<Quantity 0.05 V / s>

>>> entry.df.head()
      t         E         j
0  0.00 -0.103158 -0.998277
1  0.02 -0.102158 -0.981762
...

Rescale from 50 mV/s to 100 mV/s (factor of 2):

>>> rescaled = entry.rescale_scan_rate(value=100, unit='mV / s')
>>> rescaled.df
              t         E         j
0      0.000000 -0.103158 -1.996553
1      0.020000 -0.102158 -1.963524
...

>>> rescaled.resource.schema.get_field('j')
{'name': 'j',
'type': 'number',
'unit': 'A / m2',
'scalingFactor': {'value': 2.0}}

Rescale using the same unit as the original scan rate:

>>> rescaled2 = entry.rescale_scan_rate(value=0.1, unit='V / s')
>>> rescaled2.df
              t         E         j
0      0.000000 -0.103158 -1.996553
1      0.020000 -0.102158 -1.963524
...

A custom field name can be provided:

>>> rescaled3 = entry.rescale_scan_rate('j', value=100, unit='mV / s')
>>> rescaled3.df
              t         E         j
0      0.000000 -0.103158 -1.996553
1      0.020000 -0.102158 -1.963524
...

property scan_rate

Return the scan rate of the entry as an astropy quantity.

The scan rate is retrieved from the entry’s metadata at figureDescription.scanRate.

EXAMPLES:

>>> entry = EchemdbEntry.create_example()
>>> entry.scan_rate
<Quantity 0.05 V / s>

>>> from unitpackage.database.echemdb import Echemdb
>>> db = Echemdb.create_example()
>>> db['engstfeld_2018_polycrystalline_17743_f4b_1'].scan_rate
<Quantity 50. mV / s>

thumbnail(width=96, height=72, dpi=72, **kwds)

Return a thumbnail of the entry’s curve as a PNG byte stream.

EXAMPLES:

>>> entry = EchemdbEntry.create_example()
>>> thumb = entry.thumbnail()
>>> thumb.startswith(b'\x89PNG')
True

The PNG’s width and height can be specified in pixels. Additional keyword arguments are passed to the data frame plotting method:

>>> thumb = entry.thumbnail(width=4, height=2, color='red', linewidth=2)
>>> thumb.startswith(b'\x89PNG')
True

Entry: alias of EchemdbEntry

property bibliography

Return a pybtex database of all bibtex bibliography files, associated with the entries.

EXAMPLES:

>>> from unitpackage.database.echemdb import Echemdb
>>> collection = Echemdb.create_example()
>>> collection.bibliography
BibliographyData(
  entries=OrderedCaseInsensitiveDict([
    ('alves_2011_electrochemistry_6010', Entry('article',
    ...
    ('engstfeld_2018_polycrystalline_17743', Entry('article',
    ...

A derived collection includes only the bibliographic entries of the remaining entries:

>>> collection.filter(lambda entry: entry.source.citationKey != 'alves_2011_electrochemistry_6010').bibliography
BibliographyData(
  entries=OrderedCaseInsensitiveDict([
    ('engstfeld_2018_polycrystalline_17743', Entry('article',
    ...

A collection with entries without bibliography:

>>> collection = Echemdb.create_example()["no_bibliography"]
>>> collection.bibliography
''

describe()

Return some statistics about the echemdb database.

EXAMPLES:

>>> from unitpackage.database.echemdb import Echemdb
>>> collection = Echemdb.create_example()
>>> collection.describe() == \
... {'number of references': 2,
... 'number of entries': 3,
... 'materials': {'Cu', 'Ru'}}
True

materials()

Return the substrate materials in the collection.

EXAMPLES:

>>> from unitpackage.database.echemdb import Echemdb
>>> collection = Echemdb.create_example()
>>> collection.materials() == {'Cu', 'Ru'}
True

unitpackage.database.echemdb

`unitpackage.database.echemdb`