SearchLibrium 0.0.239__tar.gz → 0.0.241__tar.gz

{searchlibrium-0.0.239/src/SearchLibrium.egg-info → searchlibrium-0.0.241}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SearchLibrium
-Version: 0.0.239
+Version: 0.0.241
 Summary: Automated specification search for discrete choice models (logit, mixed logit, nested logit, RRM and more) using metaheuristic optimisation
 Author: Mario Fernando Taco Morales, Alexander Paz, Prithvi Beeramole, Robert Burdett
 Author-email: Zeke Ahern <z.ahern@qut.edu.au>

{searchlibrium-0.0.239 → searchlibrium-0.0.241}/pyproject.toml

@@ -129,7 +129,7 @@ Documentation = "https://pypi.org/project/SearchLibrium/"
 realpython = "SearchLibrium.__main__:main"
 
 [tool.bumpver]
-current_version = "0.0.239"
+current_version = "0.0.241"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "[skip ci] Bump version {old_version} -> {new_version}"
 commit = true

{searchlibrium-0.0.239 → searchlibrium-0.0.241}/src/SearchLibrium/__init__.py

@@ -140,6 +140,8 @@ try:
     from .selection_models import BinaryProbit, HeckmanTwoStep
     from .zero_inflated_ordered_probit import ZeroInflatedOrderedProbit, ZeroInflatedProbit
     from .latent_class import LatentClassMixedLogit
+    from .latent_spec import (vip_table, near_unidentified_report,
+                              align_classes, propose_class_params_spec)
     from .mdcev import MDCEVFitResult, MDCEVModel
     from .multinomial_probit import MultinomialProbit
     from .MixedLogitGSE import MixedLogitGSE
@@ -173,6 +175,8 @@ except Exception:
         from selection_models import BinaryProbit, HeckmanTwoStep
         from zero_inflated_ordered_probit import ZeroInflatedOrderedProbit, ZeroInflatedProbit
         from latent_class import LatentClassMixedLogit
+        from latent_spec import (vip_table, near_unidentified_report,
+                                 align_classes, propose_class_params_spec)
         from mdcev import MDCEVFitResult, MDCEVModel
         from multinomial_probit import MultinomialProbit
         from MixedLogitGSE import MixedLogitGSE
@@ -209,7 +213,8 @@ __all__ = [
     "RandomRegret", "MixedRandomRegret", "OrderedLogit", "OrderedLogitLong", "ExplodedLogit", "MixedExplodedLogit",
     "BinaryProbit", "HeckmanTwoStep",
     "ZeroInflatedOrderedProbit", "ZeroInflatedProbit",
-    "LatentClassMixedLogit", "MDCEVFitResult", "MDCEVModel", "MultinomialProbit",
+    "LatentClassMixedLogit", "vip_table", "near_unidentified_report",
+    "align_classes", "propose_class_params_spec", "MDCEVFitResult", "MDCEVModel", "MultinomialProbit",
     "MixedLogitGSE", "RandomParameters", "ConstraintBuilder", "create_constraints",
     "Parameters", "misc",
     "SAPBIL", "ProbabilityMatrix", "HSPBIL", "SparseEAAGDS", "BanditSA", "PerturbationBandit",

{searchlibrium-0.0.239 → searchlibrium-0.0.241}/src/SearchLibrium/latent_class.py

@@ -57,6 +57,9 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
         smart_jitter=0.5,
         min_share=0.05,
         sort_classes=True,
+        gamma_max_abs=None,
+        share_floor=0.0,
+        membership_standardize=False,
     ):
         self.n_classes = int(n_classes)
         self.maxiter = int(maxiter)
@@ -80,6 +83,22 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
         self.smart_jitter = float(smart_jitter)
         self.min_share = float(min_share)
         self.sort_classes = bool(sort_classes)
+        # ── membership identification guardrails (all opt-in) ──────────
+        # gamma_max_abs : box bound |gamma| <= B on membership coefficients in
+        #   the L-BFGS-B M-step. Stops one covariate from saturating the
+        #   membership softmax and collapsing a class. None = unbounded.
+        # share_floor : minimum allowed implied class share; after each
+        #   membership M-step, gammas shrink toward 0 until every class
+        #   clears the floor. 0.0 = off.
+        # membership_standardize : z-score X_membership at setup so bounds and
+        #   penalties are scale-free (fitted gammas then live in standardized
+        #   units; means/stds are kept in _memb_standardize_).
+        self.gamma_max_abs = (None if gamma_max_abs is None
+                              else float(gamma_max_abs))
+        self.share_floor = float(share_floor)
+        self.membership_standardize = bool(membership_standardize)
+        self._memb_standardize_ = None
+        self._memb_floor_shrinks_ = 0
         # Diagnostics populated by fit()/fit_direct().
         self.starts_ = []
         self.sort_perm_ = None
@@ -299,6 +318,21 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
             self.K_membership = 0
             self.X_membership = None
 
