Readers¶

Augment the summary frame with one value per cycle pulled from raw.

For every cycle present in self.data.summary, group the raw rows of column by cycle_index and reduce them with method. The result is written onto the summary frame in place.

Parameters:

• column (str) –

  name of the column in self.data.raw to look up.

• method (str, default: 'last' ) –

  groupby reducer applied per cycle. One of "last" (default), "first", "mean", "min", "max".

• new_name (Optional[str], default: None ) –

  name to use for the new summary column. Defaults to column.

Returns:

• CellpyCell –

  self (chainable).

Raises:

• ValueError –

  if column is not present in the raw frame or method is not one of the supported reducers.

• NoDataFound –

  propagated from self.data if no data is loaded.

Check the stats for the files (raw-data and cellpy hdf5).

This method checks if the hdf5 file and the res-files have the same timestamps etc. to find out if we need to bother to load .res -files.

if detailed is set to True, the method returns dict containing True or False for each individual raw-file. If not, it returns False if the raw files are newer than the cellpy hdf5-file (i.e. update is needed), else True.

Parameters:

• cellpyfile (str) –

  filename of the cellpy hdf5-file.

• rawfiles (list of str) –

  name(s) of raw-data file(s).

• detailed (bool, default: False ) –

  return a dict containing True or False for each individual raw-file.

Returns:

• –

  Bool or dict

Select middle part of experiment. See :func:cellpy.readers.slicing.drop_edges.

Select first part of experiment up to cycle. See :func:cellpy.readers.slicing.drop_from.

Select last part of experiment from cycle. See :func:cellpy.readers.slicing.drop_to.

Return a filtered copy of the summary DataFrame.

Thin wrapper around :func:cellpy.filters.filter_summary that resolves the rate column names from self.headers_summary. See the underlying function for the full range semantics; in short (low, high) keeps rows where low < value <= high and {"value": v, "delta": d} keeps rows where v - d < value <= v + d.

Parameters:

• rate –

  Range filter applied to the rate columns. None disables it (default).

• rate_columns –

  Override which rate columns are filtered. Defaults to both (headers_summary.charge_c_rate, headers_summary.discharge_c_rate). Pass a single string to filter on only one side.

• **extra_filters –

  Additional range filters registered with :func:cellpy.filters.register_range_filter.

Returns:

• –

  Filtered copy of self.data.summary (cycle index reset

• –

  to a column so the result is a plain DataFrame).

Select experiment from cycle number. See :func:cellpy.readers.slicing.from_cycle.

Load a raw data-file.

Parameters:

• file_names (list of raw-file names, default: None ) –

  uses CellpyCell.file_names if None. If the list contains more than one file name, then the runs will be merged together. Remark! the order of the files in the list is important.

• pre_processor_hook (callable, default: None ) –

  function that will be applied to the data within the loader.

• post_processor_hook (callable, default: None ) –

  function that will be applied to the cellpy.Dataset object after initial loading.

• is_a_file (bool, default: True ) –

  set this to False if it is a not a file-like object.

• refuse_copying (bool, default: False ) –

  if set to True, the raw-file will not be copied before loading.

Gets the capacity for the run. See :func:cellpy.readers.capacity_curves.get_cap.

Returns charge capacity and voltage for the selected cycle. See :func:cellpy.readers.capacity_curves.get_ccap.

Convert from absolute units to specific (areal or gravimetric).

The method provides a conversion factor that you can multiply your values with to get them into specific values.

Parameters:

• dataset (Data, default: None ) –

  data instance

• value (float, default: None ) –

  value used to scale on.

• from_units (CellpyUnits, default: None ) –

  defaults to data.raw_units.

• to_units (CellpyUnits, default: None ) –

  defaults to cellpy_units.

• mode (str, default: 'gravimetric' ) –

  gravimetric, areal or absolute

Returns:

• float –

  conversion factor (float)

Returns current (in raw units).

Parameters:

• cycle –

  cycle number (all cycles if None).

• with_index –

  if True, includes the cycle index as a column in the returned pandas.DataFrame.

• with_time –

  if True, includes the time as a column in the returned pandas.DataFrame.

