eclab: For BioLogic data files

Extractors for data files generated by BioLogic’s EC-Lab software.

yadg.extractors.eclab.mpr module

For processing of BioLogic’s EC-Lab binary modular files.

Usage

Available since yadg-4.0.

pydantic model dgbowl_schemas.yadg.dataschema_6_0.filetype.EClab_mpr

Config:

extra: str = forbid

Validators:

field filetype: Literal['eclab.mpr'] [Required]

Schema

The mpr files contain many columns that vary depending on the electrochemical technique used. Below is shown a list of columns that can be expected to be present in a typical mpr file.

xarray.DataTree:
  coords:
    uts:            !!float     # Unix timestamp, without date
  data_vars:
    Ewe             (uts)       # Potential of the working electrode
    Ece             (uts)       # Potential of the counter electrode, if present
    I               (uts)       # Instantaneous current
    time            (uts)       # Time elapsed since the start of the experiment
    <Ewe>           (uts)       # Average Ewe potential since last data point
    <Ece>           (uts)       # Average Ece potential since last data point
    <I>             (uts)       # Average current since last data point
    ...

Note

Note that in most cases, either the instantaneous or the averaged quantities are stored - only rarely are both available!

Notes on file structure

.mpr files are structured in a set of “modules”, one concerning settings, one for actual data, one for logs, and an optional loops module. The parameter sequences can be found in the settings module.

This code is partly an adaptation of the galvani module by Chris Kerr, and builds on the work done by the previous civilian service member working on the project, Jonas Krieger.

At a top level, .mpr files are made up of a number of modules, separated by the MODULE keyword. In all the files we have seen, the first module is the settings module, followed by the data module, the log module and then an optional loop module.

0x0000 BIO-LOGIC MODULAR FILE  # File magic.
0x0034 MODULE                  # Module magic.
...                            # Module 1.
0x???? MODULE                  # Module magic.
...                            # Module 2.
0x???? MODULE                  # Module magic.
...                            # Module 3.
0x???? MODULE                  # Module magic.
...                            # Module 4.

After splitting the entire file on MODULE, each module starts with a header that is structured like this (offsets from start of module):

0x0000 short_name  # Short name, e.g. VMP Set.
0x000A long_name   # Longer name, e.g. VMP settings.
0x0023 length      # Number of bytes in module data.
0x0027 version     # Module version.
0x002B date        # Acquisition date in ASCII, e.g. 08/10/21.
...                # Module data.

The contents of each module’s data vary wildly depending on the used technique, the module and perhaps the software version, the settings in EC-Lab, etc. Here a quick overview (offsets from start of module data).

Settings Module

0x0000 technique_id           # Unique technique ID.
...                           # ???
0x0007 comments               # Pascal string.
...                           # Zero padding.
# Cell Characteristics.
0x0107 active_material_mass   # Mass of active material
0x010B at_x                   # at x =
0x010F molecular_weight       # Molecular weight of active material
0x0113 atomic_weight          # Atomic weight of intercalated ion
0x0117 acquisition_start      # Acquisition started a: xo =
0x011B e_transferred          # Number of e- transferred
0x011E electrode_material     # Pascal string.
...                           # Zero Padding
0x01C0 electrolyte            # Pascal string.
...                           # Zero Padding, ???.
0x0211 electrode_area         # Electrode surface area
0x0215 reference_electrode    # Pascal string
...                           # Zero padding
0x024C characteristic_mass    # Characteristic mass
...                           # ???
0x025C battery_capacity       # Battery capacity C =
0x0260 battery_capacity_unit  # Unit of the battery capacity.
...                           # ???
# Technique parameters can randomly be found at 0x0572, 0x1845 or
# 0x1846. All you can do is guess and try until it fits.
0x1845 ns                     # Number of sequences.
0x1847 n_params               # Number of technique parameters.
0x1849 params                 # ns sets of n_params parameters.
...                           # ???

Data Module

0x0000 n_datapoints   # Number of datapoints.
0x0004 n_columns      # Number of values per datapoint.
0x0005 column_ids     # n_columns unique column IDs.
...
# Depending on module version, datapoints start 0x195, 0x196, or 0x3ef
# Length of each datapoint depends on number and IDs of columns.
0x0195 datapoints     # n_datapoints points of data.

Log Module

