openstat-cli 1.0.0__py3-none-any.whl

openstat/commands/groupby_cmds.py

@@ -0,0 +1,155 @@
+"""Group-by aggregation and rolling window commands."""
+
+from __future__ import annotations
+
+from openstat.commands.base import command, CommandArgs, friendly_error
+from openstat.session import Session
+
+
+@command("groupby", usage="groupby <groupcol> [groupcol2 ...] agg <col>:<func> [...]")
+def cmd_groupby(session: Session, args: str) -> str:
+    """Group-by aggregation: compute statistics by group.
+
+    Aggregation functions: mean, sum, min, max, std, var, median,
+                           count, n, nunique, first, last
+
+    Examples:
+      groupby gender agg income:mean age:mean
+      groupby country year agg sales:sum profit:mean
+      groupby category agg price:min price:max price:mean count:n
+      groupby region agg value:median value:std
+
+    The result replaces the current dataset. Use 'undo' to restore.
+    """
+    import polars as pl
+
+    ca = CommandArgs(args)
+    # Split at 'agg' keyword
+    agg_raw = ca.rest_after("agg")
+    if not agg_raw:
+        return "Usage: groupby <col> [col2] agg <col>:<func> [col:func ...]"
+
+    # Everything before 'agg' is group columns
+    before_agg = args.split("agg", 1)[0].strip()
+    group_cols = before_agg.split()
+    if not group_cols:
+        return "Specify at least one group column."
+
+    # Parse agg specs: col:func or col:func=alias
+    agg_specs = agg_raw.strip().split()
+    FUNC_MAP = {
+        "mean": pl.Expr.mean,
+        "sum": pl.Expr.sum,
+        "min": pl.Expr.min,
+        "max": pl.Expr.max,
+        "std": pl.Expr.std,
+        "var": pl.Expr.var,
+        "median": pl.Expr.median,
+        "count": pl.Expr.count,
+        "n": pl.Expr.count,
+        "nunique": pl.Expr.n_unique,
+        "first": pl.Expr.first,
+        "last": pl.Expr.last,
+    }
+
+    try:
+        df = session.require_data()
+        for gc in group_cols:
+            if gc not in df.columns:
+                return f"Group column not found: {gc}"
+
+        exprs = []
+        for spec in agg_specs:
+            if ":" not in spec:
+                return f"Invalid agg spec '{spec}'. Use col:func format."
+            col, func = spec.split(":", 1)
+            alias = None
+            if "=" in func:
+                func, alias = func.split("=", 1)
+            func = func.lower()
+            if col not in df.columns and func not in ("n", "count"):
+                return f"Column not found: {col}"
+            if func not in FUNC_MAP:
+                avail = ", ".join(FUNC_MAP)
+                return f"Unknown function '{func}'. Available: {avail}"
+
+            expr_col = pl.col(col) if col in df.columns else pl.first()
+            expr = FUNC_MAP[func](expr_col)
+            out_name = alias or f"{col}_{func}"
+            exprs.append(expr.alias(out_name))
+
+        session.snapshot()
+        session.df = df.group_by(group_cols).agg(exprs).sort(group_cols)
+        return f"Group-by complete. Result: {session.shape_str}"
+
+    except Exception as e:
+        return friendly_error(e, "groupby")
+
+
+@command("rolling", usage="rolling <col> <window> <func> [into(<newcol>)]")
+def cmd_rolling(session: Session, args: str) -> str:
+    """Rolling window statistics on a column.
+
+    Functions: mean, sum, min, max, std, var, median
+
+    Options:
+      --center          — centered window (default: trailing)
+      --min_periods=N   — minimum observations required
+
+    Examples:
+      rolling price 7 mean into(price_7d_avg)
+      rolling sales 30 sum into(sales_30d)
+      rolling returns 20 std into(vol_20d) --center
+      rolling value 5 median
+    """
+    import polars as pl
+
+    ca = CommandArgs(args)
+    if len(ca.positional) < 3:
+        return "Usage: rolling <col> <window> <func> [into(<newcol>)]"
+
+    col = ca.positional[0]
+    try:
+        window = int(ca.positional[1])
+    except ValueError:
+        return f"Window must be an integer, got: {ca.positional[1]}"
+    func = ca.positional[2].lower()
+    center = "--center" in args
+    min_periods = int(ca.options.get("min_periods", 1))
+
+    into_raw = ca.rest_after("into")
+    newcol = into_raw.strip().strip("()") if into_raw else f"{col}_roll{window}_{func}"
+
+    FUNC_MAP = {
+        "mean": "mean",
+        "sum": "sum",
+        "min": "min",
+        "max": "max",
+        "std": "std",
+        "var": "var",
+        "median": "median",
+    }
+
+    try:
+        df = session.require_data()
+        if col not in df.columns:
+            return f"Column not found: {col}"
+        if func not in FUNC_MAP:
+            return f"Unknown function '{func}'. Available: {', '.join(FUNC_MAP)}"
+
+        roll_kwargs = dict(window_size=window, min_periods=min_periods, center=center)
+        roll = pl.col(col).rolling_mean(**roll_kwargs) if func == "mean" else \
+               pl.col(col).rolling_sum(**roll_kwargs) if func == "sum" else \
+               pl.col(col).rolling_min(**roll_kwargs) if func == "min" else \
+               pl.col(col).rolling_max(**roll_kwargs) if func == "max" else \
+               pl.col(col).rolling_std(**roll_kwargs) if func == "std" else \
+               pl.col(col).rolling_var(**roll_kwargs) if func == "var" else \
+               pl.col(col).rolling_median(**roll_kwargs)
+
+        session.snapshot()
+        session.df = df.with_columns(roll.alias(newcol))
+        n_valid = session.df[newcol].drop_nulls().len()
+        return f"Rolling {func}({window}) → '{newcol}': {n_valid}/{df.height} non-null values."
+
+    except Exception as e:
+        return friendly_error(e, "rolling")