• as_frame –

  if not True, returns a list of current values as numpy arrays (one for each cycle). Remark that with_time and with_index will be False if as_frame is set to False.

Returns:

• –

  pandas.DataFrame (or list of pandas.Series if cycle=None and as_frame=False)

Get a array containing the cycle numbers in the test.

Parameters:

• steptable (DataFrame, default: None ) –

  the step-table to use (if None, the step-table from the cellpydata object will be used).

• rate (float, default: None ) –

  the rate to filter on. Remark that it should be given as a float, i.e. you will have to convert from C-rate to the actual numeric value. For example, use rate=0.05 if you want to filter on cycles that has a C/20 rate.

• rate_on (str, default: None ) –

  only select cycles if based on the rate of this step-type (e.g. on="discharge").

• rate_std (float, default: None ) –

  allow for this inaccuracy in C-rate when selecting cycles

• rate_agg (str, default: 'first' ) –

  perform an aggregation on rate if more than one step of charge or discharge is found (e.g. "mean", "first", "max"). For example, if agg='mean', the average rate for each cycle will be returned. Set to None if you want to keep all the rates.

• inverse (bool, default: False ) –

  select steps that does not have the given C-rate.

Returns:

• –

  numpy.ndarray of cycle numbers.

Returns datetime (in raw units).

Parameters:

• cycle –

  cycle number (all cycles if None).

• with_index –

  if True, includes the cycle index as a column in the returned pandas.DataFrame.

• with_time –

  if True, includes the time as a column in the returned pandas.DataFrame.

• as_frame –

  if not True, returns a list of current values as numpy arrays (one for each cycle). Remark that with_time and with_index will be False if as_frame is set to False.

Returns:

• –

  pandas.DataFrame (or list of pandas.Series if cycle=None and as_frame=False)

Returns discharge capacity and voltage for the selected cycle. See :func:cellpy.readers.capacity_curves.get_dcap.

Get the IR data (Deprecated).

Returns the mass of the active material (in mg).

This method will be deprecated in the future.

Get the number of cycles in the test.

Get the open circuit voltage relaxation curves. See :func:cellpy.readers.capacity_curves.get_ocv.

Get the rates in the test (only valid for constant current).

Parameters:

• steptable –

  provide custom steptable (if None, the steptable from the cellpydata object will be used).

• agg (str, default: 'first' ) –

  perform an aggregation if more than one step of charge or discharge is found (e.g. "mean", "first", "max"). For example, if agg='mean', the average rate for each cycle will be returned. Set to None if you want to keep all the rates.

• direction (str or list of str, default: None ) –

  only select rates for this direction (e.g. "charge" or "discharge").

Returns:

• –

  pandas.DataFrame with cycle, type, and rate_avr (i.e. C-rate) columns.

Returns the values for column with given header (in raw units).

Parameters:

• header –

  header name.

• cycle (Optional[Union[Iterable, int]], default: None ) –

  cycle number (all cycles if None).

• with_index (bool, default: True ) –

  if True, includes the cycle index as a column in the returned pandas.DataFrame.

• with_step (bool, default: False ) –

  if True, includes the step index as a column in the returned pandas.DataFrame.

• with_time (bool, default: False ) –

  if True, includes the time as a column in the returned pandas.DataFrame.

• additional_headers (list, default: None ) –

  additional headers to include in the returned pandas.DataFrame.

• as_frame (bool, default: True ) –

  if not True, returns a list of current values as numpy arrays (one for each cycle). Remark that with_time and with_index will be False if as_frame is set to False.

• scaler (Optional[float], default: None ) –

  if not None, the returned values are scaled by this value.

Returns:

• Union[DataFrame, List[array]] –

  pandas.DataFrame (or list of numpy arrays if as_frame=False)

Get the step numbers of selected type.

Returns the selected step_numbers for the selected type of step(s). Either in a dictionary containing a list of step numbers corresponding to the selected steptype for the cycle(s), or a pandas.DataFrame instead of a dict of lists if pdtype is set to True. The frame is a sub-set of the step-table frame (i.e. all the same columns, only filtered by rows).

