ampworks.mathutils#

General-purpose mathematical utilities for array and numerical computations. Provides reusable functions to simplify common tasks in data analysis and math.

Functions#

aggregate_over_x(datasets, x, y[, n])

Aggregate datasets over a shared x grid.

combinations(values[, names])

Generate all value combinations.

Module Contents#

ampworks.mathutils.aggregate_over_x(datasets, x, y, n=100)[source]#

Aggregate datasets over a shared x grid.

The function finds the overlapping range of x across all datasets, interpolates each dataset’s y onto an evenly spaced x grid, and then computes summary statistics for y at each grid point.

Parameters:

  • datasets (Sequence[Dataset]) – Datasets to aggregate. Each dataset must contain requested x/y columns.

  • x (str) – Column name used to build the interpolation grid.

  • y (str) – Column name interpolated and aggregated on the shared grid.

  • n (int, optional) – Number of evenly spaced points in the shared grid. Default is 100.

Returns:

data (Dataset) – Dataset with columns for the x grid and aggregated y statistics, including: mean, standard deviation, minimum, and maximum.

Raises:

  • TypeError – If any input argument has an invalid type.

  • ValueError – If datasets is empty, if n < 2, if the requested columns are missing from any dataset, or if the datasets have no overlapping range in x.

Examples

The code snippet below demonstrates how to use aggregate_over_x. Here, we load a beginning-of-life and end-of-life cell dataset from the datasets subpackage. Combining these datasets has no particular physical meaning, but serves to illustrate the function.

import ampworks as amp
import matplotlib.pyplot as plt

data1, data2 = amp.datasets.load_datasets(
    'dqdv/cell1_rough', 'dqdv/cell2_rough',
)

avg = amp.mathutils.aggregate_over_x([data1, data2], 'Volts', 'Ah')
dwn = avg.downsample(n=25)

errbar = plt.errorbar(
    dwn['Ah_mean'], dwn['Volts'], xerr=dwn['Ah_std'], fmt='.',
)
fill_x = plt.fill_betweenx(
    dwn['Volts'], dwn['Ah_min'], dwn['Ah_max'], alpha=0.2,
)

plt.legend([errbar, fill_x], ["Mean +/- Std", "Min-Max Range"])
plt.xlabel("Discharge Capacity [Ah]")
plt.ylabel("Voltage [V]")

plt.show()
ampworks.mathutils.combinations(values, names=None)[source]#

Generate all value combinations.

Parameters:

  • values (Sequence[1D array]) – Variable values. Array i corresponds to names[i], if provided.

  • names (Sequence[str], optional) – Variable names. Defaults to range(N) when not provided, where N is the length of ‘values’, i.e., how many arrays are in the sequence.

Returns:

combinations (list[dict]) – Dictionaries for each possible combination of values.