structural-topic-model 0.2.0__py3-none-any.whl

pystm/stm.py

@@ -0,0 +1,443 @@
+"""Structural Topic Model with a scikit-learn style API.
+
+Port of the R ``stm`` package's core estimation routine (variational EM
+for the logistic-normal topic model with prevalence covariates).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.sparse import csr_matrix, issparse
+from scipy.stats import rankdata
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.utils import check_random_state
+from sklearn.utils.validation import check_is_fitted
+
+from ._estep import decompose_sigma, estep, optimize_document
+from ._mnreg import mnreg
+from ._mstep import opt_beta, opt_mu, opt_sigma
+from ._spectral import spectral_init
+from ._utils import row_softmax, safelog, to_doc_list
+
+
+class StructuralTopicModel(BaseEstimator, TransformerMixin):
+    """Structural Topic Model (STM) with variational EM.
+
+    STM is a logistic-normal topic model in which document metadata
+    ("prevalence covariates") shifts the prior mean of each document's
+    topic proportions.  Without covariates the model reduces to the
+    Correlated Topic Model.  The API follows
+    :class:`sklearn.decomposition.LatentDirichletAllocation`; covariates
+    are passed to :meth:`fit` / :meth:`transform` via the ``prevalence``
+    keyword.
+
+    Parameters
+    ----------
+    n_components : int, default=10
+        Number of topics K (must be >= 2).
+    init : {"spectral", "random"}, default="spectral"
+        Initialization method.  "spectral" is the deterministic anchor-word
+        algorithm of Arora et al. (2013), recommended by the stm authors.
+    max_iter : int, default=500
+        Maximum number of EM iterations.
+    tol : float, default=1e-5
+        EM stops when the relative change of the approximate evidence
+        lower bound falls below ``tol``.
+    sigma_prior : float, default=0.0
+        Weight in [0, 1] of regularization of the topic covariance matrix
+        towards its diagonal.
+    gamma_max_iter : int, default=1000
+        Iteration limit for the variational prevalence regression.
+    e_step_max_iter : int, default=500
+        BFGS iteration limit for each document's optimization.
+    max_vocab : int or None, default=10000
+        With spectral initialization, only this many most frequent terms
+        are used to build the gram matrix (None disables the cap).
+    content_interactions : bool, default=True
+        For content covariate models, whether to include topic-by-level
+        interaction deviations in addition to the main effects.
+    warm_start : bool, default=False
+        When True, repeated calls to :meth:`fit` continue EM from the
+        previous solution instead of re-initializing (the analogue of the
+        R package's ``model=`` restart argument).  Each call runs up to
+        ``max_iter`` further iterations and ``bound_`` keeps the full
+        history.  ``n_components``, the vocabulary and the covariate
+        setup must stay the same; per-document state is reused only when
+        the corpus has the same number of documents.
+    random_state : int, RandomState or None, default=None
+        Only used for ``init="random"``; the spectral method is
+        deterministic.
+    verbose : int, default=0
+        If positive, print the bound after each EM iteration.
+
+    Attributes
+    ----------
+    components_ : ndarray of shape (n_components, n_features)
+        Topic-word distributions (each row sums to 1).  Note this differs
+        from sklearn's LDA, whose ``components_`` holds unnormalized
+        pseudo-counts.  For content covariate models this is the
+        aspect-frequency-weighted average of ``aspect_components_``.
+    aspect_components_ : ndarray of shape (n_levels, n_components, n_features) or None
+        Per-content-level topic-word distributions (content models only).
+    kappa_ : dict or None
+        SAGE parameters of the content model: baseline log-probabilities
+        ``m`` (n_features,) and sparse deviations ``params``.
+    content_levels_ : ndarray or None
+        Sorted unique content covariate levels seen at fit time.
+    gamma_ : ndarray of shape (1 + n_covariates, n_components - 1) or None
+        Prevalence regression coefficients (first row is the intercept).
+        None when no covariates were used.
+    mu_ : ndarray
+        Prior means of eta: shape (n_components - 1,) without covariates,
+        (n_samples, n_components - 1) with covariates.
+    sigma_ : ndarray of shape (n_components - 1, n_components - 1)
+        Topic covariance matrix.
+    theta_ : ndarray of shape (n_samples, n_components)
+        Topic proportions of the training documents.
+    eta_ : ndarray of shape (n_samples, n_components - 1)
+        Variational means of the logistic-normal parameters.
+    bound_ : list of float
+        Approximate evidence lower bound at each EM iteration.
+    n_iter_ : int
+        Number of EM iterations run.
+    converged_ : bool
+        Whether the bound converged before ``max_iter``.
+
+    References
+    ----------
+    Roberts, M., Stewart, B., & Tingley, D. (2019). "stm: An R Package for
+    Structural Topic Models." Journal of Statistical Software 91(2).
+    """
+
+    def __init__(self, n_components=10, *, init="spectral", max_iter=500,
+                 tol=1e-5, sigma_prior=0.0, gamma_max_iter=1000,
+                 e_step_max_iter=500, max_vocab=10000,
+                 content_interactions=True, warm_start=False,
+                 random_state=None, verbose=0):
+        self.n_components = n_components
+        self.init = init
+        self.max_iter = max_iter
+        self.tol = tol
+        self.sigma_prior = sigma_prior
+        self.gamma_max_iter = gamma_max_iter
+        self.e_step_max_iter = e_step_max_iter
+        self.max_vocab = max_vocab
+        self.content_interactions = content_interactions
+        self.warm_start = warm_start
+        self.random_state = random_state
+        self.verbose = verbose
+
+    # ------------------------------------------------------------------
+    # validation helpers
+
+    def _validate_inputs(self, X, prevalence, *, reset):
+        X = csr_matrix(X) if not issparse(X) else X.tocsr()
+        X = X.astype(np.float64)
+        if not reset and X.shape[1] != self.components_.shape[1]:
+            raise ValueError(
+                f"X has {X.shape[1]} features, but the model was fitted "
+                f"with {self.components_.shape[1]}."
+            )
+        doc_lens = np.asarray(X.sum(axis=1)).ravel()
+        if np.any(doc_lens == 0):
+            raise ValueError(
+                "X contains empty documents; remove them before fitting "
+                "(cf. prepDocuments in the R package)."
+            )
+        design = None
+        if prevalence is not None:
+            design = np.asarray(prevalence, dtype=np.float64)
+            if design.ndim == 1:
+                design = design[:, None]
+            if design.shape[0] != X.shape[0]:
+                raise ValueError(
+                    "prevalence has a different number of rows than X."
+                )
+            if np.isnan(design).any():
+                raise ValueError("Missing values in prevalence covariates.")
+            # prepend an intercept unless one is already there
+            if not np.allclose(design[:, 0], 1.0):
+                design = np.column_stack([np.ones(design.shape[0]), design])
+        return X, design
+
+    def _encode_content(self, content, n_docs, *, reset):
+        """Map content covariate labels to aspect indices (betaindex)."""
+        if content is None:
+            if not reset and getattr(self, "content_levels_", None) is not None:
+                raise ValueError(
+                    "The model was fitted with a content covariate; pass "
+                    "the matching content labels."
+                )
+            return None, np.zeros(n_docs, dtype=np.int64)
+        content = np.asarray(content).ravel()
+        if content.shape[0] != n_docs:
+            raise ValueError("content has a different number of rows than X.")
+        if reset:
+            levels = np.unique(content)
+        else:
+            if getattr(self, "content_levels_", None) is None:
+                raise ValueError(
+                    "The model was fitted without a content covariate."
+                )
+            levels = self.content_levels_
+            unseen = ~np.isin(content, levels)
+            if unseen.any():
+                raise ValueError(
+                    f"Unseen content levels: {np.unique(content[unseen])!r}"
+                )
+        index = np.searchsorted(levels, content)
+        return levels, index
+
+    # ------------------------------------------------------------------
+    # fitting
+
+    def fit(self, X, y=None, *, prevalence=None, content=None):
+        """Fit the model to a document-term count matrix.
+
+        Parameters
+        ----------
+        X : array-like or sparse matrix of shape (n_samples, n_features)
+            Word counts per document.
+        y : ignored
+        prevalence : array-like of shape (n_samples, n_covariates), optional
+            Prevalence covariate design matrix.  An intercept column is
+            added automatically.  Categorical variables must be encoded
+            numerically (e.g. one-hot) beforehand.
+        content : array-like of shape (n_samples,), optional
+            Content covariate: one categorical label per document.  Each
+            level gets its own topic-word distributions, estimated as
+            sparse deviations from a shared baseline (SAGE-style, via
+            distributed Poisson regression as in the R package's L1 mode).
+        """
+        K = self.n_components
+        if not (isinstance(K, (int, np.integer)) and K >= 2):
+            raise ValueError("n_components must be an integer >= 2.")
+        if not 0.0 <= self.sigma_prior <= 1.0:
+            raise ValueError("sigma_prior must be between 0 and 1.")
+        if self.init not in ("spectral", "random"):
+            raise ValueError("init must be 'spectral' or 'random'.")
+
+        warm = self.warm_start and hasattr(self, "components_")
+        X, design = self._validate_inputs(X, prevalence, reset=not warm)
+        docs = to_doc_list(X)
+        N, V = X.shape
+
+        if warm:
+            # ---- continue from the previous solution (cf. the R
+            #      package's model= restart argument) ----
+            if self.components_.shape[0] != K:
+                raise ValueError(
+                    f"warm_start requires the same n_components as the "
+                    f"previous fit ({self.components_.shape[0]}), "
+                    f"got {K}."
+                )
+            levels, beta_index = self._encode_content(content, N,
+                                                      reset=False)
+            A = 1 if levels is None else len(levels)
+            beta = [b.copy() for b in self._beta_list()]
+            sigma = self.sigma_.copy()
+            if (design is not None and self.gamma_ is not None
+                    and design.shape[1] == self.gamma_.shape[0]):
+                gamma = self.gamma_.copy()
+                mu = design @ gamma
+            else:
+                gamma = None
+                mu = (self.mu_.copy() if self.mu_.ndim == 1
+                      else np.zeros(K - 1))
+            # per-document state is only reusable for the same corpus
+            lambda_ = (self.eta_.copy() if self.eta_.shape[0] == N
+                       else np.zeros((N, K - 1)))
+            kappa = self.kappa_
+            bound_history = list(self.bound_)
+        else:
+            levels, beta_index = self._encode_content(content, N,
+                                                      reset=True)
+            A = 1 if levels is None else len(levels)
+
+            # ---- initialization (stm.init) ----
+            if self.init == "spectral":
+                init_beta = spectral_init(X, K, max_vocab=self.max_vocab)
+            else:
+                rng = check_random_state(self.random_state)
+                b = rng.gamma(0.1, 1.0, size=(K, V))
+                init_beta = b / b.sum(axis=1, keepdims=True)
+            beta = [init_beta.copy() for _ in range(A)]
+            mu = np.zeros(K - 1)
+            sigma = np.diag(np.full(K - 1, 20.0))
+            lambda_ = np.zeros((N, K - 1))
+            gamma = None
+            kappa = None
+            bound_history = []
+
+        wcounts = np.asarray(X.sum(axis=0)).ravel()
+
+        # ---- EM loop (stm.control) ----
+        converged = False
+        for _ in range(self.max_iter):
+            # like the R code, document-specific means are only available
+            # once gamma has been estimated (i.e. from the second iteration)
+            update_mu = gamma is not None
+            sigma_ss, beta_ss, bound, lambda_ = estep(
+                docs, beta_index, update_mu, beta, lambda_, mu, sigma,
+                max_optim_iter=self.e_step_max_iter,
+            )
+            mu, gamma = opt_mu(lambda_, covar=design,
+                               max_iter=self.gamma_max_iter)
+            sigma = opt_sigma(sigma_ss, lambda_, mu, self.sigma_prior)
+            if levels is None:
+                beta = opt_beta(beta_ss)
+            else:
+                beta, kappa = mnreg(
+                    beta_ss, wcounts,
+                    interactions=self.content_interactions,
+                )
+
+            bound_history.append(float(bound.sum()))
+            if self.verbose:
+                print(f"Iteration {len(bound_history)}: "
+                      f"bound = {bound_history[-1]:.2f}")
+            if len(bound_history) > 1:
+                old, new = bound_history[-2], bound_history[-1]
+                if (new - old) / abs(old) < self.tol:
+                    converged = True
+                    if self.verbose:
+                        print("Model converged.")
+                    break
+
+        # ---- pack the results ----
+        self.content_levels_ = levels
+        if levels is None:
+            self.components_ = beta[0]
+            self.aspect_components_ = None
+            self.kappa_ = None
+        else:
+            self.aspect_components_ = np.stack(beta)
+            # corpus-level summary: aspect betas weighted by frequency
+            weights = np.bincount(beta_index, minlength=A) / N
+            self.components_ = np.tensordot(
+                weights, self.aspect_components_, axes=1
+            )
+            self.kappa_ = kappa
+        self.gamma_ = gamma
+        self.mu_ = mu
+        self.sigma_ = sigma
+        self.eta_ = lambda_
+        full_eta = np.column_stack([lambda_, np.zeros(N)])
+        self.theta_ = row_softmax(full_eta)
+        self.bound_ = bound_history
+        self.n_iter_ = len(bound_history)
+        self.converged_ = converged
+        self.n_features_in_ = V
+        return self
+
+    def fit_transform(self, X, y=None, *, prevalence=None, content=None):
+        """Fit the model and return the training documents' theta."""
+        return self.fit(X, prevalence=prevalence, content=content).theta_
+
+    # ------------------------------------------------------------------
+    # inference on new documents
+
+    def _new_doc_priors(self, design):
+        """Per-document prior means for held-out inference."""
+        if self.gamma_ is not None:
+            if design is None:
+                raise ValueError(
+                    "The model was fitted with prevalence covariates; pass "
+                    "the matching covariates."
+                )
+            if design.shape[1] != self.gamma_.shape[0]:
+                raise ValueError(
+                    "prevalence has a different number of columns than "
+                    "at fit time."
+                )
+            return design @ self.gamma_, True
+        mu = self.mu_ if self.mu_.ndim == 1 else self.mu_.mean(axis=0)
+        return mu, False
+
+    def _beta_list(self):
+        """Topic-word distributions as a per-aspect list."""
+        if self.aspect_components_ is None:
+            return [self.components_]
+        return list(self.aspect_components_)
+
+    def transform(self, X, *, prevalence=None, content=None):
+        """Infer topic proportions for (possibly new) documents.
+
+        Runs one E-step with the fitted global parameters held fixed
+        (cf. fitNewDocuments in the R package) and returns theta of shape
+        (n_samples, n_components).
+        """
+        check_is_fitted(self, "components_")
+        X, design = self._validate_inputs(X, prevalence, reset=False)
+        docs = to_doc_list(X)
+        N = X.shape[0]
+        K = self.n_components
+        _, beta_index = self._encode_content(content, N, reset=False)
+        beta = self._beta_list()
+        mu, update_mu = self._new_doc_priors(design)
+
+        siginv, sigmaentropy = decompose_sigma(self.sigma_)
+        eta = np.zeros((N, K - 1))
+        for i, (words, counts) in enumerate(docs):
+            beta_d = np.ascontiguousarray(beta[beta_index[i]][:, words])
+            mu_d = mu[i] if update_mu else mu
+            _, eta[i] = optimize_document(
+                eta[i], beta_d, counts, mu_d, siginv, sigmaentropy,
+                max_optim_iter=self.e_step_max_iter,
+            )
+        return row_softmax(np.column_stack([eta, np.zeros(N)]))
+
+    def score(self, X, y=None, *, prevalence=None, content=None):
+        """Approximate evidence lower bound of ``X`` under the fitted model."""
+        check_is_fitted(self, "components_")
+        X, design = self._validate_inputs(X, prevalence, reset=False)
+        docs = to_doc_list(X)
+        N = X.shape[0]
+        K = self.n_components
+        _, beta_index = self._encode_content(content, N, reset=False)
+        mu, update_mu = self._new_doc_priors(design)
+        _, _, bound, _ = estep(
+            docs, beta_index, update_mu,
+            self._beta_list(), np.zeros((N, K - 1)), mu, self.sigma_,
+            max_optim_iter=self.e_step_max_iter,
+        )
+        return float(bound.sum())
+
+    def perplexity(self, X, *, prevalence=None, content=None):
+        """Per-token perplexity of ``X``, ``exp(-bound / n_tokens)``.
+
+        Like :meth:`sklearn.decomposition.LatentDirichletAllocation.perplexity`
+        this is based on the variational bound (here the logistic-normal
+        ELBO from :meth:`score`), so values are comparable between fits
+        of this class on the same data; lower is better.
+        """
+        check_is_fitted(self, "components_")
+        bound = self.score(X, prevalence=prevalence, content=content)
+        X_csr, _ = self._validate_inputs(X, None, reset=False)
+        n_tokens = X_csr.sum()
+        return float(np.exp(-bound / n_tokens))
+
+    # ------------------------------------------------------------------
+    # interpretation helpers
+
+    def top_words(self, n_words=10, *, kind="prob", frex_weight=0.5):
+        """Indices of the top words per topic (cf. labelTopics).
+
+        ``kind="prob"`` ranks by within-topic probability; ``kind="frex"``
+        balances frequency and exclusivity with weight ``frex_weight``.
+        Returns an array of shape (n_components, n_words).
+        """
+        check_is_fitted(self, "components_")
+        logbeta = safelog(self.components_)
+        if kind == "prob":
+            scores = logbeta
+        elif kind == "frex":
+            from scipy.special import logsumexp
+
+            excl = logbeta - logsumexp(logbeta, axis=0, keepdims=True)
+            freq_rank = np.apply_along_axis(rankdata, 1, logbeta) / logbeta.shape[1]
+            excl_rank = np.apply_along_axis(rankdata, 1, excl) / logbeta.shape[1]
+            scores = 1.0 / (frex_weight / freq_rank + (1 - frex_weight) / excl_rank)
+        else:
+            raise ValueError("kind must be 'prob' or 'frex'.")
+        return np.argsort(-scores, axis=1)[:, :n_words]

structural_topic_model-0.2.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: structural-topic-model
+Version: 0.2.0
+Summary: Python implementation of the Structural Topic Model (STM), a port of the R stm package with a scikit-learn style API
+Project-URL: Homepage, https://github.com/hirata-keisuke/pystm
+Project-URL: Repository, https://github.com/hirata-keisuke/pystm
+Project-URL: Issues, https://github.com/hirata-keisuke/pystm/issues
+Author-email: hirata-keisuke <plainpeace39th@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: NLP,STM,structural topic model,text mining,topic model
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.0
+Requires-Dist: scikit-learn>=1.9.0
+Requires-Dist: scipy>=1.14
+Description-Content-Type: text/markdown
+
+# pystm — Structural Topic Model in Python
+
+R の [stm](https://github.com/bstewart/stm) パッケージ(Roberts, Stewart & Tingley)のコア推定アルゴリズムを Python に移植したものです。API は scikit-learn の `LatentDirichletAllocation` に倣っています。
+
+## STM とは
+
+STM はロジスティック正規トピックモデルで、文書のメタデータ(prevalence 共変量)が各文書のトピック比率の事前平均をシフトさせます。共変量なしの場合は Correlated Topic Model (CTM) に帰着します。推定は semi-collapsed 変分 EM で行います(R 版 `stm()` と同一のアルゴリズム)。
+
+## 使い方
+
+```python
+import numpy as np
+from pystm import StructuralTopicModel
+
+# X: (n_docs, n_vocab) の単語カウント行列(dense / scipy.sparse どちらも可)
+# covar: (n_docs, n_covariates) の prevalence 共変量(切片は自動付与)
+
+model = StructuralTopicModel(n_components=10, init="spectral")
+model.fit(X, prevalence=covar)
+
+model.theta_        # 学習文書のトピック比率 (n_docs, K)
+model.components_   # トピック-単語分布 (K, V)。各行の和は1
+model.gamma_        # prevalence 回帰係数 (1+P, K-1)。先頭行が切片
+model.sigma_        # トピック共分散行列 (K-1, K-1)
+
+# 新規文書の推論(fitNewDocuments 相当)
+theta_new = model.transform(X_new, prevalence=covar_new)
+
+# トピックの代表語(labelTopics 相当)
+model.top_words(n_words=10)               # 確率順
+model.top_words(n_words=10, kind="frex")  # FREX(頻度と排他性のバランス)
+```
+
+共変量を渡さなければ CTM として推定されます:
+
+```python
+model = StructuralTopicModel(n_components=10).fit(X)
+```
+
+### content 共変量(SAGE / Distributed Multinomial Regression)
+
+文書のカテゴリによってトピック内の語彙の使い方が変わるモデルです。各文書に1つのカテゴリラベルを渡します:
+
+```python
+model = StructuralTopicModel(n_components=10)
+model.fit(X, prevalence=covar, content=party_labels)  # 例: 政党ラベル
+
+model.aspect_components_   # カテゴリ別トピック-語彙分布 (n_levels, K, V)
+model.kappa_["params"]     # ベースラインからのスパースな偏差(lasso 推定)
+model.content_levels_      # カテゴリ水準
+# transform / score にも同じ content を渡す
+model.transform(X_new, prevalence=c_new, content=labels_new)
+```
+
+R 版の `kappa.prior="L1"`(既定)に相当する Distributed Poisson 回帰で推定します。glmnet の代わりに、設計行列のインジケータ構造を利用して語彙方向に完全ベクトル化した IRLS+座標降下の Poisson lasso を実装しています(正則化パスと情報量規準による選択も R と同じ)。
+
+### estimateEffect 相当: 共変量効果の推定
+
+トピック比率を目的変数とする回帰を method of composition(変分事後分布からの θ サンプリング)で行い、測定不確実性込みの係数を返します:
+
+```python
+from pystm import estimate_effect
+
+eff = estimate_effect(model, covar, uncertainty="Global", nsims=25)
+tables = eff.summary()        # {topic: 構造化配列(estimate/std_error/t_value/p_value)}
+tables[0]["estimate"]         # トピック0の回帰係数(先頭が切片)
+```
+
+`uncertainty="Global"`(推奨・既定)と `"None"` をサポートします(R の `"Local"` は未実装)。
+
+### searchK 相当: トピック数の選択
+
+```python
+from pystm import search_k
+
+res = search_k(X, K_values=[5, 10, 15], prevalence=covar,
+               model_params={"max_iter": 100})
+res["heldout"]   # document completion による heldout 対数尤度
+res["residual"]  # Taddy (2012) の残差分散(1 に近いほど良い)
+res["semcoh"]    # 意味的一貫性 / res["exclus"]: 排他性
+res["bound"], res["lbound"], res["em_its"]
+```
+
+### その他の診断
+
+```python
+from pystm import topic_corr, semantic_coherence, exclusivity, check_residuals
+
+tc = topic_corr(model, cutoff=0.01)   # トピック相関グラフ(simple 法)
+tc.posadj                              # 正相関の隣接行列
+semantic_coherence(model, X, M=10)     # トピックごとの意味的一貫性
+exclusivity(model, M=10)               # トピックごとの排他性(content モデル不可)
+check_residuals(model, X)              # 残差分散検定 {dispersion, pvalue, df}
+```
+
+## R 版との対応
+
+| R | Python |
+|---|---|
+| `stm(docs, vocab, K, prevalence=~x, data=meta)` | `StructuralTopicModel(n_components=K).fit(X, prevalence=design)` |
+| `init.type="Spectral"` (推奨・既定) | `init="spectral"` (既定) |
+| `init.type="Random"` | `init="random"` |
+| `gamma.prior="Pooled"` (既定) | 実装済み(共変量ありのとき自動) |
+| `sigma.prior` | `sigma_prior` |
+| `emtol` / `max.em.its` | `tol` / `max_iter` |
+| `model=`(フィット済みモデルから再開) | `warm_start=True`(fit を繰り返し呼ぶ。`bound_` に履歴が蓄積) |
+| `content=~group`(`kappa.prior="L1"`, 既定) | `fit(X, content=labels)` |
+| `interactions` | `content_interactions` |
+| `fitNewDocuments()` | `transform()` |
+| `labelTopics()` | `top_words()` |
+| `estimateEffect()` / `summary()` | `estimate_effect()` / `.summary()` |
+| `searchK()` | `search_k()` |
+| `make.heldout()` / `eval.heldout()` | `make_heldout()` / `eval_heldout()` |
+| `topicCorr(method="simple")` | `topic_corr()` |
+| `semanticCoherence()` / `exclusivity()` / `checkResiduals()` | `semantic_coherence()` / `exclusivity()` / `check_residuals()` |
+| `$theta` / `$beta` / `$sigma` / `$mu$gamma` | `theta_` / `components_` / `sigma_` / `gamma_` |
+| `$beta$logbeta`(content モデル) | `aspect_components_`(確率スケール) |
+| `$beta$kappa` | `kappa_` |
+
+### scikit-learn LDA との API 差分
+
+- `perplexity(X)` を sklearn LDA と同様に提供(変分下界ベースの `exp(-bound/総トークン数)`。低いほど良い)。
+- `warm_start=True` で sklearn 流の継続学習(R 版 `model=` 相当)。
+- `components_` は正規化済みの確率分布(sklearn LDA は擬似カウント)。
+- 共変量は `fit(X, prevalence=...)` / `transform(X, prevalence=...)` のキーワードで渡す。R の formula は使えないので、カテゴリ変数は事前に one-hot 等で数値化してください(`patsy` や `pandas.get_dummies` が便利)。
+
+### 未実装
+
+- `gamma.prior="L1"`(prevalence 側の glmnet 依存モード)
+- `kappa.prior="Jeffreys"`(content の旧推定法。R 版でも後方互換のためだけに残されている)
+- `fixedintercept=FALSE`(content モデルの切片推定)
+- LDA(collapsed Gibbs)初期化、`ngroups` メモ化推論、`K=0`(Lee & Mimno)
+- `estimateEffect()` の `uncertainty="Local"`、formula インターフェース(スプライン `s()` 等は事前に基底展開した行列を渡せば等価)
+- `topicCorr(method="huge")`(huge パッケージ依存)、`selectModel()`、`permutationTest()`、プロット関数群
+
+また、spectral 初期化の RecoverL2 は R 版既定の quadprog の代わりにペナルティ付き NNLS による厳密に近い解法を使います(指数勾配法 `recoverEG=TRUE` 相当も `pystm._spectral.recover_l2(solver="expgrad")` として利用可能)。
+
+## 実装メモ(R 版からの移植で見つかった重要な点)
+
+1. **`update.mu` の切り替えタイミング**: R 版(`stm.control.R`)では E-step に渡す事前平均の選択を `update.mu = !is.null(mu$gamma)` で判定している。つまり**初回 E-step は共有平均(ゼロベクトル)を使い、γ が推定された 2 回目以降に文書別の事前平均 Xγ に切り替わる**。「prevalence 共変量があるか」で判定すると、初回 E-step で形状不一致または誤った事前を使うバグになる(本実装も最初これを踏んだ)。
+
+2. **RecoverL2 のソルバー選択**: R 版の既定は quadprog による厳密な単体制約付き QP(`recoverEG=FALSE`)。論文由来の指数勾配法(`recoverEG=TRUE`)は反復上限 500 では、**1つのトピックが支配的なコーパス(文書内でトピックが強く混ざる場合)に収束不足**となり、初期化品質が大きく劣化した(K=10 の合成データで cos 類似度 0.45 前後 vs NNLS で 0.97)。反復を 20,000 まで増やしても改善しなかったため、最適化の遅さではなく平坦な目的関数で実質停止していた。本実装はペナルティ付き NNLS(和=1 制約を重み付き行で課す)を既定とした。
+
+3. **Random 初期化は局所解に落ちやすい**(R 版ドキュメントの記述どおり、seed によりトピック復元が大きく変わる)。動作確認・検証には決定的な Spectral 初期化を使うこと。
+
+4. **gram 行列の検証方法**: スペクトル初期化の正しさは、合成データで経験 gram 行列が理論期待値 `β' E[θθ'] β`(行正規化後)と一致するかで切り分けられる(本実装では最大誤差 ~1e-3 で一致)。初期化品質が悪いときは実装バグではなく、コーパス側の共起信号の弱さ(θ の混合度)が原因のことがある。
+
+5. **mnreg(content 共変量)の高速化**: Distributed Poisson 回帰の設計行列は「トピック主効果 / アスペクト主効果 / 交互作用」の3グループのインジケータ列で、**各グループ内の列は互いに素な行しか触らない**。そのためグループ単位の座標降下が1回の行列演算になり、さらに全語彙が同一の設計行列を共有するので V 方向にも完全ベクトル化できる。汎用の座標降下実装と比べ同一解で大幅に高速(さらに IRLS 上限 4 / スイープ上限 8 / tol 1e-4 に絞っても β の最大差は ~2e-5)。
+
+6. **同梱 gadarianFit の前処理は現行 textProcessor と異なる**: パッケージ同梱の `gadarianFit`(2017年)の語彙は、現行 `textProcessor.R` の処理順(句読点除去→ストップワード除去、ダッシュ保存)では再現できない。旧版の処理順(**ストップワード除去が句読点除去より先**=アポストロフィ付きの "can't" 等がストップワードとして除去される、かつ**ダッシュ非保存**= "tax-payers"→"taxpayers")+ `lower.thresh=3` で215語が完全一致する([scripts/gadarian_prep.py](scripts/gadarian_prep.py) の `legacy_order=True`)。R 版の再現実験をする際はパッケージバージョンごとの前処理差に注意。
+
+7. **E-step の数値ガードが実データでは必須**: R/C++ 原実装どおりの素朴な `exp(eta)` 計算は、実コーパス(短文・偏った β・大きめ K)で BFGS の直線探索が極端な点を踏んだときに inf/NaN を発生させ、Hessian の cholesky が落ちる。η のクリップ(±200)、log と除算の下限(1e-300)、非有限解のフォールバックを `_estep.py` に追加した(通常領域の値は不変、合成データ・gadarian 検証とも退行なし)。
+
+8. **heldout 構築時の語彙消失**: トークンを訓練側から取り除くと、コーパス全体から消える語が生じうる。R 版 `make.heldout` は語彙を再番号付けして missing 側からも削除している。これを怠ると、その語の β が 0 になり heldout 対数尤度が -inf になる。本実装も missing 側から該当トークンを除外している。
+
+## R 版との検証(gadarianFit)
+
+R パッケージ同梱の `gadarianFit`(Roberts et al. 2014 AJPS の Gadarian & Albertson 移民調査データ、K=3、prevalence = treatment*pid_rep、N=341)を参照解として、本実装を数値レベルで検証済み。再現方法:
+
+```bash
+uv run python scripts/validate_gadarian.py   # 11/11 チェック合格
+```
+
+| 検証項目 | 結果 |
+|---|---|
+| コーパス再現(textProcessor + prepDocuments の移植) | 語彙215語・単語カウントともR版と**完全一致** |
+| R版パラメータでの E-step bound | pystm -13575.82 vs R -13575.91(R の1反復増分 0.103 の範囲内で一致) |
+| R版パラメータでの文書別 θ | 相関 > 0.9999、最大差 0.02 |
+| R版の解からの EM 継続(不動点チェック) | bound 単調増加・増分は収束閾値レベル(10反復で +1.86) |
+| 独立フィット(Spectral 初期化)の bound | R比 -0.18%(R は確率的 LDA 初期化なので局所解の違いは想定内) |
+| トピックの対応 | 3トピックとも cos 類似度 0.88 前後、上位語ほぼ一致(worri/immigr/border、job/tax/pay、peopl/countri/come) |
+| treatment 効果 | 全トピックで符号一致。有意な正の効果は +0.215 vs R +0.219 とほぼ同値 |
+
+注: R 版のフィット自体は LDA Gibbs 初期化(R の乱数)に依存するため完全一致は原理的に不可能。代わりに「R の解が本実装の EM の不動点になっているか」「bound 計算が R の報告値と一致するか」で実装の同一性を確認している。
+
+## 開発
+
+```bash
+uv sync
+uv run pytest tests/
+```
+
+## 他プロジェクトからの利用(配布)
+
+配布名・import 名ともに `pystm`。実行時依存は numpy / scipy / scikit-learn のみ
+(janome / dash 等は application 用の dev 依存で、配布物には含まれない)。
+
+```bash
+# PyPI からインストール
+pip install structural-topic-model
+# または
+uv add structural-topic-model
+
+# ローカルパス参照(開発中)
+uv add --editable /path/to/202606_StructuralTopicModel
+
+# Git 経由
+uv add git+<リポジトリURL>
+
+# wheel をビルド
+uv build   # dist/structural_topic_model-x.y.z-py3-none-any.whl
+```
+
+配布名は `structural-topic-model`、import 名は `pystm` のまま維持しています
+(PyPI の `pystm` は別の実装に取られているため)。
+
+## 参考文献
+
+- Roberts, M., Stewart, B., & Tingley, D. (2019). stm: An R Package for Structural Topic Models. *Journal of Statistical Software*, 91(2).
+- Arora, S. et al. (2013). A Practical Algorithm for Topic Modeling with Provable Guarantees. *ICML*.