Parameters:

• steptype (str, default: 'charge' ) –

  string identifying type of step.

• allctypes (bool, default: True ) –

  get all types of charge (or discharge).

• pdtype (bool, default: False ) –

  return results as pandas.DataFrame

• cycle_number (int, default: None ) –

  selected cycle, selects all if not set.

• trim_taper_steps (int, default: None ) –

  number of taper steps to skip (counted from the end, i.e. 1 means skip last step in each cycle).

• steps_to_skip (list, default: None ) –

  step numbers that should not be included.

• steptable (DataFrame, default: None ) –

  optional steptable

Returns:

• Union[dict, Any] –

  dict or pandas.DataFrame

Examples:

>>> my_charge_steps = CellpyCell.get_step_numbers(
>>>    "charge",
>>>    cycle_number = 3
>>> )
>>> print my_charge_steps
{3: [5,8]}

Retrieve summary returned as a pandas DataFrame.

Returns timestamp.

Parameters:

• cycle –

  cycle number (all cycles if None).

• with_index –

  if True, includes the cycle index as a column in the returned pandas.DataFrame.

• as_frame –

  if not True, returns a list of current values as numpy arrays (one for each cycle). Remark that with_time and with_index will be False if as_frame is set to False.

• in_minutes –

  (deprecated, use units="minutes" instead) return values in minutes instead of seconds if True.

• units –

  return values in given time unit ("raw", "seconds", "minutes", "hours").

Returns:

• –

  pandas.DataFrame (or list of pandas.Series if cycle=None and as_frame=False)

Returns voltage (in raw units).

Parameters:

• cycle –

  cycle number (all cycles if None).

• with_index –

  if True, includes the cycle index as a column in the returned pandas.DataFrame.

• with_time –

  if True, includes the time as a column in the returned pandas.DataFrame.

• as_frame –

  if not True, returns a list of current values as numpy arrays (one for each cycle). Remark that with_time and with_index will be False if as_frame is set to False.

Returns:

• –

  pandas.DataFrame (or list of pandas.Series if cycle=None and as_frame=False)

Check if the raw data has data_point as column.

Check if the raw data has data_point as index.

Check if the raw data has no full duplicates.

Check if the raw data has no partial duplicates.

Initialize the CellpyCell object with empty Data instance.

Method for estimating the nominal capacity

Parameters:

• cycles (list of ints, default: None ) –

  the cycles where it is assumed that the data reaches nominal capacity.

Returns:

• –

  Nominal capacity (float).

Loads a cellpy file.

Parameters:

• cellpy_file ((OtherPath, str)) –

  Full path to the cellpy file.

• parent_level (str, default: None ) –

  Parent level. Warning! Deprecating this soon!

• return_cls (bool, default: True ) –

  Return the class.

• accept_old (bool, default: False ) –

  Accept loading pre-v8 cellpy-file versions. Default is False (2.0 freeze): pre-v8 raises WrongFileVersion naming cellpy convert on 1.x. Pass True only as an escape (tests / advanced use). Prefer rewriting with cellpy convert instead.

• selector (dict, default: None ) –

  Experimental feature - select specific ranges of data.

Returns:

• –

  cellpy.CellpyCell class if return_cls is True

Load a table that contains step-type definitions.

This method loads a file containing a specification for each step or for each (cycle_number, step_number) combinations if short==False, and runs the make_step_table method. The step_cycle specifications that are allowed are stored in the variable cellreader.list_of_step_types.

Parameters:

• file_name (str) –

  name of the file to load

• short (bool, default: False ) –

  if True, the file only contains step numbers and step types. If False, the file contains cycle numbers as well.

Returns:

• –

  None

Loads data for given cells (soon to be deprecated).

Parameters:

• raw_files (list) –

  name of res-files

• cellpy_file (path, default: None ) –

  name of cellpy-file

• mass (float or str, default: None ) –

  mass of electrode or active material in cellpy_units (default mg). Pass a string with unit (e.g. "1.14 mg") to override cellpy_units.

• summary_on_raw (bool, default: True ) –

  calculate summary if loading from raw

