OpenEconometrics

An open-source Python statistics library and local research workbench with a code editor, persistent Python session, data inspector, plots and MCP integration. Apache-2.0 licensed.

Python package remains openecon. Project website: openeconometrics.com.

Reviewed source snapshots and Mac alpha releases are distributed through bluearf/openeconometrics. Mac packages require Apple Silicon and macOS 15 or later. Read each release's checksum and signing status before installation. Developer ID signing and notarization are pending for the first alpha; neither Python package is published to PyPI. See PUBLIC-SOURCE.md and SOURCE-MANIFEST.json in the public snapshot for its precise source and external-fixture boundary.

Distribution preserves the third-party notices. See contribution guidelines and the private security-reporting process. Source availability and published installer access are verified separately from the license declaration.

Status: 0.3 alpha. OpenEconometrics implements a registered native estimator catalogue on one PyTorch float64 core; see the source-generated current scope for estimator, Dataset fitting and saved prediction coverage. OLS and weighted least squares include robust/cluster/HAC/resampling covariance and postestimation; dense OLS also supports CUDA. The interface is built around writing Python, inspecting results and continuing the same session. There is no numerical-engine selector. Full Stata coverage and numerical parity with Stata have not been established. The interface, Python API and CLI are in English.

The desktop edition packages the existing interface in a Rust/Tauri window with a bundled Python runtime. Code runs locally; cloud projects store drafts, data and shared results. See platform build instructions.

Start the workbench

Prerequisites: uv and Node.js 22.12+ (or 24 LTS). Python 3.13 is selected by this checkout; uv can provision it.

./scripts/start.sh

Open http://127.0.0.1:8765. The launcher installs locked dependencies, builds the interface and starts the local server. The initial installation needs internet access. Stop the server with Ctrl+C.

The equivalent manual steps are:

uv sync --frozen --extra app
npm --prefix web ci
npm --prefix web run build
uv run --extra app openecon serve --workspace .openecon

The Python console keeps variables between commands. Start with the bundled synthetic dataset:

import openecon as oe

df = oe.example()
model = oe.ols(data=df, y="wage", x=["education", "experience"], covariance="HC3")
print(model.summary())
oe.plot.coefficients(model)

Continue with a transformation and another plot:

df["experience_squared"] = df["experience"] ** 2
oe.plot.scatter(data=df, x="education", y="wage")

The console displays the last expression automatically. display(...) can show additional tables, models and OpenEconometrics plots. Charts use the separate openecon-charts Python package and the existing D3 visual family from the Dart-D3/Bluearf projects. Scatter, numeric line, histogram, coefficient intervals, grouped/horizontal bars, multi-series area, stacked bars and donut charts are available. Legends, tooltips, a data table, enlargement and SVG/PNG/JPEG/CSV exports share the same renderer. This is not general Matplotlib figure capture.

The editor autosaves its draft and can download that exact draft as a .py file. This is console source, not a self-contained analysis bundle: display() and automatic last-expression rendering are console conveniences, and imported dataset IDs belong to the current workspace. For a regular Python script, use print(model.summary()), explicit data paths, and chart.save_html("chart.html") for an independently viewable chart. “Dosyadan ekle” appends imported source to the current draft; it does not execute it.

The editor shows function signatures and documentation on hover or with F1. Call arguments show parameter help, and Ctrl+Space opens completion suggestions. Help covers the bundled OpenEconometrics API, common Python builtins and functions defined in the current script. It follows import aliases and conservatively identifies dataframes and model results. This assistance runs locally in the editor without executing Python. It is not a language server for every third-party package. See editor assistance for supported behavior and shortcuts.

Relative file paths in the console resolve inside the active workspace (.openecon by default). Imported datasets are available by ID through oe.load_dataset(...); use an absolute path to read a file elsewhere.

Console code runs with your local account's permissions. It can read and write files, access the network and import installed packages. The worker is a separate process, not a security sandbox. Run code you trust. A stop, timeout or session reset terminates the worker and clears its variables. Successful commands and ordinary Python errors leave the session alive; errors do not roll back assignments made before the error. Command history is saved, but in-memory variables do not survive a server restart.

