pola-rs/polars · error · ValueError

require `com` >= 0 (found {com!r})

Error message

require `com` >= 0 (found {com!r})

What it means

_prepare_alpha validates that com (center of mass) is non-negative: com >= 0 maps to alpha = 1/(1+com), and negative com would yield alpha > 1, which is not a valid smoothing factor. The ValueError reports the offending value via {com!r} so you see exactly what was passed.

Source

Thrown at py-polars/src/polars/expr/expr.py:12797

        return wrap_expr(result)


def _prepare_alpha(
    com: float | int | None = None,
    span: float | int | None = None,
    half_life: float | int | None = None,
    alpha: float | int | None = None,
) -> float:
    """Normalise EWM decay specification in terms of smoothing factor 'alpha'."""
    if sum((param is not None) for param in (com, span, half_life, alpha)) > 1:
        msg = (
            "parameters `com`, `span`, `half_life`, and `alpha` are mutually exclusive"
        )
        raise ValueError(msg)
    if com is not None:
        if com < 0.0:
            msg = f"require `com` >= 0 (found {com!r})"
            raise ValueError(msg)
        alpha = 1.0 / (1.0 + com)

    elif span is not None:
        if span < 1.0:
            msg = f"require `span` >= 1 (found {span!r})"
            raise ValueError(msg)
        alpha = 2.0 / (span + 1.0)

    elif half_life is not None:
        if half_life <= 0.0:
            msg = f"require `half_life` > 0 (found {half_life!r})"
            raise ValueError(msg)
        alpha = 1.0 - math.exp(-math.log(2.0) / half_life)

    elif alpha is None:
        msg = "one of `com`, `span`, `half_life`, or `alpha` must be set"
        raise ValueError(msg)

View on GitHub (pinned to df599052da)

Solutions

1. Pass com >= 0, or equivalently switch to alpha in (0, 1].
2. Trace where the negative value originates and clamp/validate it at the source (config parsing).
3. If you meant faster decay, use a smaller com (toward 0) — direction is opposite to what you may expect.

Example fix

# before
pl.col('x').ewm_mean(com=-0.5)

# after
pl.col('x').ewm_mean(com=0.5)

if com is not None:
    assert com >= 0, f'com must be >= 0, got {com!r}'

When it happens

Trigger: pl.col('x').ewm_mean(com=-0.5); also float('nan') sneaking in from config compares False against 0.0... only strictly negative values trigger it.

Common situations: Sign errors in upstream calculations that derive com from data; user-tunable 'decay' knobs where a negative value was never rejected; porting formulas that define com differently (e.g. as a negative exponent).

Related errors

• parameters `com`, `span`, `half_life`, and `alpha` are mutua
• require `span` >= 1 (found {span!r})
• require `half_life` > 0 (found {half_life!r})
• one of `com`, `span`, `half_life`, or `alpha` must be set
• require 0 < `alpha` <= 1 (found {alpha!r})

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/aeaa852628835335. Report an issue: GitHub.