bossanova 0.1.0.dev18__tar.gz → 0.1.0.dev19__tar.gz

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bossanova
-Version: 0.1.0.dev18
+Version: 0.1.0.dev19
 Summary: Bridging statistical cultures with some jazz
 Author: Eshin Jolly
 License-Expression: MIT

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/__init__.py

@@ -36,6 +36,9 @@ from bossanova.internal.compare import compare, lrt  # noqa: E402
 # Visualization
 from bossanova.internal import viz  # noqa: E402
 
+# Export utilities
+from bossanova.internal.rendering.markdown import to_markdown  # noqa: E402
+
 # Expressions
 from bossanova import expressions  # noqa: E402
 
@@ -53,6 +56,7 @@ __all__ = [
     "set_display_digits",
     "set_singular_tolerance",
     "show_datasets",
+    "to_markdown",
     "viz",
 ]
 

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/data/__init__.py

@@ -1,4 +1,20 @@
-"""Bundled sample datasets for regression and mixed-effects modeling."""
+"""Bundled sample datasets for regression and mixed-effects modeling.
+
+| Dataset | Argument | Description |
+|---------|----------|-------------|
+| Advertising | `"advertising"` | TV, radio, newspaper ad spend vs sales (200 x 4) |
+| Cake | `"cake"` | Baking angle by recipe and temperature (270 x 5) |
+| ChickWeight | `"chickweight"` | Chick weight over time by diet (578 x 4) |
+| Credit | `"credit"` | Credit card balance by income and demographics (400 x 11) |
+| Gammas | `"gammas"` | Simulated BOLD signal for Gamma GLM (6000 x 4) |
+| mtcars | `"mtcars"` | Motor Trend car road tests (32 x 12) |
+| Penguins | `"penguins"` | Palmer Penguins body measurements (344 x 8) |
+| Poker | `"poker"` | Poker hand outcomes by skill and limit (300 x 4) |
+| Sleep | `"sleep"` | Reaction time vs sleep deprivation (180 x 3) |
+| Titanic | `"titanic"` | Passenger survival with demographics (891 x 15) |
+| Titanic Train | `"titanic_train"` | Titanic training set, Kaggle format (891 x 12) |
+| Titanic Test | `"titanic_test"` | Titanic test set, Kaggle format (418 x 11) |
+"""
 
 from importlib.resources import files
 from typing import Literal
