Transformations¶

Transforms¶

CRateTransformSpec `dataclass` ¶

CRateTransformSpec(
    source_col: MappingSpec,
    target_col: MappingSpec,
    nominal_capacity_ah: float,
)

Derive C-rate from current and nominal capacity.

If target_col already exists, null target values are filled from the derived C-rate and existing non-null values are preserved. If source_col is absent, the input frame is returned unchanged.

Attributes:

source_col (MappingSpec) –

Current column in amps.
target_col (MappingSpec) –

Output C-rate column.
nominal_capacity_ah (float) –

Nominal cell capacity used as the divisor.

Examples:

>>> CRateTransformSpec(
...     source_col=BaseColumns.curr,
...     target_col=BaseColumns.crate,
...     nominal_capacity_ah=5.0,
... )
CRateTransformSpec(...)

Methods:

apply –

Apply the C-rate derivation to a frame when the source column exists.

input_columns `property` ¶

input_columns: tuple[MappingSpec, ...]

Columns required before this transform runs.

Returns:

tuple[MappingSpec, ...] –

Source current column.

produced_columns `property` ¶

produced_columns: tuple[MappingSpec, ...]

Columns produced or filled by this transform.

Returns:

tuple[MappingSpec, ...] –

Target C-rate column.

apply ¶

apply(data: DataFrame) -> DataFrame

apply(data: LazyFrame) -> LazyFrame

apply(data: DataFrame | LazyFrame) -> DataFrame | LazyFrame

Apply the C-rate derivation to a frame when the source column exists.

Parameters:

data (DataFrame | LazyFrame) –

Input dataframe or lazy frame.

Returns:

DataFrame | LazyFrame –

Frame with target_col added or filled when source_col exists;
DataFrame | LazyFrame –

otherwise the original frame.

Checks¶

MissingCheckSpec `dataclass` ¶

MissingCheckSpec(
    columns: tuple[MappingSpec, ...] | None = None,
)

Annotate null or NaN numeric values.

If columns is omitted, all numeric columns present in the input frame are checked. The check produces internal annotation columns that are finalized by normalization when annotations are requested.

Attributes:

columns (tuple[MappingSpec, ...] | None) –

Optional columns to check. Missing requested columns are ignored.

TimeCheckSpec `dataclass` ¶

TimeCheckSpec(
    time_col: MappingSpec,
    dt_col: MappingSpec,
    max_dt_s: float | None = 86400.0,
)

Validate and rebuild a monotonically increasing task time axis.

The check computes dt_col from consecutive time_col differences, drops duplicate or non-positive intervals, optionally flags large intervals, and rebuilds time from cumulative dt_col. Full-task normalization applies the diff within group_by; because this uses a forward interval, the final row has no dt_col and is dropped. Bounded normalization carries a pending tail row across chunks and may emit no rows until at least two rows are available.

Attributes:

time_col (MappingSpec) –

Source time column.
dt_col (MappingSpec) –

Output time-step column.
max_dt_s (float | None) –

Maximum allowed interval in seconds. Set to None to skip the large time-step annotation.

ColumnBoundsCheckSpec `dataclass` ¶

ColumnBoundsCheckSpec(
    bounds: dict[
        MappingSpec, tuple[float | None, float | None]
    ],
)

Annotate numeric values outside configured inclusive bounds.

Bounds use (lower, upper) pairs. None disables one side. Values equal to a bound are accepted; the check annotates values below lower or above upper and never clips data.

Attributes:

bounds (dict[MappingSpec, tuple[float | None, float | None]]) –

Per-column (lower, upper) bounds.

ImpedanceComponentsCheckSpec `dataclass` ¶

ImpedanceComponentsCheckSpec(
    z_real: MappingSpec = z_real,
    z_imag: MappingSpec = z_imag,
    z_mag: MappingSpec = z_mag,
    z_phase: MappingSpec = z_phase,
)

Ensure EIS data has both rectangular and polar impedance components.

