openstat-cli 1.0.0__py3-none-any.whl

openstat/stats/timeseries.py

@@ -0,0 +1,142 @@
+"""Time series analysis: ARIMA, VAR, ADF test, ACF/PACF, forecasting."""
+
+from __future__ import annotations
+
+import numpy as np
+import polars as pl
+import statsmodels.api as sm
+from scipy import stats as sp_stats
+
+from openstat.stats.models import FitResult
+
+
+def adf_test(series: np.ndarray, variable_name: str = "y") -> str:
+    """Augmented Dickey-Fuller unit root test."""
+    from statsmodels.tsa.stattools import adfuller
+
+    result = adfuller(series, autolag="AIC")
+    adf_stat, p_value, used_lag, nobs, crit_values, icbest = result
+
+    lines = [
+        f"Augmented Dickey-Fuller Test: {variable_name}",
+        f"  ADF Statistic: {adf_stat:.4f}",
+        f"  p-value: {p_value:.4f}",
+        f"  Lags used: {used_lag}",
+        f"  Observations: {nobs}",
+        "  Critical Values:",
+    ]
+    for level, val in crit_values.items():
+        lines.append(f"    {level}: {val:.4f}")
+
+    if p_value < 0.05:
+        lines.append("  ✓ Reject H0: Series is stationary")
+    else:
+        lines.append("  ⚠ Cannot reject H0: Series has a unit root (non-stationary)")
+
+    return "\n".join(lines)
+
+
+def fit_arima(
+    df: pl.DataFrame,
+    dep: str,
+    order: tuple[int, int, int],
+    exog_vars: list[str] | None = None,
+    time_var: str | None = None,
+) -> tuple[FitResult, object]:
+    """Fit an ARIMA(p,d,q) model, optionally with exogenous variables (ARIMAX)."""
+    from statsmodels.tsa.arima.model import ARIMA
+
+    pdf = df.to_pandas()
+    if time_var and time_var in pdf.columns:
+        pdf = pdf.sort_values(time_var)
+        try:
+            pdf = pdf.set_index(time_var)
+        except Exception:
+            pass
+
+    endog = pdf[dep].dropna()
+    exog = pdf[exog_vars].loc[endog.index] if exog_vars else None
+
+    model = ARIMA(endog, exog=exog, order=order)
+    result = model.fit()
+
+    # Build FitResult
+    params = {name: float(val) for name, val in result.params.items()}
+    bse = result.bse
+    std_errors = {name: float(bse[name]) for name in params}
+    z_values = {name: float(result.tvalues[name]) for name in params}
+    p_values = {name: float(result.pvalues[name]) for name in params}
+    ci = result.conf_int()
+    conf_low = {name: float(ci.loc[name, 0]) for name in params}
+    conf_high = {name: float(ci.loc[name, 1]) for name in params}
+
+    warnings_list = [
+        f"Order: ARIMA{order}",
+        f"AIC: {result.aic:.1f}",
+        f"BIC: {result.bic:.1f}",
+    ]
+
+    fit = FitResult(
+        model_type=f"ARIMA{order}",
+        formula=f"{dep} ~ ARIMA{order}" + (f" + {' + '.join(exog_vars)}" if exog_vars else ""),
+        dep_var=dep,
+        indep_vars=list(params.keys()),
+        n_obs=int(result.nobs),
+        params=params,
+        std_errors=std_errors,
+        t_values=z_values,
+        p_values=p_values,
+        conf_int_low=conf_low,
+        conf_int_high=conf_high,
+        aic=float(result.aic),
+        bic=float(result.bic),
+        log_likelihood=float(result.llf),
+        warnings=warnings_list,
+    )
+
+    return fit, result
+
+
+def fit_var(
+    df: pl.DataFrame,
+    variables: list[str],
+    lags: int,
+    time_var: str | None = None,
+) -> tuple[str, object]:
+    """Fit a Vector Autoregression (VAR) model.
+
+    Returns summary string and raw result.
+    """
+    from statsmodels.tsa.api import VAR
+
+    pdf = df.to_pandas()
+    if time_var and time_var in pdf.columns:
+        pdf = pdf.sort_values(time_var)
+
+    data = pdf[variables].dropna()
+    model = VAR(data)
+    result = model.fit(maxlags=lags)
+
+    summary = str(result.summary())
+    return summary, result
+
+
+def forecast_model(result, steps: int) -> np.ndarray:
+    """Generate forecasts from a fitted time series model."""
+    if hasattr(result, 'forecast'):
+        # ARIMA result
+        fc = result.forecast(steps=steps)
+        return np.array(fc)
+    elif hasattr(result, 'forecast') and hasattr(result, 'endog'):
+        # VAR result
+        fc = result.forecast(result.endog[-result.k_ar:], steps=steps)
+        return fc
+    raise ValueError("Model does not support forecasting")
+
+
+def compute_irf(var_result, steps: int = 10) -> str:
+    """Compute impulse response functions for VAR model."""
+    irf = var_result.irf(steps)
+    lines = ["Impulse Response Functions:"]
+    lines.append(str(irf.summary()))
+    return "\n".join(lines)

