Neware Reader

class ionworks.data.read.neware.Neware[source]

Bases: BaseReader

name: str = 'Neware'
default_options: dict[str, Any] = {'cell_metadata': {}, 'file_encoding': 'utf-8', 'sheets': None}
classmethod sniff_excel(filename: str | Path) → bool[source]

Return True if filename is a Neware .xls/.xlsx export.

Every sheet is checked, because a BTSDA workbook leads with a metadata sheet carrying none of the signature columns. Headers are read one row at a time rather than resolving the data sheet, so detection does not pay for the sheet-selection probe of a file it is about to reject.

The signature is deliberately looser than the sheet-selection criteria: a timestamp plus either current or voltage, so a workbook missing one of the two still routes here instead of failing detection.

Parameters:

filename (str | Path) – Path to the workbook to inspect.

Returns:

True when some sheet carries the Neware signature.

Return type:

bool

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

Read and process data from a Neware file (CSV or Excel).

Parameters:

  • filename (str | Path) – Path to the Neware file to be read (supports .csv, .xls, .xlsx).

  • extra_column_mappings (dict[str, str] | None, optional) –

    Dictionary of additional column mappings to use when reading the Neware file. The keys are the original column names and the values are the new column names; they take priority over the defaults. Default is None. The default mappings are:

    • ”Current (mA)”, “Cur(mA)” -> “Current [mA]”

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

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

    • ”Temperature 1 (degC)” -> “Temperature [degC]”

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

    • ”Cycle ID”, “Cycle”, “Cycle Index” -> “Cycle from cycler”

    • ”Status” -> “Status”

    • ”DateTime”, “Absolute Time”, “Date(h:min:s.ms)”, “Date” -> “Timestamp”

  • options (dict[str, str] | None, optional) –

    Dictionary of options to use when reading the Neware file. Supported options:

    • ’cell_metadata’: dictionary of metadata about the cell

    • ’file_encoding’: text encoding for CSV files. Default is ‘utf-8’. If UTF-8 decoding fails, the reader falls back to Latin-1-compatible encodings.

    • ’sheets’: dict specifying sheet selection for Excel files (.xls/.xlsx only). If not specified, the reader auto-selects the record sheet of a multi-sheet Neware BTSDA workbook when present, otherwise reads the first sheet (index 0). Format:

      • {‘type’: ‘name’, ‘value’: ‘Sheet1’} for single sheet

      • {‘type’: ‘name’, ‘value’: [‘Sheet1’, ‘Sheet2’]} for multiple sheets

      • {‘type’: ‘pattern’, ‘value’: ‘regex_pattern’} for pattern matching

      • {‘type’: ‘all’} to read all sheets

Returns:

Processed data from the Neware file with standardized column names and units. If multiple sheets are read, a ‘Sheet’ column is added to identify the source sheet.

Return type:

pandas.DataFrame

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

Read the start time from a Neware file (CSV or Excel).

Parameters:

  • filename (str | Path) – Path to the Neware file to be read (supports .csv, .xls, .xlsx).

  • extra_column_mappings (dict[str, str] | None, optional) – Dictionary of additional column mappings to use when reading the Neware file.

  • options (dict[str, str] | None, optional) – Options for reading the file. See ionworks.data.read.Neware.run(). Can include ‘sheets’ specification for Excel files.

Returns:

The start time of the Neware file.

Return type:

datetime

read_metadata(filename: str | Path, options: dict[str, str] | None = None) → dict[str, Any][source]

Read the descriptive metadata a Neware export carries.

Parameters:

  • filename (str | Path) – Path to the Neware file (.csv, .xls, or .xlsx).

  • options (dict[str, str] | None, optional) – Options for reading the file. See ionworks.data.read.Neware.run(). There is no timezone option: this reader treats Neware timestamps as UTC throughout (see _ensure_timestamp_datetime()), and the sheet’s own timestamps are read the same way, so the two agree.

Returns:

Fields grouped the way the measurement API defines them:

  • protocol["name"]: the schedule .xml, from Process name or the block’s Step file.

  • test_setup["channel_number"]: Channel.

  • test_setup["instrument"]: device, the cycler unit’s id.

  • test_setup["test_name"]: the export filename the Test information banner opens with.

  • test_setup["source_file_path"]: the path it was exported from.

  • test_setup["export_date"]: when it was exported, ISO.

  • test_setup["end_time"]: End time, ISO – the API models only start_time as a datetime of its own.

  • test_setup["notes"]: Remarks.

  • test_setup["cycler"]: this reader’s name.

  • start_time: from Starting time, else from read_start_time(), which reads the first data row. UTC, as everywhere else in this reader.

Keys the file does not carry are omitted. A .csv export and a single-sheet workbook have no Info sheet at all, so for those the result is the reader’s name plus start_time.

Return type:

dict[str, Any]