Data parsing

A collection of functions and classes for parsing experimental data into data sets that can then be analyzed and/or visualized.

Wrapper functions

pyimpspec.dataframe_to_data_sets(df, path, label='', degrees=True)

Takes a pandas.DataFrame object, checks if there are multiple frequency sweeps, and, if necessary, splits the data into multiple DataSet objects.

Parameters:

  • df (pandas.DataFrame) –

    The pandas.DataFrame to be converted. The object should contain columns for frequencies and either real and imaginary impedances, or the magnitudes and phases of impedances. Multiple labels are supported for the column headers and they are detected based on whether or not the header starts with one of the supported labels. The comparisons are case insensitive and inverted signs are detected based on if the column header starts with either a hyphen (-) or a minus sign (\(-\)).

    • Frequencies: ‘frequency’, ‘freq’, and ‘f’.

    • Real parts of the impedances: “z’”, ‘z_re’, ‘zre’, ‘z re’, ‘real’, and ‘re’.

    • Imaginary parts of the impedances: ‘z”’, “z’’, ‘z_im’, ‘zim’, ‘z im’, ‘imaginary’, ‘imag’, and ‘im’.

    • Magnitudes of the impedances: ‘|z|’, ‘z’, ‘magnitude’, ‘modulus’, ‘mag’, and ‘mod’.

    • Phases of the impedances: ‘phase’, ‘phz’, and ‘phi’.

  • path (Union[str, pathlib.Path]) – The path to the file that was used to create the pandas.DataFrame.

  • label (str, optional) – The label assigned to the new DataSet.

  • degrees (bool, optional) – Whether or not the phase data (if provided) is in degrees instead of radians.

Return type:

List[DataSet]

pyimpspec.get_parsers()

Get a mapping of file extensions to their corresponding parser functions.

Return type:

Dict[str, Callable]

pyimpspec.parse_data(path, file_format='', **kwargs)

Parse experimental data and return a list of DataSet instances. One or more specific sheets can be specified by name when parsing spreadsheets (e.g., .xlsx or .ods) to only return DataSet instances for those sheets. If no sheets are specified, then all sheets will be processed and the data from successfully parsed sheets will be returned as DataSet instances.

Parameters:

  • path (Union[str, pathlib.Path]) – The path to a file containing experimental data that is to be parsed.

  • file_format (str, optional) – The file format (or extension) that should be assumed when parsing the data. If no file format is specified, then the file format will be determined based on the file extension. If there is no file extension, then attempts will be made to parse the file as if it was one of the supported file formats.

  • **kwargs – Keyword arguments are passed to the parser.

Return type:

List[DataSet]

Format-specific functions

pyimpspec.data.formats.parse_csv(path, **kwargs)

Parse a file containing data as character-separated values.

Parameters:

  • path (Union[str, pathlib.Path]) – The path to the file to process.

  • **kwargs – Keyword arguments are passed forward to pandas.read_csv.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_dfr(path)

Parse an Eco Chemie .dfr file containing an impedance spectrum.

Parameters:

path (Union[str, pathlib.Path]) – The path to the file to process.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_dta(path)

Parse a Gamry .dta file containing an impedance spectrum.

If the file contains drift corrected data, then the returned list will contain the drift corrected spectrum as the first element and the uncorrected spectrum as the second element.

Parameters:

path (Union[str, pathlib.Path]) – The path to the file to process.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_i2b(path)

Parse an Elchemea Analytical .i2b file containing an impedance spectrum.

Parameters:

path (Union[str, pathlib.Path]) – The path to the file to process.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_ids(path)

Parse an Ivium .ids or .idf file containing one or more impedance spectra.

Parameters:

path (Union[str, pathlib.Path]) – The path to the file to process.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_mpt(path)

Parse a BioLogic EC-Lab .mpt file containing one or more impedance spectra.

Parameters:

path (Union[str, pathlib.Path]) – The path to the file to process.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_p00(path)

Parse a .P00 file containing an impedance spectrum.

Parameters:

path (Union[str, pathlib.Path]) – The path to the file to process.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_pssession(path)

Parse a PalmSens .pssession file.

Parameters:

path (Union[str, pathlib.Path]) – The path to the file to process.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_spreadsheet(path, **kwargs)

Parse a spreadsheet (.xlsx or .ods) containing one or more impedance spectra.

Parameters:

  • path (Union[str, pathlib.Path]) – The path to the file to process.

  • kwargs – Keyword arguments are passed forward to pandas.read_excel.

Return type:

List[DataSet]

pyimpspec.data.formats.parse_z(path, **kwargs)

Parse a ZView/ZPlot .z file.

Parameters:

  • path (Union[str, pathlib.Path]) – The path to the file to process.

  • **kwargs – Keyword arguments are passed forward to pandas.read_csv.

Return type:

List[DataSet]

Class

class pyimpspec.DataSet(frequencies, impedances, mask=None, path='', label='', uuid='')

A class that represents an impedance spectrum. The data points can be masked, which results in those data points being omitted from any analyses and visualization.

Parameters:

  • frequencies (Frequencies) – A 1-dimensional array of frequencies in hertz.

  • impedances (ComplexImpedances) – A 1-dimensional array of complex impedances in ohms.

  • mask (Optional[Dict[int, bool]], optional) – A mapping of integer indices to boolean values where a value of True means that the data point is to be omitted.

  • path (str, optional) – The path to the file that has been parsed to generate this DataSet instance.

  • label (str, optional) – The label assigned to this DataSet instance.

  • uuid (str, optional) – The universally unique identifier assigned to this DataSet instance. If empty, then one will be automatically assigned.