openstat/stats/ts_advanced.py

@@ -0,0 +1,114 @@
+"""Advanced time-series: Granger causality, VECM, Johansen cointegration, STL, tssmooth."""
+
+from __future__ import annotations
+
+import numpy as np
+import polars as pl
+
+
+def granger_causality(df: pl.DataFrame, dep: str, cause: str, maxlag: int = 4) -> dict:
+    """Granger causality test: does 'cause' Granger-cause 'dep'?"""
+    from statsmodels.tsa.stattools import grangercausalitytests
+    sub = df.select([dep, cause]).drop_nulls()
+    data = sub.to_numpy()
+    results = grangercausalitytests(data, maxlag=maxlag, verbose=False)
+    # Collect F-test p-values per lag
+    lag_pvals = {}
+    for lag, res in results.items():
+        lag_pvals[lag] = float(res[0]["ssr_ftest"][1])
+    min_pval = min(lag_pvals.values())
+    best_lag = min(lag_pvals, key=lag_pvals.get)
+    return {
+        "test": "Granger Causality",
+        "dep": dep,
+        "cause": cause,
+        "maxlag": maxlag,
+        "lag_pvalues": lag_pvals,
+        "min_pvalue": min_pval,
+        "best_lag": best_lag,
+        "reject_null_5pct": min_pval < 0.05,
+    }
+
+
+def johansen_test(df: pl.DataFrame, cols: list[str], det_order: int = -1, k_ar_diff: int = 1) -> dict:
+    """Johansen cointegration test."""
+    from statsmodels.tsa.vector_ar.vecm import coint_johansen
+    sub = df.select(cols).drop_nulls()
+    data = sub.to_numpy()
+    result = coint_johansen(data, det_order, k_ar_diff)
+    trace_stat = result.lr1.tolist()
+    trace_cv_90 = result.cvt[:, 0].tolist()
+    trace_cv_95 = result.cvt[:, 1].tolist()
+    max_stat = result.lr2.tolist()
+    max_cv_95 = result.cvm[:, 1].tolist()
+    n_cointegrated = int(np.sum(np.array(trace_stat) > np.array(trace_cv_95)))
+    return {
+        "test": "Johansen Cointegration",
+        "cols": cols,
+        "trace_statistics": trace_stat,
+        "trace_cv_95": trace_cv_95,
+        "trace_cv_90": trace_cv_90,
+        "max_eigen_statistics": max_stat,
+        "max_eigen_cv_95": max_cv_95,
+        "n_cointegrating_vectors": n_cointegrated,
+    }
+
+
+def fit_vecm(df: pl.DataFrame, cols: list[str], k_ar_diff: int = 1, coint_rank: int = 1) -> dict:
+    """Vector Error Correction Model."""
+    from statsmodels.tsa.vector_ar.vecm import VECM
+    sub = df.select(cols).drop_nulls()
+    data = sub.to_numpy()
+    model = VECM(data, k_ar_diff=k_ar_diff, coint_rank=coint_rank).fit()
+    return {
+        "test": "VECM",
+        "cols": cols,
+        "k_ar_diff": k_ar_diff,
+        "coint_rank": coint_rank,
+        "alpha": model.alpha.tolist(),
+        "beta": model.beta.tolist(),
+        "gamma": model.gamma.tolist() if hasattr(model, "gamma") else None,
+        "det_coef": model.det_coef.tolist() if hasattr(model, "det_coef") else None,
+        "llf": float(model.llf) if hasattr(model, "llf") else None,
+        "_model": model,
+    }
+
+
+def stl_decompose(df: pl.DataFrame, col: str, period: int = 12) -> dict:
+    """STL decomposition: trend + seasonal + residual."""
+    from statsmodels.tsa.seasonal import STL
+    sub = df.select([col]).drop_nulls()
+    y = sub[col].to_numpy().astype(float)
+    stl = STL(y, period=period).fit()
+    return {
+        "test": "STL Decomposition",
+        "col": col,
+        "period": period,
+        "trend": stl.trend.tolist(),
+        "seasonal": stl.seasonal.tolist(),
+        "resid": stl.resid.tolist(),
+        "strength_trend": float(1 - np.var(stl.resid) / np.var(stl.trend + stl.resid)),
+        "strength_seasonal": float(1 - np.var(stl.resid) / np.var(stl.seasonal + stl.resid)),
+        "_model": stl,
+    }
+
+
+def tssmooth(df: pl.DataFrame, col: str, method: str = "ma", window: int = 3, alpha: float = 0.3) -> pl.DataFrame:
+    """Smooth a time series: moving average (ma) or exponential smoothing (exp)."""
+    series = df[col].to_numpy().astype(float)
+    n = len(series)
+    if method == "ma":
+        smoothed = np.convolve(series, np.ones(window) / window, mode="same")
+        # Fix edges
+        for i in range(window // 2):
+            smoothed[i] = np.mean(series[:i + window // 2 + 1])
+            smoothed[n - 1 - i] = np.mean(series[n - i - window // 2 - 1:])
+    elif method == "exp":
+        smoothed = np.zeros(n)
+        smoothed[0] = series[0]
+        for t in range(1, n):
+            smoothed[t] = alpha * series[t] + (1 - alpha) * smoothed[t - 1]
+    else:
+        raise ValueError(f"Unknown smoothing method: {method}. Use 'ma' or 'exp'.")
+    new_col = f"{col}_smooth"
+    return df.with_columns(pl.Series(new_col, smoothed))

openstat/types.py

@@ -0,0 +1,11 @@
+"""Shared type constants."""
+
+from __future__ import annotations
+
+import polars as pl
+
+NUMERIC_DTYPES: set[type[pl.DataType]] = {
+    pl.Float32, pl.Float64,
+    pl.Int8, pl.Int16, pl.Int32, pl.Int64,
+    pl.UInt8, pl.UInt16, pl.UInt32, pl.UInt64,
+}

openstat/web/__init__.py

@@ -0,0 +1 @@
+"""Web-based GUI for OpenStat using FastAPI and WebSocket."""

openstat/web/app.py

@@ -0,0 +1,117 @@
+"""FastAPI application for OpenStat web GUI."""
+
+from __future__ import annotations
+
+import base64
+import json
+import tempfile
+from pathlib import Path
+
+try:
+    from fastapi import FastAPI, WebSocket, WebSocketDisconnect, UploadFile, File
+    from fastapi.staticfiles import StaticFiles
+    from fastapi.responses import HTMLResponse
+    HAS_FASTAPI = True
+except ImportError:
+    HAS_FASTAPI = False
+
+from openstat.web.session_manager import SessionManager
+from openstat.logging_config import get_logger
+
+log = get_logger("web")
+
+if HAS_FASTAPI:
+    app = FastAPI(title="OpenStat Web", version="0.3.0")
+    sessions = SessionManager()
+
+    # Serve static files
+    static_dir = Path(__file__).parent / "static"
+    if static_dir.exists():
+        app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+    @app.get("/", response_class=HTMLResponse)
+    async def index():
+        """Serve the main HTML page."""
+        html_path = static_dir / "index.html"
+        if html_path.exists():
+            return html_path.read_text()
+        return "<h1>OpenStat Web</h1><p>Static files not found.</p>"
+
+    @app.post("/api/session")
+    async def create_session():
+        """Create a new analysis session."""
+        session_id = sessions.create()
+        return {"session_id": session_id}
+
+    @app.post("/api/upload/{session_id}")
+    async def upload_file(session_id: str, file: UploadFile = File(...)):
+        """Upload a data file to a session."""
+        session = sessions.get(session_id)
+        if session is None:
+            return {"error": "Session not found"}
+
+        # Save to temp file
+        suffix = Path(file.filename).suffix if file.filename else ".csv"
+        with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
+            content = await file.read()
+            tmp.write(content)
+            tmp_path = tmp.name
+
+        # Load into session
+        from openstat.repl import _dispatch
+        result = _dispatch(session, f"load {tmp_path}")
+        return {
+            "result": result,
+            "shape": session.shape_str,
+            "filename": file.filename,
+        }
+
+    @app.websocket("/ws/{session_id}")
+    async def websocket_endpoint(websocket: WebSocket, session_id: str):
+        """WebSocket REPL for interactive commands."""
+        await websocket.accept()
+        session = sessions.get_or_create(session_id)
+        log.info("WebSocket connected: %s", session_id)
+
+        try:
+            while True:
+                command = await websocket.receive_text()
+                from openstat.repl import _dispatch
+                result = _dispatch(session, command)
+
+                if result == "__QUIT__":
+                    await websocket.send_json({
+                        "type": "quit",
+                        "content": "Session ended.",
+                    })
+                    break
+
+                # Check for new plot files
+                plot_data = None
+                if session.plot_paths:
+                    last_plot = session.plot_paths[-1]
+                    plot_path = Path(last_plot)
+                    if plot_path.exists():
+                        with open(plot_path, "rb") as f:
+                            plot_data = base64.b64encode(f.read()).decode()
+
+                await websocket.send_json({
+                    "type": "result",
+                    "content": result or "",
+                    "shape": session.shape_str,
+                    "plot": plot_data,
+                })
+        except WebSocketDisconnect:
+            log.info("WebSocket disconnected: %s", session_id)
+        except Exception as e:
+            log.error("WebSocket error: %s", e)
+
+    @app.get("/api/status")
+    async def status():
+        """Server status."""
+        return {
+            "active_sessions": sessions.active_count,
+            "status": "running",
+        }
+else:
+    app = None

openstat/web/session_manager.py

@@ -0,0 +1,73 @@
+"""Multi-user session management with TTL cleanup."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta
+
+from openstat.session import Session
+from openstat.logging_config import get_logger
+
+log = get_logger("web.sessions")
+
+
+class SessionManager:
+    """Manages multiple user sessions with automatic cleanup."""
+
+    def __init__(self, max_sessions: int = 100, ttl_minutes: int = 60) -> None:
+        self._sessions: dict[str, Session] = {}
+        self._last_access: dict[str, datetime] = {}
+        self._max_sessions = max_sessions
+        self._ttl = timedelta(minutes=ttl_minutes)
+
+    def create(self) -> str:
+        """Create a new session, return its ID."""
+        self._cleanup()
+        session_id = str(uuid.uuid4())[:8]
+        self._sessions[session_id] = Session()
+        self._last_access[session_id] = datetime.now()
+        log.info("Created session: %s", session_id)
+        return session_id
+
+    def get(self, session_id: str) -> Session | None:
+        """Get an existing session by ID."""
+        session = self._sessions.get(session_id)
+        if session is not None:
+            self._last_access[session_id] = datetime.now()
+        return session
+
+    def get_or_create(self, session_id: str) -> Session:
+        """Get existing session or create new one."""
+        session = self.get(session_id)
+        if session is None:
+            self._sessions[session_id] = Session()
+            self._last_access[session_id] = datetime.now()
+            log.info("Created session: %s", session_id)
+            session = self._sessions[session_id]
+        return session
+
+    def remove(self, session_id: str) -> None:
+        """Remove a session."""
+        self._sessions.pop(session_id, None)
+        self._last_access.pop(session_id, None)
+
+    def _cleanup(self) -> None:
+        """Remove expired sessions and enforce max count."""
+        now = datetime.now()
+        expired = [
+            sid for sid, last in self._last_access.items()
+            if now - last > self._ttl
+        ]
+        for sid in expired:
+            self.remove(sid)
+            log.info("Expired session: %s", sid)
+
+        # If still over limit, remove oldest
+        while len(self._sessions) >= self._max_sessions:
+            oldest = min(self._last_access, key=self._last_access.get)
+            self.remove(oldest)
+            log.info("Evicted session: %s", oldest)
+
+    @property
+    def active_count(self) -> int:
+        return len(self._sessions)

openstat/web/static/app.js

@@ -0,0 +1,117 @@
+// OpenStat Web Client
+(function() {
+    let ws = null;
+    let sessionId = null;
+    const output = document.getElementById('output');
+    const input = document.getElementById('command-input');
+    const status = document.getElementById('status');
+    const shapeInfo = document.getElementById('shape-info');
+    const plotContainer = document.getElementById('plot-container');
+    const plotImg = document.getElementById('plot-img');
+    const fileUpload = document.getElementById('file-upload');
+    const history = [];
+    let historyIdx = -1;
+
+    async function init() {
+        const resp = await fetch('/api/session', { method: 'POST' });
+        const data = await resp.json();
+        sessionId = data.session_id;
+        connectWS();
+    }
+
+    function connectWS() {
+        const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+        ws = new WebSocket(`${proto}//${location.host}/ws/${sessionId}`);
+
+        ws.onopen = () => {
+            status.textContent = 'Connected';
+            status.style.color = '#a6e3a1';
+            appendOutput('OpenStat v0.3.0 — Web Interface\nType help for commands.\n', 'result');
+        };
+
+        ws.onmessage = (event) => {
+            const msg = JSON.parse(event.data);
+            if (msg.content) {
+                appendOutput(msg.content + '\n', 'result');
+            }
+            if (msg.shape) {
+                shapeInfo.textContent = msg.shape;
+            }
+            if (msg.plot) {
+                plotImg.src = 'data:image/png;base64,' + msg.plot;
+                plotContainer.style.display = 'block';
+            }
+            if (msg.type === 'quit') {
+                status.textContent = 'Disconnected';
+                status.style.color = '#f38ba8';
+            }
+        };
+
+        ws.onclose = () => {
+            status.textContent = 'Disconnected';
+            status.style.color = '#f38ba8';
+        };
+    }
+
+    function appendOutput(text, cls) {
+        const span = document.createElement('span');
+        span.className = cls;
+        span.textContent = text;
+        output.appendChild(span);
+        output.scrollTop = output.scrollHeight;
+    }
+
+    input.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter') {
+            const cmd = input.value.trim();
+            if (!cmd) return;
+            history.push(cmd);
+            historyIdx = history.length;
+            appendOutput('openstat> ' + cmd + '\n', 'cmd');
+            if (ws && ws.readyState === WebSocket.OPEN) {
+                ws.send(cmd);
+            }
+            input.value = '';
+        } else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            if (historyIdx > 0) {
+                historyIdx--;
+                input.value = history[historyIdx];
+            }
+        } else if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            if (historyIdx < history.length - 1) {
+                historyIdx++;
+                input.value = history[historyIdx];
+            } else {
+                historyIdx = history.length;
+                input.value = '';
+            }
+        }
+    });
+
+    fileUpload.addEventListener('change', async (e) => {
+        const file = e.target.files[0];
+        if (!file) return;
+        const formData = new FormData();
+        formData.append('file', file);
+        try {
+            const resp = await fetch(`/api/upload/${sessionId}`, {
+                method: 'POST',
+                body: formData,
+            });
+            const data = await resp.json();
+            if (data.result) {
+                appendOutput(data.result + '\n', 'result');
+            }
+            if (data.shape) {
+                shapeInfo.textContent = data.shape;
+            }
+        } catch (err) {
+            appendOutput('Upload failed: ' + err + '\n', 'error');
+        }
+        fileUpload.value = '';
+    });
+
+    init();
+})();

openstat/web/static/index.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>OpenStat Web</title>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <header>
+        <h1>OpenStat <span class="version">v0.3.0</span></h1>
+        <span class="status" id="status">Connecting...</span>
+    </header>
+
+    <main>
+        <div id="output" class="output"></div>
+        <div id="plot-container" class="plot-container" style="display:none;">
+            <img id="plot-img" alt="Plot" />
+        </div>
+    </main>
+
+    <footer>
+        <div class="input-row">
+            <span class="prompt">openstat&gt;</span>
+            <input type="text" id="command-input" placeholder="Type a command..." autofocus />
+        </div>
+        <div class="toolbar">
+            <label class="upload-label">
+                Upload Data
+                <input type="file" id="file-upload" accept=".csv,.parquet,.dta,.xlsx,.sas7bdat,.sav" />
+            </label>
+            <span id="shape-info" class="shape-info">No data</span>
+        </div>
+    </footer>
+
+    <script src="/static/app.js"></script>
+</body>
+</html>