{"record":{"id":"e161ef8be1662c01","repo":"pola-rs/polars","slug":"require-span-1-found-span-r","errorCode":null,"errorMessage":"require `span` >= 1 (found {span!r})","messagePattern":"require `span` >= 1 \\(found (.+?)\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/expr/expr.py","lineNumber":12803,"sourceCode":"    half_life: float | int | None = None,\n    alpha: float | int | None = None,\n) -> float:\n    \"\"\"Normalise EWM decay specification in terms of smoothing factor 'alpha'.\"\"\"\n    if sum((param is not None) for param in (com, span, half_life, alpha)) > 1:\n        msg = (\n            \"parameters `com`, `span`, `half_life`, and `alpha` are mutually exclusive\"\n        )\n        raise ValueError(msg)\n    if com is not None:\n        if com < 0.0:\n            msg = f\"require `com` >= 0 (found {com!r})\"\n            raise ValueError(msg)\n        alpha = 1.0 / (1.0 + com)\n\n    elif span is not None:\n        if span < 1.0:\n            msg = f\"require `span` >= 1 (found {span!r})\"\n            raise ValueError(msg)\n        alpha = 2.0 / (span + 1.0)\n\n    elif half_life is not None:\n        if half_life <= 0.0:\n            msg = f\"require `half_life` > 0 (found {half_life!r})\"\n            raise ValueError(msg)\n        alpha = 1.0 - math.exp(-math.log(2.0) / half_life)\n\n    elif alpha is None:\n        msg = \"one of `com`, `span`, `half_life`, or `alpha` must be set\"\n        raise ValueError(msg)\n\n    elif not (0 < alpha <= 1):\n        msg = f\"require 0 < `alpha` <= 1 (found {alpha!r})\"\n        raise ValueError(msg)\n\n    return alpha\n","sourceCodeStart":12785,"sourceCodeEnd":12821,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/expr/expr.py#L12785-L12821","documentation":"_prepare_alpha requires span >= 1 because span maps to alpha = 2/(span+1); a span below 1 would produce alpha > 1, an invalid smoothing factor. span=1 means no smoothing (alpha=1) and is the accepted lower bound.","triggerScenarios":"pl.col('x').ewm_mean(span=0.5) or span=0; often from dividing by a window that can collapse, or from a percentage (0..1) mistakenly passed where a span was expected.","commonSituations":"Confusing span with fraction/alpha (e.g. passing 0.2 intending 20% weight); spans computed as ratios; data-driven spans like span = n_observations / total where the ratio can drop below 1.","solutions":["Pass span >= 1 (e.g. span=5).","If the value is a proportion, convert: alpha = 2/(span+1) — or just pass it as alpha if in (0,1].","Guard computed spans with max(span, 1) if sub-1 values are possible but nonsensical in your domain."],"exampleFix":"# before\npl.col('x').ewm_mean(span=0.5)\n\n# after\npl.col('x').ewm_mean(span=5)\n# proportion? then\npl.col('x').ewm_mean(alpha=0.5)","handlingStrategy":"validation","validationCode":"if span is not None:\n    assert span >= 1, f'span must be >= 1, got {span!r}'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["span is a window length, not a ratio — minimum meaningful value is 1.","Unit-test EWM parameters at their boundaries (1 and large values)."],"tags":["validation","polars","expression","ewm","statistics"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}