Use the library

The library accepts pandas DataFrames, dictionaries of columns and lists of records. It is not tied to the included wage dataset.

import openecon as oe

rows = [
    {"output": 11.0, "hours": 2.0},
    {"output": 14.0, "hours": 3.0},
    {"output": 12.0, "hours": 4.0},
    {"output": 19.0, "hours": 5.0},
    {"output": 20.0, "hours": 6.0},
]
result = oe.ols(data=rows, y="output", x=["hours"], covariance="HC3")
print(result.summary())
print(result.model_dump_json(indent=2))

File loading and more explicit model specifications are also available:

data = oe.read("survey.csv")
result = oe.fit(
    oe.ModelSpec(
        estimator="ols", outcome="wage",
        predictors=["education", "experience", "region"],
        categorical=["region"], covariance="HC3", missing="raise",
    ),
    data=data,
)

oe.logit(...) and oe.probit(...) use the same data, y and x interface. Ordinary OLS and binary models default to classical covariance; sampling-weighted OLS defaults to HC1. Supplying cluster="firm_id" selects cluster covariance when covariance is omitted. ModelSpec applies the same defaults. Unsupported combinations fail explicitly. oe.capabilities() describes implemented methods. See the complete OLS API for formulas, weights and postestimation.

Library fits return result objects without automatically persisting them. oe.load_dataset(dataset_id) loads an imported dataset in the workbench's active workspace; imported IDs are visible in the dataset inspector. The console session, saved structured analyses and imported snapshots are separate records.

LaTeX results and exports

The results pane switches directly between Sonuç (rendered results) and LaTeX (source). Select all outputs or one table, model or chart, then copy or download the same complete .tex document. Tables and coefficients use a local, lazily loaded KaTeX preview; charts retain their interactive D3 view and export as self-contained TikZ/PGFPlots source.

df = oe.example()
df.head().to_latex()                         # Rendered table in the workbench
df.to_latex("data.tex", index=False)          # Export every row to a file
baseline = oe.ols(data=df, y="wage", x=["education"])
model = oe.ols(data=df, y="wage", x=["education", "experience"])
model.to_latex("model.tex")                   # Publication layout by default
oe.regression_table([baseline, model], "models.tex")
chart = oe.plot.coefficients(model)
chart.to_latex("chart.tex", standalone=True)

oe.read, oe.example and oe.load_dataset return an oe.DataFrame, which retains pandas operations and provides to_latex() and .latex. Wrap an existing pandas table with oe.DataFrame(table) or use oe.to_latex(table). Model results also expose .latex and summary(format="latex"); ordinary summary() remains text. oe.latex(value) converts tables, models and plain text; oe.Latex(source, math=...) displays explicit source with an optional math preview.

Publication defaults use booktabs rules without vertical grid lines. Regression coefficients sit above parenthesized standard errors; columns are numbered, constants come last and significance stars use the original p-values. Model notes report the actual covariance method, clustering, sample and inference. oe.regression_table compares fitted models with missing terms left blank. Long tables repeat their headers across pages. These are paper-style defaults, not an official NBER template. See publication tables.

Automatic exports include the displayed preview rows, with truncation recorded; df.to_latex(...) exports the full table. Source text safely escapes TeX special characters. Downloaded documents use XeLaTeX or LuaLaTeX with fontspec, tikz booktabs, adjustbox, array, longtable, placeins and pgfplots. Exports run without pandas' Jinja-based LaTeX renderer or a Python LaTeX installation. See LaTeX verification.

Network analysis

Build weighted, directed or undirected networks from edge tables. Large local CSV/Parquet edge lists are read in batches; graph storage remains sparse and must fit the explicit memory budget. Degrees, strengths, weak/strong components, weighted PageRank, shortest paths, Louvain/Leiden communities, modularity, betweenness/closeness/harmonic/eigenvector centrality, clustering, triangles and k-core use the full network. Expensive exact methods have explicit work budgets; sampled betweenness is an opt-in estimator.

graph = oe.network(data=edges, source="from", target="to", weight="weight",
                   directed=True)
