Skip to content

filters

AbsoluteValueFilter

Bases: BaseFilter

Rectifies the signal by taking the magnitude of every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[ABSOLUTE_VALUE] = ABSOLUTE_VALUE

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

ClipFilter

Bases: BaseFilter

Clamps the signal values within a specified range.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[CLIP] = CLIP

The discriminator type for Pydantic.

min class-attribute instance-attribute

Python
min: float | None = None

Optional lower bound; values below this will be set to min.

max class-attribute instance-attribute

Python
max: float | None = None

Optional upper bound; values above this will be set to max.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

ComparisonFilter

Bases: BaseFilter

Compares each sample against a threshold, returning 1.0 (true) or 0.0 (false).

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[COMPARISON] = COMPARISON

The discriminator type for Pydantic.

operator class-attribute instance-attribute

Python
operator: _COMPARISON_OPS = Field(
    default="gt", json_schema_extra={"ui_type": "select"}
)

Comparison operator: gt (>), gte (>=), lt (<), lte (<=), eq (==), neq (!=).

threshold class-attribute instance-attribute

Python
threshold: float = 0.0

The value to compare each sample against.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

DeadbandFilter

Bases: BaseFilter

Suppresses noise around zero by forcing values below a threshold to zero.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[DEADBAND] = DEADBAND

The discriminator type for Pydantic.

threshold class-attribute instance-attribute

Python
threshold: float = Field(default=0.01, ge=0)

Magnitude threshold; values where abs(x) <= threshold are set to 0.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

DerivativeFilter

Bases: BaseFilter

Computes the numerical rate of change using backward difference. Useful for deriving velocity from position or acceleration from velocity.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[DERIVATIVE] = DERIVATIVE

The discriminator type for Pydantic.

dt class-attribute instance-attribute

Python
dt: float = Field(default=0.001, gt=0)

The time step between samples in seconds. Ignored when wrt_col is set.

wrt_col class-attribute instance-attribute

Python
wrt_col: str | None = Field(
    default=None, json_schema_extra={"ui_type": "col"}
)

Optional column to differentiate with respect to instead of a fixed dt.

ExpFilter

Bases: BaseFilter

Raises a base to the power of each signal sample. Defaults to e^x.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[EXP] = EXP

The discriminator type for Pydantic.

base class-attribute instance-attribute

Python
base: float = Field(default=e, gt=0)

The base to exponentiate. Use e (2.718...) for the natural exponential.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

FirstFilter

Bases: BaseFilter

Reduces the signal to its first value, broadcast across every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[STAT_FIRST] = STAT_FIRST

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

HighPassFilter

Bases: BaseFilter

Removes low-frequency drift or steady-state offsets. Implemented as the complement of the Exponential Moving Average.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[HIGH_PASS] = HIGH_PASS

The discriminator type for Pydantic.

alpha class-attribute instance-attribute

Python
alpha: float = Field(default=0.1, gt=0, le=1)

Smoothing factor used for the underlying low-pass component.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

IntegralFilter

Bases: BaseFilter

Computes the cumulative sum of the signal multiplied by the time step. Useful for deriving position from velocity or calculating energy.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[INTEGRAL] = INTEGRAL

The discriminator type for Pydantic.

dt class-attribute instance-attribute

Python
dt: float = Field(default=0.001, gt=0)

The time step between samples in seconds. Ignored when wrt_col is set.

wrt_col class-attribute instance-attribute

Python
wrt_col: str | None = Field(
    default=None, json_schema_extra={"ui_type": "col"}
)

Optional column to integrate with respect to instead of a fixed dt.

LastFilter

Bases: BaseFilter

Reduces the signal to its last value, broadcast across every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[STAT_LAST] = STAT_LAST

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

LogFilter

Bases: BaseFilter

Applies a logarithm to the signal. Defaults to natural log (base e).

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[LOG] = LOG

The discriminator type for Pydantic.

base class-attribute instance-attribute

Python
base: float = Field(default=e, gt=0)

Logarithm base. Use e (2.718...) for natural log, 2 for log2, 10 for log10.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

LowPassFilter

Bases: BaseFilter

Applies a 1st-order Exponential Moving Average (EMA) to smooth the signal. Effective for removing high-frequency noise while introducing slight phase lag.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[LOW_PASS] = LOW_PASS

The discriminator type for Pydantic.

alpha class-attribute instance-attribute

Python
alpha: float = Field(default=0.1, gt=0, le=1)