...                         # ???
0x0009 channel_number       # Zero-based channel number.
...                         # ???
0x00AB channel_sn           # Channel serial number.
...                         # ???
0x01F8 Ewe_ctrl_min         # Ewe ctrl range min.
0x01FC Ewe_ctrl_max         # Ewe ctrl range max.
...                         # ???
0x0249 ole_timestamp        # Timestamp in OLE format.
0x0251 filename             # Pascal String.
...                         # Zero padding, ???.
0x0351 host                 # IP address of host, Pascal string.
...                         # Zero padding.
0x0384 address              # IP address / COM port of potentiostat.
...                         # Zero padding.
0x03B7 ec_lab_version       # EC-Lab version (software)
...                         # Zero padding.
0x03BE server_version       # Internet server version (firmware)
...                         # Zero padding.
0x03C5 interpreter_version  # Command interpretor version (firmware)
...                         # Zero padding.
0x03CF device_sn            # Device serial number.
...                         # Zero padding.
0x0922 averaging_points     # Smooth data on ... points.
...                         # ???

Loop Module

0x0000 n_indexes  # Number of loop indexes.
0x0004 indexes    # n_indexes indexes at which loops start in data.
...               # ???

Metadata

The metadata will contain the information from the Settings module. This should include information about the technique, as well as any explicitly parsed cell characteristics data specified in EC-Lab.

The metadata also contains the infromation from the Log module, which contains more general parameters, like software, firmware and server versions, channel number, host address and an acquisition start timestamp in Microsoft OLE format.

Note

If the .mpr file contains an ExtDev module (containing parameters of any external sensors plugged into the device), the log is usually not present and therefore the full timestamp cannot be calculated.

Code author: Nicolas Vetsch, Peter Kraus,

yadg.extractors.eclab.mpr.process_settings(data: bytes, minver: str) → tuple[dict, list]

Processes the contents of settings modules.

Parameters:: data – The data to parse through.
Returns:: The parsed settings.
Return type:: dict

yadg.extractors.eclab.mpr.parse_columns(column_ids: list[int]) → tuple[list, list, list, dict]

Puts together column info from a list of data column IDs.

Note

The binary layout of the data in the .mpr file is described by a sequence of column IDs. Some column IDs relate to (flags) which are all packed into a single byte.

Parameters:: column_ids – A list of column IDs.
Returns:: The column names, dtypes, units and a dictionary of flag names and bitmasks.
Return type:: tuple[list, list, list, dict]

yadg.extractors.eclab.mpr.process_data(data: bytes, version: int, Eranges: list[float], Iranges: list[float], controls: list[str])

Processes the contents of data modules.

Parameters:

data – The data to parse through.
version – Module version from the data module header.

Returns:

Processed data ([{column -> value}, …, {column -> value}]). If the column unit is set to None, the value is an int. Otherwise, the value is a dict with value (“n”), sigma (“s”), and unit (“u”).

Return type:

list[dict]

yadg.extractors.eclab.mpr.process_log(data: bytes) → dict

Processes the contents of log modules.

Parameters:: data – The data to parse through.
Returns:: The parsed log.
Return type:: dict

yadg.extractors.eclab.mpr.process_loop(data: bytes) → dict

Processes the contents of loop modules.

Parameters:: data – The data to parse through.
Returns:: The parsed loops.
Return type:: dict

yadg.extractors.eclab.mpr.process_ext(data: bytes) → dict

Processes the contents of external device modules.

Parameters:: data – The data to parse through.
Returns:: The parsed log.
Return type:: dict

yadg.extractors.eclab.mpr.process_modules(contents: bytes) → tuple[dict, list, list, dict, dict]

Handles the processing of all modules.

Parameters:: contents – The contents of an .mpr file, minus the file magic.
Returns:: The processed settings, data, log, and loop modules. If they are not present in the provided modules, returns None instead.
Return type:: tuple[dict, list, dict, dict]

yadg.extractors.eclab.mpr.extract(*, fn: str, timezone: str, **kwargs: dict) → DataTree

yadg.extractors.eclab.mpr_columns module

yadg.extractors.eclab.mpt module

For processing of BioLogic’s EC-Lab binary modular files.

Usage

Available since yadg-4.0.

pydantic model dgbowl_schemas.yadg.dataschema_6_0.filetype.EClab_mpt

Config:

extra: str = forbid

Validators:

set_encoding » encoding

field filetype: Literal['eclab.mpt'] [Required]

field encoding: str | None = 'windows-1252'

Validated by:

set_encoding

validator set_encoding » encoding

Schema

The .mpt files contain many columns that vary depending on the electrochemical technique used. Below is shown a list of columns that can be expected to be present in a typical .mpt file.

