What causes "Unknown clip_method" in microsoft/qlib?

Use one of "clamp", "tanh", "sigmoid".

microsoft/qlib · error · ValueError

Unknown clip_method

Error message

Unknown clip_method

What it means

preds_to_weight_with_clamp converts raw meta-model predictions into instrument weights, choosing a transform by clip_method: 'clamp' (hard clamp at 1/clip_weight..clip_weight), 'tanh' (exp(tanh(x)*log(clip_weight))), or 'sigmoid'. Any other string reaches the else and raises ValueError.

Source

Thrown at qlib/contrib/meta/data_selection/utils.py:93

    clip_method: str
        The clip method. Current available: "clamp", "tanh", and "sigmoid".
    """
    if clip_weight is not None:
        if clip_method == "clamp":
            weights = torch.exp(preds)
            weights = weights.clamp(1.0 / clip_weight, clip_weight)
        elif clip_method == "tanh":
            weights = torch.exp(torch.tanh(preds) * np.log(clip_weight))
        elif clip_method == "sigmoid":
            # intuitively assume its sum is 1
            if clip_weight == 0.0:
                weights = torch.ones_like(preds)
            else:
                sm = nn.Sigmoid()
                weights = sm(preds) * clip_weight  # TODO: The clip_weight is useless here.
                weights = weights / torch.sum(weights) * weights.numel()
        else:
            raise ValueError("Unknown clip_method")
    else:
        weights = torch.exp(preds)
    return weights


class SingleMetaBase(nn.Module):
    def __init__(self, hist_n, clip_weight=None, clip_method="clamp"):
        # method can be tanh or clamp
        super().__init__()
        self.clip_weight = clip_weight
        if clip_method in ["tanh", "clamp"]:
            if self.clip_weight is not None and self.clip_weight < 1.0:
                self.clip_weight = 1 / self.clip_weight
        self.clip_method = clip_method

    def is_enabled(self):
        if self.clip_weight is None:
            return True

View on GitHub (pinned to 79633dd950)

Solutions

Use one of "clamp", "tanh", "sigmoid".
If you want unclipped weights, pass clip_weight=None — the whole transform block is skipped and weights are exp(preds).
Validate clip_method at configuration load time so the error surfaces early with a clear message.

Example fix

// before
w = preds_to_weight_with_clamp(preds, clip_weight=3.0, clip_method="none")

// after
w = preds_to_weight_with_clamp(preds, clip_weight=3.0, clip_method="clamp")
# unclipped: preds_to_weight_with_clamp(preds, clip_weight=None)

Defensive patterns

Strategy: validation

Validate before calling

VALID = {"clamp", "tanh", "sigmoid"}
if clip_method not in VALID and clip_weight is not None:
    raise ValueError(f"clip_method must be one of {VALID}, got {clip_method!r}")
w = preds_to_weight_with_clamp(preds, clip_weight, clip_method)

Type guard

def is_clip_method(m) -> bool:
    return m in ("clamp", "tanh", "sigmoid")

Try / catch

try:
    w = preds_to_weight_with_clamp(preds, clip_weight, clip_method)
except ValueError as e:
    if "Unknown clip_method" in str(e):
        w = preds_to_weight_with_clamp(preds, clip_weight, "tanh")
    else:
        raise

Prevention

Pass clip_weight=None when clipping is not wanted — the method check is skipped entirely.
Validate clip_method wherever configs are loaded (SingleMetaBase and the helper both accept it).
Keep the valid set as a shared constant in your code.

When it happens

Trigger: Calling preds_to_weight_with_clamp(preds, clip_weight=w, clip_method='none'/'softplus'/etc.), or SingleMetaBase(..., clip_method=...) with an unsupported name.

Common situations: Assuming clip_weight=None disables clipping while passing an invalid clip_method anyway; typos ('Tanh', 'clamped'); newer code expecting a method name that this version does not have.

Related errors

AI-assisted analysis of microsoft/qlib@79633dd950 (2026-08-15). Data as JSON: /api/errors/149822032c03e148. Report an issue: GitHub.