Smoothing factor (0 < alpha <= 1). Lower values result in heavier smoothing.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

MaxFilter

Bases: BaseFilter

Reduces the signal to its maximum value, broadcast across every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[STAT_MAX] = STAT_MAX

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

MeanFilter

Bases: BaseFilter

Reduces the signal to its mean value, broadcast across every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[STAT_MEAN] = STAT_MEAN

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

MedianFilter

Bases: BaseFilter

Reduces the signal to its median value, broadcast across every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[STAT_MEDIAN] = STAT_MEDIAN

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

MinFilter

Bases: BaseFilter

Reduces the signal to its minimum value, broadcast across every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[STAT_MIN] = STAT_MIN

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

ModeFilter

Bases: BaseFilter

Reduces the signal to its most frequent value, broadcast across every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[STAT_MODE] = STAT_MODE

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

NormalizeFilter

Bases: BaseFilter

Rescales the signal to the range [0, 1].

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[NORMALIZE] = NORMALIZE

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

PowerFilter

Bases: BaseFilter

Raises each signal sample to a fixed exponent. Supports fractional exponents (e.g. 0.5 for sqrt).

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[POWER] = POWER

The discriminator type for Pydantic.

exponent class-attribute instance-attribute

Python
exponent: float = Field(default=2.0)

The power to raise each sample to. Use 0.5 for square root, 1/3 for cube root.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

ReverseFilter

Bases: BaseFilter

Reverses the order of the signal's values without changing their order of occurrence in time.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[REVERSE] = REVERSE

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

RollingMeanFilter

Bases: BaseFilter

Applies a sliding window average to the signal.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[ROLLING_MEAN] = ROLLING_MEAN

The discriminator type for Pydantic.

window class-attribute instance-attribute

Python
window: int = Field(default=10, gt=0)

Size of the sliding window in samples.

center class-attribute instance-attribute

Python
center: bool = True

If True, centers the window on the current sample to minimize phase lag.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

RollingMedianFilter

Bases: BaseFilter

Applies a sliding window median filter. Highly effective for removing impulse noise (spikes) without blurring edges.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[MEDIAN] = MEDIAN

The discriminator type for Pydantic.

window class-attribute instance-attribute

Python
window: int = Field(default=10, gt=0)

Size of the sliding window in samples.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

RotationFilter

Bases: BaseFilter

Rotates a 3D vector component into a reference frame using a quaternion column.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[ROTATION] = ROTATION

The discriminator type for Pydantic.

quat_col class-attribute instance-attribute

Python
quat_col: str | None = Field(
    default=None, json_schema_extra={"ui_type": "quat_col"}
)

Base name of the quaternion column group (e.g. 'Bodies/hand/xquat'). Leave unset together with an origin_col for a pure translation with no rotation.

invert class-attribute instance-attribute

Python
invert: bool = True

If True, transforms world-to-local (invert the quaternion rotation; with no quat_col, subtracts origin_col instead of adding it).

origin_col class-attribute instance-attribute

Python
origin_col: str | None = Field(
    default=None, json_schema_extra={"ui_type": "vec_col"}
)

Base name of a position column group giving this frame's origin in world coordinates (e.g. 'Bodies/hand/xpos'). Only needed for position-type vectors, which need translating as well as rotating; leave unset for free vectors (velocity, angular velocity, force, etc.) that have no origin to translate against.

apply_to_frame

Python
apply_to_frame(
    df: DataFrame,
    vector_bases: set[str],
    point_bases: set[str] | None = None,
) -> DataFrame