openstat/commands/help_cmds.py

@@ -0,0 +1,237 @@
+"""Enhanced help command with examples and category browsing."""
+
+from __future__ import annotations
+
+from openstat.commands.base import command, get_registry, get_usage
+from openstat.session import Session
+
+# ── Command categories and examples ─────────────────────────────────────────
+
+_CATEGORIES: dict[str, list[str]] = {
+    "Data Management": [
+        "load", "save", "describe", "summarize", "drop", "keep", "rename",
+        "generate", "replace", "sort", "filter", "sample", "undo", "redo",
+        "append", "merge", "reshape", "encode", "decode", "validate",
+        "fuzzyjoin", "regex", "sql", "sqlload",
+    ],
+    "Descriptive Statistics": [
+        "tabulate", "correlate", "crosstab", "anova",
+    ],
+    "Regression Models": [
+        "ols", "logit", "probit", "poisson", "ivregress",
+        "quantreg", "truncreg", "intreg", "heckman",
+    ],
+    "Post-Estimation": [
+        "margins", "predict", "test", "posthoc", "mediate", "modmediate",
+        "estat", "esttab", "outreg2",
+    ],
+    "Panel / Time Series": [
+        "xtset", "xtreg", "xttest", "hausman",
+        "tsset", "arima", "ardl", "adf", "kpss", "forecast",
+        "vecm", "var", "granger", "threshold", "arch", "garch",
+    ],
+    "Survival Analysis": [
+        "stset", "stcox", "streg", "stsum",
+    ],
+    "Causal Inference": [
+        "pscore", "teffects", "did", "rddesign", "iptw",
+    ],
+    "Machine Learning": [
+        "mlfit", "randomforest", "gradientboost", "neuralnet", "svm", "knn",
+        "automodel", "cluster", "discriminant",
+    ],
+    "Factor / SEM": [
+        "factor", "pca", "sem", "cfa",
+    ],
+    "Epidemiology / Biostatistics": [
+        "epi", "irt",
+    ],
+    "Meta-analysis": [
+        "meta",
+    ],
+    "Network Analysis": [
+        "network",
+    ],
+    "Non-parametric": [
+        "kruskal", "mannwhitney", "wilcoxon", "friedman",
+    ],
+    "Resampling & Inference": [
+        "bootstrap", "jackknife", "permtest", "power",
+    ],
+    "Model Evaluation": [
+        "roc", "calibration", "confusion", "influence",
+    ],
+    "Plots": [
+        "plot hist", "plot scatter", "plot line", "plot box", "plot bar",
+        "plot heatmap", "plot coef", "plot margins", "plot interaction",
+        "plot diagnostics", "plot violin", "plot pairplot",
+    ],
+    "Export & Reporting": [
+        "export docx", "export pptx", "export pdf", "export md",
+        "log using", "report",
+    ],
+    "Session & Reproducibility": [
+        "session info", "session save", "session replay",
+        "set seed", "set backend", "version",
+    ],
+    "Scripting": [
+        "run", "watch", "import do", "define", "alias",
+    ],
+    "Settings & Integration": [
+        "theme", "locale", "dashboard", "ask", "r",
+        "config", "plugin",
+    ],
+}
+
+_EXAMPLES: dict[str, list[str]] = {
+    "load":        ["load data.csv", "load survey.dta", "load results.parquet"],
+    "save":        ["save cleaned.csv", "save output.parquet"],
+    "ols":         ["ols income educ age", "ols y x1 x2 x3 --robust"],
+    "logit":       ["logit employed age educ female", "logit y x1 x2 --margins"],
+    "margins":     ["margins educ", "margins age --at(educ=12)"],
+    "mediate":     ["mediate income educ age --boot=2000"],
+    "modmediate":  ["modmediate y mediator x moderator"],
+    "plot":        [
+        "plot hist income", "plot scatter y x", "plot coef",
+        "plot interaction y x moderator", "plot margins",
+    ],
+    "export":      ["export docx", "export pdf report.pdf", "export md summary.md"],
+    "validate":    ["validate age min=0 max=120 notnull", "validate email regex=^[^@]+@[^@]+"],
+    "fuzzyjoin":   ["fuzzyjoin companies.csv on(name) --threshold=85"],
+    "regex":       [
+        'regex extract email "([^@]+)@" into(username)',
+        'regex replace phone "[^0-9]" "" into(phone_clean)',
+    ],
+    "alias":       ["alias reg ols", "alias list", "alias rm reg"],
+    "theme":       ["theme dark", "theme solarized", "theme list"],
+    "ask":         ['ask "What variables have the most missing data?"'],
+    "watch":       ["watch analysis.ost", "watch pipeline.ost --interval=5"],
+    "import do":   ["import do stata_script.do", "import do analysis.do --run"],
+    "dashboard":   ["dashboard"],
+    "session":     ["session info", "session save analysis.ost", "session replay analysis.ost"],
+    "sem":         ["sem 'y1 =~ x1 + x2\ny2 =~ x3 + x4'"],
+    "meta":        ["meta es se --random --forest"],
+    "network":     ["network build from src to dst", "network centrality", "network plot"],
+    "automodel":   ["automodel y x1 x2 x3 x4 x5 --criterion=aic"],
+    "bootstrap":   ["bootstrap ols income educ age --reps=500"],
+    "power":       ["power ttest --delta=0.5 --alpha=0.05"],
+    "r":           ['r "summary(data)"', 'r "cor(data)"'],
+}
+
+
+@command("help", usage="help [<command>] [--list] [--category=<name>]")
+def cmd_help(session: Session, args: str) -> str:
+    """Show help for a command, list all commands, or browse by category.
+
+    Usage:
+      help                        — show command categories
+      help <command>              — detailed help with examples
+      help --list                 — alphabetical list of all commands
+      help --category=Plots       — list commands in a category
+      help --search=<keyword>     — search command names and descriptions
+
+    Examples:
+      help ols
+      help plot
+      help --list
+      help --category="Machine Learning"
+      help --search=regression
+    """
+    from openstat.commands.base import _REGISTRY
+
+    tokens = args.strip().split()
+
+    # --list flag
+    if "--list" in tokens:
+        cmds = sorted(_REGISTRY.keys())
+        lines = [f"All commands ({len(cmds)}):", "=" * 50]
+        for i, name in enumerate(cmds):
+            usage = get_usage(name)
+            short_desc = _REGISTRY[name].__doc__ or ""
+            short_desc = short_desc.strip().split("\n")[0][:60] if short_desc else ""
+            lines.append(f"  {name:<22} {short_desc}")
+        return "\n".join(lines)
+
+    # --search flag
+    search_term = None
+    for t in tokens:
+        if t.startswith("--search="):
+            search_term = t[9:].lower()
+    if search_term:
+        matches = []
+        for name, handler in sorted(_REGISTRY.items()):
+            doc = (handler.__doc__ or "").lower()
+            if search_term in name.lower() or search_term in doc:
+                short = (handler.__doc__ or "").strip().split("\n")[0][:60]
+                matches.append(f"  {name:<22} {short}")
+        if matches:
+            return f"Search results for '{search_term}':\n" + "\n".join(matches)
+        return f"No commands matching '{search_term}'."
+
+    # --category flag
+    for t in tokens:
+        if t.startswith("--category="):
+            cat = t[11:].strip('"\'')
+            # Case-insensitive match
+            matched_cat = next(
+                (k for k in _CATEGORIES if k.lower() == cat.lower()), None
+            )
+            if matched_cat is None:
+                cats = "\n".join(f"  {k}" for k in _CATEGORIES)
+                return f"Category '{cat}' not found. Available:\n{cats}"
+            cmds = _CATEGORIES[matched_cat]
+            lines = [f"Category: {matched_cat}", "-" * 40]
+            for name in cmds:
+                handler = _REGISTRY.get(name)
+                if handler:
+                    short = (handler.__doc__ or "").strip().split("\n")[0][:60]
+                    lines.append(f"  {name:<22} {short}")
+                else:
+                    lines.append(f"  {name:<22} (not loaded)")
+            return "\n".join(lines)
+
+    # Specific command help
+    cmd_name = " ".join(tokens).strip() if tokens else ""
+    if cmd_name and cmd_name in _REGISTRY:
+        handler = _REGISTRY[cmd_name]
+        usage = get_usage(cmd_name)
+        doc = (handler.__doc__ or "").strip()
+        examples = _EXAMPLES.get(cmd_name, [])
+
+        lines = [
+            f"Command: {cmd_name}",
+            "=" * 50,
+            f"Usage: {usage}",
+            "",
+        ]
+        if doc:
+            lines += [doc, ""]
+        if examples:
+            lines += ["Examples:"]
+            for ex in examples:
+                lines.append(f"  {ex}")
+        return "\n".join(lines)
+
+    # No args — show category overview
+    lines = [
+        "OpenStat Help — type 'help <command>' for details",
+        "=" * 55,
+        "Options: help --list | help --search=<kw> | help --category=<name>",
+        "",
+        "Command Categories:",
+        "-" * 55,
+    ]
+    for cat, cmds in _CATEGORIES.items():
+        available = [c for c in cmds if c in _REGISTRY]
+        if available:
+            lines.append(f"  {cat:<30} ({len(available)} commands)")
+    lines += [
+        "",
+        "Quick start:",
+        "  load data.csv",
+        "  describe",
+        "  ols outcome predictor1 predictor2",
+        "  plot coef",
+        "  export pdf",
+    ]
+    return "\n".join(lines)

