Collect¶

Collect capacity-voltage curves per cell/cycle into one tidy Collection.

Collect dV/dQ (differential voltage) curves per cell into one Collection.

Cycle selection is derived per cell from the originally requested cycles every iteration, so a cell missing a cycle never narrows the request for the cells after it (mirrors collect_ica).

Collect dQ/dV (incremental capacity) curves per cell into one Collection.

Cycle selection is derived per cell from the originally requested cycles every iteration, so a cell missing a cycle never narrows the request for the cells after it.

Collect per-cell summaries into one tidy Collection.

With defaults this is a plain long-format concatenation (one row per cell/cycle). The options add rate filtering, CV partition, per-group averaging and inf/extreme cleanup -- see SummaryOptions.

Collect voltage-capacity curves per cell and cycle.

Returns a BatchCollector holding a Collection: .data is the tidy frame, .plot() draws it and .save(dir) writes the frame plus its metadata.

Examples:

>>> curves = cycles_collector(b, cycles=[1, 10, 20])
>>> curves.plot(layout="per_cell")  # or layout="per_cycle", kind="film"

Parameters:

• batch (Any) –

  The Batch to collect from.

• options (CurveOptions, default: None ) –

  A ready options object; the keyword arguments below still update it.

• cycles (sequence of int, default: None ) –

  Cycles to collect. Resolved per cell, so a cell missing one cycle does not narrow the others.

• rate (float, default: None ) –

  Rate-based cycle selection (see rate_on / rate_std / inverse on CurveOptions).

• mode (str, default: None ) –

  Capacity mode forwarded to CellpyCell.get_cap (gravimetric / areal / absolute).

• method (str, default: None ) –

  forth-and-forth / back-and-forth / forth, forwarded to CellpyCell.get_cap.

• autorun (bool, default: True ) –

  Run the collector immediately (default True).

• **overrides –

  Any other field of CurveOptions -- rate_on, rate_std, inverse, transforms.

Returns:

• BatchCollector ( BatchCollector ) –

  bound to collect_cycles.

Collect differential-voltage (dV/dQ) curves per cell and cycle.

Returns a BatchCollector holding a Collection: .data is the tidy frame, .plot() draws it and .save(dir) writes the frame plus its metadata.

Examples:

>>> dva = dva_collector(b, cycles=[1, 10, 20])
>>> dva.plot(layout="per_cell")

Parameters:

• batch (Any) –

  The Batch to collect from.

• options (IcaOptions, default: None ) –

  A ready options object; the keyword arguments below still update it.

• cycles (sequence of int, default: None ) –

  Cycles to collect (resolved per cell).

• capacity_resolution (float, default: None ) –

  Capacity step for the V(q) interpolation dV/dQ differentiates along.

• autorun (bool, default: True ) –

  Run the collector immediately (default True).

• **overrides –

  Any other field of IcaOptions -- transforms.

Returns:

• BatchCollector ( BatchCollector ) –

  bound to collect_dva.

Build a Batch from already-loaded cells (see from_cells) -- feed it to collect_summaries / collect_cycles or call batch.plot().

Collect incremental-capacity (dQ/dV) curves per cell and cycle.

Returns a BatchCollector holding a Collection: .data is the tidy frame, .plot() draws it and .save(dir) writes the frame plus its metadata.

Examples:

>>> ica = ica_collector(b, cycles=[1, 10, 20])
>>> ica.plot(layout="per_cell")

Parameters:

• batch (Any) –

  The Batch to collect from.

• options (IcaOptions, default: None ) –

  A ready options object; the keyword arguments below still update it.

• cycles (sequence of int, default: None ) –

  Cycles to collect (resolved per cell).

• voltage_resolution (float, default: None ) –

  Voltage step for the q(V) interpolation dQ/dV differentiates along.

• autorun (bool, default: True ) –

  Run the collector immediately (default True).

• **overrides –

  Any other field of IcaOptions -- transforms.

Returns:

• BatchCollector ( BatchCollector ) –

  bound to collect_ica.

Yield the batch's loaded cells with their journal group/sub_group.

