mocaco 0.1.0__py3-none-any.whl

mocaco/__init__.py

@@ -0,0 +1,10 @@
+"""Main module to expose the mocaco API."""
+
+from .api import convergence, describe, methods, samples
+
+__all__ = [
+    "convergence",
+    "describe",
+    "methods",
+    "samples",
+]

mocaco/api.py

@@ -0,0 +1,109 @@
+"""Main module to define the API behaviour and usage."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from . import methods as _methods  # noqa: F401
+from .protocols import SampleFrame
+from .registry import registry
+from .wrappers import EvalFrequencyWrapper
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import polars as pl
+
+    from .result import ConvergenceResult
+
+
+def samples(
+    df: pl.DataFrame,
+    *,
+    target_col: str,
+    it_col: str | None = None,
+) -> SampleFrame:
+    """
+    Create the normalized and frozen data representation used by convergence criteria.
+
+    This prevents input errors and ensure the input data is read-only and is
+    never modified accidentally.
+
+    Parameters
+    ----------
+        df
+            Source Polars DataFrame.
+        it_col
+            Column containing the iteration/order of the samples. If the user omit it, it
+            is automatically completed.
+        target_col
+            Column containing the quantity to analyze.
+    """
+    return SampleFrame(
+        df=df,
+        target_col=target_col,
+        it_col=it_col,
+    )
+
+
+class Convergence:
+    """
+    Callable namespace exposing registered convergence criteria as attributes.
+
+    Use as ``convergence(samples, method="...", **kwargs)`` for generic calls,
+    or ``convergence.clt_absolute(samples, threshold=...)`` for typed calls.
+    """
+
+    def __call__(
+        self,
+        samples: SampleFrame,
+        *,
+        method: str,
+        **kwargs: Any,
+    ) -> ConvergenceResult:
+        """Invoke a registered convergence criterion generically by name."""
+        criterion = registry.get(method)
+        eval_frequency = kwargs.pop("eval_frequency", None)
+        params = criterion.params_type(**kwargs)
+
+        if eval_frequency is not None:
+            if not getattr(criterion, "supports_eval_frequency", False):
+                raise TypeError(f"Criterion '{criterion.name}' does not support eval_frequency")
+            wrapper = EvalFrequencyWrapper(criterion, eval_frequency=eval_frequency)
+            return wrapper.run(samples=samples, params=params)
+
+        return criterion.run(
+            samples=samples,
+            params=params,
+        )
+
+    def __getattr__(self, name: str) -> Callable[..., ConvergenceResult]:
+        """Resolve registered criteria as callable attributes."""
+        criterion = registry.get(name)
+
+        def _method(samples: SampleFrame, **kwargs: Any) -> ConvergenceResult:
+            eval_frequency = kwargs.pop("eval_frequency", None)
+            params = criterion.params_type(**kwargs)
+
+            if eval_frequency is not None:
+                if not getattr(criterion, "supports_eval_frequency", False):
+                    raise TypeError(f"Criterion '{criterion.name}' does not support eval_frequency")
+                wrapper = EvalFrequencyWrapper(criterion, eval_frequency=eval_frequency)
+                return wrapper.run(samples=samples, params=params)
+
+            return criterion.run(samples=samples, params=params)
+
+        return _method
+
+
+convergence = Convergence()
+
+
+def methods() -> tuple[str, ...]:
+    """Return the names of all registered convergence criteria."""
+    return registry.names()
+
+
+def describe(name: str) -> None:
+    """Return metadata and parameter information for a criterion."""
+    return registry.describe(name)

mocaco/api.pyi

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+import polars as pl
+
+from .protocols import SampleFrame
+from .result import ConvergenceResult
+
+def samples(df: pl.DataFrame, *, target_col: str, it_col: str | None = None) -> SampleFrame: ...
+def methods() -> tuple[str, ...]: ...
+def describe(name: str) -> None: ...
+
+class Convergence:
+    def __call__(
+        self, samples: SampleFrame, *, method: str, **kwargs: Any
+    ) -> ConvergenceResult: ...
+    def clt_absolute(
+        self,
+        samples: SampleFrame,
+        *,
+        threshold: float,
+        confidence_level: float = 0.95,
+        eval_frequency: int = 1,
+    ) -> ConvergenceResult:
+        """
+        Central Limit Theorem based convergence criterion using an absolute Monte Carlo error threshold.
+
+        Parameters
+        ----------
+        threshold : float
+            Maximum accepted absolute Monte Carlo error.
+        confidence_level : float, default 0.95
+            Confidence level used for the CLT margin of error.
+        eval_frequency : int, default 1
+            Number of rows between successive evaluations.
+        """
+        ...
+
+convergence: Convergence

mocaco/methods/__init__.py

@@ -0,0 +1,7 @@
+"""Module to automatically expose all addded methods."""
+
+import importlib
+import pkgutil
+
+for _finder, module_name, _ispkg in pkgutil.iter_modules(__path__):
+    importlib.import_module(f"{__name__}.{module_name}")

mocaco/methods/clt_absolute.py

@@ -0,0 +1,133 @@
+"""Central Limit Theorem based convergence criterion using an absolute Monte Carlo error threshold."""
+
+# Mandatory basic modules
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Basic modules used to build the criterion (According contributor needs)
+import polars as pl
+from pydantic import BaseModel, Field
+from scipy.stats import norm
+
+# Modules needed from mocaco
+from mocaco.registry import registry
+from mocaco.result import ConvergenceResult
+
+if TYPE_CHECKING:
+    from mocaco.protocols import SampleFrame
+
+
+# 1. Criterion input parameters
+class CLTAbsoluteParams(BaseModel):
+    threshold: float = Field(
+        ...,
+        gt=0,
+        description="Maximum accepted absolute Monte Carlo error.",
+    )
+
+    confidence_level: float = Field(
+        0.95,
+        gt=0,
+        lt=1,
+        description="Confidence level used for the CLT margin of error.",
+    )
+
+
+# 2. Criterion logic (calculous)
+@registry.register()
+class CLTAbsoluteCriterion:
+    name = "clt_absolute"
+
+    supports_eval_frequency = True
+
+    description = (
+        "Central Limit Theorem based convergence criterion "
+        "using an absolute Monte Carlo error threshold."
+    )
+
+    params_type = CLTAbsoluteParams
+
+    assumptions = (
+        "Samples are independent and identically distributed (i.i.d.).",
+        "The target quantity has finite variance.",
+        "The sample size is sufficiently large for the CLT to provide a normal approximation. The deafult stb_window = 30 aims to support this assumption.",
+    )
+
+    limitations = (
+        "This is a probabilistic stopping criterion, not a proof of convergence.",
+        "For small sample sizes, the normal approximation may be inaccurate.",
+        "Does not detect systematic bias or non-stationarity in the sampling process.",
+        "The stability window introduces a lag in detecting convergence.",
+    )
+
+    result_interpretation = (
+        "is_converged is True when the CLT-based absolute error has stayed below "
+        "the threshold for at least stb_window consecutive iterations. "
+        "estimate is the cumulative mean at the final sample. "
+        "error is the CLT-based absolute error (z_score * SEM) at the final sample. "
+        "n is the total number of samples evaluated."
+    )
+
+    example_usage = """\
+import polars as pl
+import mocaco as mcc
+
+df = pl.DataFrame({"it": range(100), "value": [1.0] * 100})
+samples = mcc.samples(df, it_col="it", target_col="value")
+result = mcc.convergence.clt_absolute(samples, threshold=0.1)
+print(result.is_converged)"""
+
+    references = ("https://en.wikipedia.org/wiki/Central_limit_theorem",)
+
+    def run(
+        self,
+        samples: SampleFrame,
+        params: CLTAbsoluteParams,
+    ) -> ConvergenceResult:
+
+        target = pl.col(samples.target_col).cast(pl.Float64)
+
+        agg_df = samples.df.select(
+            [pl.len().alias("n"), target.mean().alias("mean"), target.std().alias("std")]
+        )
+
+        final = agg_df.row(0, named=True)
+        n = final["n"]
+        mean = final["mean"]
+        std = final["std"] if final["std"] is not None else 0.0
+
+        sem = std / (n**0.5) if n > 0 else 0.0
+        z_score = float(norm.ppf(1.0 - (1.0 - params.confidence_level) / 2.0))
+        abs_error = sem * z_score
+
+        is_converged = abs_error <= params.threshold
+
+        final_df = pl.DataFrame(
+            {
+                "n": [n],
+                "mean": [mean],
+                "std": [std],
+                "sem": [sem],
+                "abs_error": [abs_error],
+                "is_converged": [is_converged],
+            }
+        )
+
+        return ConvergenceResult(
+            method=self.name,
+            n=int(n),
+            n_col="n",
+            estimate=float(mean) if mean is not None else None,
+            estimate_col="mean",
+            error=float(abs_error),
+            error_col="abs_error",
+            is_converged=is_converged,
+            is_converged_col="is_converged",
+            data=final_df,
+            diagnostics={
+                "threshold": params.threshold,
+                "confidence_level": params.confidence_level,
+                "z_score": z_score,
+            },
+        )

mocaco/protocols.py

@@ -0,0 +1,104 @@
+"""Protocol for method addition and its input data format."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol
+
+import polars as pl
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .result import ConvergenceResult
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class SampleFrame:
+    """
+    Normalized representation of Monte Carlo samples.
+
+    Parameters
+    ----------
+    df
+        Source Polars DataFrame.
+    it_col
+        Column containing the iteration/order of the samples.
+    target_col
+        Column containing the quantity to analyze.
+    """
+
+    df: pl.DataFrame
+    target_col: str
+    it_col: str | None = None
+
+    def __post_init__(self) -> None:
+        """Validate columns, assign default iteration indices if missing, and handle edge cases."""
+        # 1. Resolve and normalize it_col name
+        if self.it_col is None:
+            it_col_name = "it"
+            new_df = self.df.with_columns(pl.arange(1, len(self.df) + 1).alias(it_col_name))
+            object.__setattr__(self, "df", new_df)
+            object.__setattr__(self, "it_col", it_col_name)
+            logger.info("it_col was None — auto-created column 'it' with sequential indices.")
+        else:
+            it_col_name = self.it_col
+
+        # 2. Validate structural integrity (it_col_name is guaranteed to be str here)
+        missing = [col for col in (it_col_name, self.target_col) if col not in self.df.columns]
+        if missing:
+            raise ValueError(
+                f"Columns not found in DataFrame: {missing}. Available columns: {self.df.columns}"
+            )
+
+        if self.df.is_empty():
+            raise ValueError("The sample DataFrame cannot be empty.")
+
+        # 3. Validate Data Types (it_col and target_col must be numeric)
+        it_dtype = self.df.get_column(it_col_name).dtype
+        if not it_dtype.is_numeric():
+            raise TypeError(
+                f"Iteration column '{it_col_name}' must be numeric (int or float), got {it_dtype}."
+            )
+
+        target = self.df.get_column(self.target_col)
+        if not target.dtype.is_numeric():
+            raise TypeError(
+                f"Target column '{self.target_col}' must be numeric (int or float), got {target.dtype}."
+            )
+
+        # 4. Input validation and edge case handling (Null, NaN, Inf)
+        if target.is_null().any():
+            raise ValueError(f"Target column '{self.target_col}' contains Null (missing) values.")
+
+        if target.dtype in (pl.Float32, pl.Float64):
+            if target.is_nan().any():
+                raise ValueError(f"Target column '{self.target_col}' contains NaN values.")
+            if target.is_infinite().any():
+                raise ValueError(
+                    f"Target column '{self.target_col}' contains Infinite (Inf) values."
+                )
+
+
+class Criterion(Protocol):
+    """Structural contract implemented by every convergence criterion."""
+
+    name: str
+    supports_eval_frequency: bool
+    description: str
+    params_type: type[Any]
+
+    assumptions: ClassVar[Sequence[str]]
+    limitations: ClassVar[Sequence[str]]
+    result_interpretation: str
+    example_usage: str
+    references: ClassVar[Sequence[str]]
+
+    def run(
+        self,
+        samples: SampleFrame,
+        params: Any,
+    ) -> ConvergenceResult: ...