+        # ── Optional membership standardisation (scale-free bounds) ──────
+        # Applied here so the L-BFGS-B box, the L1/L2 penalties and the VIP
+        # swing diagnostics all operate in comparable units.
+        if (getattr(self, 'membership_standardize', False)
+                and self.X_membership is not None and self.K_membership > 0):
+            _mu = np.nanmean(self.X_membership, axis=0)
+            _sd = np.nanstd(self.X_membership, axis=0)
+            _sd = np.where(np.isfinite(_sd) & (_sd > 0), _sd, 1.0)
+            self.X_membership = ((self.X_membership - _mu) / _sd).astype(float)
+            self._memb_standardize_ = {
+                'mean': np.asarray(_mu, dtype=float),
+                'std': np.asarray(_sd, dtype=float),
+                'vars': list(self.membership_vars or []),
+            }
+
         self._prepare_backend_arrays()
         self._prepare_membership_backend()
         return self
@@ -439,14 +473,60 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
         if gamma0.ndim > 1:
             gamma0 = gamma0.ravel()
 
+        # Opt-in box bound: stops one covariate from saturating the membership
+        # softmax (the class-collapse pathology). None = unbounded (legacy).
+        _B = getattr(self, 'gamma_max_abs', None)
+        _bounds = None
+        if _B is not None:
+            try:
+                _b = float(_B)
+                if np.isfinite(_b) and _b > 0:
+                    _bounds = [(-_b, _b)] * int(np.asarray(gamma0).size)
+            except Exception:
+                _bounds = None
+
         result = minimize(
             lambda g: self._membership_loglik_and_grad(g, weights),
             gamma0,
             method="L-BFGS-B",
             jac=True,
+            bounds=_bounds,
             options={"maxiter": self.membership_maxiter},
         )
-        return result.x.reshape(C - 1, Km)
+        _g = result.x.reshape(C - 1, Km)
+        return self._project_gammas_to_share_floor(_g)
+
+    def _project_gammas_to_share_floor(self, gammas):
+        """Shrink membership coefficients until every implied class clears
+        ``share_floor`` (or give up after 25 halvings and return as-is).
+
+        A saturated membership equation assigns ~everyone by one covariate;
+        pulling gammas toward 0 moves priors back toward uniform, which
+        re-inflates the emptied class and keeps its utility parameters
+        identified. Only active when ``share_floor > 0``.
+        """
+        _floor = float(getattr(self, 'share_floor', 0.0) or 0.0)
+        if (not _floor > 0 or not self._has_membership
+                or self.X_membership is None or self.K_membership <= 0):
+            return gammas
+        _g = np.asarray(gammas, dtype=float)
+        for _ in range(25):
+            try:
+                _priors = self._compute_membership_priors(_g)
+            except Exception:
+                break
+            try:
+                _shares = np.asarray(_priors, dtype=float).mean(axis=0)
+            except Exception:
+                break
+            if bool(np.all(np.isfinite(_shares))) and bool(np.all(_shares >= _floor)):
+                break
+            _g = 0.5 * _g
+            try:
+                self._memb_floor_shrinks_ = int(getattr(self, '_memb_floor_shrinks_', 0)) + 1
+            except Exception:
+                pass
+        return _g
 
     def _make_initial_gammas(self, rng, gammas0=None):
         """Initialise membership coefficients."""
@@ -507,7 +587,7 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
         if hasattr(self, cache_key):
             return getattr(self, cache_key)
 
-        if not self._jax_enabled or len(set(self._Ks)) != 1 or self._panelled:
+        if not self._jax_enabled or len(set(self._Ks)) != 1:
             setattr(self, cache_key, None)
             return None
 
@@ -531,6 +611,13 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
         l2 = self.l2_penalty
         l1 = self.l1_penalty
 
+        # Panel aggregation: the class marginalisation is per decision-maker, so
+        # per-task log-choice is segment-summed into M = n_panels person totals.
+        panelled = bool(self._panelled)
+        M = int(self.n_panels)
+        panel_idx_b = self.jnp.asarray(self.panel_idx) if panelled else None
+        seg_sum = self.jax.ops.segment_sum
+
         def _negloglik_flat(params):
             phi = params[:n_phi]
             beta_flat = params[n_phi:n_phi + C * K]
@@ -543,11 +630,15 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
             denom = jnp.clip(exp_u.sum(axis=2, keepdims=True), 1e-300)
             probs = exp_u / denom
             chosen = jnp.clip((probs * y_b[:, None, :]).sum(axis=2), 1e-300)
-            log_chosen = jnp.log(chosen)
+            log_chosen_task = jnp.log(chosen)
+            if panelled:
+                log_chosen = seg_sum(log_chosen_task, panel_idx_b, num_segments=M)
+            else:
+                log_chosen = log_chosen_task
 
             if has_memb:
                 gammas = params[n_phi + C * K:].reshape(C - 1, Km)