Input must contain either (z_real, z_imag) or (z_mag, z_phase). Missing counterparts are derived from the available representation. Existing columns are preserved by coalescing existing values before derived values.

DomainAxisCheckSpec `dataclass` ¶

DomainAxisCheckSpec(
    axis_col: MappingSpec,
    zero_replacement: float | None = None,
    enforce_positive: bool = False,
)

Annotate invalid domain-axis values within a task or group.

The axis is invalid when it is null, NaN, or not strictly increasing. Use zero_replacement before validation for sources that encode the first EIS frequency as zero. Set enforce_positive to also reject zero or negative values after replacement. Bounded normalization carries the previous axis value across chunks; the first row is not invalid only because it has no previous value.

Attributes:

axis_col (MappingSpec) –

Domain column to validate.
zero_replacement (float | None) –

Optional value used to replace zeros before checking.
enforce_positive (bool) –

Whether to reject non-positive axis values.

apply_checks_full_task ¶

apply_checks_full_task(
    data: LazyFrame,
    group_by: tuple[MappingSpec, ...],
    checks: tuple[CheckSpec, ...],
    *,
    annotate: bool = True,
) -> tuple[LazyFrame, tuple[CheckViolation, ...]]

Apply checks to a full lazy normalization task.

Parameters:

data (LazyFrame) –

Task frame.
group_by (tuple[MappingSpec, ...]) –

Columns that define independent time/domain groups.
checks (tuple[CheckSpec, ...]) –

Checks to run in order.
annotate (bool, default: True ) –

When True, write annotation columns. When False, leave the frame unchanged and return detected violations.

Returns:

tuple[LazyFrame, tuple[CheckViolation, ...]] –

Updated frame and unique (column, reason) violations.

apply_checks_bounded_chunk ¶

apply_checks_bounded_chunk(
    data: DataFrame,
    checks: tuple[CheckSpec, ...],
    states: tuple[CheckState, ...],
    *,
    annotate: bool = True,
) -> tuple[DataFrame, tuple[CheckViolation, ...]]

Apply checks to one bounded normalization chunk.

Parameters:

data (DataFrame) –

Chunk frame.
checks (tuple[CheckSpec, ...]) –

Checks to run in order.
states (tuple[CheckState, ...]) –

Mutable per-check state created with CheckSpec.init_state.
annotate (bool, default: True ) –

When True, write annotation columns. When False, return detected violations for the chunk.

Returns:

tuple[DataFrame, tuple[CheckViolation, ...]] –

Updated chunk and unique (column, reason) violations.

Resampling¶

MinMaxLTTBResamplingSpec `dataclass` ¶

MinMaxLTTBResamplingSpec(
    x_col: MappingSpec,
    y_col: MappingSpec,
    points: int | None = None,
    points_ratio: float | None = None,
    min_points: int = 3,
    method: str = "min_max_lttb",
)

Downsample a task with MinMaxLTTB using one domain and one signal column.

x_col is the domain column used for ordering and point placement. y_col is the signal whose shape should be preserved. Use either an absolute points budget or a points_ratio; min_points is the lower bound after the budget is resolved. If both points and points_ratio are set, points takes precedence. Non-finite domain or signal rows are ignored for sampling.

Bounded normalization uses the same spec without materializing the full task. When physics compensation is enabled and dt plus current or C-rate are available, bounded output rebuilds interval dt, time, and averaged signal values for the selected rows. Physics compensation is bounded-only and prefers C-rate over current when both are present.

Attributes:

x_col (MappingSpec) –

Domain column used for sampling.
y_col (MappingSpec) –

Signal column used by MinMaxLTTB to preserve shape.
points (int | None) –

Absolute number of output rows, if set.
points_ratio (float | None) –

Output row ratio relative to the input row count, if set.
min_points (int) –

Lower bound for the resolved output row budget.

Examples:

>>> MinMaxLTTBResamplingSpec(
...     x_col=BaseColumns.time,
...     y_col=BaseColumns.volt,
...     points_ratio=0.1,
... )
MinMaxLTTBResamplingSpec(...)