display(graph.summary())
display(graph.pagerank())
communities = graph.communities(method="leiden", seed=42)
oe.plot.network(graph, groups=communities, title="Connections")

Interactive charts use Canvas and a worker for force layout. Large networks show a bounded subset with full and displayed counts; this does not change analytical results. PNG, SVG and CSV exports are available; LaTeX exports a compact summary table. See network analysis for semantics, memory limits and examples, including static GraphML/GEXF/Pajek import/export and scalar attributes. The implementation uses Torch sparse numerical buffers and bounded Python traversal; it does not depend on SciPy or NetworkX. CUDA PageRank is optional and has not been verified on physical CUDA hardware.

Independent chart package

oe.plot re-exports the independently installable package in packages/openecon-charts. It has no required Python dependencies and does not import PyTorch, pandas, NumPy or OpenEconometrics. It accepts column dictionaries, record lists and pandas-like tables through an adapter. D3 and Barlow assets are bundled; chart viewing needs no CDN or network request.

import openecon_charts as charts

chart = charts.area(
    data={"year": [2022, 2023, 2024, 2025],
          "A": [12, 18, 15, 26], "B": [8, 11, 16, 21]},
    x="year", y=["A", "B"], title="Illustrative series",
)
chart.save_html("chart.html")
# In the workbench: display(chart)

From this checkout, install just the chart package with pip install ./packages/openecon-charts. It has not been published to PyPI. The workspace launcher installs it alongside OpenEconometrics. For distributable wheels, build both using uv build --all-packages and install both wheels together.

Chart helpers never silently aggregate observations into categories. For example, compute df.groupby("region", observed=True, as_index=False)["wage"].mean() before passing it to oe.plot.bar(...). Missing values, display sampling and exclusions are preserved in the plot contract. Chart documentation covers supported inputs and limits; provenance records which existing renderers were adapted and the bundled licenses.

Implemented statistical methods

OLS generally uses Student-t inference; bootstrap uses normal inference. Multiway clusters use intersection-specific CR1 corrections and the minimum marginal cluster degrees of freedom; optional HC2/HC3 corrections provide contrast-specific inference. OLS treatment coding omits the first level with an intercept and keeps all levels without one; collinear terms are omitted deterministically. Binary category/rank rules remain unchanged. Pandas category order is respected; other levels are sorted. See OLS methods and boundaries.

The estimator, covariance, inference, likelihood and separation safeguards belong to OpenEconometrics. PyTorch supplies tensor and linear-algebra primitives; pandas provides tables and file interoperability. SciPy is not a runtime dependency: the separation LP uses a native float64 primal-dual solver with independently checked certificates. NumPy remains a transitive table dependency, with no NumPy estimator backend. Statsmodels and SciPy are development-only numerical references. See the numerical design.

Files, CLI and agents

Import CSV, Parquet, XLSX or Stata DTA files through the workbench or CLI:

uv run --extra cli openecon inspect survey.csv
uv run --extra cli openecon import survey.csv --workspace .openecon
uv run --extra cli openecon fit survey.csv -y wage -x education -x experience --covariance HC3
uv run --extra cli openecon fit survey.csv -y employed -x education --estimator logit
uv run --extra cli openecon --help

The imported original file and canonical Parquet snapshot remain in the local workspace. CLI fit returns JSON without adding a saved workspace analysis. Workspace API and MCP analyses persist immutable result records. Generated Python/ZIP exports refer to the recorded dataset and model; a portable ZIP includes the data. Recorded hashes bind category semantics and metadata as well as rows. Older results retain their original provenance; the current API does not promise replay compatibility with obsolete model specifications.

MCP exposes structured dataset inspection and model-fitting tools to Codex, Claude or other MCP clients. It does not expose the console's arbitrary Python execution. Raw row previews require an explicit option; summaries and coefficient labels can still contain sensitive information and may be forwarded by a client to its AI provider. No AI account is needed for the workbench itself. See CLI and agent integration.

Current limits