Rotate all xyz vector families in vector_bases in one pass, and translate-then-rotate every family in point_bases. Used by MojoDataFrame.change_frame. Requires quat_col; point_bases additionally requires origin_col, since a position needs translating against a frame origin as well as rotating - unlike vector_bases, which is rotated only. A point_bases base's :m magnitude sibling, if present, is recomputed from the transformed x/y/z rather than left stale, since translation changes distance-from-origin.

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
def apply_to_frame(
    self,
    df: pl.DataFrame,
    vector_bases: set[str],
    point_bases: set[str] | None = None,
) -> pl.DataFrame:
    """Rotate all xyz vector families in `vector_bases` in one pass, and translate-then-rotate every family in `point_bases`. Used by `MojoDataFrame.change_frame`. Requires `quat_col`; `point_bases` additionally requires `origin_col`, since a position needs translating against a frame origin as well as rotating - unlike `vector_bases`, which is rotated only. A `point_bases` base's `:m` magnitude sibling, if present, is recomputed from the transformed x/y/z rather than left stale, since translation changes distance-from-origin."""
    point_bases = point_bases or set()
    if not self.quat_col:
        return df
    q_cols = [f"{self.quat_col}:{k}" for k in "xyzw"]
    missing = [c for c in q_cols if c not in df.columns]
    if missing:
        raise ValueError(
            f"Rotation failed: quaternion column(s) {missing} not found for quat_col '{self.quat_col}'."
        )
    if point_bases and not self.origin_col:
        raise ValueError(
            "Rotation failed: point_bases given but origin_col is not set."
        )
    qs = df.select(q_cols).to_numpy()
    origin = None
    if point_bases:
        o_cols = [f"{self.origin_col}:{k}" for k in "xyz"]
        missing_o = [c for c in o_cols if c not in df.columns]
        if missing_o:
            raise ValueError(
                f"Rotation failed: origin column(s) {missing_o} not found for origin_col '{self.origin_col}'."
            )
        origin = df.select(o_cols).to_numpy()

    new_columns: list[pl.Series] = []
    for base in vector_bases:
        v_cols = [f"{base}:x", f"{base}:y", f"{base}:z"]
        if not all(c in df.columns for c in v_cols):
            continue
        v_rot = self._rotate(df.select(v_cols).to_numpy(), qs.copy())
        new_columns.extend(
            [
                pl.Series(name=f"{base}:x", values=v_rot[:, 0]),
                pl.Series(name=f"{base}:y", values=v_rot[:, 1]),
                pl.Series(name=f"{base}:z", values=v_rot[:, 2]),
            ]
        )
    for base in point_bases:
        assert (
            origin is not None
        )  # guaranteed above whenever point_bases is non-empty
        v_cols = [f"{base}:x", f"{base}:y", f"{base}:z"]
        if not all(c in df.columns for c in v_cols):
            continue
        v_rot = self._rotate(df.select(v_cols).to_numpy(), qs.copy(), origin.copy())
        new_columns.extend(
            [
                pl.Series(name=f"{base}:x", values=v_rot[:, 0]),
                pl.Series(name=f"{base}:y", values=v_rot[:, 1]),
                pl.Series(name=f"{base}:z", values=v_rot[:, 2]),
            ]
        )
        mag_col = f"{base}:m"
        if mag_col in df.columns:
            new_columns.append(
                pl.Series(name=mag_col, values=np.linalg.norm(v_rot, axis=1))
            )
    return df.with_columns(new_columns) if new_columns else df

compose_to_frame

Python
compose_to_frame(
    df: DataFrame, quaternion_bases: set[str]
) -> DataFrame

Composes every quaternion family in quaternion_bases with this filter's quat_col quaternion: q' = quat_col^-1 (x) q when invert (world-to-local), or q' = quat_col (x) q otherwise (local-to-world). Used by MojoDataFrame.change_frame for orientation columns, which need composition rather than the sandwich rotation apply_to_frame uses for vectors/points. origin_col is irrelevant here - quaternions don't translate.

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
def compose_to_frame(
    self, df: pl.DataFrame, quaternion_bases: set[str]
) -> pl.DataFrame:
    """Composes every quaternion family in `quaternion_bases` with this filter's `quat_col` quaternion: q' = quat_col^-1 (x) q when `invert` (world-to-local), or q' = quat_col (x) q otherwise (local-to-world). Used by `MojoDataFrame.change_frame` for orientation columns, which need composition rather than the sandwich rotation `apply_to_frame` uses for vectors/points. `origin_col` is irrelevant here - quaternions don't translate."""
    if not self.quat_col:
        return df
    q_cols = [f"{self.quat_col}:{k}" for k in "xyzw"]
    missing = [c for c in q_cols if c not in df.columns]
    if missing:
        raise ValueError(
            f"Rotation failed: quaternion column(s) {missing} not found for quat_col '{self.quat_col}'."
        )
    qb = _normalize_quaternions(df.select(q_cols).to_numpy())
    if self.invert:
        qb = qb * np.array([-1.0, -1.0, -1.0, 1.0])

    new_columns: list[pl.Series] = []
    for base in quaternion_bases:
        a_cols = [f"{base}:{k}" for k in "xyzw"]
        if not all(c in df.columns for c in a_cols):
            continue
        qa = _normalize_quaternions(df.select(a_cols).to_numpy())
        q_new = _hamilton_product(qb, qa)
        new_columns.extend(
            pl.Series(name=f"{base}:{k}", values=q_new[:, i])
            for i, k in enumerate("xyzw")
        )
    return df.with_columns(new_columns) if new_columns else df