openstat/commands/i18n_cmds.py

@@ -0,0 +1,43 @@
+"""i18n command: locale get|set <code>."""
+
+from __future__ import annotations
+
+from openstat.commands.base import command
+from openstat.session import Session
+
+
+@command("locale", usage="locale [get | set <code>]")
+def cmd_locale(session: Session, args: str) -> str:
+    """Get or set the display language.
+
+    Examples:
+      locale            — show current locale
+      locale get        — show current locale
+      locale set tr     — switch to Turkish
+      locale set en     — switch to English
+    """
+    from openstat.i18n import get_locale, set_locale, _STRINGS
+
+    tokens = args.strip().split()
+    subcmd = tokens[0].lower() if tokens else "get"
+
+    if subcmd in ("get", ""):
+        return f"Current locale: {get_locale()}"
+
+    elif subcmd == "set":
+        if len(tokens) < 2:
+            available = ", ".join(sorted(_STRINGS))
+            return f"Usage: locale set <code>   Available: {available}"
+        code = tokens[1].lower()
+        try:
+            set_locale(code)
+            return f"Locale set to: {code}"
+        except ValueError as exc:
+            return str(exc)
+
+    elif subcmd == "list":
+        available = ", ".join(sorted(_STRINGS))
+        return f"Available locales: {available}"
+
+    else:
+        return "Usage: locale [get | set <code> | list]"