Methods:

metadata_values –

Return method name and JSON parameters written to normalized metadata.

input_columns `property` ¶

input_columns: tuple[MappingSpec, ...]

Columns required before this resampling step runs.

Returns:

tuple[MappingSpec, ...] –

Domain and signal columns used by MinMaxLTTB.

metadata_values ¶

metadata_values() -> tuple[str, str]

Return method name and JSON parameters written to normalized metadata.

Returns:

tuple[str, str] –

Resampling method id and compact JSON argument string.

LinearResamplingSpec `dataclass` ¶

LinearResamplingSpec(
    x_col: MappingSpec,
    points: int,
    scale: Literal["linear", "log"] = "linear",
    value_range: tuple[float, float] | None = None,
    method: str = "linear",
)

Resample rows onto a fixed domain grid with interpolation.

Numeric columns are interpolated against x_col; non-numeric columns are carried from the nearest source row. This is used for protocols such as EIS, where each task should have the same frequency grid. Linear resampling only supports full-task execution. Non-finite domain rows are dropped, duplicate domain values keep the last row, and explicit value_range may extrapolate numeric columns beyond the source range.

Attributes:

x_col (MappingSpec) –

Domain column used as the interpolation axis.
points (int) –

Number of target grid points.
scale (Literal['linear', 'log']) –

Grid spacing, either linear or logarithmic.
value_range (tuple[float, float] | None) –

Optional explicit lower and upper x-axis range.

Examples:

>>> LinearResamplingSpec(
...     x_col=BaseColumns.freq,
...     points=48,
...     scale="log",
... )
LinearResamplingSpec(...)

Methods:

metadata_values –

Return method name and JSON parameters written to normalized metadata.

input_columns `property` ¶

input_columns: tuple[MappingSpec, ...]

Columns required before this resampling step runs.

Returns:

tuple[MappingSpec, ...] –

Domain column used as the interpolation axis.

metadata_values ¶

metadata_values() -> tuple[str, str]

Return method name and JSON parameters written to normalized metadata.

Returns:

tuple[str, str] –

Resampling method id and compact JSON argument string.

resolve_min_max_lttb_budget ¶

resolve_min_max_lttb_budget(
    spec: MinMaxLTTBLikeSpec, row_count: int
) -> int

Resolve MinMaxLTTB output rows from points or points_ratio.

Parameters:

spec (MinMaxLTTBLikeSpec) –

Resampling spec with points, points_ratio, and min_points.
row_count (int) –

Number of input rows.

Returns:

int –

Output row budget capped by row_count and bounded by min_points.

Transformations¶

Transforms¶

CRateTransformSpec dataclass ¶

input_columns property ¶

produced_columns property ¶

apply ¶

Checks¶

MissingCheckSpec dataclass ¶

TimeCheckSpec dataclass ¶

ColumnBoundsCheckSpec dataclass ¶

ImpedanceComponentsCheckSpec dataclass ¶

DomainAxisCheckSpec dataclass ¶

apply_checks_full_task ¶

apply_checks_bounded_chunk ¶

Resampling¶

MinMaxLTTBResamplingSpec dataclass ¶

input_columns property ¶

metadata_values ¶

LinearResamplingSpec dataclass ¶

input_columns property ¶

metadata_values ¶

resolve_min_max_lttb_budget ¶

CRateTransformSpec `dataclass` ¶

input_columns `property` ¶

produced_columns `property` ¶

MissingCheckSpec `dataclass` ¶

TimeCheckSpec `dataclass` ¶

ColumnBoundsCheckSpec `dataclass` ¶

ImpedanceComponentsCheckSpec `dataclass` ¶

DomainAxisCheckSpec `dataclass` ¶

MinMaxLTTBResamplingSpec `dataclass` ¶

input_columns `property` ¶

LinearResamplingSpec `dataclass` ¶

input_columns `property` ¶