mocaco/registry.py

@@ -0,0 +1,126 @@
+"""Registry singleton of mocaco convergence methods."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar, overload
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from .protocols import Criterion
+
+C = TypeVar("C", bound=type)
+
+console = Console()
+
+
+class CriterionRegistry:
+    def __init__(self) -> None:
+        self._criteria: dict[str, Criterion] = {}
+
+    # Overload 1: Decorator usage (no criterion provided)
+    @overload
+    def register(self, criterion: None = None, *, overwrite: bool = False) -> Callable[[C], C]: ...
+
+    # Overload 2: Programmatic usage (criterion instance provided)
+    @overload
+    def register(self, criterion: Criterion, *, overwrite: bool = False) -> Criterion: ...
+
+    def register(
+        self,
+        criterion: Criterion | None = None,
+        *,
+        overwrite: bool = False,
+    ) -> Any:
+        # 1. Programmatic use: registry.register(MyCriterion())
+        if criterion is not None:
+            name = criterion.name
+
+            if not name:
+                raise ValueError("A criterion must define a non-empty name.")
+
+            if name in self._criteria and not overwrite:
+                raise ValueError(f"Criterion {name!r} is already registered.")
+
+            self._criteria[name] = criterion
+            return criterion
+
+        # 2. Decorator use: @registry.register()
+        def wrapper(cls: C) -> C:
+            instance = cls()
+            self.register(instance, overwrite=overwrite)
+            return cls
+
+        return wrapper
+
+    def get(self, name: str) -> Criterion:
+        try:
+            return self._criteria[name]
+        except KeyError as exc:
+            available = ", ".join(self.names())
+            raise ValueError(
+                f"Unknown convergence criterion: {name!r}. Available criteria: {available}"
+            ) from exc
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(self._criteria.keys())
+
+    def describe(self, name: str) -> None:
+        # 1. Fetch the criterion from the registry
+        try:
+            criterion = registry.get(name)
+        except ValueError:
+            console.print(f"[bold red]Error:[/bold red] Method '{name}' not found in registry.")
+            return
+
+        # 2. Print the Method Name and Main Description in a Panel
+        console.print()
+        console.print(
+            Panel(
+                f"{criterion.description}",
+                title=f"Method: [bold cyan]{name}[/bold cyan]",
+                title_align="left",
+                border_style="cyan",
+                expand=False,
+            )
+        )
+
+        # 3. Create a Table for the Parameters
+        table = Table(
+            title="Parameters",
+            title_style="bold magenta",
+            title_justify="left",
+            show_header=True,
+            header_style="bold black on white",
+        )
+
+        table.add_column("Name", style="bold cyan", no_wrap=True)
+        table.add_column("Type", style="green")
+        table.add_column("Required", justify="center")
+        table.add_column("Default", style="yellow")
+        table.add_column("Description", style="dim")
+
+        # 4. Introspect the Pydantic V2 model fields
+        params_type = criterion.params_type
+
+        for field_name, field_info in params_type.model_fields.items():
+            # Get type name cleanly
+            field_type = getattr(field_info.annotation, "__name__", str(field_info.annotation))
+
+            is_required = field_info.is_required()
+            req_icon = "[green]✔[/green]" if is_required else "[red]✘[/red]"
+            default_val = "-" if is_required else repr(field_info.default)
+            desc = field_info.description or "No description provided."
+
+            table.add_row(field_name, field_type, req_icon, default_val, desc)
+
+        # 5. Render the table
+        console.print(table)
+        console.print()
+
+
+registry = CriterionRegistry()

mocaco/result.py

@@ -0,0 +1,222 @@
+"""Module to format Result output from convergence methods."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import matplotlib.pyplot as plt
+import polars as pl
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class ResultPlotter:
+    """Helper class to provide plotting capabilities for ConvergenceResult."""
+
+    def __init__(self, result: ConvergenceResult) -> None:
+        self.result = result
+
+    def evolution(
+        self,
+        *,
+        show: bool = False,
+    ) -> Any:
+        """
+        Plot the evolution of the estimate, the error band, and the convergence point.
+
+        Requires `matplotlib` to be installed.
+
+        Parameters
+        ----------
+        show
+            If True, automatically displays the plot with `plt.show()` and cleans up resources.
+
+        Returns
+        -------
+        matplotlib.axes.Axes
+            The matplotlib Axes object containing the plot.
+        """
+        df = self.result.data
+
+        # Ensure required columns exist
+        missing = [
+            col
+            for col in (
+                self.result.estimate_col,
+                self.result.error_col,
+                self.result.n_col,
+                self.result.is_converged_col,
+            )
+            if col not in self.result.data.columns
+        ]
+        if missing:
+            raise ValueError(f"Columns not found in diagnostic data for plotting: {missing}")
+
+        # Extract arrays
+        n_vals = df.get_column(self.result.n_col).to_numpy()
+        estimate_vals = df.get_column(self.result.estimate_col).to_numpy()
+        error_vals = df.get_column(self.result.error_col).to_numpy()
+
+        fig, ax = plt.subplots(figsize=(8, 5))
+
+        # Plot estimate line
+        ax.plot(n_vals, estimate_vals, label="Estimate", color="#1f77b4", linewidth=2)
+
+        # Plot error band
+        ax.fill_between(
+            n_vals,
+            estimate_vals - error_vals,
+            estimate_vals + error_vals,
+            color="#1f77b4",
+            alpha=0.2,
+            label="Error Band",
+        )
+
+        # Plot vertical line for convergence (first True occurrence)
+        converged_df = df.filter(pl.col(self.result.is_converged_col))
+        if not converged_df.is_empty():
+            first_converged_n = converged_df.get_column(self.result.n_col)[0]
+            ax.axvline(
+                x=first_converged_n,
+                color="red",
+                linestyle="--",
+                label=f"Converged at n={first_converged_n}",
+            )
+
+        ax.set_xlabel("Number of samples (n)")
+        ax.set_ylabel("Estimate")
+        ax.set_title(f"Convergence Evolution ({self.result.method})")
+        ax.legend()
+        ax.grid(True, linestyle=":", alpha=0.7)
+
+        if show:
+            plt.show()
+            plt.close(fig)
+
+        return ax
+
+
+@dataclass(frozen=True)
+class ConvergenceResult:
+    """
+    Common result returned by convergence criteria.
+
+    Parameters
+    ----------
+    method
+        Name of the convergence criterion.
+    n
+        Number of samples used in the final estimate.
+    n_col
+        Name of the n column set on the method data output
+    estimate
+        Final estimate of the target quantity.
+    estimate_col
+        Name of the estimate column set on the method data output
+    error
+        Final estimated error.
+    error_col
+            Name of the error column set on the method data output
+    is_converged
+        Whether the final evaluated state satisfies the criterion.
+    is_converged_col
+            Name of the is_converged column set on the method data output
+    data
+        Full diagnostic DataFrame generated by the method/wrapper.
+    diagnostics
+        Method-specific diagnostic information.
+    """
+
+    # Common outputs to all criterions
+    method: str
+    n: int
+    n_col: str
+    estimate: float | None
+    estimate_col: str
+    error: float | None
+    error_col: str
+    is_converged: bool | None
+    is_converged_col: str
+
+    # Build by Wrapper or by the criterion default
+    data: pl.DataFrame
+
+    # Method-specific outputs
+    diagnostics: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def plot(self) -> ResultPlotter:
+        """Access the plotting API for this result."""
+        return ResultPlotter(self)
+
+    def to_polars(self) -> pl.DataFrame:
+        """Return the complete diagnostic DataFrame as a Polars DataFrame."""
+        return self.data
+
+    def to_pandas(self) -> pd.DataFrame:
+        """Return the complete diagnostic DataFrame as a Pandas DataFrame."""
+        return self.data.to_pandas()
+
+    def summary(self) -> None:
+        """Print a rich formatted summary of the convergence result to the console."""
+        console = Console()
+
+        # Define status colors and icons
+        status_color = "green" if self.is_converged else "yellow"
+        status_icon = "✔" if self.is_converged else "⚠"
+        status_text = "Converged" if self.is_converged else "Not Converged"
+
+        # Create the inner layout table
+        table = Table(show_header=False, box=None, padding=(0, 2))
+        table.add_row("[bold]Method:[/bold]", f"[cyan]{self.method}[/cyan]")
+        table.add_row(
+            "[bold]Status:[/bold]", f"[{status_color}]{status_icon} {status_text}[/{status_color}]"
+        )
+        table.add_row("[bold]Samples (n):[/bold]", str(self.n))
+        est_str = f"{self.estimate:.6g}" if self.estimate is not None else "-"
+        table.add_row("[bold]Estimate:[/bold]", est_str)
+        err_str = f"{self.error:.6g}" if self.error is not None else "-"
+        table.add_row("[bold]Error:[/bold]", err_str)
+
+        # Append diagnostics dynamically if they exist
+        if self.diagnostics:
+            table.add_row("", "")  # Spacer
+            table.add_row("[bold italic]Diagnostics:[/bold italic]", "")
+            for key, value in self.diagnostics.items():
+                # Format floats cleanly, otherwise just cast to str
+                val_str = f"{value:.6g}" if isinstance(value, float) else str(value)
+                table.add_row(f"  {key}:", val_str)
+
+        # Wrap in a stylized panel
+        panel = Panel(
+            table,
+            title="[bold]Convergence Summary[/bold]",
+            title_align="left",
+            border_style=status_color,
+            expand=False,
+        )
+
+        console.print()
+        console.print(panel)
+        console.print()
+
+    def __str__(self) -> str:
+        """Return the string representation of the underlying Polars DataFrame."""
+        return str(self.data)
+
+    def __repr__(self) -> str:
+        """Return a compact string representation of the result summary."""
+        return (
+            f"ConvergenceResult("
+            f"method={self.method!r}, "
+            f"n={self.n!r}"
+            f"estimate={self.estimate!r}, "
+            f"error={self.error!r}, "
+            f"is_converged={self.is_converged!r}, "
+            f")"
+        )

