bossanova 0.1.0.dev18__tar.gz → 0.1.0.dev20__tar.gz

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev20}/.gitignore

@@ -17,7 +17,7 @@ docs/_build/
 docs/performance/
 profile_*.py
 benchmarks/
-!bossanova-docs/engineering/benchmarks/
+!bossanova-docs/benchmarking/
 examples/
 papers/
 paper-summaries/
@@ -84,3 +84,4 @@ bossanova-docs/wip/
 research.md
 201b-ghct-05-models/
 emmeans/
+walkthrough.md

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

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

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev20}/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.dev20}/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.dev20}/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.dev20/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.dev20}/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.dev20}/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.dev20}/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.dev20}/bossanova/internal/fit/dispatch.py

@@ -105,7 +105,7 @@ def dispatch_solver(
     tol: float | None = None,
     verbose: bool = False,
     nAGQ: int = 1,
-    use_hessian: bool = True,
+    use_hessian: bool = False,
 ) -> FitState:
     """Dispatch to the concrete solver implementation.
 
@@ -121,7 +121,7 @@ def dispatch_solver(
         tol: Convergence tolerance (solver-specific defaults if None).
         verbose: Print optimization progress (default: False).
         nAGQ: Quadrature points for GLMER (default: 1).
-        use_hessian: Use Hessian-based vcov for GLMER (default: True).
+        use_hessian: Use Hessian-based vcov for GLMER (default: False).
 
     Returns:
         FitState from the selected solver.
@@ -172,7 +172,7 @@ def fit_model(
     tol: float | None = None,
     verbose: bool = False,
     nAGQ: int = 1,
-    use_hessian: bool = True,
+    use_hessian: bool = False,
 ) -> FitState:
     """Dispatch to appropriate fitter based on model specification.
 
@@ -205,7 +205,7 @@ def fit_model(
         tol: Convergence tolerance (solver-specific defaults if None).
         verbose: Print optimization progress (default: False).
         nAGQ: Quadrature points for GLMER (default: 1).
-        use_hessian: Use Hessian-based vcov for GLMER (default: True).
+        use_hessian: Use Hessian-based vcov for GLMER (default: False).
 
     Returns:
         FitState containing all fitting results.

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev20}/bossanova/internal/fit/glmer.py

@@ -29,7 +29,7 @@ def fit_glmer_pirls(
     tol: float = 1e-7,
     verbose: bool = False,
     nAGQ: int = 1,
-    use_hessian: bool = True,
+    use_hessian: bool = False,
 ) -> FitState:
     """Fit generalized linear mixed model using Penalized IRLS.
 
@@ -70,7 +70,10 @@ def fit_glmer_pirls(
         tol: PIRLS convergence tolerance (default: 1e-7).
         verbose: Print optimization progress (default: False).
         nAGQ: Quadrature points (0 or 1, default: 1).
-        use_hessian: Use Hessian-based vcov (default: True).
+        use_hessian: Use Hessian-based vcov (default: False). The default
+            Schur complement approach matches lme4's ``vcov()`` with
+            ``use.hessian=FALSE`` and avoids expensive numerical
+            differentiation. Set to True for observed-information vcov.
 
     Returns:
         FitState containing:
@@ -91,7 +94,6 @@ def fit_glmer_pirls(
         - bossanova.internal.maths.solvers.glmer: Underlying PIRLS implementation
     """
     from bossanova.internal.maths.solvers.glmer import (
-        compute_hessian_vcov,
         compute_irls_quantities,
         fit_glmm_pirls,
     )
@@ -177,9 +179,17 @@ def fit_glmer_pirls(
     converged = fit_result["converged"]
     n_iter = fit_result["n_func_evals"]
 
+    # Compute IRLS weights once (needed by both vcov paths and for XtWX_inv)
+    working_weights, _ = compute_irls_quantities(y, eta, family)
+    if weights is not None:
+        total_weights = weights * working_weights
+    else:
+        total_weights = working_weights
+
     # Compute variance-covariance matrix of beta
     if use_hessian:
-        # Hessian-based vcov (matches lme4 default)
+        from bossanova.internal.maths.solvers.glmer import compute_hessian_vcov
+
         vcov, _ = compute_hessian_vcov(
             theta=theta,
             beta=beta,
@@ -196,15 +206,7 @@ def fit_glmer_pirls(
             eta_init=eta,  # Use optimal eta as starting point
         )
     else:
-        # Schur complement-based vcov (faster)
-        working_weights, _ = compute_irls_quantities(y, eta, family)
-
-        if weights is not None:
-            total_weights = weights * working_weights
-        else:
-            total_weights = working_weights
-
-        # Build Lambda for Schur complement
+        # Schur complement-based vcov (analytical, matches lme4 vcov(use.hessian=FALSE))
         Lambda = build_lambda_sparse(theta, n_groups_list, re_structure, metadata)
         vcov = compute_vcov_schur_sparse(X, Z, Lambda, weights=total_weights)
 
@@ -218,13 +220,8 @@ def fit_glmer_pirls(
     # Degrees of freedom
     df_resid = float(n - p)
 
-    # Compute final IRLS weights and XtWX_inv for cluster-robust SEs
-    final_working_weights, _ = compute_irls_quantities(y, eta, family)
-    if weights is not None:
-        final_irls_weights = weights * final_working_weights
-    else:
-        final_irls_weights = final_working_weights
-    XtWX = X.T @ (X * final_irls_weights[:, np.newaxis])
+    # XtWX_inv for sandwich/cluster-robust SEs (reuse total_weights)
+    XtWX = X.T @ (X * total_weights[:, np.newaxis])
     XtWX_inv = np.linalg.inv(XtWX)
 
     return build_fit_state(
@@ -240,6 +237,6 @@ def fit_glmer_pirls(
         u=u,
         converged=converged,
         n_iter=n_iter,
-        irls_weights=final_irls_weights,
+        irls_weights=total_weights,
         XtWX_inv=XtWX_inv,
     )

{bossanova-0.1.0.dev18 → bossanova-0.1.0.dev20}/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.dev20}/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.dev20}/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.dev20}/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.dev18 → bossanova-0.1.0.dev20}/bossanova/internal/marginal/slopes.py

@@ -312,6 +312,15 @@ def compute_slopes_finite_diff(
 
     validate_focal_var(bundle, focal_var)
 
+    # --- drop rows with missing values in model variables -----------------
+    # The caller may pass raw data that includes rows dropped during fitting.
+    # Null/NaN values propagate through matrix multiplication and corrupt the
+    # AME estimate, so filter to complete cases on the model's columns.
+    model_cols = [c for c in bundle.X_names if c in data.columns]
+    if bundle.y_name in data.columns:
+        model_cols.append(bundle.y_name)
+    data = data.drop_nulls(subset=model_cols)
+
     # --- step size --------------------------------------------------------
     focal_col = data[focal_var].cast(pl.Float64).to_numpy()
     var_range = float(focal_col.max() - focal_col.min())
@@ -443,6 +452,12 @@ def compute_slopes_crossed(
             "(needed by evaluate_newdata)."
         )
 
+    # --- drop rows with missing values in model variables -----------------
+    model_cols = [c for c in bundle.X_names if c in data.columns]
+    if bundle.y_name in data.columns:
+        model_cols.append(bundle.y_name)
+    data = data.drop_nulls(subset=model_cols)
+
     # --- step size --------------------------------------------------------
     focal_col = data[focal_var].cast(pl.Float64).to_numpy()
     var_range = float(focal_col.max() - focal_col.min())

bossanova-0.1.0.dev20/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.dev20/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.dev20}/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 (