Define numeric regression-term specifications explicitly
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 124
- Forks
- 24
- Avg merge
- 19h 32m
- Merged PRs (30d)
- 60
Description
## Problem
HSSM's public regression-prior documentation currently says that each term may be
assigned either a prior or a numeric value. In the current Bambi integration,
however, numeric values are not interpreted as fixed regression coefficients.
Both common and group-specific terms fail during Bambi prior preparation:
```python
bmb.Model(..., priors={"x": 2.0})
bmb.Model(..., priors={"1|participant_id": 2.0})
```
Both raise:
```text
ValueError: 'prior' must be instance of Prior or None.
```
This is distinct from fixing an entire HSSM distributional parameter to a number.
A numeric regression coefficient would need explicit predictor semantics; it is not
currently a supported Bambi prior.
The audit for #1225 found this while implementing group-prior compatibility checks.
#1225 will give numeric **group-term** specifications an early, specific HSSM error
instead of forwarding them to Bambi. Numeric common-term specifications and the
broader public contract remain unresolved here.
## Decision needed
Choose and apply one consistent contract across exact common terms, exact group
terms, and the `common` / `group_specific` wildcards:
1. **Validation/documentation policy:** numeric regression-term values are not
supported; validate them centrally before Bambi and remove the claim that they
fix coefficients.
2. **Fixed-coefficient feature:** define and implement fixed regression-coefficient
semantics explicitly in HSSM, including how a fixed coefficient contributes to
the predictor and how vector-valued Formulae terms are handled.
The second option is a feature, not a small prior-conversion change, because Bambi's
prior mapping does not currently provide fixed-coefficient semantics.
## Proposed commit plan
### 1. `test: define numeric regression-term behavior (#NNNN)`
- Reproduce current behavior for numeric common and group-specific exact keys.
- Cover both wildcards, scalar and vector-valued Formulae terms, and
`prior_settings="safe"` / `None`.
- Distinguish numeric regression-term specifications from fixed HSSM parameters.
### 2. `fix: enforce the chosen numeric regression-term contract (#NNNN)`
- If unsupported, reject every numeric regression-term specification in HSSM with
one clear pre-Bambi error naming parameter and term.
- If supported, implement the predictor contribution explicitly and prove the fixed
coefficient is not represented by a PyMC free RV.
- Preserve exact-over-wildcard precedence.
### 3. `docs: clarify fixed values versus regression priors (#NNNN)`
- Correct constructor/type documentation and examples.
- Explain the difference between fixing an HSSM parameter and fixing a regression
coefficient.
- Add an Unreleased changelog entry and cross-link #1225.
## Acceptance criteria
- Common and group terms follow the same documented policy.
- Users never reach Bambi's generic `Prior or None` error for a numeric term.
- Exact and wildcard precedence is covered.
- Vector-valued terms have defined behavior or a precise rejection.
- No sampling is required; graph/structure tests are sufficient.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the common and group-specific numeric examples through Bambi prior preparation, including wildcard and vector-valued Formulae cases. Compare behavior with prior_settings="safe" and None, then use graph or structure tests to verify one consistent contract, exact-over-wildcard precedence, and a clear pre-Bambi error without sampling.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend, documentation, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100