Fix docstring drift surfaced by audit

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "scorepilot"
-version = "0.22.0"
+version = "0.22.1"
 description = "Web-based tool for PCA/PLS model analysis in chemometrics."
 readme = "README.md"
 requires-python = ">=3.12"

src/scorepilot/core/profiling.py

@@ -142,9 +142,17 @@ def sequence(series: pd.Series) -> list[float | None]:
 def suggest_transform(summary: VariableSummary) -> TransformKind:
     """Suggest a transform from a variable's shape.
 
-    A strongly right-skewed, strictly positive variable with a wide dynamic range
-    is a candidate for a log transform; a milder skew suggests a signed power
-    (root). Otherwise no transform is suggested.
+    Only strongly right-skewed quantitative variables (skewness > 1.0) trigger a
+    suggestion:
+
+    - If the variable is also strictly positive and has a wide dynamic range
+      (min-max ratio > 20), suggest a log transform.
+    - Otherwise (skewed, but either not strictly positive or not wide-range),
+      suggest a signed power (root).
+
+    Anything else -- non-quantitative, unknown skewness, or skewness at or below
+    1.0 -- returns ``TransformKind.NONE``. Milder skew is deliberately left
+    alone.
     """
     if summary.column_type is not ColumnType.QUANTITATIVE or summary.skewness is None:
         return TransformKind.NONE

src/scorepilot/core/transforms.py

@@ -48,7 +48,9 @@ def apply_transform(
     - ``neglog``: ``sign(x) * log1p(abs(x))`` (sign-symmetric log)
     - ``logit``: ``log(p / (1 - p))`` with ``p = x`` (defined for ``0 < x < 1``)
     - ``exponential``: ``exp(x)``
-    - ``power``: ``sign(x) * abs(x) ** c1`` (default ``c1 = 0.5``, i.e. signed root)
+    - ``power``: ``sign(x) * abs(x) ** c1``. The signature default is ``c1 = 0.0``;
+      when ``c1 == 0.0`` the function substitutes ``0.5`` internally (signed
+      square root). Pass an explicit ``c1`` for any other exponent.
     """
     values = to_numeric(series).astype(float).to_numpy()
 

src/scorepilot/db/models.py

@@ -47,10 +47,14 @@ def __repr__(self) -> str:
 class Model(Base):
     """A fitted PCA/PLS model variant.
 
-    Queryable metadata lives in real columns and JSON; the fitted arrays (P, W,
-    means, scales, ...) are stored as a compressed ``npz`` blob in ``params``. If
-    those artifacts grow, ``params`` can be swapped for an object-storage path
-    behind the same repository method without changing anything upstream.
+    Queryable metadata lives in real columns and JSON; a compact set of fitted
+    diagnostics is stored as a compressed ``npz`` blob in ``params``. Today the
+    blob holds ``x_loadings`` (the X-block loadings matrix), ``explained_variance``
+    (per-component), and ``r2_cumulative`` (cumulative R²X across components) --
+    the arrays needed by the current API's diagnostic endpoints. If more fitted
+    state is later persisted, or those artifacts grow, ``params`` can be swapped
+    for an object-storage path behind the same repository method without changing
+    anything upstream.
     """
 
     __tablename__ = "model"