ampworks.labels#

A module for applying user-defined labels to steps, cycles, and sections of a dataset. This is intended to be used for datasets that have a ‘Cycle’ and ‘Step’ column. Note that all classes and functions in this module are also available in the top-level ampworks namespace. This is done for convenience so that calls to these classes and functions can stay short and simple, e.g. amp.StepLabel instead of amp.labels.StepLabel. However, the module is still available separately to help discoverability and to keep the code organized.

Classes#

CycleLabel

Readable label for cycles.

LabelSet

A set of step, cycle, and section labels.

SectionLabel

Readable label for sections.

StepLabel

Readable label for a single step.

Functions#

apply_labels(data, labels)

Apply labels to a dataset.

Module Contents#

class ampworks.labels.CycleLabel(label, *, steps=None, cycles=None)[source]#

Readable label for cycles.

Parameters:

  • label (str) – The label to apply for the cycle, defined by the ‘steps’ argument.

  • steps (Sequence[int] or None, optional) – The step numbers that define the cycle. Defaults to None. Must be provided if cycles is not provided.

  • cycles (Sequence[int] or None, optional) – The cycle numbers that define the cycle. Defaults to None. Must be provided if steps is not provided.

Raises:

  • TypeError – If the label is not a string or if steps or cycles is not a sequence of integers.

  • ValueError – If both steps and cycles are None, or if both are not None.

Notes

Either steps or cycles must be provided, but not both. If steps is provided, the label will be applied to all cycles that contain those steps. Otherwise, if cycles is provided, the label will be applied to those cycles.

Examples

The following demonstrates how to create cycle labels for a dataset. The inputs must be a string label and either a sequence of step numbers or a sequence of cycle numbers. Each label can only be defined using either steps or cycles, not both. However, when applying the labels, there are no restrictions on mixing cycle labels defined using both methods. Also, you can use a range object to define your sequence if more convenient, so there is no need to explicitly list all step or cycle numbers.

>>> from ampworks import CycleLabel
>>> cycle1 = CycleLabel('HPPC', steps=range(1, 9))
>>> cycle2 = CycleLabel('Aging Cycle', cycles=[1, 2, 3, 4, 5])
class ampworks.labels.LabelSet(*, step_labels=None, cycle_labels=None, section_labels=None)[source]#

A set of step, cycle, and section labels.

Parameters:

  • step_labels (Sequence[StepLabel] or None, optional) – The step labels for a given dataset. Defaults to None.

  • cycle_labels (Sequence[CycleLabel] or None, optional) – The cycle labels for a given dataset. Defaults to None.

  • section_labels (Sequence[SectionLabel] or None, optional) – The section labels for a given dataset. Defaults to None.

Raises:

TypeError – If any of the label inputs are not sequences of the appropriate label type, e.g. if step_labels is not a sequence of StepLabel.

class ampworks.labels.SectionLabel(label, *, steps=None, cycles=None)[source]#

Readable label for sections.

Parameters:

  • label (str) – The label to apply for the section, defined by the ‘steps’ argument.

  • steps (Sequence[int] or None, optional) – The step numbers that define the section. Defaults to None. Must be provided if cycles is not provided.

  • cycles (Sequence[int] or None, optional) – The cycle numbers that define the section. Defaults to None. Must be provided if steps is not provided.

Raises:

  • TypeError – If the label is not a string or if steps or cycles is not a sequence of integers.

  • ValueError – If both steps and cycles are None, or if both are not None.

Notes

Either steps or cycles must be provided, but not both. If steps is provided, the label will be applied to all cycles that contain those steps. Otherwise, if cycles is provided, the label will be applied to those cycles.

Examples

The following demonstrates how to create section labels for a dataset. A section label is intended to be one level of abstraction higher than a cycle label.

The inputs must be a string label and either a sequence of step numbers or a sequence of cycle numbers. Each label can only be defined using either steps or cycles, not both. However, when applying the labels, there are no restrictions on mixing section labels defined using both methods. Also, you can use a range object to define your sequence if more convenient, so there is no need to list all step or cycle numbers.

>>> from ampworks import SectionLabel
>>> section1 = SectionLabel('RPT1', cycles=[1, 2, 3])
>>> section2 = SectionLabel('RPT2', cycles=range(100, 104))
class ampworks.labels.StepLabel(label, step)[source]#

Readable label for a single step.

Parameters:

  • label (str) – The label to apply for the step, defined by the ‘step’ argument.

  • step (int) – The step number to which the label will be applied.

Raises:

TypeError – If label is not a string or if step is not an integer.

Examples

The following demonstrates how to create step labels for a dataset. The inputs must be a string label and an integer step number. The label can be as simple or descriptive as desired.

>>> from ampworks import StepLabel
>>> step1 = StepLabel('Initial Rest', 1)
>>> step2 = StepLabel('1C CC Charge until 4.2V', 2)
>>> step3 = StepLabel('CV Charge at 4.2V', 3)
>>> step4 = StepLabel('Final Rest', 4)
ampworks.labels.apply_labels(data, labels)[source]#

Apply labels to a dataset.

Parameters:

  • data (Dataset) – The dataset to which labels will be applied.

  • labels (LabelSet) – The set of step, cycle, and section labels to apply.

Returns:

labeled (Dataset) – A new dataset with the applied labels.

Raises:

  • TypeError – If data is not a Dataset or if labels is not a LabelSet.

  • ValueError – If data does not contain the required ‘Cycle’ and ‘Step’ columns.

Notes

Any cycles or steps that are not labeled will have a label of 'None' in the resulting CycleLabel and StepLabel columns. Also, if a step is given in more than one cycle, the last cycle label will be applied. Similarly, if a step is given more than one step label, only the last step label will be applied to that step.

Examples

The following demonstrates how to apply labels to an HPPC dataset from the ampworks.datasets module. First, we create the labels and them apply them to the dataset. The final line of code plots the resulting dataset with some hover hints so the applied labels can be viewed and checked for accuracy.

import ampworks as amp

# Load in an example dataset
data = amp.datasets.load_datasets('hppc/hppc_discharge')

# Create the labels
labels = amp.LabelSet(
    step_labels=[
        amp.StepLabel('Initial Rest', 1),
        amp.StepLabel('C/3 Discharge', 2),
        amp.StepLabel('Equilibrium Rest', 3),
        amp.StepLabel('1C Discharge Pulse', 4),
        amp.StepLabel('40s Rest', 5),
        amp.StepLabel('0.75C Charge Pulse', 6),
        amp.StepLabel('40s Rest', 7),
        amp.StepLabel('Final Rest', 8),
    ],
    cycle_labels=[
        amp.CycleLabel('HPPC', steps=range(1, 9)),
    ],
)

# Apply the labels
labeled = amp.apply_labels(all_data, labels)

# Add an hours column and plot with the labels as hover tips
labeled['Hours'] = labeled['Seconds'] / 3600

labeled.interactive_xy_plot(
    x='Hours', y='Volts', tips=['StepLabel', 'CycleLabel'],
)