lnccbrown / lnccbrown/HSSM

Define numeric regression-term specifications explicitly

Open
#1,271 1 comment 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.