cellpy.readers package
Subpackages
- cellpy.readers.instruments package
- Subpackages
- cellpy.readers.instruments.configurations package
- Submodules
- cellpy.readers.instruments.configurations.maccor_txt_four module
- cellpy.readers.instruments.configurations.maccor_txt_one module
- cellpy.readers.instruments.configurations.maccor_txt_three module
- cellpy.readers.instruments.configurations.maccor_txt_two module
- cellpy.readers.instruments.configurations.maccor_txt_zero module
- cellpy.readers.instruments.configurations.neware_txt_zero module
- Module contents
- cellpy.readers.instruments.loader_specific_modules package
- cellpy.readers.instruments.processors package
- cellpy.readers.instruments.configurations package
- Submodules
- cellpy.readers.instruments.arbin_res module
- cellpy.readers.instruments.arbin_sql module
- cellpy.readers.instruments.arbin_sql_7 module
- cellpy.readers.instruments.arbin_sql_csv module
- cellpy.readers.instruments.arbin_sql_h5 module
- cellpy.readers.instruments.arbin_sql_xlsx module
- cellpy.readers.instruments.base module
AtomicLoad
AutoLoader
AutoLoader.get_headers_aux()
AutoLoader.get_raw_limits()
AutoLoader.get_raw_units()
AutoLoader.instrument_name
AutoLoader.loader()
AutoLoader.parse_formatter_parameters()
AutoLoader.parse_loader_parameters()
AutoLoader.parse_meta()
AutoLoader.pre_init()
AutoLoader.query_file()
AutoLoader.register_configuration()
AutoLoader.validate()
BaseLoader
TxtLoader
find_delimiter_and_start()
query_csv()
- cellpy.readers.instruments.biologics_mpr module
- cellpy.readers.instruments.custom module
- cellpy.readers.instruments.ext_nda_reader module
- cellpy.readers.instruments.local_instrument module
- cellpy.readers.instruments.maccor_txt module
- cellpy.readers.instruments.neware_txt module
- cellpy.readers.instruments.pec_csv module
- Module contents
- Subpackages
Submodules
cellpy.readers.cellreader module
Datareader for cell testers and potentiostats.
This module is used for loading data and databases created by different cell testers and exporing them in a common hdf5-format.
Example
>>> c = cellpy.get(["super_battery_run_01.res", "super_battery_run_02.res"]) # loads and merges the runs
>>> voltage_curves = c.get_cap()
>>> c.save("super_battery_run.hdf")
- class cellpy.readers.cellreader.CellpyCell(filenames=None, selected_scans=None, profile=False, filestatuschecker=None, tester=None, initialize=False, cellpy_units=None, output_units=None, debug=False)[source]
Bases:
object
Main class for working and storing data.
This class is the main work-horse for cellpy where all the functions for reading, selecting, and tweaking your data is located. It also contains the header definitions, both for the cellpy hdf5 format, and for the various cell-tester file-formats that can be read. The class can contain several cell-tests and each test is stored in a list. If you see what I mean…
- # TODO v.1.0.1
update this
- data
cellpy.Data object
- cellpy_units
cellpy.units object
- cellpy_datadir
path to cellpy data directory
- raw_datadir
path to raw data directory
- filestatuschecker
filestatuschecker object
- force_step_table_creation
force step table creation
- ensure_step_table
ensure step table
- limit_loaded_cycles
limit loaded cycles
- profile
profile
- select_minimal
select minimal
- empty
empty
- forced_errors
forced errors
- capacity_modifiers
capacity modifiers
- sep
separator
- cycle_mode
cycle mode
- tester
tester
- cell_name
cell name
- cellpy_file_version
cellpy file version
- property active_electrode_area
returns the area
- property cell_name
returns the session name
- check_file_ids(rawfiles, cellpyfile, detailed=False)[source]
Check the stats for the files (raw-data and cellpy hdf5).
This function 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.
- Parameters
cellpyfile (str) – filename of the cellpy hdf5-file.
rawfiles (list of str) – name(s) of raw-data file(s).
detailed (bool) – return a dict containing True or False for each individual raw-file.
- Returns
- False if the raw files are newer than the cellpy hdf5-file
(update needed). True if update is not needed.
- If detailed is True it returns a dict containing True or False for each
individual raw-file.
- Return type
If detailed is False
- property cycle_mode
- property data
returns the DataSet instance
- dev_update(file_names=None, **kwargs)[source]
Experimental method for updating a cellpy-file with new raw-files.
- dev_update_from_raw(file_names=None, data_points=None, **kwargs)[source]
This method is under development. Using this to develop updating files with only new data.
- dev_update_loadcell(raw_files, cellpy_file=None, mass=None, summary_on_raw=False, summary_ir=True, summary_end_v=True, force_raw=False, use_cellpy_stat_file=None, nom_cap=None, selector=None, **kwargs)[source]
Load cell from raw-files or cellpy-file.
This is an experimental method. It is not finished yet and the logics in this method will most likely be moved to other methods since new versions of cellpy is now based on the get method (it implements similar logic as loadcell, but is more flexible and easier to use).
- drop_edges(start, end)[source]
Select middle part of experiment (CellpyCell object) from cycle number ‘start’ to ‘end’
- drop_from(cycle=None)[source]
Select first part of experiment (CellpyCell object) up to cycle number ‘cycle’
- drop_to(cycle=None)[source]
Select last part of experiment (CellpyCell object) from cycle number ‘cycle’
- property empty
Gives True if the CellpyCell object is empty (or non-functional)
- from_raw(file_names=None, pre_processor_hook=None, post_processor_hook=None, is_a_file=True, refuse_copying=False, **kwargs)[source]
Load a raw data-file.
- Parameters
file_names (list of raw-file names) – uses CellpyCell.file_names if None. If the list contains more than one file name, then the runs will be merged together.
pre_processor_hook (callable) – function that will be applied to the data within the loader.
post_processor_hook (callable) – function that will be applied to the cellpy.Dataset object after initial loading.
is_a_file (bool) – set this to False if it is a not a file-like object.
refuse_copying (bool) – if set to True, the raw-file will not be copied before loading.
- Keyword Args for merging:
- recalc (bool): set to false if you don’t want cellpy to automatically shift cycle number
and time (e.g. add last cycle number from previous file to the cycle numbers in the next file).
- Other keywords depending on loader:
- [ArbinLoader]:
- bad_steps (list of tuples): (c, s) tuples of steps s (in cycle c)
to skip loading.
- data_points (tuple of ints): load only data from data_point[0] to
data_point[1] (use None for infinite). NOT IMPLEMENTED YET.
- get_cap(cycle=None, method='back-and-forth', insert_nan=None, shift=0.0, categorical_column=False, label_cycle_number=False, split=False, interpolated=False, dx=0.1, number_of_points=None, ignore_errors=True, dynamic=False, inter_cycle_shift=True, interpolate_along_cap=False, capacity_then_voltage=False, **kwargs)[source]
Gets the capacity for the run.
- Parameters
cycle (int) – cycle number.
method (string) – how the curves are given “back-and-forth” - standard back and forth; discharge (or charge) reversed from where charge (or discharge) ends. “forth” - discharge (or charge) continues along x-axis. “forth-and-forth” - discharge (or charge) also starts at 0 (or shift if not shift=0.0)
insert_nan (bool) – insert a np.nan between the charge and discharge curves. Defaults to True for “forth-and-forth”, else False
shift – start-value for charge (or discharge) (typically used when plotting shifted-capacity).
categorical_column – add a categorical column showing if it is charge or discharge.
label_cycle_number (bool) – add column for cycle number (tidy format).
split (bool) – return a list of c and v instead of the default that is to return them combined in a DataFrame. This is only possible for some specific combinations of options (neither categorical_column=True or label_cycle_number=True are allowed).
interpolated (bool) – set to True if you would like to get interpolated data (typically if you want to save disk space or memory). Defaults to False.
dx (float) – the step used when interpolating.
number_of_points (int) – number of points to use (over-rides dx) for interpolation (i.e. the length of the interpolated data).
ignore_errors (bool) – don’t break out of loop if an error occurs.
dynamic – for dynamic retrieving data from cellpy-file. [NOT IMPLEMENTED YET]
inter_cycle_shift (bool) – cumulative shifts between consecutive cycles. Defaults to True.
interpolate_along_cap (bool) – interpolate along capacity axis instead of along the voltage axis. Defaults to False.
capacity_then_voltage (bool) – return capacity and voltage instead of voltage and capacity. Defaults to False.
- Returns
pandas.DataFrame ((cycle) voltage, capacity, (direction (-1, 1))) unless split is explicitly set to True. Then it returns a tuple with capacity and voltage.
- get_ccap(cycle=None, converter=None, mode='gravimetric', as_frame=True, **kwargs)[source]
Returns charge-capacity and voltage for the selected cycle. :param cycle: cycle number. :type cycle: int :param converter: a multiplication factor that converts the values to specific values (i.e.
from Ah to mAh/g). If not provided (or None), the factor is obtained from the self.get_converter_to_specific() method.
- Parameters
mode (string) – ‘gravimetric’, ‘areal’ or ‘absolute’. Defaults to ‘gravimetric’. Used if converter is not provided (or None).
as_frame (bool) – if True: returns pd.DataFrame instead of capacity, voltage series.
- Returns
charge_capacity, voltage (pandas.Series or pandas.DataFrame if return_dataframe is True).
- get_converter_to_specific(dataset: Optional[Data] = None, value: Optional[float] = None, from_units: Optional[CellpyUnits] = None, to_units: Optional[CellpyUnits] = None, mode: str = 'gravimetric') float [source]
Convert from absolute units to specific (areal or gravimetric).
- Parameters
dataset – data instance
value – value used to scale on.
from_units – defaults to data.raw_units.
to_units – defaults to cellpy_units.
mode (str) – gravimetric, areal or absolute
- Returns
conversion factor (multiply with this to get your values into specific values).
- get_current(cycle=None, with_index=True, with_time=False, as_frame=True)[source]
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_cycle_numbers(steptable=None, rate=None, rate_on=None, rate_std=None, rate_column=None, inverse=False)[source]
Get a list containing all the cycle numbers in the test.
- Parameters
rate (float) – 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) – only select cycles if based on the rate of this step-type (e.g. on=”charge”).
rate_std (float) – allow for this inaccuracy in C-rate when selecting cycles
rate_column (str) – column header name of the rate column,
inverse (bool) – select steps that does not have the given C-rate.
- Returns
numpy.ndarray of cycle numbers.
- get_datetime(cycle=None, with_index=True, with_time=False, as_frame=True)[source]
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)
- get_dcap(cycle=None, converter=None, mode='gravimetric', as_frame=True, **kwargs)[source]
Returns discharge-capacity and voltage for the selected cycle :param cycle: cycle number. :type cycle: int :param converter: a multiplication factor that converts the values to specific values (i.e.
from Ah to mAh/g). If not provided (or None), the factor is obtained from the self.get_converter_to_specific() method.
- Parameters
mode (string) – ‘gravimetric’, ‘areal’ or ‘absolute’. Defaults to ‘gravimetric’. Used if converter is not provided (or None).
as_frame (bool) – if True: returns pd.DataFrame instead of capacity, voltage series.
**kwargs –
- Returns
discharge_capacity, voltage (pd.Series or pd.DataFrame if return_dataframe is True).
- get_ocv(cycles=None, direction='up', remove_first=False, interpolated=False, dx=None, number_of_points=None) DataFrame [source]
get the open circuit voltage relaxation curves.
- Parameters
cycles (list of ints or None) – the cycles to extract from (selects all if not given).
direction ("up", "down", or "both") – extract only relaxations that is performed during discharge for “up” (because then the voltage relaxes upwards) etc.
remove_first – remove the first relaxation curve (typically, the first curve is from the initial rest period between assembling the data to the actual testing/cycling starts)
interpolated (bool) – set to True if you want the data to be interpolated (e.g. for creating smaller files)
dx (float) – the step used when interpolating.
number_of_points (int) – number of points to use (over-rides dx) for interpolation (i.e. the length of the interpolated data).
- Returns
- A pandas.DataFrame with cycle-number, step-number, step-time, and
voltage columns.
- get_raw(header, cycle: Optional[Union[Iterable, int]] = None, with_index: bool = True, with_step: bool = False, with_time: bool = False, additional_headers: Optional[list] = None, as_frame: bool = True, scaler: Optional[float] = None) Union[DataFrame, List[array]] [source]
Returns the values for column with given header (in raw units).
- Parameters
header – header name.
cycle – cycle number (all cycles if None).
with_index – if True, includes the cycle index as a column in the returned pandas.DataFrame.
with_step – if True, includes the step index as a column in the returned pandas.DataFrame.
with_time – if True, includes the time as a column in the returned pandas.DataFrame.
additional_headers (list) – additional headers to include 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.
scaler – if not None, the returned values are scaled by this value.
- Returns
pandas.DataFrame (or list of numpy arrays if as_frame=False)
- get_step_numbers(steptype='charge', allctypes=True, pdtype=False, cycle_number=None, trim_taper_steps=None, steps_to_skip=None, steptable=None)[source]
Get the step numbers of selected type.
Returns the selected step_numbers for the selected type of step(s).
- Parameters
steptype (string) – string identifying type of step.
allctypes (bool) – get all types of charge (or discharge).
pdtype (bool) – return results as pandas.DataFrame
cycle_number (int) – selected cycle, selects all if not set.
trim_taper_steps (integer) – number of taper steps to skip (counted from the end, i.e. 1 means skip last step in each cycle).
steps_to_skip (list) – step numbers that should not be included.
steptable (pandas.DataFrame) – optional steptable
- Returns
- A dictionary containing a list of step numbers corresponding
to the selected steptype for the cycle(s).
- Returns 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).
Example
>>> my_charge_steps = CellpyCell.get_step_numbers( >>> "charge", >>> cycle_number = 3 >>> ) >>> print my_charge_steps {3: [5,8]}
- get_timestamp(cycle=None, with_index=True, as_frame=True, in_minutes=False, units='raw')[source]
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)
- get_voltage(cycle=None, with_index=True, with_time=False, as_frame=True)[source]
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)
- inspect_nominal_capacity(cycles=None)[source]
Method for estimating the nominal capacity
- Parameters
cycles (list of ints) – the cycles where it is assumed that the data reaches nominal capacity.
- Returns
Nominal capacity (float).
- link(**kwargs)[source]
Create a link to a cellpy file.
If the file is very big, it is sometimes better to work with the data out of memory (i.e. on disk). A CellpyCell object with a linked file will in most cases work as a normal object. However, some methods might be disabled. And it will be slower.
Notes
- 2020.02.08 - maybe this functionality is not needed and can be replaced
by using dask or similar?
- load(cellpy_file, parent_level=None, return_cls=True, accept_old=True, selector=None, **kwargs)[source]
Loads a cellpy file.
- Parameters
cellpy_file (OtherPath, str) – Full path to the cellpy file.
parent_level (str, optional) – Parent level. Warning! Deprecating this soon!
return_cls (bool) – Return the class.
accept_old (bool) – Accept loading old cellpy-file versions. Instead of raising WrongFileVersion it only issues a warning.
() (selector) – under development
- Returns
cellpy.CellPyCellpy class if return_cls is True
- load_step_specifications(file_name, short=False)[source]
Load a table that contains step-type definitions.
This function loads a file containing a specification for each step or for each (cycle_number, step_number) combinations if short==False. The step_cycle specifications that are allowed are stored in the variable cellreader.list_of_step_types.
- loadcell(raw_files, cellpy_file=None, mass=None, summary_on_raw=True, summary_on_cellpy_file=True, find_ir=True, find_end_voltage=True, force_raw=False, use_cellpy_stat_file=None, cell_type=None, loading=None, area=None, estimate_area=True, selector=None, **kwargs)[source]
Loads data for given cells.
- Parameters
raw_files (list) – name of res-files
cellpy_file (path) – name of cellpy-file
mass (float) – mass of electrode or active material
summary_on_raw (bool) – calculate summary if loading from raw
summary_on_cellpy_file (bool) – calculate summary if loading from cellpy-file.
find_ir (bool) – summarize ir
find_end_voltage (bool) – summarize end voltage
force_raw (bool) – only use raw-files
use_cellpy_stat_file (bool) – use stat file if creating summary from raw
cell_type (str) – set the data type (e.g. “anode”). If not, the default from the config file is used.
loading (float) – loading in units [mass] / [area], used to calculate area if area not given
area (float) – area of active electrode
estimate_area (bool) – calculate area from loading if given (defaults to True).
selector (dict) – passed to load.
**kwargs – passed to from_raw
Example
>>> 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) >>>
- make_step_table(step_specifications=None, short=False, profiling=False, all_steps=False, add_c_rate=True, skip_steps=None, sort_rows=True, from_data_point=None, nom_cap_specifics=None)[source]
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 (pandas.DataFrame) – step specifications
short (bool) – step specifications in short format
profiling (bool) – turn on profiling
all_steps (bool) – investigate all steps including same steps within one cycle (this is useful for e.g. GITT).
add_c_rate (bool) – include a C-rate estimate in the steps
skip_steps (list of integers) – list of step numbers that should not be processed (future feature - not used yet).
sort_rows (bool) – sort the rows after processing.
from_data_point (int) – first data point to use.
nom_cap_specifics (str) – “gravimetric”, “areal”, or “absolute”.
- Returns
None
- make_summary(find_ir=False, find_end_voltage=True, use_cellpy_stat_file=None, ensure_step_table=True, normalization_cycles=None, nom_cap=None, nom_cap_specifics=None)[source]
Convenience function that makes a summary of the cycling data.
- property mass
returns the mass
- mod_raw_split_cycle(data_points: List) None [source]
Split cycle(s) into several cycles.
- Parameters
data_points – list of the first data point(s) for additional cycle(s).
- property nom_cap
returns the nominal capacity
- property nom_cap_specifics
returns the nominal capacity specific
- nominal_capacity_as_absolute(value=None, specific=None, nom_cap_specifics=None, convert_charge_units=False)[source]
Get the nominal capacity as absolute value.
- populate_step_dict(step)[source]
Returns a dict with cycle numbers as keys and corresponding steps (list) as values.
- property raw_units
returns the raw_units dictionary
- save(filename, force=False, overwrite=None, extension='h5', ensure_step_table=None, ensure_summary_table=None)[source]
Save the data structure to cellpy-format.
- 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.
ensure_step_table – (bool) make step-table if missing.
ensure_summary_table – (bool) make summary-table if missing.
Returns: Nothing at all.
- set_cellpy_datadir(directory=None)[source]
Set the directory containing .hdf5-files.
Used for setting directory for looking for hdf5-files. A valid directory name is required.
- Parameters
directory (str) – path to hdf5-directory
Example
>>> d = CellpyCell() >>> directory = "MyData/HDF5" >>> d.set_raw_datadir(directory)
- static set_col_first(df, col_names)[source]
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_instrument(instrument=None, model=None, instrument_file=None, **kwargs)[source]
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,
kwargs (dict) – key-word arguments sent to the initializer of the loader class
Notes
If you are using a local instrument loader, you will have to register it first to the loader factory.
>>> c = CellpyCell() # this will automatically register the already implemented loaders >>> c.instrument_factory.register_builder(instrument_id, (module_name, path_to_instrument_loader_file))
It is highly recommended using the module_name as the instrument_id.
- set_raw_datadir(directory=None)[source]
Set the directory containing .res-files.
Used for setting directory for looking for res-files.@ A valid directory name is required.
- Parameters
directory (str) – path to res-directory
Example
>>> d = CellpyCell() >>> directory = "MyData/Arbindata" >>> d.set_raw_datadir(directory)
- sget_current(cycle, step)[source]
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
- sget_step_numbers(cycle, step)[source]
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
- sget_steptime(cycle, step)[source]
Returns step time for cycle, step.
- 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
- sget_timestamp(cycle, step)[source]
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
- sget_voltage(cycle, step)[source]
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(cycle=None)[source]
Split experiment (CellpyCell object) into two sub-experiments. if cycle is not give, it will split on the median cycle number
- split_many(base_cycles=None)[source]
Split experiment (CellpyCell object) into several sub-experiments.
- Parameters
base_cycles (int or list of ints) – cycle(s) to do the split on.
- Returns
List of CellpyCell objects
- to_cellpy_unit(value, physical_property)[source]
Convert value to cellpy units.
- Parameters
value (numeric, pint.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
- to_csv(datadir=None, sep=None, cycles=False, raw=True, summary=True, shifted=False, method=None, shift=0.0, last_cycle=None)[source]
Saves the data as .csv file(s).
- Parameters
datadir – folder where to save the data (uses current folder if not given).
sep – the separator to use in the csv file (defaults to CellpyCell.sep).
cycles – (bool) export voltage-capacity curves if True.
raw – (bool) export raw-data if True.
summary – (bool) export summary if True.
shifted (bool) – export with cumulated shift.
method (string) –
how the curves are given:
"back-and-forth" - standard back and forth; discharge (or charge) reversed from where charge (or discharge) ends. "forth" - discharge (or charge) continues along x-axis. "forth-and-forth" - discharge (or charge) also starts at 0 (or shift if not shift=0.0)
shift – start-value for charge (or discharge)
last_cycle – process only up to this cycle (if not None).
- Returns
Nothing
- to_excel(filename=None, cycles=None, raw=False, steps=True, nice=True, get_cap_kwargs=None, to_excel_kwargs=None)[source]
Saves the data as .xlsx file(s).
- Parameters
filename – name of the Excel file.
cycles – (None, bool, or list of ints) export voltage-capacity curves if given.
raw – (bool) export raw-data if True.
steps – (bool) export steps if True.
nice – (bool) use nice formatting if True.
get_cap_kwargs – (dict) kwargs for CellpyCell.get_cap method.
to_excel_kwargs – (dict) kwargs for pandas.DataFrame.to_excel method.
- unit_scaler_from_raw(unit, physical_property)[source]
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)
- cellpy.readers.cellreader.get(filename=None, instrument=None, instrument_file=None, cellpy_file=None, cycle_mode=None, mass: Optional[Union[str, Number]] = None, nominal_capacity: Optional[Union[str, Number]] = None, nom_cap_specifics=None, loading=None, area: Optional[Union[str, Number]] = None, estimate_area=True, logging_mode=None, auto_pick_cellpy_format=True, auto_summary=True, units=None, step_kwargs=None, summary_kwargs=None, selector=None, testing=False, refuse_copying=False, initialize=False, debug=False, **kwargs)[source]
Create a CellpyCell object
- Parameters
filename (str, os.PathLike, OtherPath, or list of raw-file names) – path to file(s) to load
instrument (str) – instrument to use (defaults to the one in your cellpy config file)
instrument_file (str or path) – yaml file for custom file type
cellpy_file (str, os.PathLike, or OtherPath) – if both filename (a raw-file) and cellpy_file (a cellpy file) is provided, cellpy will try to check if the raw-file is has been updated since the creation of the cellpy-file and select this instead of the raw file if cellpy thinks they are similar (use with care!).
logging_mode (str) – “INFO” or “DEBUG”
cycle_mode (str) – the cycle mode (e.g. “anode” or “full_cell”)
mass (float) – mass of active material (mg) (defaults to mass given in cellpy-file or 1.0)
nominal_capacity (float) – nominal capacity for the cell (e.g. used for finding C-rates)
nom_cap_specifics (str) – either “gravimetric” (pr mass), “areal” (per area), or “volumetric” (per volume)
loading (float) – loading in units [mass] / [area]
area (float) – active electrode area (e.g. used for finding the areal capacity)
estimate_area (bool) – calculate area from loading if given (defaults to True)
auto_pick_cellpy_format (bool) – decide if it is a cellpy-file based on suffix.
auto_summary (bool) – (re-) create summary.
units (dict) – update cellpy units (used after the file is loaded, e.g. when creating summary).
step_kwargs (dict) – sent to make_steps
summary_kwargs (dict) – sent to make_summary
selector (dict) – passed to load (when loading cellpy-files).
testing (bool) – set to True if testing (will for example prevent making .log files)
refuse_copying (bool) – set to True if you do not want to copy the raw-file before loading.
initialize (bool) – set to True if you want to initialize the CellpyCell object (probably only useful if you want to return a cellpy-file with no data in it)
debug (bool) – set to True if you want to debug the loader.
**kwargs – sent to the loader
- Keyword args (“arbin_res”):
bad_steps (list of tuples): (c, s) tuples of steps s (in cycle c) to skip loading [arbin_res]. dataset_number (int): the data set number (‘Test-ID’) to select if you are dealing
with arbin files with more than one data-set. Defaults to selecting all data-sets and merging them.
- data_points (tuple of ints): load only data from data_point[0] to
data_point[1] (use None for infinite).
increment_cycle_index (bool): increment the cycle index if merging several datasets (default True).
- Keyword args (“maccor_txt”, “neware_txt”, “local_instrument”, “custom”):
sep (str): separator used in the file. skip_rows (int): number of rows to skip in the beginning of the file. header (int): row number of the header. encoding (str): encoding of the file. decimal (str): decimal separator. thousand (str): thousand separator. pre_processor_hook (callable): pre-processors to use.
- Keyword args (“pec_csv”):
bad_steps (list): separator used in the file (not implemented yet).
- Returns
CellpyCell object (if successful, None if not)
Examples
>>> # read an arbin .res file and create a cellpy object with >>> # populated summary and step-table: >>> c = cellpy.get("my_data.res", instrument="arbin_res", mass=1.14, area=2.12, loading=1.2, nom_cap=155.2) >>> >>> # load a cellpy-file: >>> c = cellpy.get("my_cellpy_file.clp") >>> >>> # load a txt-file exported from Maccor: >>> c = cellpy.get("my_data.txt", instrument="maccor_txt", model="one") >>> >>> # load a raw-file if it is newer than the corresponding cellpy-file, >>> # if not, load the cellpy-file: >>> c = cellpy.get("my_data.res", cellpy_file="my_data.clp") >>> >>> # load a file with a custom file-description: >>> c = cellpy.get("my_file.csv", instrument_file="my_instrument.yaml") >>> >>> # load three subsequent raw-files (of one cell) and merge them: >>> c = cellpy.get(["my_data_01.res", "my_data_02.res", "my_data_03.res"]) >>> >>> # load a data set and get the summary charge and discharge capacities >>> # in Ah/g: >>> c = cellpy.get("my_data.res", units=dict(capacity="Ah")) >>> >>> # get an empty CellpyCell instance: >>> c = cellpy.get() # or c = cellpy.get(initialize=True) if you want to initialize it.
cellpy.readers.core module
This module contains several of the most important classes used in cellpy.
It also contains functions that are used by readers and utils. And it has the file version definitions.
- class cellpy.readers.core.BaseDbReader[source]
Bases:
object
Base class for database readers.
- class cellpy.readers.core.Data(**kwargs)[source]
Bases:
object
Object to store data for a cell-test.
This class is used for storing all the relevant data for a cell-test, i.e. all the data collected by the tester as stored in the raw-files, and user-provided metadata about the cell-test.
- property active_electrode_area
- property cell_name
- property empty
- property has_data
- property has_steps
check if the step table exists
- property has_summary
check if the summary table exists
- property mass
- property material
- property nom_cap
- property raw_id
- property start_datetime
- property tot_mass
- class cellpy.readers.core.FileID(filename: Optional[Union[str, OtherPath]] = None, is_db: bool = False)[source]
Bases:
object
class for storing information about the raw-data files.
This class is used for storing and handling raw-data file information. It is important to keep track of when the data was extracted from the raw-data files so that it is easy to know if the hdf5-files used for @storing “treated” data is up-to-date.
- name
Filename of the raw-data file.
- Type
str
- full_name
Filename including path of the raw-data file.
- Type
str
- size
Size of the raw-data file.
- Type
float
- last_modified
Last time of modification of the raw-data file.
- Type
datetime
- last_accessed
last time of access of the raw-data file.
- Type
datetime
- last_info_changed
st_ctime of the raw-data file.
- Type
datetime
- location
Location of the raw-data file.
- Type
str
- get_raw()[source]
Get a list with information about the file.
The returned list contains name, size, last_modified and location.
- property last_data_point
- class cellpy.readers.core.InstrumentFactory[source]
Bases:
object
- create(key: Optional[str], **kwargs)[source]
Create the instrument loader module and initialize the loader class.
- Parameters
key – instrument id
**kwargs – sent to the initializer of the loader class.
- Returns
instance of loader class.
- query(key: str, variable: str) Any [source]
performs a get_params lookup for the instrument loader.
- Parameters
key – instrument id.
variable – the variable you want to lookup.
- Returns
The value of the variable if the loaders get_params method supports it.
- register_builder(key: str, builder: Tuple[str, Any], **kwargs) None [source]
register an instrument loader module.
- Parameters
key – instrument id
builder – (module_name, module_path)
**kwargs – stored in the factory (will be used in the future for allowing to set defaults to the builders to allow for using .query).
- class cellpy.readers.core.PickleProtocol(level)[source]
Bases:
object
Context for using a specific pickle protocol.
- cellpy.readers.core.check64bit(current_system='python')[source]
checks if you are on a 64-bit platform
- cellpy.readers.core.collect_capacity_curves(cell, direction='charge', trim_taper_steps=None, steps_to_skip=None, steptable=None, max_cycle_number=None, **kwargs)[source]
Create a list of pandas.DataFrames, one for each charge step.
The DataFrames are named by its cycle number.
- Parameters
cell (
CellpyCell
) – objectdirection (str) –
trim_taper_steps (integer) – number of taper steps to skip (counted from the end, i.e. 1 means skip last step in each cycle).
steps_to_skip (list) – step numbers that should not be included.
steptable (
pandas.DataFrame
) – optional steptable.max_cycle_number (int) – only select cycles up to this value.
- Returns
list of pandas.DataFrames, list of cycle numbers, minimum voltage value, maximum voltage value
- cellpy.readers.core.find_all_instruments() Dict[str, Tuple[str, Path]] [source]
finds all the supported instruments
- cellpy.readers.core.generate_default_factory()[source]
This function searches for all available instrument readers and registers them in an InstrumentFactory instance.
- Returns
InstrumentFactory
- cellpy.readers.core.group_by_interpolate(df, x=None, y=None, group_by=None, number_of_points=100, tidy=False, individual_x_cols=False, header_name='Unit', dx=10.0, generate_new_x=True)[source]
Do a pandas.DataFrame.group_by and perform interpolation for all groups.
This function is a wrapper around an internal interpolation function in cellpy (that uses scipy.interpolate.interp1d) that combines doing a group-by operation and interpolation.
- Parameters
df (pandas.DataFrame) – the dataframe to morph.
x (str) – the header for the x-value (defaults to normal header step_time_txt) (remark that the default group_by column is the cycle column, and each cycle normally consist of several steps (so you risk interpolating / merging several curves on top of each other (not good)).
y (str) – the header for the y-value (defaults to normal header voltage_txt).
group_by (str) – the header to group by (defaults to normal header cycle_index_txt)
number_of_points (int) – if generating new x-column, how many values it should contain.
tidy (bool) – return the result in tidy (i.e. long) format.
individual_x_cols (bool) – return as xy xy xy … data.
header_name (str) – name for the second level of the columns (only applies for xy xy xy … data) (defaults to “Unit”).
dx (float) – if generating new x-column and number_of_points is None or zero, distance between the generated values.
generate_new_x (bool) –
create a new x-column by using the x-min and x-max values from the original dataframe where the method is set by the number_of_points key-word:
if number_of_points is not None (default is 100):
` new_x = np.linspace(x_max, x_min, number_of_points) `
else:
` new_x = np.arange(x_max, x_min, dx) `
- Returns: pandas.DataFrame with interpolated x- and y-values. The returned
dataframe is in tidy (long) format for tidy=True.
- cellpy.readers.core.humanize_bytes(b, precision=1)[source]
Return a humanized string representation of a number of b.
- cellpy.readers.core.identify_last_data_point(data)[source]
Find the last data point and store it in the fid instance
- cellpy.readers.core.interpolate_y_on_x(df, x=None, y=None, new_x=None, dx=10.0, number_of_points=None, direction=1, **kwargs)[source]
Interpolate a column based on another column.
- Parameters
df – DataFrame with the (cycle) data.
x – Column name for the x-value (defaults to the step-time column).
y – Column name for the y-value (defaults to the voltage column).
new_x (numpy array or None) – Interpolate using these new x-values instead of generating x-values based on dx or number_of_points.
dx – step-value (defaults to 10.0)
number_of_points – number of points for interpolated values (use instead of dx and overrides dx if given).
direction (-1,1) – if direction is negative, then invert the x-values before interpolating.
**kwargs – arguments passed to
scipy.interpolate.interp1d
- Returns: DataFrame with interpolated y-values based on given or
generated x-values.
- cellpy.readers.core.xldate_as_datetime(xldate, datemode=0, option='to_datetime')[source]
Converts a xls date stamp to a more sensible format.
- Parameters
xldate (str, int) – date stamp in Excel format.
datemode (int) – 0 for 1900-based, 1 for 1904-based.
option (str) – option in (“to_datetime”, “to_float”, “to_string”), return value
- Returns
datetime (datetime object, float, or string).
cellpy.readers.dbreader module
- class cellpy.readers.dbreader.Reader(db_file=None, db_datadir=None, db_datadir_processed=None, db_frame=None, batch=None, batch_col_name=None)[source]
Bases:
BaseDbReader
- filter_by_col(column_names)[source]
filters sheet/table by columns (input is column header)
The routine returns the serial numbers with values>1 in the selected columns.
- Parameters
column_names (list) – the column headers.
- Returns
pandas.DataFrame
- filter_by_col_value(column_name, min_val=None, max_val=None)[source]
filters sheet/table by column.
The routine returns the serial-numbers with min_val <= values >= max_val in the selected column.
- Parameters
column_name (str) – column name.
min_val (int) – minimum value of serial number.
max_val (int) – maximum value of serial number.
- Returns
pandas.DataFrame
- filter_by_slurry(slurry, appender='_')[source]
Filters sheet/table by slurry name.
Input is slurry name or list of slurry names, for example ‘es030’ or [“es012”,”es033”,”es031”].
- Parameters
slurry (str or list of strings) – slurry names.
appender (chr) – char that surrounds slurry names.
- Returns
List of serial_number (ints).
- from_batch(batch_name: str, include_key: bool = False, include_individual_arguments: bool = False) dict [source]
- print_serial_number_info(serial_number, print_to_screen=True)[source]
Print information about the run.
- Parameters
serial_number – serial number.
print_to_screen – runs the print statement if True, returns txt if not.
- Returns
txt if print_to_screen is False, else None.
- select_all(serial_numbers)[source]
Select rows for identification for a list of serial_number.
- Parameters
serial_numbers – list (or ndarray) of serial numbers
- Returns
pandas.DataFrame
- select_batch(batch, batch_col_name=None, case_sensitive=True, drop=True) List[int] [source]
Selects the rows in column batch_col_number.
- Parameters
batch – batch to select
batch_col_name – column name to use for batch selection (default: DbSheetCols.batch).
case_sensitive – if True, the batch name must match exactly (default: True).
drop – if True, all un-selected rows are dropped from the table (default: True).
- Returns
List of row indices
cellpy.readers.filefinder module
- cellpy.readers.filefinder.list_raw_file_directory(raw_file_dir: Optional[Union[OtherPath, Path, str]] = None, project_dir: Optional[Union[OtherPath, Path, str]] = None, extension: Optional[str] = None, levels: Optional[int] = 1, only_filename: Optional[bool] = False, with_prefix: Optional[bool] = True)[source]
Dumps the raw-file directory to a list.
- Parameters
raw_file_dir (path) – optional, directory where to look for run-files (default: read prm-file)
project_dir (path) – optional, subdirectory in raw_file_dir to look for run-files
extension (str) – optional, extension of run-files (without the ‘.’). If not given, all files will be listed.
levels (int, optional) – How many sublevels to list. Defaults to 1. If you want to list all sublevels, use listdir(levels=-1). If you want to list only the current level (no subdirectories), use listdir(levels=0).
only_filename (bool, optional) – If True, only the file names will be returned. Defaults to False.
with_prefix (bool, optional) – If True, the full path to the files including the prefix and the location (e.g. ‘scp://user@server.com/…’) will be returned. Defaults to True.
- Returns
list of file paths (only the actual file names).
- Return type
list of str
Notes
This function might be rather slow and memory consuming if you have a lot of files in your raw-file directory. If you have a lot of files, you might want to consider running this function in a separate process (e.g. in a separate python script or using multiprocessing).
The function currently returns the full path to the files from the root directory. It does not include the prefix (e.g. ssh://). Future versions might change this to either include the prefix or return the files relative to the
raw_file_dir
directory.
- cellpy.readers.filefinder.search_for_files(run_name: str, raw_extension: Optional[str] = None, cellpy_file_extension: Optional[str] = None, raw_file_dir: Optional[Union[OtherPath, Path, str]] = None, project_dir: Optional[Union[OtherPath, Path, str]] = None, cellpy_file_dir: Optional[Union[OtherPath, Path, str]] = None, prm_filename: Optional[Union[Path, str]] = None, file_name_format: Optional[str] = None, reg_exp: Optional[str] = None, sub_folders: Optional[bool] = True, file_list: Optional[List[str]] = None, pre_path: Optional[Union[OtherPath, Path, str]] = None) Tuple[List[str], str] [source]
Searches for files (raw-data files and cellpy-files).
- Parameters
run_name (str) – run-file identification.
raw_extension (str) – optional, extension of run-files (without the ‘.’).
cellpy_file_extension (str) – optional, extension for cellpy files (without the ‘.’).
raw_file_dir (path) – optional, directory where to look for run-files (default: read prm-file)
project_dir (path) – optional, subdirectory in raw_file_dir to look for run-files (default: read prm-file)
cellpy_file_dir (path) – optional, directory where to look for cellpy-files (default: read prm-file)
prm_filename (path) – optional parameter file can be given.
file_name_format (str) – format of raw-file names or a glob pattern (default: YYYYMMDD_[name]EEE_CC_TT_RR).
reg_exp (str) – use regular expression instead (defaults to None).
sub_folders (bool) – perform search also in sub-folders.
file_list (list of str) – perform the search within a given list of filenames instead of searching the folder(s). The list should not contain the full filepath (only the actual file names). If you want to provide the full path, you will have to modify the file_name_format or reg_exp accordingly.
pre_path (path or str) – path to prepend the list of files selected from the file_list.
- Returns
run-file names (list of strings) and cellpy-file-name (str of full path).