Skip to content

Accelerometers

labda.accelerometers.AutoCalibrate dataclass

Automated gravitational calibration of tri-axial accelerometer data.

This class corrects gain (scale) and offset errors by identifying stationary periods in the data where the magnitude of the acceleration vector should theoretically be exactly 1 g.

The Algorithm:

  1. Stationary Detection: The signal is resampled into windows (defined by window). Windows where the standard deviation of all axes is below tolerance are marked as stationary.
  2. Sphere Fitting: Uses an iterative Reweighted Least Squares (IRLS) approach to map the stationary points onto a unit sphere.
  3. Correction: Solves for the parameters $S$ (scale) and $O$ (offset) such that: $$ \text{Target} = S \cdot (\text{Raw} + O) $$

Attributes:

Name Type Description
window str | timedelta

The window size for resampling and stationarity checks (e.g., "10s"). Defaults to "10s".
tolerance float

Maximum standard deviation (in g) allowed for a window to be considered stationary. Defaults to 0.015.
samples int

Minimum number of stationary windows required to attempt calibration. Defaults to 50.
calib_cube float

Coverage threshold. Ensures stationary points exist at least calib_cube g away from the origin on all axes (both positive and negative) to prevent overfitting to a single orientation. Defaults to 0.3.
max_iter int

Maximum number of optimization iterations.
improv_tol float

Minimum relative error improvement required to continue optimization iterations.
err_tol float

Target mean error (in g) for successful calibration.

compute 

compute(df: DataFrame) -> pd.DataFrame

Applies calibration to the provided DataFrame.

If sufficient stationary data is found and the algorithm converges, the returned DataFrame will contain corrected values. If calibration fails (e.g., not enough stationary periods or poor coverage), the original data is returned, and a warning is logged.

Parameters:

Name Type Description Default
df DataFrame

Input dataframe containing raw accelerometer data. Must contain columns: acc_x, acc_y, acc_z.

 required

Returns:

Type Description
DataFrame

pd.DataFrame: A new DataFrame with calibrated data (float32). The index and column names are preserved.