Load a saved collection (parquet/csv frame + meta.json if present).

Build a transform that adds 100 * column / norm_factor as a new series.

Works on both the wide (non-grouped) frame -- adding an <out> column -- and the grouped long frame -- adding an <out> variable with mean (and std) scaled. Missing columns are left untouched.

Build a transform that adds scaler * column / max(column) as a new series.

The counterpart of normalize_column for the case where the reference value is not known up front — retention against the cell's own best cycle, which is what summary_plot does by default (fullcell_standard_normalization_type="max").

Works on both the wide (non-grouped) frame and the grouped long frame, and leaves the frame untouched when column is missing.

Parameters:

• column (str) –

  source column (wide) or variable value (long).

• out (str, default: None ) –

  name of the series to add. Defaults to "<column>_norm".

• scaler (float, default: 100.0 ) –

  factor applied after dividing by the maximum.

Returns:

• Callable[[DataFrame], DataFrame] –

  A polars.DataFrame -> polars.DataFrame transform.

The standard gravimetric summary recipe.

Successor of collectors.standard_gravimetric_collector: collect the charge/discharge/CE metrics, partition capacity by CV step, average per group, and add a normalized discharge-capacity-retention series (100 * discharge / norm_factor). Uses native cellpycore column names (the legacy *_gravimetric suffix is not part of the native schema). The figure itself lands with the plotting handover.

Collect the per-cell summaries of a batch (cycle-life data).

Returns a BatchCollector holding a Collection: .data is the tidy frame, .plot() draws it and .save(dir) writes the frame plus its metadata.

Examples:

>>> caps = summary_collector(b, family="fullcell_standard_gravimetric",
...                          group_it=True)
>>> caps.plot(height=600)

Parameters:

• batch (Any) –

  The Batch to collect from.

• options (SummaryOptions, default: None ) –

  A ready options object. Wins over family and is still updated by the keyword arguments below.

• family (str, default: None ) –

  Name of a registered plot family, the same names summary_plot(y=...) takes (capacities_gravimetric, fullcell_standard_gravimetric, ...). Its columns and transforms are resolved against the first loaded cell's summary schema. An unknown name raises ValueError listing the known families; cellpy.plotting.families() lists them too.

• y (str, default: None ) –

  Alias of family, matching summary_plot(y=...).

• columns (sequence of str, default: None ) –

  Summary columns to keep. Wins over family. Journal keys (cell/group/...) are always kept. Plot facet rows follow this order top → bottom (Plotly first row on top).

• group_it (bool, default: None ) –

  Average per journal group -> tidy long frame (group, cycle_num, variable, mean, std).

• custom_group_labels (mapping, default: None ) –

  group id -> display label, used for the plot legend (int or str keys both match).

• rate (float, default: None ) –

  Keep only cycles run at this C-rate (see rate_on / rate_std / rate_inverted on SummaryOptions).

• max_cycle (int, default: None ) –

  Drop cycles above this number.

• partition_by_cv (bool, default: None ) –

  Also emit *_non_cv / *_cv capacity contributions.

• autorun (bool, default: True ) –

  Run the collector immediately (default True).

• **overrides –

  Any other field of SummaryOptions -- rate_on, rate_std, rate_inverted, only_selected, remove_last, normalize_cycles, average_method, transforms, ...

Returns:

• BatchCollector ( BatchCollector ) –

  bound to collect_summaries.

Raises:

• ValueError –

  family/y is not a registered family, or no loaded cell is available to resolve it against.

Collect per-cell summaries into one tidy Collection.

With defaults this is a plain long-format concatenation (one row per cell/cycle). The options add rate filtering, CV partition, per-group averaging and inf/extreme cleanup -- see SummaryOptions.

Collect capacity-voltage curves per cell/cycle into one tidy Collection.

Collect dQ/dV (incremental capacity) curves per cell into one Collection.

Cycle selection is derived per cell from the originally requested cycles every iteration, so a cell missing a cycle never narrows the request for the cells after it.

Load a saved collection (parquet/csv frame + meta.json if present).