xarray.DataTree:
  coords:
    uts:            !!float     # Unix timestamp, without date
  data_vars:
    Ewe             (uts)       # Potential of the working electrode
    Ece             (uts)       # Potential of the counter electrode, if present
    I               (uts)       # Instantaneous current
    time            (uts)       # Time elapsed since the start of the experiment
    <Ewe>           (uts)       # Average Ewe potential since last data point
    <Ece>           (uts)       # Average Ece potential since last data point
    <I>             (uts)       # Average current since last data point
    ...

Note

Note that in most cases, either the instantaneous or the averaged quantities are stored - only rarely are both available!

Notes on file structure

These human-readable files are sectioned into header lines and data lines. The header part of the .mpt files is made up of information that can be found in the settings, log and loop modules of the binary .mpr file.

If no header is present, the timestamps will instead be calculated from the file’s mtime().

Metadata

The metadata will contain the information from the header of the file.

Code author: Nicolas Vetsch, Peter Kraus

yadg.extractors.eclab.mpt.process_settings(lines: list[str]) → dict[str, str]

yadg.extractors.eclab.mpt.process_params(technique: str, lines: list[str], locale: str) → dict[str, Any]

yadg.extractors.eclab.mpt.process_external(lines: list[str]) → dict

yadg.extractors.eclab.mpt.process_header(lines: list[str], timezone: str, locale: str) → tuple[dict, list, dict]

Processes the header lines.

Parameters:: lines – The header lines, starting at line 3 (which is an empty line), right after the “Nb header lines : “ line.
Returns:: A dictionary containing the settings (and the technique parameters) and a dictionary containing the loop indexes.
Return type:: tuple[dict, dict]

yadg.extractors.eclab.mpt.process_data(lines: list[str], Eranges: list[float], Iranges: list[float], controls: list[str], locale: str)

Processes the data lines.

Parameters:: lines – The data lines, starting right after the last header section. The first line is an empty line, the column names can be found on the second line.
Returns:: A dictionary containing the datapoints in the format ([{column -> value}, …, {column -> value}]). If the column unit is set to None, the value is an int. Otherwise, the value is a dict with value (“n”), sigma (“s”), and unit (“u”).
Return type:: dict

yadg.extractors.eclab.mpt.extract(*, fn: str, encoding: str, locale: str, timezone: str, **kwargs: dict) → DataTree

yadg.extractors.eclab.mpt_columns module

yadg.extractors.eclab.techniques module

techniques: Parameters for implemented techniques.

Implemented techniques:

CA - Chronoamperometry / Chronocoulometry

CP - Chronopotentiometry

CV - Cyclic Voltammetry

CVA - Cyclic Voltammetry Advanced

GCPL - Galvanostatic Cycling with Potential Limitation

GEIS - Galvano Electrochemical Impedance Spectroscopy

LOOP - Loop

LSV - Linear Sweep Voltammetry

MB - Modulo Bat

OCV - Open Circuit Voltage

PEIS - Potentio Electrochemical Impedance Spectroscopy

WAIT - Wait

ZIR - IR compensation (PEIS)

MP - Modular Potentio

CoV - Constant Voltage

CoC - Constant Current

The module also implements resolution determination for parameters of techniques, in get_resolution().

Code author: Nicolas Vetsch, Peter Kraus, Carla Terboven

yadg.extractors.eclab.techniques.param_from_key(param: str, key: int | str, to_str: bool = True) → str | float

Convert a supplied key of a certain parameter to its string or float value.

The function uses the map defined in param_map to convert between the entries in the tuples, which contain the str value of the parameter (present in .mpt files), the int value of the parameter (present in .mpr files), and the corresponding float value in SI units.

Parameters:

param – The name of the parameter, a key within the param_map. If param is not present in param_map, the supplied key is returned back.
key – The key of the parameter that is to be converted to a different representation.
to_str – A switch between str and float output.

Returns:

key – The key converted to the requested format.

Return type:

Union[str, float, int]

yadg.extractors.eclab.techniques.dev_VI(name: str, value: float, unit: str, Erange: float, Irange: float) → float

Function that returns the resolution of a voltage or current based on its name, value, E-range and I-range.

The values used here are hard-coded from VMP-3 potentiostats.

yadg.extractors.eclab.techniques.dev_derived(name: str, unit: str, val: float, rtol_I: float, rtol_V: float, rtol_VI: float) → float

Function that returns the resolution of a derived quantity based on its unit, value, and the relative error in the current and voltage.

The values used here are hard-coded from VMP-3 potentiostats.

yadg.extractors.eclab.techniques.get_devs(vals: dict[str, Any], units: dict[str, str], Erange: float, Irange: float, devs: dict[str, float] | None = None) → dict[str, float]