RoundFilter

Bases: BaseFilter

Quantizes the signal to a fixed number of decimal places.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[ROUND] = ROUND

The discriminator type for Pydantic.

method class-attribute instance-attribute

Python
method: Literal["round", "floor", "ceil"] = Field(
    default="round", json_schema_extra={"ui_type": "select"}
)

Rounding method: round (nearest), floor (toward -inf), or ceil (toward +inf).

decimals class-attribute instance-attribute

Python
decimals: int = Field(default=0, ge=0)

Number of decimal places to round to (only used when method is 'round').

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

SavitzkyGolayFilter

Bases: BaseFilter

Applies a Savitzky-Golay smoothing filter by fitting a polynomial to the data. Preserves signal features (like peaks and transients) better than a simple moving average.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[SAVITZKY_GOLAY] = SAVITZKY_GOLAY

The discriminator type for Pydantic.

window class-attribute instance-attribute

Python
window: int = Field(default=11, gt=1)

Number of samples in the sliding window; must be an odd integer.

order class-attribute instance-attribute

Python
order: int = Field(default=2, ge=0)

The order of the polynomial used to fit the samples.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

ScaleFilter

Bases: BaseFilter

Applies a linear transformation: (value * factor) + offset.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[SCALE] = SCALE

The discriminator type for Pydantic.

factor class-attribute instance-attribute

Python
factor: float = 1.0

Multiplicative gain applied to the signal.

offset class-attribute instance-attribute

Python
offset: float = 0.0

Additive constant applied after scaling.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

SignFilter

Bases: BaseFilter

Returns the sign of each sample: 1 for positive, -1 for negative, 0 for zero.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[SIGN] = SIGN

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

SortFilter

Bases: BaseFilter

Sorts the signal's values in ascending or descending order.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[SORT] = SORT

The discriminator type for Pydantic.

descending class-attribute instance-attribute

Python
descending: bool = False

Whether to sort in descending order.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

StandardDeviationFilter

Bases: BaseFilter

Reduces the signal to its standard deviation, broadcast across every sample.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[STAT_STANDARD_DEVIATION] = (
    STAT_STANDARD_DEVIATION
)

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

TaringFilter

Bases: BaseFilter

Offsets the entire signal so that the first sample is zero.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[TARING] = TARING

The discriminator type for Pydantic.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

TrigFilter

Bases: BaseFilter

Applies a trigonometric or angle-conversion function to the signal.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[TRIG] = TRIG

The discriminator type for Pydantic.

func class-attribute instance-attribute

Python
func: _TRIG_FUNCS = Field(
    default="sin", json_schema_extra={"ui_type": "select"}
)

The trig function to apply.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

UnitFilter

Bases: BaseFilter

Unit conversion using Pint. Ensures dimensional consistency and applies necessary scaling/offsets.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[UNIT] = UNIT

The discriminator type for Pydantic.

from_unit instance-attribute

Python
from_unit: SignalUnit

The original unit of the telemetry data (e.g., 'rad').

to_unit instance-attribute

Python
to_unit: SignalUnit

The target unit for analysis/display (e.g., 'deg').

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None

WrapFilter

Bases: BaseFilter

Keeps circular data (like Euler angles or radians) within a specific range. Ensures continuity when a signal crosses the upper or lower boundary.

enabled class-attribute instance-attribute

Python
enabled: bool = True

Whether this filter step is active.

type class-attribute instance-attribute

Python
type: Literal[WRAP] = WRAP

The discriminator type for Pydantic.

lb class-attribute instance-attribute

Python
lb: float = -pi

Lower boundary for the wrap operation.

ub class-attribute instance-attribute

Python
ub: float = pi

Upper boundary for the wrap operation.

apply_with_context

Python
apply_with_context(
    series: Series, df: DataFrame
) -> Series | None

Override for filters that need access to other columns. Receives the current (already-transformed) series and the original dataframe. Return None to fall back to apply(expr).

Source code in src/mujoco_mojo/utils/filters/filters.py
Python
116
117
118
119
120
121
122
123
124
def apply_with_context(
    self, series: pl.Series, df: pl.DataFrame
) -> pl.Series | None:
    """
    Override for filters that need access to other columns.
    Receives the current (already-transformed) series and the original dataframe.
    Return None to fall back to apply(expr).
    """
    return None