opendta-pyodide 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 NakliTechie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+opendta.json contains the modules of OpenDTA, Copyright (c) 2026 OpenDTA
+contributors, under the MIT licence in LICENSE-OpenDTA.

package/LICENSE-OpenDTA

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 OpenDTA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Trademark Notice
+
+Stata is a registered trademark of StataCorp LLC. OpenDTA is an independent
+project and is not affiliated with, endorsed by, or sponsored by StataCorp LLC.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+<h1 align="center">opendta-pyodide</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><b>Run Stata 14 commands, graphs and Mata in the browser or Node.<br>
+OpenDTA's open-source engine, packaged for Pyodide, with a bridge to your own data.</b></p>
+
+<p align="center">Pyodide 0.27, NumPy and SciPy (matplotlib for graphs). No server. MIT.</p>
+
+<p align="center">
+<img alt="npm" src="https://img.shields.io/npm/v/opendta-pyodide?style=flat-square&color=555">
+<img alt="licence MIT" src="https://img.shields.io/badge/licence-MIT-555?style=flat-square">
+<img alt="runtime Pyodide 0.27" src="https://img.shields.io/badge/runtime-Pyodide%200.27-555?style=flat-square">
+</p>
+
+## Install
+
+| Where | How |
+|---|---|
+| npm | `npm install opendta-pyodide pyodide@0.27.7` |
+| CDN | `import { createSession } from 'https://cdn.jsdelivr.net/npm/opendta-pyodide@0.2.3/index.mjs'` |
+| GitHub tag | `https://cdn.jsdelivr.net/gh/NakliTechie/opendta-pyodide@v0.2.3/index.mjs` |
+
+```js
+import { loadPyodide } from 'pyodide';
+import { createSession } from 'opendta-pyodide';
+
+const stata = await createSession(await loadPyodide());       // loads numpy and scipy once
+await stata.stata('set obs 100\ngen x = runiform()\ngen y = 2*x + rnormal()');
+const out = await stata.stata('regress y x\nmargins, dydx(x)');
+console.log(out.log);          // the log as Stata 14 prints it
+const g = await stata.stata('scatter y x');
+document.body.innerHTML = g.graphs[0];                         // each graph as SVG text
+const m = await stata.mata('A = (4,2\\2,3)\ncholesky(A)');    // Mata, in the same package
+```
+
+`createSession` fetches `opendta.json` (4.9 MB, 0.9 MB with brotli) and
+`opendta_bridge.py` from beside `index.mjs`. A command that draws loads matplotlib first.
+
+## Why
+
+You have Stata do-files and want them to run where your users are, in a web page or a
+Node script, without a Stata licence. [OpenDTA](https://github.com/yaskepalhares/opendta)
+is an MIT Python reimplementation of Stata 14: data management, estimation and
+post-estimation, programs and `syntax`, graphs drawn with matplotlib, and a Mata
+interpreter. This package ships its engine (287 modules, without the desktop interface),
+and a bridge so the engine reads and writes a dataset that your own code owns.
+
+How close OpenDTA is to Stata is OpenDTA's claim, checked by its 108 Stata 14 reference
+logs. NakliData, a browser data workbench, runs 9 of them (the Mata files) through this
+bridge: 7 print logs equal to Stata 14's, and the other 2 differ where OpenDTA lists known
+differences.
+
+## Give the engine your data
+
+`runRequest` takes the dataset as columns, plus macros and scalars, runs Stata command
+lines, and returns what changed:
+
+```js
+import { runRequest } from 'opendta-pyodide';
+
+const out = await runRequest(pyodide, {
+  kind: 'command',
+  nobs: 4,
+  vars: [['x', 'num', 'DOUBLE']],
+  columns: [new Float64Array([4, 1, 3, NaN])],   // NaN is Stata's missing value
+  code: 'xtile q = x, nq(2)',
+});
+out.data.columns;   // only the new or changed variables: [{ name: 'q', values: [2, 1, 2, null] }]
+```
+
+The response holds `log`, `error` (`{ code, message }` with Stata's return code), the
+changed `data`, `locals`, `globals`, `scalars`, `r`, `e`, `ematrix` (e(b) and e(V)),
+`graphs` and the random-number state. Pass `rng` back so `runiform()` continues Stata 14's
+stream. Use `kind: 'block'` for Mata and `kind: 'matrix'` for a `matrix` command (without
+the word `matrix`).
+
+## Call back into your host
+
+From Mata, `stata("...")` calls your `stata: async (stateJson) => reply`, and expressions
+in `matrix` commands call `evaluate`. Both wait on your async code through Pyodide's
+`run_sync`, which needs WebAssembly stack switching (JSPI): on by default in current
+Chrome, and behind `--experimental-wasm-jspi` in Node 22. Without JSPI the call stops with
+Stata error 3000 and says why. The formats are in `index.d.ts`.
+
+## Commands
+
+```sh
+npm test                                     # 15 tests in Node: commands, data, e(b), graphs, Mata
+python3 -I scripts/bundle-opendta.py <opendta checkout>   # rebuild opendta.json at the pin
+```
+
+## Verify it yourself
+
+```sh
+npm ci && npm test
+```
+
+The tests run in Pyodide 0.27.7. They check `tabstat` output, a host dataset round trip
+through `xtile` that returns only the new variable, `poisson` results in `e()` and e(b),
+error 199 for an unknown command, a `scatter` drawn as SVG, and the Mata path: printed
+matrices, a singular matrix, Stata 14's first `runiform()` draw for seed 123, a `stata()`
+callback and a `matrix` command. The bundle pins OpenDTA commit `29a3b28`. Pyodide's
+NumPy returns NaN from `cholesky`, `inv` and `solve` instead of raising, because
+WebAssembly has no floating-point flags; the bridge restores the `LinAlgError` that
+OpenDTA expects.
+
+## Licence
+
+MIT. OpenDTA is Copyright (c) 2026 OpenDTA contributors, MIT (`LICENSE-OpenDTA`).
+
+[OpenDTA](https://github.com/yaskepalhares/opendta) · [bridge](opendta_bridge.py) · [types](index.d.ts)

package/index.d.ts

@@ -0,0 +1,119 @@
+// Types for opendta-pyodide.
+
+/** The slice of the Pyodide API this package uses (Pyodide 0.27). */
+export interface PyodideLike {
+  runPython(code: string): unknown;
+  runPythonAsync(code: string): Promise<unknown>;
+  loadPackage(names: string[]): Promise<unknown>;
+  globals: { set(name: string, value: unknown): void; delete(name: string): void };
+  FS: { mkdirTree(path: string): void; writeFile(path: string, data: string): void };
+}
+
+type Value = number | string | null;
+
+
+/** What the host holds, as Mata reads it. Every field is optional in a request. */
+export interface HostState {
+  nobs: number;
+  /** [name, 'num' | 'str' | 'date', SQL type] per variable, in dataset order. The SQL type sets
+   *  Stata's storage type: TINYINT byte, SMALLINT int, INTEGER long, FLOAT float, else double. */
+  vars: Array<[string, 'num' | 'str' | 'date', string]>;
+  /** Float64Array (NaN = missing; dates as days since 1960-01-01) or strings. */
+  columns: Array<Float64Array | string[]>;
+  locals: Record<string, string>;
+  globals: Record<string, string>;
+  scalars: Record<string, Value>;
+  r: Record<string, Value>;
+  e: Record<string, Value>;
+  /** Stata 14's random-number state ("X" + hex), as returned in a response's `rng`. Empty for a fresh seed. */
+  rng: string;
+  /** e(b) and e(V) of the last estimation, for `matrix list e(b)` and st_matrix("e(b)"). */
+  ematrix: { names: string[]; b: number[]; V: number[][] } | null;
+}
+
+/**
+ * Reply to a `stata()` call from Mata: the host's full state after the command
+ * (every HostState field except columns, plus `log: string[]` and
+ * `error: {code, message} | null`) as JSON, and the columns separately.
+ */
+export interface StataReply {
+  json: string;
+  columns: Array<Float64Array | string[]>;
+}
+
+export interface OpenDTARequest extends Partial<HostState> {
+  /** Stata command lines, a `mata` block, a `mata:` line, or a Stata `matrix` command. */
+  kind?: 'command' | 'block' | 'line' | 'matrix';
+  /** For `command`: echo each line as `. cmd` in the log, as a do-file does. Default false. */
+  echo?: boolean;
+  /** For `command`: ignore the host fields and keep OpenDTA's own dataset and results. */
+  keepData?: boolean;
+  /** Block body (the lines between `mata` and `end`), one statement, or a matrix command without the word `matrix`. */
+  code: string;
+  /** `mata:` stops at the first error; `mata` reports it and carries on. Default false. */
+  colon?: boolean;
+  /** Start a fresh Mata session (functions and globals cleared). Default false. */
+  reset?: boolean;
+  /** `set linesize`: Mata wraps matrices and rules at this width. Default 80. */
+  linesize?: number;
+  /** Runs `stata("cmd")`: receives Mata's changes as JSON (StateChanges plus `cmd`). Needs JSPI. */
+  stata?: (stateJson: string) => Promise<StataReply>;
+  /** Evaluates a Stata scalar expression for `matrix`; returns JSON `{"value": number | string | null}` or `{"error": {code, message}}`. Needs JSPI. */
+  evaluate?: (expr: string) => Promise<string>;
+}
+
+export interface HostColumn {
+  name: string;
+  kind: 'num' | 'str' | 'date';
+  integer?: boolean;
+  values: Value[];
+}
+
+/** What Mata changed. `data` is null when the dataset is unchanged. */
+export interface StateChanges {
+  data: { full: boolean; nobs: number; order: string[]; columns: HostColumn[] } | null;
+  locals: Record<string, string>;
+  globals: Record<string, string>;
+  scalars: Record<string, Value>;
+  /** null when Mata left r() / e() unchanged. */
+  r: Record<string, Value> | null;
+  e: Record<string, Value> | null;
+  rng: string;
+}
+
+export interface OpenDTAResponse extends StateChanges {
+  log: string;
+  error: { code: number; message: string } | null;
+  /** For `command`: e(b) and e(V) after an estimation, else null. */
+  ematrix?: { names: string[]; b: number[]; V: number[][] } | null;
+  /** For `command`: each graph drawn, as SVG text. */
+  graphs?: string[];
+}
+
+/** The parsed opendta.json. */
+export interface OpenDTABundle {
+  source: string;
+  commit: string;
+  licence: string;
+  patched: string[];
+  files: Record<string, string>;
+}
+
+export interface InstallOptions {
+  /** URL of opendta.json (relative to this module), or the parsed bundle. */
+  bundle?: string | URL | OpenDTABundle;
+  /** URL of opendta_bridge.py (relative to this module). */
+  bridge?: string | URL;
+}
+
+export function installOpenDTA(pyodide: PyodideLike, options?: InstallOptions): Promise<{ source: string; commit: string }>;
+export function runRequest(pyodide: PyodideLike, request: OpenDTARequest): Promise<OpenDTAResponse>;
+export function drawsGraph(code: string): boolean;
+export function createSession(
+  pyodide: PyodideLike,
+  options?: InstallOptions,
+): Promise<{
+  stata(code: string, request?: OpenDTARequest): Promise<OpenDTAResponse>;
+  mata(code: string, request?: OpenDTARequest): Promise<OpenDTAResponse>;
+  reset(): void;
+}>;

package/index.mjs

@@ -0,0 +1,136 @@
+// opendta-pyodide: run Stata 14 commands and Mata in the browser or Node, on
+// Pyodide. The engine is OpenDTA (https://github.com/yaskepalhares/opendta,
+// MIT), bundled in opendta.json; opendta_bridge.py connects it to a host that
+// owns the dataset, macros and scalars.
+
+const ROOT = '/opendta_pyodide';
+const installed = new WeakMap();
+const withGraphs = new WeakSet();
+
+// Commands that draw: their first word, as Stata accepts it (abbreviations included).
+const GRAPH = /^\s*(?:(?:quietly|qui|noisily|noi|capture|cap)\s+)*(?:gr(?:a(?:ph?)?)?|tw(?:o(?:w(?:ay?)?)?)?|sc(?:a(?:t(?:t(?:er?)?)?)?)?|line|connected|area|bar|hist(?:o(?:g(?:r(?:am?)?)?)?)?|kdensity|kdens|qnorm|pnorm|qqplot|lowess|binscatter|marginsplot|coefplot|rvfplot|avplots?|lvr2plot|graph\s+\w+)\b/m;
+
+async function text(source, fallback) {
+  const u = new URL(source ?? fallback, import.meta.url);
+  if (u.protocol === 'file:') {
+    const { readFile } = await import('node:fs/promises');
+    return readFile(u, 'utf8');
+  }
+  const res = await fetch(u);
+  if (!res.ok) throw new Error(`opendta-pyodide: could not fetch ${u.href} (HTTP ${res.status})`);
+  return res.text();
+}
+
+/**
+ * Install OpenDTA into a Pyodide instance: loads numpy and scipy, writes the
+ * OpenDTA modules and the bridge into Pyodide's file system, and imports the
+ * bridge. `bundle` and `bridge` are URLs (relative to this module) of
+ * opendta.json and opendta_bridge.py, defaulting to the copies next to this
+ * module; `bundle` may also be the parsed bundle object.
+ */
+export async function installOpenDTA(pyodide, { bundle, bridge } = {}) {
+  if (installed.has(pyodide)) return installed.get(pyodide);
+  const job = (async () => {
+    const b = bundle?.files ? bundle : JSON.parse(await text(bundle, './opendta.json'));
+    const py = await text(bridge, './opendta_bridge.py');
+    await pyodide.loadPackage(['numpy', 'scipy']);
+    for (const [path, body] of Object.entries(b.files)) {
+      pyodide.FS.mkdirTree(`${ROOT}/${path}`.replace(/\/[^/]+$/, ''));
+      pyodide.FS.writeFile(`${ROOT}/${path}`, body);
+    }
+    pyodide.FS.mkdirTree(ROOT);
+    pyodide.FS.writeFile(`${ROOT}/opendta_bridge.py`, py);
+    pyodide.runPython(
+      `import sys\nif ${JSON.stringify(ROOT)} not in sys.path: sys.path.insert(0, ${JSON.stringify(ROOT)})\nimport opendta_bridge`,
+    );
+    return { source: b.source, commit: b.commit };
+  })();
+  installed.set(pyodide, job);
+  job.catch(() => installed.delete(pyodide));
+  return job;
+}
+
+const DEFAULTS = {
+  kind: 'block',
+  colon: false,
+  reset: false,
+  echo: false,
+  linesize: 80,
+  nobs: 0,
+  vars: [],
+  columns: [],
+  locals: {},
+  globals: {},
+  scalars: {},
+  r: {},
+  e: {},
+  rng: '',
+  ematrix: null,
+};
+
+/** True when Stata command text draws a graph (so matplotlib must be loaded first). */
+export function drawsGraph(code) {
+  return GRAPH.test(code);
+}
+
+/**
+ * Run one request: Stata command lines (`kind: 'command'`), a Mata block, one
+ * `mata:` line, or a Stata `matrix` command. Returns the log, any error, what
+ * the code changed, and (for commands) the graphs drawn, as SVG text.
+ */
+export async function runRequest(pyodide, request) {
+  await installOpenDTA(pyodide);
+  const { columns, stata, evaluate, ...meta } = { ...DEFAULTS, ...request };
+  if (meta.kind === 'command' && !withGraphs.has(pyodide) && drawsGraph(meta.code)) {
+    await pyodide.loadPackage(['matplotlib']);
+    withGraphs.add(pyodide);
+  }
+  const g = pyodide.globals;
+  g.set('__od_meta', JSON.stringify(meta));
+  g.set('__od_cols', columns);
+  g.set('__od_host', stata ?? null);
+  g.set('__od_eval', evaluate ?? null);
+  try {
+    // runPythonAsync lets stata() and matrix expressions wait on the host through
+    // Pyodide's run_sync, which needs WebAssembly stack switching (JSPI).
+    const out = await pyodide.runPythonAsync(
+      'opendta_bridge.run_json(__od_meta, __od_cols, __od_host, __od_eval)',
+    );
+    return JSON.parse(out);
+  } finally {
+    for (const k of ['__od_meta', '__od_cols', '__od_host', '__od_eval']) g.delete(k);
+  }
+}
+
+/**
+ * A session with no host dataset: `stata(lines)` runs Stata commands on
+ * OpenDTA's own dataset, which persists between calls; `mata(code)` runs a
+ * Mata block. Matrices are shared between the two. `reset()` starts both over.
+ */
+export async function createSession(pyodide, options) {
+  await installOpenDTA(pyodide, options);
+  // One reset for both: commands and Mata share matrices, so neither may clear the other.
+  let fresh = true;
+  return {
+    async stata(code, request = {}) {
+      const out = await runRequest(pyodide, {
+        echo: true,
+        ...request,
+        kind: 'command',
+        code,
+        reset: fresh,
+        keepData: true,
+      });
+      fresh = false;
+      return out;
+    },
+    async mata(code, request = {}) {
+      const out = await runRequest(pyodide, { ...request, kind: 'block', code, reset: fresh });
+      fresh = false;
+      return out;
+    },
+    reset() {
+      fresh = true;
+    },
+  };
+}