• summary_on_cellpy_file (bool, default: True ) –

  calculate summary if loading from cellpy-file.

• find_ir (bool, default: True ) –

  summarize ir

• find_end_voltage (bool, default: True ) –

  summarize end voltage

• force_raw (bool, default: False ) –

  only use raw-files

• use_cellpy_stat_file (bool, default: None ) –

  use stat file if creating summary from raw

• cell_type (str, default: None ) –

  set the data type (e.g. "anode"). If not, the default from the config file is used.

• loading (float or str, default: None ) –

  loading in units [mass] / [area] (cellpy_units), used to calculate area if area not given.

• area (float or str, default: None ) –

  area of active electrode in cellpy_units (default cm2). Pass a string with unit (e.g. "2.12 cm2") to override cellpy_units.

• estimate_area (bool, default: True ) –

  calculate area from loading if given (defaults to True).

• selector (dict, default: None ) –

  passed to load.

• **kwargs –

  passed to from_raw

Examples:

>>> srnos = my_dbreader.select_batch("testing_new_solvent")
>>> cell_datas = []
>>> for srno in srnos:
>>> ... my_run_name = my_dbreader.get_cell_name(srno)
>>> ... mass = my_dbreader.get_mass(srno)
>>> ... rawfiles, cellpyfiles =             >>> ...     filefinder.search_for_files(my_run_name)
>>> ... cell_data = cellreader.CellpyCell()
>>> ... cell_data.loadcell(raw_files=rawfiles,
>>> ...                    cellpy_file=cellpyfiles)
>>> ... cell_data.set_mass(mass)
>>> ... cell_data.make_summary() # etc. etc.
>>> ... cell_datas.append(cell_data)
>>>

Create a table (v.4) that contains summary information for each step.

This function creates a table containing information about the different steps for each cycle and, based on that, decides what type of step it is (e.g. charge) for each cycle.

The format of the steps is:

• index: cycleno - stepno - sub-step-no - ustep
• Time info: average, stdev, max, min, start, end, delta
• Logging info: average, stdev, max, min, start, end, delta
• Current info: average, stdev, max, min, start, end, delta
• Voltage info: average, stdev, max, min, start, end, delta
• Type: (from pre-defined list) - SubType
• Info: not used.

Parameters:

• step_specifications (DataFrame, default: None ) –

  step specifications

• short (bool, default: False ) –

  step specifications in short format

• override_step_types (dict, default: None ) –

  override the provided step types, for example set all steps with step number 5 to "charge" by providing {5: "charge"}.

• override_raw_limits (dict, default: None ) –

  override the instrument limits (resolution), for example set 'current_hard' to 0.1 by providing {'current_hard': 0.1}.

• profiling (bool, default: False ) –

  turn on profiling

• usteps (bool, default: False ) –

  investigate all steps including same steps within one cycle (this is useful for e.g. GITT).

• add_c_rate (bool, default: True ) –

  include a C-rate estimate in the steps

• skip_steps (list of integers, default: None ) –

  list of step numbers that should not be processed (future feature - not used yet).

• sort_rows (bool, default: True ) –

  sort the rows after processing.

• from_data_point (int, default: None ) –

  first data point to use.

• nom_cap_specifics (str, default: None ) –

  "gravimetric", "areal", or "absolute".

Returns:

• –

  None

Convenience function that makes a summary of the cycling data.

Parameters:

• find_ir (bool, default: False ) –

  if True, the internal resistance will be calculated.

• find_end_voltage (bool, default: True ) –

  if True, the end voltage will be calculated.

• use_cellpy_stat_file (bool, default: None ) –

  if True, the summary will be made from the cellpy_stat file (soon to be deprecated).

• ensure_step_table (bool, default: True ) –

  if True, the step-table will be made if it does not exist.

• remove_duplicates (bool, default: True ) –

  if True, duplicates will be removed from the summary.

• normalization_cycles (int or list of int, default: None ) –

  cycles to use for normalization.

• nom_cap (float or str, default: None ) –

  nominal capacity (if None, the nominal capacity from the data will be used).

