eclab: For BioLogic data files
Subpackages
yadg.extractors.eclab.mpr module
For processing of BioLogic’s EC-Lab binary modular files.
Usage
Available since yadg-4.0.
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.
datatree.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.
These are the implemented techniques for which the technique parameter sequences can be parsed:
CA |
Chronoamperometry / Chronocoulometry |
CP |
Chronopotentiometry |
CV |
Cyclic Voltammetry |
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) |
At a top level, .mpr files are made up of a number of modules,
separated by the MODULE keyword. In all the files I 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.
TODO
https://github.com/dgbowl/yadg/issues/12
The mapping between metadata parameters between .mpr and .mpt files
is not yet complete. In .mpr files, some technique parameters in the settings
module correspond to entries in drop-down lists in EC-Lab. These values are
stored as single-byte values in .mpr files.
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
- 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.mpt module
For processing of BioLogic’s EC-Lab binary modular files.
Usage
Available since yadg-4.0.
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.
datatree.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 headerlines and datalines.
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.
Note
The mapping between metadata parameters between .mpr and .mpt files
is not yet complete.
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_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