The Cloud Run team edition provides Google sign-in and verified email/password accounts, persistent projects, email-bound invitations and owner/editor/viewer roles. Firestore and private Cloud Storage retain drafts, data and results. Production executes each complete Python script in a fresh sandbox through a private Cloud Run compute service; the authenticated API never executes user code. Variables do not persist between runs. The managed runtime proof, all 13 broker integration cases and complete five-user preview and production suites passed. The initial sandbox rollout completed its production OLS, D3, input and durable-output check in 11.9 seconds; the LaTeX update passed native dataframe/model/chart exports and shared CSV/TeX downloads in 12.4 seconds; the publication-table release then passed the complete suite with multi-model exports in 13.0 seconds. Startup verification records the deployment and distinguishes analysis timings from browser opening and cold starts. Previously accepted Job runs retain status/cancellation support. Concurrent draft writes are version-checked; simultaneous collaborative text editing and remote MCP are not included. The earlier single-owner IAP edition remains a separate legacy deployment mode.

• Large local CSV/Parquet imports automatically use a projected, replayable Dataset. The 32 MiB/100,000-row thresholds choose the bounded reader; they do not reject those formats. Large desktop data stays local. Cloud project uploads retain their 24 MiB limit; eager XLSX/DTA have separate format limits. Native model adapters process complete samples through bounded passes and owned temporary storage, with model-specific option conditions in oe.capabilities(). See large local datasets for algorithms, resource budgets and measured physical workloads.
• Statistical estimates and inference use native PyTorch float64. Supported factor operations can use CUDA float64 or checked Mac Metal preconditioning with original CPU float64 refinement; likelihood/state recursions and disk operations remain CPU. Actual execution devices and fallbacks are recorded. CUDA hardware throughput has not been validated.
• Local console commands have no automatic execution deadline; explicit deadlines and Stop remain available. Output, table previews and history are bounded. Stop/timeout resets the local session; it has no rollback, hard memory quota or OS security sandbox. Cloud computation retains its previous deadlines and independent sandbox limits.
• Workspace fits and MCP run_analysis are synchronous and serialized within each process. MCP also offers bounded background jobs with status, cancellation and durable retry IDs; one background job runs per workspace. See the job contract. These jobs are separate from the console's worker.
• The current catalogue includes weights, absorbed fixed effects, IV/GMM, panel models, time series, survival models and supported postestimation. Complex surveys, imputation, SEM, Stata command execution and do-file translation remain separate work; model coverage does not imply complete Stata parity.
• XLSX reads the first worksheet's stored values. CSV expects UTF-8 and comma separators. DTA labels and tagged missing codes are retained as metadata; this is not a full Stata round trip or DTA export.
• The local HTTP server is for one trusted local user and only accepts loopback binding. Cloud teams use a separate authenticated control API with live membership checks and isolated execution. Do not expose the local console or broaden the legacy IAP mode as a substitute for this team architecture.

Development and evidence

uv sync --frozen --extra cloud --extra desktop
uv run --no-sync ruff check src tests scripts packages/openecon-charts
npm --prefix web ci
npm --prefix web test
npm --prefix web run build
uv run --no-sync python -m pytest
uv build --all-packages

GitHub verification and Windows packaging use workflow_dispatch only. Pushes and pull-request updates do not start Actions runs while the account's billing restriction blocks runners. Manual Actions runs also require that restriction to be resolved; the local checks above remain available.

For interface development, run uv run --extra app openecon serve and npm --prefix web run dev separately. Vite proxies /api and /chart-assets to port 8765. Build the interface before packaging; the OpenEconometrics wheel includes generated interface assets and the frozen synthetic fixture. The chart wheel contains the single shared D3 renderer and its local assets.

Tests cover independent statistical references, data integrity and metadata, Python/CLI/MCP behavior, local API access, console persistence/interruption and plot validation. Test results do not establish universal numerical correctness or Stata parity. Architecture notes describe the execution boundaries. Performance records are historical 0.2 measurements of the former dual-engine implementation; they do not measure the current single-core workbench.

License

OpenEconometrics code is licensed under Apache-2.0. Dependencies retain their licenses; datasets remain subject to their own permissions and licenses.

Library-only users can install openecon without the web/CLI/MCP layers. See distribution extras and measured dependencies.