• nom_cap_specifics (str, default: None ) –

  gravimetric, areal, or volumetric.

• create_copy (bool, default: False ) –

  if True, a copy of the cellpy object will be returned.

• exclude_types (list of str, default: None ) –

  deprecated, has no effect.

• exclude_steps (list of int, default: None ) –

  deprecated, has no effect.

• selector_type (str, default: None ) –

  deprecated, has no effect.

• selector (callable, default: None ) –

  deprecated, has no effect.

• exclude_step_types (list of str, default: None ) –

  step-type prefixes whose capacity contributions are excluded from the summary (issue #509, core #54). E.g. ["cv_"] matches cv_charge and cv_discharge; the capacity gained during the excluded steps is subtracted per cycle from the cycle-end charge/discharge capacities before derived columns (coulombic efficiency, losses, cumulated and specific columns) are computed — a summary "as if those steps never happened". Replaces the removed selector-based exclusion.

• **kwargs –

  additional keyword arguments sent to internal method (check source for info).

Returns:

• –

  cellpy.CellpyData: cellpy object with the summary added to it.

Merge other cells/datasets into this one.

Two distinct semantics (issue #507, epic #402 V2-03/V2-07):

• mode="campaign" (default): the sources are different tests (possibly different cells or programs). Each source keeps its identity via a distinct compact test_id stamped on the raw frame (this overwrites tester-assigned ids such as Arbin's Test_ID — those remain as provenance in meta_test_dependent.test_ID), and its metadata becomes a record in self.data.tests. Cycle numbers are renumbered to be globally unique by default (see renumber_cycles); data points are offset; test_time / date_time are not shifted (independent timelines). Sources are never mutated. Mixing different cycle_mode values is allowed here, but computing steps/summary on the merged object then raises MixedCycleModesError.
• mode="continuation": the sources are the same physical test resumed across files — the classic fold, numerically identical to from_raw([file1, file2]) (cycles, data points and test time are renumbered into one continuous run; source metadata is dropped). Extra **kwargs (e.g. recalc) are forwarded.

Parameters:

• cells –

  a CellpyCell or Data instance, or a sequence of them.

• mode (str, default: 'campaign' ) –

  "campaign" (default) or "continuation".

• renumber_cycles (bool, default: True ) –

  campaign mode only. If True (default), cycle numbers are renumbered to be globally unique. If False (#529, needs cellpycore >= 0.2.2), sources keep their original cycle numbers: the identifying key becomes (test_id, cycle) and cycle numbers repeat across tests — cycle-keyed consumers (get_cap(cycle=...), split / with_cycles, exporters) then operate on the union of the matching cycles. Data points are always offset to stay globally unique.

• **kwargs –

  forwarded to the continuation fold.

Returns:

• –

  self (chainable), with self.data holding the merged object.

Split cycle(s) into several cycles. See :func:cellpy.readers.slicing.mod_raw_split_cycle.

Get the nominal capacity as absolute value.

Delegated to cellpycore.units.nominal_capacity_as_absolute (#451, unit plan Phase 2). A DimensionalityError here usually means the nominal capacity is given in a different unit than the chosen nom_cap_specifics — e.g. nom_cap='1.2 mAh/cm**2' with gravimetric specifics; pass nom_cap_specifics='areal' (or set it on the cell before processing).

Print the step table.

Register instrument readers.

Builds the default factory only when none is set — an injected instrument_factory (#520, DI) is kept as-is. Set self.instrument_factory = None first to force a rebuild.

Save the data structure to cellpy-format.

Default on-disk format is v9 (zip-of-parquet + meta.json, .cellpy). Pass cellpy_file_format="hdf5" / "v8" or a .h5 / .hdf5 path to write the legacy HDF5 layout.

Parameters:

• filename –

  (str or pathlib.Path) the name you want to give the file

• force –

  (bool) save a file even if the summary is not made yet (not recommended)

• overwrite –

  (bool) save the new version of the file even if old one exists.

• extension –

  (str) filename extension when filename has no suffix (default cellpy).

• ensure_step_table –

  (bool) make step-table if missing.

• ensure_summary_table –

  (bool) make summary-table if missing.

• cellpy_file_format –

  (str | None) "v9" / "cellpy" (default), or "hdf5" / "v8" for the legacy HDF5 writer. When omitted, inferred from the path suffix (.h5/.hdf5 → hdf5, otherwise v9).

Returns:

• –

  None

Set the directory containing .hdf5-files.

Used for setting directory for looking for hdf5-files. A valid directory name is required.

Parameters:

• directory (str, default: None ) –

  path to hdf5-directory

Examples:

>>> d = CellpyCell()
>>> directory = "MyData/HDF5"
>>> d.set_raw_datadir(directory)

Set selected columns first in a pandas.DataFrame.

This function sets cols with names given in col_names (a list) first in the DataFrame. The last col in col_name will come first (processed last)

Set the instrument (i.e. tell cellpy the file-type you use).

Three different modes of setting instruments are currently supported. You can provide the already supported instrument names (see the documentation, e.g. "arbin_res"). You can use the "custom" loader by providing the path to a yaml-file describing the file format. This can be done either by setting instrument to "instrument_name::instrument_definition_file_name", or by setting instrument to "custom" and provide the definition file name through the instrument_file keyword argument. A last option exists where you provide the yaml-file name directly to the instrument parameter. Cellpy will then look into your local instrument folder and search for the yaml-file. Some instrument types also supports a model key-word.

Parameters:

• instrument –

  (str) in ["arbin_res", "maccor_txt",...]. If instrument ends with ".yml" a local instrument file will be used. For example, if instrument is "my_instrument.yml", cellpy will look into the local instruments folders for a file called "my_instrument.yml" and then use LocalTxtLoader to load after registering the instrument. If the instrument name contains a '::' separator, the part after the separator will be interpreted as 'instrument_file'.

• model –

  (str) optionally specify if the instrument loader supports handling several models (some instruments allow for exporting data in slightly different formats depending on the choices made during the export or the model of the instrument, e.g. different number of header lines, different encoding).

• instrument_file –

  (path) instrument definition file,

• unit_test –

  (bool) set to True if you want to print the settings instead of setting them.

• kwargs (dict, default: {} ) –

  key-word arguments sent to the initializer of the loader class

Set the directory containing .res-files.

Used for setting directory for looking for res-files. A valid directory name is required.

Parameters:

• directory (str, default: None ) –

  path to res-directory

Examples:

>>> d = CellpyCell()
>>> directory = "MyData/cycler-data"
>>> d.set_raw_datadir(directory)

Returns current for cycle, step.

Convenience function; same as issuing::

raw[(raw[cycle_index_header] == cycle) & (raw[step_index_header] == step)][current_header]

Parameters:

• cycle –

  cycle number

• step –

  step number

Returns:

• –

  pandas.Series or None if empty

Returns step number for cycle, step.

Convenience function; same as issuing::

raw[(raw[cycle_index_header] == cycle) &
     (raw[step_index_header] == step)][step_index_header]

Parameters:

• cycle –

  cycle number

• step –

  step number (can be a list of several step numbers)

Returns:

• –

  pandas.Series

Returns step time for cycle, step.

Convenience function; Convenience function; same as issuing::

raw[(raw[cycle_index_header] == cycle) & (raw[step_index_header] == step)][step_time_header]

Parameters:

• cycle –

  cycle number

• step –

  step number

Returns:

• –

  pandas.Series or None if empty

Returns timestamp for cycle, step.

Convenience function; same as issuing::

raw[(raw[cycle_index_header] == cycle) &
     (raw[step_index_header] == step)][timestamp_header]

Parameters:

• cycle –

  cycle number

• step –

  step number (can be a list of several step numbers)

Returns:

• –

  pandas.Series

Returns voltage for cycle, step.

Convenience function; same as issuing::

raw[(raw[cycle_index_header] == cycle) &
     (raw[step_index_header] == step)][voltage_header]

Parameters:

• cycle –

  cycle number

• step –

  step number

Returns:

• –

  pandas.Series or None if empty

Split experiment into two sub-experiments. See :func:cellpy.readers.slicing.split.

Split experiment into several sub-experiments. See :func:cellpy.readers.slicing.split_many.

Export the raw time-series in Battery Data Format (BDF).

See Battery Data Format <https://github.com/battery-data-alliance/battery-data-format>_ for the full specification.

Parameters:

• filename –

  Output path. If None or extensionless, a default <cell_name>.bdf.<format> (or <filename>.bdf.<format>) is used. An explicit suffix is honoured as-is.

• cycles –

  Optional cycle filter. None exports all cycles; an int exports that single cycle; an iterable of ints exports the listed cycles. Combines with last_cycle.

• last_cycle –

  If given, drop rows whose cycle index exceeds last_cycle.

• header_style –

  "preferred" (default, BDF spec) writes headers like "Test Time / s". "machine" writes machine-readable names like "test_time_second".

• format –

  "csv" (default) or "parquet".

• extras –

  Append columns from data.raw that are not in the BDF column map. False (default) exports only the BDF columns. True appends every unmapped raw column verbatim (no unit conversion, original name preserved). A string or iterable of strings restricts the appended columns to the listed names. The resulting file is no longer strictly BDF-compliant.

• preprocess_fn –

  A function that takes the raw DataFrame and returns a new DataFrame. This function is applied to the raw DataFrame after the cycle filter and before the BDF export.

• bdf_units –

  Optional :class:~cellpy.parameters.internal_settings.CellpyUnits controlling the units written into the BDF file. None (default) emits a strictly BDF-compliant file (A, V, Ah, Wh, s, W, ohm). When set, each attribute on the CellpyUnits overrides the spec target for the corresponding column kind (charge → charge / discharge capacity, energy → charge / discharge energy, etc.); column labels and machine names are rebuilt from the override (e.g. "Charging Capacity / mAh" / "charging_capacity_mah") and values are scaled accordingly via pint. An incompatible unit (e.g. charge="kg") raises :class:ValueError. A file written with overrides is no longer strictly BDF- compliant; this is logged once at INFO level.

  Example::

  from cellpy.parameters.internal_settings import CellpyUnits
  
  # write charge in mAh and current in mA
  bdf_units = CellpyUnits(charge="mAh", current="mA")
  cell.to_bdf("out.bdf.csv", bdf_units=bdf_units)
  

Returns:

• –

  pathlib.Path: The path that the file was written to.

Raises:

• ValueError –

  If the cell has no raw data, any BDF-required column is missing from data.raw, or bdf_units specifies a unit that cannot be converted from the cell's source unit.

Convert value to cellpy units.

Parameters:

• value ((numeric, Quantity or str)) –

  what you want to convert from

• physical_property (str) –

  What this value is a measure of (must correspond to one of the keys in the CellpyUnits class).

Returns (numeric): the value in cellpy units

Saves the data as .csv file(s). See :func:cellpy.exporters.tabular.to_csv.

Select experiment to cycle number. See :func:cellpy.readers.slicing.to_cycle.

Saves the data as .xlsx file(s). See :func:cellpy.exporters.tabular.to_excel.

Experimental method for getting the total time spent at low / high voltage.

Parameters:

• cycles –

  cycle number (all cycles if None).

• voltage_limit –

  voltage limit (default 0.5 V). Can be a tuple (low, high) if at="between".

• sampling_unit –

  sampling unit (default "S") H: hourly frequency T, min: minutely frequency S: secondly frequency L, ms: milliseconds U, us: microseconds N: nanoseconds

• at (str, default: 'low' ) –

  "low", "high", or "between" (default "low")

Get the conversion factor going from raw to given unit.

Parameters:

• unit (str) –

  what you want to convert to

• physical_property (str) –

  what this value is a measure of (must correspond to one of the keys in the CellpyUnits class).

Returns (numeric): conversion factor (scaler)

Create a CellpyCell instance.

Parameters:

• cell (CellpyCell instance, default: None ) –

  the attributes from the data will be copied to the new CellpyCell instance.

Returns:

• –

  CellpyCell instance.

Return quantity as pint.Quantity object.

Select a subset of cycles. See :func:cellpy.readers.slicing.with_cycles.