classmethod average(data_sets, label='Average')

Create a DataSet by averaging the impedances of multiple DataSet instances.

Parameters:

  • data_sets (List[DataSet]) – The DataSet instances to average.

  • label (str, optional) – The label that the new DataSet should have.

Return type:

DataSet

classmethod duplicate(data, label=None)

Create a duplicate of an existing DataSet but assign another universally unique identifier (UUID) to the copy.

Parameters:

  • data (DataSet) – The existing DataSet to duplicate.

  • label (Optional[str], optional) – The label that the copy should have.

Return type:

DataSet

classmethod from_dict(dictionary)

Create a DataSet from a dictionary.

Parameters:

dictionary (dict) – A dictionary containing at least the frequencies, and the real and the imaginary parts of the impedances.

Return type:

DataSet

get_bode_data(masked=False)

Get the data necessary to plot this DataSet as a Bode plot: the frequencies, the absolute magnitudes of the impedances, and the negative phase angles/shifts of the impedances in degrees.

Parameters:

masked (Optional[bool], optional) – None means that all impedances are returned. True means that only impedances that are to be omitted are returned. False means that only impedances that are to be included are returned.

Return type:

Tuple[Frequencies, Impedances, Phases]

get_frequencies(masked=False)

Get the frequencies in this DataSet.

Parameters:

masked (Optional[bool], optional) – None means that all frequencies are returned. True means that only frequencies that are to be omitted are returned. False means that only frequencies that are to be included are returned.

Return type:

Frequencies

get_impedances(masked=False)

Get the complex impedances in this DataSet.

Parameters:

masked (Optional[bool], optional) – None means that all impedances are returned. True means that only impedances that are to be omitted are returned. False means that only impedances that are to be included are returned.

Return type:

ComplexImpedances

get_label()

Get the label assigned to this DataSet.

Return type:

str

get_magnitudes(masked=False)

Get the absolute magnitudes of the impedances in this DataSet.

Parameters:

masked (Optional[bool], optional) – None means that all impedances are returned. True means that only impedances that are to be omitted are returned. False means that only impedances that are to be included are returned.

Return type:

Impedances

get_mask()

Get the mask for this DataSet. True means that the data point is to be omitted and False means that the data point is to be included. The keys are zero-based integer indices and the values are booleans.

Return type:

Dict[int, bool]

get_num_points(masked=False)

Get the number of data points in this DataSet

Parameters:

masked (Optional[bool], optional) – None means that all impedances are returned. True means that only impedances that are to be omitted are returned. False means that only impedances that are to be included are returned.

Return type:

int

get_nyquist_data(masked=False)

Get the data necessary to plot this DataSet as a Nyquist plot: the real and the negative imaginary parts of the impedances.

Parameters:

masked (Optional[bool], optional) – None means that all impedances are returned. True means that only impedances that are to be omitted are returned. False means that only impedances that are to be included are returned.

Return type:

Tuple[Impedances, Impedances]

get_path()

Get the path to the file that was parsed to generate this DataSet.

Return type:

str

get_phases(masked=False)

Get the phase angles/shifts of the impedances in this DataSet in degrees.

Parameters:

masked (Optional[bool], optional) – None means that all impedances are returned. True means that only impedances that are to be omitted are returned. False means that only impedances that are to be included are returned.

Return type:

Phases

high_pass(cutoff)

Mask data points by applying a high-pass filter with the provided cutoff frequency.

Parameters:

cutoff (float) – The cutoff frequency to use. Data points with frequencies lower than this cutoff frequency are masked.

low_pass(cutoff)

Mask data points by applying a low-pass filter with the provided cutoff frequency.

Parameters:

cutoff (float) – The cutoff frequency to use. Data points with frequencies higher than this cutoff frequency are masked.

set_label(label)

Set the label assigned to this DataSet.

Parameters:

label (str) – The new label.

set_mask(mask)

Set the mask for this DataSet.

Parameters:

mask (Dict[int, bool]) – The new mask that determines which data points are omitted. True means that the data point is to be omitted and False means that the data point is to be included. The keys must be zero-based integer indices and the values must be boolean values.

set_path(path)

Set the path to the file that was parsed to generate this DataSet.

Parameters:

path (str) – The path.

subtract_impedances(impedances)

Subtract either the same complex value from all data points or a unique complex value for each data point in this DataSet.

Parameters:

impedances (ComplexImpedances) – The complex value(s) to subtract from this DataSet’s impedances.

to_dataframe(masked=False, columns=None, negative_imaginary=False, negative_phase=False)

Create a pandas.DataFrame instance from this DataSet.

Parameters:

  • masked (Optional[bool], optional) – None means that all impedances are returned. True means that only impedances that are to be omitted are returned. False means that only impedances that are to be included are returned.

  • columns (Optional[List[str]], optional) – The column headers to use.

  • negative_imaginary (bool, optional) – Whether or not the sign of the imaginary part of the impedance data should be inverted. Note that this does not automatically add a minus sign in front of the column label.

  • negative_phase (bool, optional) – Whether or not the sign of the phase of the impedance data should be inverted. Note that this does not automatically add a minus sign in front of the column label.

Return type:

pandas.DataFrame

to_dict()

Get a dictionary that represents this DataSet, can be used to serialize the DataSet (e.g. as a JSON file), and then used to recreate this DataSet.

Return type:

dict