@@ -52,7 +68,7 @@ def show_datasets() -> pl.DataFrame:
         ```python
         from bossanova.data import show_datasets
         show_datasets()
-        # shape: (11, 2)
+        # shape: (12, 2)
         # ┌───────────────┬─────────────────────────────────┐
         # │ name          ┆ description                     │
         # │ ---           ┆ ---                             │

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/expressions.py

@@ -4,17 +4,17 @@ This module provides stateless Polars expressions for data transformations
 commonly used in statistical modeling. These match the semantics of the
 formula-based transforms in `bossanova.internal.formula`.
 
-Core Transforms:
-    center(col): x - mean(x) — subtract mean only
-    norm(col): x / std(x) — divide by std only (normalize magnitude)
-    zscore(col): (x - mean(x)) / std(x) — traditional z-score (1 SD)
-    scale(col): (x - mean(x)) / (2 * std(x)) — Gelman scaling (2 SD)
-
-Additional Helpers:
-    rank(col, method): Average-method rank transform (matches R's rank())
-    winsorize(col, lower, upper): Percentile capping for outliers
-    lag(col, n): Lagged (shifted backward) values
-    lead(col, n): Lead (shifted forward) values
+**Core Transforms:**
+- `center(col)` — subtract mean only
+- `norm(col)` — divide by std only
+- `zscore(col)` — traditional z-score (1 SD)
+- `scale(col)` — Gelman scaling (2 SD)
+
+**Additional Helpers:**
+- `rank(col, method)` — average-method rank transform
+- `winsorize(col, lower, upper)` — percentile capping
+- `lag(col, n)` — lagged values
+- `lead(col, n)` — lead values
 
 The scale() transform follows Gelman (2008) recommendation to divide by
 2 standard deviations, making continuous predictor coefficients directly

bossanova-0.1.0.dev19/bossanova/internal/compare/__init__.py

@@ -0,0 +1,12 @@
+"""Model comparison: information criteria, likelihood ratio tests, and composite tables.
+
+Call chain:
+    bossanova.compare(m1, m2, ...) -> compare() (composite AIC/BIC/loglik table)
+    bossanova.lrt(m1, m2) -> lrt() (nested model likelihood ratio test)
+"""
+
+from bossanova.internal.compare.compare import compare
+from bossanova.internal.compare.ic import compare_aic, compare_bic
+from bossanova.internal.compare.lrt import lrt
+
+__all__ = ["compare", "compare_aic", "compare_bic", "lrt"]

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/containers/structs/display.py

@@ -101,3 +101,47 @@ class MathDisplay:
             LaTeX equation without $$ delimiters.
         """
         return self.equation
+
+    def to_markdown(
+        self,
+        path: str | None = None,
+        *,
+        include_explanations: bool = True,
+    ) -> str:
+        """Export equation as Quarto-compatible display math markdown.
+
+        Wraps the equation in ``$$...$$`` display math delimiters. When
+        *include_explanations* is True, appends the term explanations as
+        a bulleted list below the equation block.
+
+        Suitable for embedding in ``.qmd`` files via Quarto's
+        ``{{< include >}}`` shortcode.
+
+        Args:
+            path: Optional file path to write the markdown. Parent
+                directories are created automatically. If None, returns
+                the string without writing.
+            include_explanations: If True (default), append term
+                explanations below the equation.
+
+        Returns:
+            Markdown string with ``$$equation$$`` and optional
+            explanations.
+
+        Examples:
+            >>> m.show_math().to_markdown("equations/model_eq.md")
+            >>> md = m.show_math().to_markdown(include_explanations=False)
+        """
+        from bossanova.internal.rendering.markdown import (
+            equation_to_markdown,
+            write_text,
+        )
+
+        text = equation_to_markdown(
+            self.equation,
+            self.explanations,
+            include_explanations=include_explanations,
+        )
+        if path is not None:
+            write_text(text, path)
+        return text

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/design/__init__.py

@@ -4,12 +4,6 @@ Call chain:
     formula.build_design_matrices() -> treatment_coding() / sum_coding() / ... (categorical columns)
     marginal.build_reference_grid() -> build_reference_row() (EMM reference grids)
     formula.build_random_effects_from_spec() -> build_z_simple() / build_z_nested() / build_z_crossed()
-
-Submodules:
-    coding: Contrast matrix builders for categorical encoding (treatment, sum, helmert, poly)
-    names: Design matrix column name parsing and variable type detection
-    reference: Reference design matrix (X_ref) for marginal effects
-    z_matrix: Sparse Z matrix (random effects design matrix) construction
 """
 
 from .coding import (

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/fit/__init__.py

@@ -2,29 +2,6 @@
 
 Call chain:
     model.fit() -> fit_model() -> resolve_solver() -> fit_ols_qr / fit_glm_irls / fit_lmer_pls / fit_glmer_pirls
-
-Container flow:
-    Input: ModelSpec, DataBundle
-    Output: FitState (coef, vcov, fitted, residuals, loglik, theta for mixed)
-
-Solver dispatch:
-    gaussian  + no RE  -> fit_ols_qr  (QR decomposition)
-    gaussian  + no RE  -> fit_glm_irls (if method="ml")
-    non-gauss + no RE  -> fit_glm_irls (IRLS)
-    gaussian  + RE     -> fit_lmer_pls (Penalized Least Squares)
-    non-gauss + RE     -> fit_glmer_pirls (Penalized IRLS)
-
-Submodules:
-    dispatch: Solver selection and fit_model entry point
-    ols: QR decomposition fitting (OLS/WLS)
-    glm: Iteratively Reweighted Least Squares (IRLS)
-    lmer: Penalized Least Squares (PLS) for LMM
-    glmer: Penalized IRLS (PIRLS) for GLMM
-    rank: Rank deficiency detection via pivoted QR
-    diagnostics: AIC/BIC, R-squared, metadata computation
-    convergence: Mixed model convergence checks (gradient, Hessian)
-    varying: BLUP extraction and variance component decomposition
-    predict: Prediction on training or new data
 """
 
 from bossanova.internal.fit.convergence import check_convergence

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/formula/__init__.py

@@ -3,25 +3,6 @@
 Call chain:
     model(formula, data) -> parse_formula() -> build_bundle_from_data() -> build_design_matrices()
     model.predict(newdata=) -> evaluate_newdata() (applies learned encoding to new observations)
-
-Container flow:
-    Input: formula string + Polars DataFrame
-    Output: FormulaSpec (via parse_formula) + DataBundle (X, y, Z matrices via build_design_matrices)
-
-Submodules:
-    parse: R-style formula string parsing into FormulaSpec
-    parser/: Recursive descent parser (scanner, tokens, AST nodes)
-    design: Design matrix construction from FormulaSpec
-    evaluate: Term evaluation (AST nodes to design matrix columns)
-    evaluate_transforms: Stateful, math, and polynomial transforms
-    evaluate_contrast: Contrast function evaluation for categorical encoding
-    evaluate_newdata: Apply learned encoding to new observations
-    encoding: Categorical variable encoding using Polars Enum
-    random_effects: Z matrix construction from FormulaSpec
-    helpers: Shared AST utilities
-    bundle: DataBundle construction from formula + DataFrame
-    contrast_registry: Contrast function vocabulary and validation
-    contrast_specs: User-facing contrast specification resolution
 """
 
 from bossanova.internal.formula.design import (

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/infer/__init__.py

@@ -1,31 +1,8 @@
 """Inference operations: asymptotic, bootstrap, permutation, cross-validation, profile, and simulation.
 
-Provides asymptotic (Wald-based), bootstrap, permutation, cross-validation,
-profile likelihood, and simulation inference for parameters, marginal effects,
-predictions, and variance components.
-
 Call chain:
     model.infer() -> dispatch_infer() -> dispatch_{params,mee,prediction}_inference()
     Each dispatcher routes to the method-specific backend (asymptotic, bootstrap, etc.)
-
-Container flow:
-    Input: ModelSpec, DataBundle, FitState (+ MeeState for effects, PredictionState for predictions)
-    Output: InferenceState (SE, CI, p-values) augmented onto the target state
-
-Submodules:
-    dispatch: Top-level infer routing
-    params: Parameter inference dispatch
-    mee: Marginal effects inference dispatch
-    prediction: Prediction inference dispatch
-    asymptotic: Wald-based SEs, CIs, p-values
-    bootstrap: Parametric and nonparametric bootstrap
-    permutation: Permutation tests for params and effects
-    cv: K-fold and group-K-fold cross-validation
-    profile: Profile likelihood for variance components
-    simulation: Summary statistics across simulation replicates
-    satterthwaite_emm: Satterthwaite df for EMM contrasts (mixed models)
-    resample/: Resampling engine (bootstrap indices, CI methods, model-type hooks)
-    formula_utils: Formula manipulation for term ablation (CV)
 """
 
 from bossanova.internal.infer.asymptotic import (

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/infer/dispatch.py

@@ -189,6 +189,15 @@ def dispatch_infer(
             threshold=threshold,
         )
 
+    # --- CV with stale predict state: reroute to fit branch ---
+    # When last_op is "predict" but predictions were made on newdata (different
+    # n than training data), CV can't attach training-data-sized arrays to the
+    # prediction state.  Fall back to the fit branch which produces model-level
+    # CV metrics (PRE, RMSE, etc.) — almost always what the user intended.
+    if how == "cv" and last_op == "predict" and pred is not None:
+        if len(pred.fitted) != bundle.n:
+            last_op = "fit"
+
     # --- Dispatch based on last_op ---
     match last_op:
         case "fit":

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/marginal/__init__.py

@@ -1,18 +1,7 @@
 """Marginal effects and estimated marginal means computation.
 
-Pipeline:
-1. Grid construction (build_reference_grid): Evaluation grid at which predictions are computed
-2. EMM/Slopes (compute_emm, compute_slopes): Predictions at grid points
-3. Contrasts (compute_contrasts): Apply contrast matrices to EMM results
-
-Provides:
-- parse_explore_formula: Parse explore formula syntax
-- ExploreFormula, ExploreFormulaError, Condition: Parsed explore formula types
-- build_reference_grid: Construct evaluation grid from DataBundle
-- compute_emm: Compute estimated marginal means at grid points
-- compute_slopes: Compute marginal effects for continuous predictors
-- compute_contrasts: Apply contrast matrices to EMM results
-- matrices: EMM contrast matrix builders (build_*_matrix)
+Call chain:
+    model.explore() -> build_reference_grid() -> compute_emm() / compute_slopes() -> compute_contrasts()
 """
 
 from bossanova.internal.marginal.explore import (

bossanova-0.1.0.dev19/bossanova/internal/rendering/__init__.py

@@ -0,0 +1,22 @@
+"""LaTeX equation and markdown rendering for model output.
+
+Call chain:
+    model.equation() -> build_equation(spec) -> LaTeX string
+    model_result.to_markdown() -> dataframe_to_markdown(df) -> markdown string
+"""
+
+from bossanova.internal.rendering.latex import build_equation
+from bossanova.internal.rendering.markdown import (
+    dataframe_to_markdown,
+    equation_to_markdown,
+    to_markdown,
+    write_text,
+)
+
+__all__ = [
+    "build_equation",
+    "dataframe_to_markdown",
+    "equation_to_markdown",
+    "to_markdown",
+    "write_text",
+]

bossanova-0.1.0.dev19/bossanova/internal/rendering/markdown.py

@@ -0,0 +1,163 @@
+"""Markdown table and equation rendering for report export.
+
+Pure functions that convert Polars DataFrames and LaTeX equations into
+pipe-delimited GitHub Flavored Markdown / Quarto-compatible text.
+Used by ``ModelResult.to_markdown()``, ``MathDisplay.to_markdown()``,
+and the top-level ``bossanova.to_markdown()`` utility.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import polars as pl
+
+__all__ = [
+    "dataframe_to_markdown",
+    "equation_to_markdown",
+    "to_markdown",
+    "write_text",
+]
+
+
+def dataframe_to_markdown(
+    df: pl.DataFrame,
+    caption: str | None = None,
+) -> str:
+    """Convert a Polars DataFrame to a pipe-delimited markdown table.
+
+    Produces GitHub Flavored Markdown (GFM) table syntax that renders
+    correctly in Quarto, GitHub, and most markdown environments. Columns
+    are padded to align visually. Null values render as empty cells.
+
+    No additional numeric formatting is applied — the DataFrame is assumed
+    to be pre-rounded (as all bossanova result DataFrames are).
+
+    Args:
+        df: Polars DataFrame to convert.
+        caption: Optional table caption. Rendered as ``Table: {caption}``
+            above the table (Quarto cross-reference syntax).
+
+    Returns:
+        Pipe-delimited markdown table as a string.
+
+    Examples:
+        >>> import polars as pl
+        >>> df = pl.DataFrame({"x": [1, 2], "y": [3.14, 2.72]})
+        >>> print(dataframe_to_markdown(df))
+        | x | y    |
+        |---|------|
+        | 1 | 3.14 |
+        | 2 | 2.72 |
+    """
+    cols = df.columns
+
+    # Convert all values to strings, rendering nulls as empty
+    str_rows: list[list[str]] = []
+    for row in df.iter_rows():
+        str_rows.append([("" if v is None else str(v)) for v in row])
+
+    # Compute column widths (minimum 3 for the separator dashes)
+    widths = [max(3, len(c)) for c in cols]
+    for row in str_rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+
+    # Build table lines
+    header = "| " + " | ".join(c.ljust(widths[i]) for i, c in enumerate(cols)) + " |"
+    separator = "|" + "|".join("-" * (w + 2) for w in widths) + "|"
+    data_lines = [
+        "| " + " | ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)) + " |"
+        for row in str_rows
+    ]
+
+    parts: list[str] = []
+    if caption is not None:
+        parts.append(f"Table: {caption}")
+        parts.append("")
+    parts.append(header)
+    parts.append(separator)
+    parts.extend(data_lines)
+    return "\n".join(parts)
+
+
+def equation_to_markdown(
+    equation: str,
+    explanations: tuple[str, ...] = (),
+    *,
+    include_explanations: bool = True,
+) -> str:
+    r"""Wrap a LaTeX equation in display math delimiters for Quarto.
+
+    Produces ``$$...$$`` display math that Quarto renders natively in
+    Typst, HTML, and PDF output. Optionally appends term explanations
+    as plain text below the equation block.
+
+    Args:
+        equation: LaTeX equation string (without ``$$`` delimiters).
+        explanations: Term explanation strings from ``MathDisplay``.
+        include_explanations: If True (default), append explanations
+            as plain text lines below the equation.
+
+    Returns:
+        Markdown string with display math block and optional explanations.
+
+    Examples:
+        >>> print(equation_to_markdown(r"y = \beta_0 + \beta_1 x"))
+        $$
+        y = \beta_0 + \beta_1 x
+        $$
+    """
+    parts = [f"$$\n{equation}\n$$"]
+    if include_explanations and explanations:
+        parts.append("")
+        for exp in explanations:
+            parts.append(f"- {exp}")
+    return "\n".join(parts)
+
+
+def write_text(text: str, path: str | Path) -> None:
+    """Write text content to a file, creating parent directories.
+
+    Args:
+        path: Destination file path. Parent directories are created
+            automatically if they don't exist.
+        text: Text content to write.
+    """
+    dest = Path(path)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(text, encoding="utf-8")
+
+
+def to_markdown(
+    df: pl.DataFrame,
+    path: str | Path | None = None,
+    caption: str | None = None,
+) -> str:
+    """Convert a Polars DataFrame to a markdown table, optionally saving to file.
+
+    Standalone utility for DataFrames not wrapped in ``ModelResult`` —
+    such as results from ``compare()``, ``model.jointtest()``,
+    ``model.vif()``, ``model.to_odds_ratio()``, etc.
+
+    For ``ModelResult`` objects (returned by ``.fit()``, ``.infer()``,
+    etc.), use ``result.to_markdown()`` instead.
+
+    Args:
+        df: Polars DataFrame to convert.
+        path: Optional file path. If given, writes the markdown and
+            creates parent directories automatically.
+        caption: Optional table caption (``Table: ...`` Quarto syntax).
+
+    Returns:
+        Pipe-delimited markdown table as a string.
+
+    Examples:
+        >>> from bossanova import compare, to_markdown
+        >>> to_markdown(compare(m1, m2), "comparison.md", caption="Model Comparison")
+        >>> md = to_markdown(m.jointtest())  # string only
+    """
+    text = dataframe_to_markdown(df, caption=caption)
+    if path is not None:
+        write_text(text, path)
+    return text

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/simulation/__init__.py

@@ -4,18 +4,6 @@ Call chain:
     model.simulate(n=...) -> generate_{lm,glm,lmer,glmer}_data() (pre-fit DGP)
     model.simulate(nsim=...) -> simulate_responses_from_fit() (post-fit parametric bootstrap)
     run_power_study(formula, ...) -> run_power_analysis() -> expand_sweep_grid()
-
-Container flow:
-    Pre-fit: SimulationSpec + VaryingSpec -> DataBundle (synthetic data)
-    Post-fit: FitState -> simulated response arrays
-    Power: sweep parameters -> Polars DataFrame (power results)
-
-Submodules:
-    dgp/: Data generating process functions (lm, glm, lmer, glmer)
-    model_sim: Response simulation from fitted model parameters
-    harness: Monte Carlo iteration runner and MonteCarloResult container
-    metrics: Recovery metrics (bias, RMSE, coverage, rejection rate)
-    power: Power analysis and parameter sweep utilities
 """
 
 from bossanova.internal.simulation.dgp import (

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/viz/mem.py

@@ -63,7 +63,7 @@ def plot_explore(
     hue: str | None = None,
     col: str | None = None,
     row: str | None = None,
-    units: Literal["link", "data"] = "data",
+    effect_scale: Literal["link", "response"] = "response",
     conf_int: float = 0.95,
     prettify: bool = False,
     height: float = 4.0,
@@ -98,9 +98,8 @@ def plot_explore(
             Auto-detected from conditioning columns when None.
         col: Column faceting variable.
         row: Row faceting variable.
-        units: Units for predictions.
-            - ``"data"``: Back-transformed scale (default).
-            - ``"link"``: Link scale (GLM/GLMER).
+        effect_scale: ``"link"`` or ``"response"`` (default).
+            Matches ``model.explore(effect_scale=...)``.
         conf_int: Confidence level (default 0.95).
         prettify: Convert axis labels to human-readable format.
         height: Height of each facet in inches.
@@ -167,7 +166,7 @@ def plot_explore(
         if not hasattr(model, "explore"):
             raise AttributeError(f"{type(model).__name__} does not have explore method")
         # Compute MEEs via explore().infer()
-        model.explore(specs, units=units).infer(conf_level=conf_int)
+        model.explore(specs, effect_scale=effect_scale).infer(conf_level=conf_int)
         effects_df = model.effects
         mee = model._mee
         result_type = mee.type

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev19}/bossanova/internal/viz/predict.py

@@ -268,6 +268,16 @@ def build_prediction_data(
     rows = [dict(zip(keys, combo)) for combo in product(*values)]
     pred_grid = pl.DataFrame(rows)
 
+    # Save model state — plot_predict should not have side effects on
+    # _last_op or _pred, since users may call .infer() after plotting and
+    # expect it to route back to the pre-plot operation (e.g. "fit").
+    # Unwrap ModelResult proxy (has __slots__, can't set attrs directly).
+    from bossanova.model.result import ModelResult
+
+    _core = model._model if isinstance(model, ModelResult) else model
+    saved_last_op = _core._last_op
+    saved_pred = _core._pred
+
     # Get predictions — request intervals in first call when possible to
     # avoid a redundant second model.predict() invocation.
     predict_kwargs: dict = {"type": pred_type}
@@ -352,6 +362,10 @@ def build_prediction_data(
 
         result_df = pl.concat([result_df, pop_df], how="diagonal")
 
+    # Restore model state so plot_predict doesn't affect subsequent .infer()
+    _core._last_op = saved_last_op
+    _core._pred = saved_pred
+
     return result_df