`echemdb.database`

A collection of datapackages with units.

EXAMPLES:

Create a database from local data packages in the data/ directory:

>>> from echemdb.local import collect_datapackages
>>> database = Database(collect_datapackages('data/'))

Create a database from the data packages published in the echemdb:

>>> database = Database()  

Search the database for a single publication:

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

class echemdb.database.Database(data_packages=None)

A collection of [data packages](https://github.com/frictionlessdata/datapackage-py).

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

EXAMPLES:

An empty database:

>>> database = Database([])
>>> len(database)
0

class Entry(package)

A data packages describing tabulated data.

EXAMPLES:

Entries are normally obtained by opening a Database of entries:

>>> from echemdb.database import Database
>>> database = Database.create_example()
>>> entry = next(iter(database))

property bibliography

Return a pybtex bibliography object.

EXAMPLES:

>>> entry = Entry.create_examples()[0]
>>> entry.bibliography 
Entry('article',
fields=[
    ('title', ...
    ...

>>> entry_no_bib = Entry.create_examples(name="no_bibliography")[0]
>>> 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 = Entry.create_examples()[0]
>>> 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\.

classmethod create_examples(name='alves_2011_electrochemistry_6010')

Return some example entries for use in automated tests.

The examples are built on-demand from data in echemdb’s examples directory.

EXAMPLES:

>>> Entry.create_examples()
[Entry('alves_2011_electrochemistry_6010_f1a_solid')]

An entry without associated BIB file.

>>> Entry.create_examples(name="no_bibliography")
[Entry('no_bibliography')]

property df

Return the data of this entry as a data frame.

EXAMPLES:

>>> entry = Entry.create_examples()[0]
>>> entry.df
              t         E         j
0      0.000000 -0.103158 -0.998277
1      0.020000 -0.102158 -0.981762
...

The units and descriptions of the axes in the data frame can be recovered:

>>> entry.package.get_resource('echemdb').schema.fields 
[{'name': 't', 'type': 'number', 'unit': 's'},
{'name': 'E', 'type': 'number', 'unit': 'V', 'reference': 'RHE'},
{'name': 'j', 'type': 'number', 'unit': 'A / m2'}]

field_unit(field_name)

Return the unit of the field_name of the echemdb resource.

EXAMPLES:

>>> entry = Entry.create_examples()[0]
>>> entry.field_unit('E')
'V'

property identifier

Return a unique identifier for this entry, i.e., its filename.

EXAMPLES:

>>> entry = Entry.create_examples()[0]
>>> entry.identifier
'alves_2011_electrochemistry_6010_f1a_solid'

plot(x_label=None, y_label=None, name=None)

Return a plot of this entry.

The default plot is constructed from the first two columns of the dataframne.

EXAMPLES:

>>> entry = Entry.create_examples()[0]
>>> entry.plot()
Figure(...)

The plot can also be returned with custom axis units available in the resource:

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

rescale(units)

Returns a rescaled Entry with axes in the specified units. Provide a dict, where the key is the axis name and the value the new unit, such as {‘j’: ‘uA / cm2’, ‘t’: ‘h’}.

EXAMPLES:

The units without any rescaling:

>>> entry = Entry.create_examples()[0]
>>> entry.package.get_resource('echemdb').schema.fields
[{'name': 't', 'type': 'number', 'unit': 's'},
{'name': 'E', 'type': 'number', 'unit': 'V', 'reference': 'RHE'},
{'name': 'j', 'type': 'number', 'unit': 'A / m2'}]

A rescaled entry using different units:

>>> rescaled_entry = entry.rescale({'j':'uA / cm2', 't':'h'})
>>> rescaled_entry.package.get_resource('echemdb').schema.fields
[{'name': 't', 'type': 'number', 'unit': 'h'},
{'name': 'E', 'type': 'number', 'unit': 'V', 'reference': 'RHE'},
{'name': 'j', 'type': 'number', 'unit': 'uA / cm2'}]

The values in the data frame are scaled to match the new units:

>>> rescaled_entry.df
             t         E          j
0     0.000000 -0.103158 -99.827664
1     0.000006 -0.102158 -98.176205
...

property bibliography

Return a pybtex database of all bibtex bibliography files.

EXAMPLES:

>>> database = Database.create_example()
>>> database.bibliography
BibliographyData(
  entries=OrderedCaseInsensitiveDict([
    ('alves_2011_electrochemistry_6010', Entry('article',
    ...
    ('engstfeld_2018_polycrystalline_17743', Entry('article',
    ...

A database with entries without bibliography.

>>> database = Database.create_example()["no_bibliography"]
>>> database.bibliography
''

classmethod create_example()

Return a sample database for use in automated tests.

EXAMPLES:

>>> Database.create_example()  
[Entry('alves_2011_electrochemistry_6010_f1a_solid'),
Entry('engstfeld_2018_polycrystalline_17743_f4b_1'),
Entry('no_bibliography')]

filter(predicate)

Return the subset of the database that satisfies predicate.

EXAMPLES:

>>> database = Database.create_example()
>>> database.filter(lambda entry: entry.source.url == 'https://doi.org/10.1039/C0CP01001D')
[Entry('alves_2011_electrochemistry_6010_f1a_solid')]

The filter predicate can use properties that are not present on all entries in the database. If a property is missing the element is removed from the database:

>>> database.filter(lambda entry: entry.non.existing.property)
[]

echemdb.database

`echemdb.database`