Maccor Reader

class ionworksdata.read.maccor.Maccor

Bases: BaseReader

default_options: dict[str, Any] = {'cell_metadata': {}, 'file_encoding': 'ISO-8859-1', 'skip_capacity_columns': False, 'time_offset_fix': -1, 'timezone': 'UTC'}
name: str = 'Maccor'
read_header(filename: str | Path, options: dict[str, str] | None = None) → str

Read the header from a Maccor file.

read_start_time(filename: str | Path, extra_column_mappings: dict[str, str] | None = None, options: dict[str, str] | None = None) → datetime | None

Read the start time from a Maccor file.

Parameters

filenamestr | Path

Path to the Maccor file to be read. Supports: - .txt files (tab-separated) - .csv files (comma-separated with units row) - .xls/.xlsx files (Excel format) - Files with .+3digits extension (e.g., .123, .456)

optionsdict of str to str, optional

See ionworksdata.read.Maccor.run().

Returns

datetime | None

The start time of the Maccor file, or None if not found.

run(filename: str | Path, extra_column_mappings: dict[str, str] | None = None, options: dict[str, str] | None = None) → DataFrame

Read and process data from a Maccor file. The following column mappings are applied by default:

  • “Voltage”, “Volts”, “Voltage (V)” -> “Voltage [V]”

  • “Current”, “Amps”, “Current (A)” -> “Current [A]”

  • “Prog Time”, “Test (Sec)”, “Test Time (sec)” -> “Time [s]”

  • “Test Time (Hr)” -> “Time [h]”

  • “Cycle”, “Cyc#”, “Cycle ID”, “Cycle P” -> “Cycle from cycler”

  • “Step”, “Step ID” -> “Step from cycler”

  • “LogTemp001”, “Temperature (°C)”, “EVTemp (C)” -> “Temperature [degC]”

  • “Status”, “State”, “MD” -> “Status”

  • “Capacity (Ah)”, “Capacity (AHr)”, “Cap. (Ah)” -> “Capacity [A.h]”

  • “Energy (Wh)”, “Energy (WHr)” -> “Energy [W.h]”

  • “Chg Capacity (Ah)”, “Chg Capacity (AHr)” -> “Charge capacity [A.h]”

  • “DChg Capacity (Ah)”, “DChg Capacity (AHr)” -> “Discharge capacity [A.h]”

  • “Chg Energy (Wh)”, “Chg Energy (WHr)” -> “Charge energy [W.h]”

  • “DChg Energy (Wh)”, “DChg Energy (WHr)” -> “Discharge energy [W.h]”

  • “DPT” -> “Timestamp” (parsed as datetime, used to compute “Time [s]”)

  • “Test Time” -> “Timestamp” (if datetime string, otherwise treated as numeric)

Additional column mappings can be provided via the extra_column_mappings parameter.

Note: Timestamp columns are parsed and used to compute “Time [s]” if not already present, then removed from the final output.

Parameters

filenamestr | Path

Path to the Maccor file to be read. Supports: - .txt files (tab-separated) - .csv files (comma-separated with units row) - .xls/.xlsx files (Excel format) - Files with .+3digits extension (e.g., .123, .456)

extra_column_mappingsdict of str to str, optional

Dictionary of additional column mappings to use when reading the Maccor file. The keys are the original column names and the values are the new column names. Default is None.

optionsdict of str to str, optional

Dictionary of options to use when reading the Maccor file. Options are:

  • file_encoding: str, optional

    Encoding format for the Maccor file. Default is “ISO-8859-1”. Note: encoding is not used for Excel files.

  • timezone: str, optional

    Timezone to use for the Maccor file. Default is “UTC”.

  • time_offset_fix: float, optional

    Minimum time difference to enforce between consecutive points. If -1 (default), raises ValueError when time decreases or duplicates. If >= 0, ensures all time differences are at least this value using vectorized operations: fixed_diff = max(diff(time), time_offset_fix), then reconstructs time via cumsum.

  • skip_capacity_columns: bool, optional

    If True, skip reading capacity and energy columns from the raw file. This forces ionworksdata to compute capacity/energy from current/power integration instead. Useful when raw capacity data has resets or other issues. Default is False.

Returns

pl.DataFrame

Processed data from the Maccor file with standardized column names and units.

Notes

This function reads a Maccor file, processes the data, and returns a DataFrame with standardized column names and units. It also handles data cleaning and formatting tasks such as removing NaN values and adjusting the time to start at zero. Supports multiple file formats including text files (.txt, .+3digits), CSV files, and Excel files (.xls, .xlsx).