mocaco/wrappers.py

@@ -0,0 +1,170 @@
+"""Criterion wrappers to expand evaluation behaviors."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import polars as pl
+
+from .protocols import SampleFrame
+from .result import ConvergenceResult
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .protocols import Criterion
+
+
+class CriterionWrapper:
+    """
+    Base class for criterion wrappers.
+
+    A wrapper intercepts calls to a criterion's ``run()`` method to add
+    cross-cutting behaviour (e.g. periodic evaluation, caching, logging)
+    without modifying the criterion itself.
+
+    All metadata attributes are delegated to the inner criterion so that
+    the wrapper satisfies the same ``Criterion`` protocol.
+    """
+
+    def __init__(self, criterion: Criterion) -> None:
+        self._criterion = criterion
+
+    @property
+    def name(self) -> str:
+        return self._criterion.name
+
+    @property
+    def description(self) -> str:
+        return self._criterion.description
+
+    @property
+    def params_type(self) -> type[Any]:
+        return self._criterion.params_type
+
+    @property
+    def assumptions(self) -> Sequence[str]:
+        return self._criterion.assumptions
+
+    @property
+    def limitations(self) -> Sequence[str]:
+        return self._criterion.limitations
+
+    @property
+    def result_interpretation(self) -> str:
+        return self._criterion.result_interpretation
+
+    @property
+    def example_usage(self) -> str:
+        return self._criterion.example_usage
+
+    @property
+    def references(self) -> Sequence[str]:
+        return self._criterion.references
+
+    def run(
+        self,
+        samples: SampleFrame,
+        params: Any,
+    ) -> ConvergenceResult:
+        return self._criterion.run(samples, params)
+
+
+class EvalFrequencyWrapper(CriterionWrapper):
+    """
+    Wrapper that evaluates a criterion at regular iteration intervals.
+
+    Instead of running the criterion once on the full dataset, this wrapper
+    runs it on cumulative slices of the data at every ``eval_frequency``
+    rows.  The diagnostic DataFrames from each evaluation are concatenated
+    into a single DataFrame, and the final ``ConvergenceResult`` carries the
+    last run's summary fields combined with the concatenated history.
+
+    Parameters
+    ----------
+    criterion
+        The inner criterion to wrap.
+    eval_frequency
+        Number of rows between successive evaluations.  Must be a
+        positive integer.
+
+    Examples
+    --------
+    >>> wrapper = EvalFrequencyWrapper(criterion, eval_frequency=10)
+    >>> result = wrapper.run(samples, params)
+    >>> result.data  # diagnostic history across all evaluations
+    """
+
+    def __init__(self, criterion: Criterion, eval_frequency: int) -> None:
+        super().__init__(criterion)
+        if eval_frequency <= 0:
+            raise ValueError(f"eval_frequency must be a positive integer, got {eval_frequency}")
+        self._eval_frequency = eval_frequency
+
+    @property
+    def eval_frequency(self) -> int:
+        return self._eval_frequency
+
+    def run(
+        self,
+        samples: SampleFrame,
+        params: Any,
+    ) -> ConvergenceResult:
+        total_rows = len(samples.df)
+
+        if self._eval_frequency >= total_rows:
+            result = self._criterion.run(samples, params)
+            return ConvergenceResult(
+                method=result.method,
+                n=result.n,
+                n_col=result.n_col,
+                estimate=result.estimate,
+                estimate_col=result.estimate_col,
+                error=result.error,
+                error_col=result.error_col,
+                is_converged=result.is_converged,
+                is_converged_col=result.is_converged_col,
+                data=result.data,
+                diagnostics={
+                    **result.diagnostics,
+                    "eval_frequency": self._eval_frequency,
+                    "n_evaluations": 1,
+                },
+            )
+
+        eval_points = list(range(self._eval_frequency, total_rows + 1, self._eval_frequency))
+        if eval_points[-1] != total_rows:
+            eval_points.append(total_rows)
+
+        results: list[ConvergenceResult] = []
+        for point in eval_points:
+            sliced_df = samples.df.head(point)
+            sliced_samples = SampleFrame(
+                df=sliced_df,
+                target_col=samples.target_col,
+                it_col=samples.it_col,
+            )
+            result = self._criterion.run(sliced_samples, params)
+            results.append(result)
+
+        data_frames = [r.data for r in results]
+        combined_data = pl.concat(data_frames, how="align")
+
+        final = results[-1]
+        return ConvergenceResult(
+            method=final.method,
+            n=final.n,
+            n_col=final.n_col,
+            estimate=final.estimate,
+            estimate_col=final.estimate_col,
+            error=final.error,
+            error_col=final.error_col,
+            is_converged=final.is_converged,
+            is_converged_col=final.is_converged_col,
+            data=combined_data,
+            diagnostics={
+                **final.diagnostics,
+                "eval_frequency": self._eval_frequency,
+                "n_evaluations": len(results),
+            },
+        )

mocaco-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: mocaco
+Version: 0.1.0
+Summary: Convergence analysis for Monte Carlo series — works with Polars DataFrames
+Author-email: Álvaro Esteban Muñoz <em.alvaro.l@gmail.com>
+License: LGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: matplotlib>=3.11.2
+Requires-Dist: numpy>=2.5.3
+Requires-Dist: pandas>=3.0.6
+Requires-Dist: polars>=1.44.2
+Requires-Dist: pyarrow>=25.0.1
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: rich>=15.0.0
+Requires-Dist: scipy>=1.18.1
+Description-Content-Type: text/markdown
+
+# mocaco
+
+[![CI](https://github.com/emalvarol/mocaco/actions/workflows/ci.yml/badge.svg)](https://github.com/emalvarol/mocaco/actions/workflows/ci.yml)
+![Python Versions](https://img.shields.io/badge/python-3.12%20|%203.13%20|%203.14-blue)
+![License: LGPL](https://img.shields.io/badge/license-LGPL-blue)
+
+Convergence analysis for Monte Carlo series using Polars DataFrames.
+
+<p align="center">
+  <img src="assets/Logo_v1.png" alt="mocaco logo" width="400"/>
+</p>
+
+The library provides a simple API for applying different convergence and
+stopping criteria to Monte Carlo simulation results.
+
+## Quickstart
+
+```python
+import polars as pl
+import mocaco as mcc
+
+# Prepare your Monte Carlo samples
+df = pl.DataFrame({"it": range(1000), "value": your_samples})
+
+# Create a normalized sample frame
+samples = mcc.samples(df, it_col="it", target_col="value")
+
+# Run a convergence criterion
+result = mcc.convergence.clt_absolute(samples, threshold=0.01)
+
+# Inspect results
+print(result.is_converged)  # True/False
+print(result.estimate)  # Final cumulative mean
+print(result.error)  # Final CLT-based absolute error
+print(result.n)  # Number of samples
+# and more...
+```
+
+## API Overview
+
+| Function | Description |
+|----------|-------------|
+| `mcc.samples(df, it_col, target_col)` | Create a normalized sample frame from a Polars DataFrame |
+| `mcc.convergence(samples, method="...")` | Generic invocation of any registered criterion |
+| `mcc.convergence.clt_absolute(samples, ...)` | Typed invocation of a specific criterion |
+| `mcc.methods()` | List all registered convergence criteria |
+| `mcc.describe("clt_absolute")` | Get metadata and parameter info for a criterion |
+
+## Available Methods
+
+- [`clt_absolute`](docs/methods/clt_absolute.md) — CLT-based absolute error threshold
+
+## Documentation
+
+Full documentation is available in the `docs/` directory or can be built with:
+
+```bash
+mkdocs serve
+```
+
+## Installation (Developers)
+
+### Environment
+
+Create the virtual environment and install the project in editable mode with `uv`:
+
+```bash
+uv venv
+uv sync
+uv pip install -e .
+```
+
+If it is needed to remove an old environment:
+
+```bash
+Remove-Item -Recurse -Force .venv
+```
+
+### ruff
+```bash
+uv run ruff check --fix . && uv run ruff format .
+```
+
+### mypy
+```bash
+uv run mypy src/
+```

mocaco-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+mocaco/__init__.py,sha256=tWfOIMSLYMu9gEYcOqpgn9z2MBvi48vSHzyg4oNhDCA,182
+mocaco/api.py,sha256=LEQmSmDVupbUY6A4eKn6AiaPqCRusZ9bLGk8GGf019E,3389
+mocaco/api.pyi,sha256=gTxbV3lDQWn-aObe5CWWn4cQuzigJGAjsUMylgeSiPE,1165
+mocaco/protocols.py,sha256=aSYD-ij3sXFZGvbn7YbSmK3XjTohujHgAkh8RsckgE0,3431
+mocaco/registry.py,sha256=7BzJVuhfihAi5wdihQouR4_mXiF8MOp-oQ2y2C5DLh4,4036
+mocaco/result.py,sha256=qdZ9Mu4OR-W-JZiQqRin2S4jRED6gZji5hRu4i_UIaQ,7068
+mocaco/wrappers.py,sha256=G97_DmlcPlAryxWAjn1DmwyEIS7BN9CtX-6lfjhTIbE,5262
+mocaco/methods/__init__.py,sha256=3Npj5Yu67T8vlTcfxNqwGbtSx2V3mmG0RSHoLFGQCz8,216
+mocaco/methods/clt_absolute.py,sha256=pkcEj8UhwFxdKVyjitXACmF9VVWGZ3K4Blrzy1-jxzE,4195
+mocaco-0.1.0.dist-info/METADATA,sha256=XqCjH_H7bXpOSWwyzvWXvESS4aibiO7OFvjYiu_T1uo,2841
+mocaco-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mocaco-0.1.0.dist-info/licenses/LICENSE,sha256=pWgb-bBdsU2Gd2kwAXxketnm5W_2u8_fIeWEgojfrxs,7651
+mocaco-0.1.0.dist-info/RECORD,,

mocaco-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mocaco-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.