-                logits = jnp.zeros((N, C))
+                logits = jnp.zeros((M, C))
                 for c in range(C - 1):
                     logits = logits.at[:, c].set(X_memb @ gammas[c])
                 logits = logits - jnp.max(logits, axis=1, keepdims=True)
@@ -557,7 +648,7 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
             else:
                 phi_full = jnp.concatenate([phi, jnp.zeros(1)])
                 log_priors_raw = phi_full - self.jax_logsumexp(phi_full)
-                log_prior = jnp.broadcast_to(log_priors_raw[None, :], (N, C))
+                log_prior = jnp.broadcast_to(log_priors_raw[None, :], (M, C))
 
             log_joint = log_chosen + log_prior
             log_marg = self.jax_logsumexp(log_joint, axis=1)
@@ -1482,6 +1573,7 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
         member_params_spec=None,
         class_params_spec=None,
         panels=None,
+        ident_penalty_kwargs=None,
         **kwargs,
     ):
         """Search over number of latent classes, optionally using DE warm-start.
@@ -1539,10 +1631,19 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
             # Pareto-style significance prioritisation:
             #  1) prefer fewer insignificant variable groups,
             #  2) among models with equal nsig, prefer lower criterion (e.g. BIC).
+            # criterion="penalized_bic" adds the latent_spec identification
+            # penalty (collapse / saturation / weak-identification) to BIC so
+            # degenerate specs lose even when their raw likelihood is good.
             from .search import count_insig_groups
             nsig = count_insig_groups(model.coeff_names, model.pvalues,
                                       p_val=kwargs.get('p_val', 0.05))
-            score = getattr(model, criterion)
+            if criterion == "penalized_bic":
+                from .latent_spec import score_spec as _score_spec
+                _sc = _score_spec(model,
+                                  **(ident_penalty_kwargs or {}))
+                score = _sc["penalized_bic"]
+            else:
+                score = getattr(model, criterion)
             if (best_model is None
                 or nsig < _best_nsig
                 or (nsig == _best_nsig and score < getattr(best_model, criterion))):
@@ -1595,6 +1696,9 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
         ll = float(logsumexp(log_joint, axis=1).sum())
         ll -= self._regularize_l2_betas(betas)
         ll -= self._regularize_l1_betas(betas)
+        if has_gamma:
+            ll -= self._regularize_l2_gammas(gammas)
+            ll -= self._regularize_l1_gammas(gammas)
         return ll
 
     def _autograd_hessian(self, params: np.ndarray) -> np.ndarray | None:
@@ -1612,10 +1716,6 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
         if len(set(self._Ks)) != 1:
             print("[LC] Autograd Hessian requires all classes to share the same variable set.")
             return None
-        if self._panelled:
-            # The JIT objective marginalises per task, not per person; use the
-            # panel-aware finite-difference Hessian instead.
-            return None
 
         cache_key = "_cached_autograd_hessian_fn"
         if hasattr(self, cache_key):
@@ -1782,25 +1882,41 @@ class LatentClassMixedLogit(DiscreteChoiceModel):
             info = -H_num   # observed info = -hessian(loglik)
             se_method = "numerical-hessian (finite differences)"
 
+        # When a membership equation is active the class-share logits (phi) do
+        # not enter the likelihood — they are exactly unidentified, which makes
+        # the observed-information matrix exactly singular in those directions
+        # (an artefact, not a genuinely ill-conditioned model).  Invert only the
+        # identified block; phi rows/cols are reinstated with zero covariance.
+        P = len(params)
+        if has_gamma and n_phi > 0:
+            keep = np.arange(n_phi, P)
+        else:
+            keep = np.arange(P)
+        info_id = info[np.ix_(keep, keep)]
+
         cond_number = np.nan
-        cov = None
+        cov_id = None
         try:
-            eigvals = np.linalg.eigvalsh(info)
+            eigvals = np.linalg.eigvalsh(info_id)
             cond_number = float(eigvals.max() / max(eigvals.min(), 1e-300))
 
             if eigvals.min() < 1e-8 * eigvals.max():
                 ridge = 1e-6 * eigvals.max()
-                info_reg = info + ridge * np.eye(len(params))
-                cov = np.linalg.inv(info_reg)
+                info_reg = info_id + ridge * np.eye(len(keep))
+                cov_id = np.linalg.inv(info_reg)
                 se_method = "hessian (ridge-regularised)"
             else:
-                cov = np.linalg.inv(info)
+                cov_id = np.linalg.inv(info_id)
         except np.linalg.LinAlgError:
-            cov = np.linalg.pinv(info)
+            cov_id = np.linalg.pinv(info_id)
             se_method = "hessian (pinv fallback)"
 
-        if cov is None:
-            cov = np.linalg.pinv(info)
+        if cov_id is None:
+            cov_id = np.linalg.pinv(info_id)
+
+        # Re-embed the identified covariance into the full parameter space.
+        cov = np.zeros((P, P))
+        cov[np.ix_(keep, keep)] = cov_id
 
         se = np.sqrt(np.clip(np.diag(cov), 0.0, None))