econenv 0.1.0__tar.gz

econenv-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.ipynb_checkpoints/
+.coverage
+htmlcov/
+*.Rhistory
+.RData
+*.wf1
+*.wf1~
+*.dta
+*.log
+*.smcl
+econenv-snapshot.json
+.econenv/

econenv-0.1.0/CITATION.cff

@@ -0,0 +1,41 @@
+cff-version: 1.2.0
+title: "EconEnv: Python, R, Stata and EViews in one reproducible Jupyter workflow"
+message: "If you use EconEnv in your research, please cite it as below."
+type: software
+authors:
+  - family-names: Roudane
+    given-names: Merwan
+    email: merwanroudane920@gmail.com
+    orcid: ""
+repository-code: "https://github.com/merwanroudane/econenv"
+url: "https://github.com/merwanroudane/econenv"
+abstract: >-
+  EconEnv is an IPython extension that lets a researcher run Python, R, Stata
+  and EViews inside a single Jupyter notebook on one Python kernel. It provides
+  persistent engine sessions, a unified pandas-based data bridge that preserves
+  econometric metadata, standardised execution and model result objects,
+  installation diagnostics, environment snapshots for reproducibility, and a
+  cross-engine model comparison framework that reports where the programs
+  genuinely disagree rather than hiding the difference.
+keywords:
+  - econometrics
+  - reproducible research
+  - jupyter
+  - stata
+  - eviews
+  - r
+  - polyglot notebook
+license: MIT
+version: 0.1.0
+date-released: "2026-09-04"
+# A DOI will be added here on the first archived release (Zenodo).
+# doi: 10.5281/zenodo.XXXXXXX
+preferred-citation:
+  type: software
+  title: "EconEnv: Python, R, Stata and EViews in one reproducible Jupyter workflow"
+  authors:
+    - family-names: Roudane
+      given-names: Merwan
+  year: 2026
+  version: 0.1.0
+  url: "https://github.com/merwanroudane/econenv"

econenv-0.1.0/LICENSE

@@ -0,0 +1,51 @@
+MIT License
+
+Copyright (c) 2026 Merwan Roudane
+
+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.
+
+---------------------------------------------------------------------------
+THIRD-PARTY SOFTWARE
+---------------------------------------------------------------------------
+
+The MIT licence above covers the EconEnv source code only. It grants no rights
+whatsoever in the third-party programs EconEnv can talk to.
+
+EconEnv contains, bundles and redistributes NO part of:
+
+  * Stata      (c) StataCorp LLC       - https://www.stata.com
+  * EViews     (c) IHS Global Inc.     - https://www.eviews.com
+  * R          (c) The R Foundation    - GPL-2 / GPL-3
+
+No binaries, no libraries, no licence files, no serial numbers, no activation
+keys. EconEnv locates software that is already installed on the user's own
+machine and drives it through each vendor's documented automation interface
+(PyStata for Stata, COM for EViews, the R console or rpy2 for R).
+
+Users are solely responsible for obtaining, installing and licensing Stata and
+EViews, and for complying with those licences - including any restriction on
+concurrent sessions, server deployment or automated use. Nothing in this
+licence modifies, waives or supersedes the terms of the Stata, EViews or R
+licences.
+
+R is free software distributed under the GNU General Public Licence. EconEnv's
+default R backend runs R as a separate process over its documented command-line
+interface and does not link against R, so EconEnv is not a derivative work of
+R. The optional rpy2 backend is a separate package, installed by the user, and
+is governed by rpy2's own licence.

econenv-0.1.0/PKG-INFO

@@ -0,0 +1,488 @@
+Metadata-Version: 2.5
+Name: econenv
+Version: 0.1.0
+Summary: One Notebook. Multiple Econometric Engines. Python, R, Stata and EViews in a single Jupyter session.
+Project-URL: Homepage, https://github.com/merwanroudane/econenv
+Project-URL: Repository, https://github.com/merwanroudane/econenv
+Project-URL: Issues, https://github.com/merwanroudane/econenv/issues
+Project-URL: Documentation, https://github.com/merwanroudane/econenv/tree/main/docs
+Author-email: Merwan Roudane <merwanroudane920@gmail.com>
+Maintainer-email: Merwan Roudane <merwanroudane920@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Merwan Roudane
+        
+        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.
+        
+        ---------------------------------------------------------------------------
+        THIRD-PARTY SOFTWARE
+        ---------------------------------------------------------------------------
+        
+        The MIT licence above covers the EconEnv source code only. It grants no rights
+        whatsoever in the third-party programs EconEnv can talk to.
+        
+        EconEnv contains, bundles and redistributes NO part of:
+        
+          * Stata      (c) StataCorp LLC       - https://www.stata.com
+          * EViews     (c) IHS Global Inc.     - https://www.eviews.com
+          * R          (c) The R Foundation    - GPL-2 / GPL-3
+        
+        No binaries, no libraries, no licence files, no serial numbers, no activation
+        keys. EconEnv locates software that is already installed on the user's own
+        machine and drives it through each vendor's documented automation interface
+        (PyStata for Stata, COM for EViews, the R console or rpy2 for R).
+        
+        Users are solely responsible for obtaining, installing and licensing Stata and
+        EViews, and for complying with those licences - including any restriction on
+        concurrent sessions, server deployment or automated use. Nothing in this
+        licence modifies, waives or supersedes the terms of the Stata, EViews or R
+        licences.
+        
+        R is free software distributed under the GNU General Public Licence. EconEnv's
+        default R backend runs R as a separate process over its documented command-line
+        interface and does not link against R, so EconEnv is not a derivative work of
+        R. The optional rpy2 backend is a separate package, installed by the user, and
+        is governed by rpy2's own licence.
+License-File: LICENSE
+Keywords: econometrics,eviews,ipython,jupyter,polyglot,r,reproducibility,stata
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: R
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: ipython>=8.0
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.5
+Requires-Dist: statsmodels>=0.13
+Provides-Extra: all
+Requires-Dist: comtypes>=1.2; (platform_system == 'Windows') and extra == 'all'
+Requires-Dist: pyarrow>=12; extra == 'all'
+Requires-Dist: rpy2>=3.5; (platform_system != 'Windows') and extra == 'all'
+Requires-Dist: stata-setup>=0.1.3; extra == 'all'
+Provides-Extra: arrow
+Requires-Dist: pyarrow>=12; extra == 'arrow'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pandas-stubs; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-setuptools; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Provides-Extra: eviews
+Requires-Dist: comtypes>=1.2; (platform_system == 'Windows') and extra == 'eviews'
+Provides-Extra: r
+Requires-Dist: rpy2>=3.5; (platform_system != 'Windows') and extra == 'r'
+Provides-Extra: stata
+Requires-Dist: stata-setup>=0.1.3; extra == 'stata'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# EconEnv
+
+**One Notebook. Multiple Econometric Engines.**
+
+Python, R, Stata and EViews in a single Jupyter workflow — on one Python kernel.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#project-status)
+
+</div>
+
+---
+
+## The problem
+
+An applied econometrics paper rarely lives in one program. The unit-root test is
+in EViews because that is where the ARDL bounds output is readable. The panel
+estimator is in Stata because `xtreg` is the reference implementation. The plots
+are in R because `ggplot2` is better. The data cleaning is in Python because
+pandas is better.
+
+So the working day looks like this:
+
+```
+Python  →  to_csv()  →  Stata  →  export delimited  →  R  →  write.csv  →  EViews
+```
+
+Four programs open. Four windows. Four copies of the same data, drifting apart.
+A missing value that meant `.a` in Stata arriving as an empty cell in R. A
+quarterly index that became a string. And when a referee asks "why does your
+robust standard error differ from mine?", there is no way to answer without
+redoing the whole chain by hand.
+
+## The solution
+
+EconEnv makes the four programs **execution engines behind one Python kernel**.
+
+```python
+%load_ext econenv
+
+df = pd.read_csv("data.csv")          # Python, as usual
+```
+
+```python
+%%R -i df
+fit <- lm(y ~ x1 + x2, data = df)
+summary(fit)
+```
+
+```python
+%%stata
+regress y x1 x2
+```
+
+```python
+%%eviews -i df
+equation eq1.ls y c x1 x2
+```
+
+One notebook. One kernel. One dataset. No CSV round-trip.
+
+And then the part that is hard to do any other way:
+
+```python
+econenv.compare_ols(df, "y ~ x1 + x2")
+```
+
+```
+OLS: y ~ x1 + x2
+Engines agree within tolerance (rtol=1e-08, atol=1e-10)
+
+Coefficients
+          python           r       stata      eviews
+term
+x1     0.4821094   0.4821094   0.4821094   0.4821094
+x2    -0.1330277  -0.1330277  -0.1330277  -0.1330277
+_cons  1.9042118   1.9042118   1.9042118   1.9042118
+
+Notes:
+  - aic: AIC normalisation differs: statsmodels -2ll+2k; R counts sigma^2 as a
+    parameter (k+1); EViews divides by n; Stata needs `estat ic`.
+```
+
+The coefficients match. The information criteria do not — and EconEnv says
+**why**, instead of quietly picking one.
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    A[JupyterLab / Notebook] --> B[IPython / Python kernel]
+    B --> C[EconEnv extension]
+    C --> D[Magics: %econ · %R · %stata · %eviews]
+    C --> E[Engine registry]
+    E --> F[Python engine]
+    E --> G[R engine]
+    E --> H[Stata engine]
+    E --> I[EViews engine]
+    G --> G1[subprocess backend<br/>persistent Rterm]
+    G --> G2[rpy2 backend<br/>when installed]
+    H --> H1[PyStata<br/>official]
+    I --> I1[COM automation<br/>comtypes]
+    C --> J[Data bridges<br/>pandas is canonical]
+    C --> K[Results · Diagnostics · Snapshots]
+    E -.future.-> L[MATLAB · Julia · SAS · Gretl · Dynare · GAUSS · Ox · RATS]
+```
+
+Three rules hold the design together:
+
+1. **No custom kernel.** EconEnv is a Python package plus an IPython extension.
+   A polyglot kernel is evaluated in the roadmap, not assumed.
+2. **Nothing above the engine layer touches a vendor API.** Magics, the CLI,
+   diagnostics and the model layer speak only to `BaseEngine`. Adding MATLAB
+   means writing one adapter, not editing the core.
+3. **Never hide a difference.** Lossy conversions warn. Engine disagreements are
+   reported with the defaults that explain them.
+
+---
+
+## Features
+
+| | |
+|---|---|
+| **Four engines, one kernel** | Python, R, Stata, EViews — persistent sessions, no kernel switching |
+| **Real data bridge** | `pandas.DataFrame` is canonical; push/pull/move between any two engines with no file round-trip |
+| **Type fidelity** | Factors, categoricals, dates, booleans, integers and missing values survive the trip — or you get a warning saying exactly what changed |
+| **Econometric metadata** | Time variable, panel variable, frequency, labels and conversion history travel with the frame |
+| **Structured results** | `ExecutionResult` and `ModelResult` instead of scraped text; raw engine output always retained |
+| **Cross-engine comparison** | Same specification, four engines, one table, with tolerance-aware agreement testing |
+| **Diagnostics** | `econenv doctor` checks every layer and tells you how to fix what is broken |
+| **Reproducibility** | Environment snapshots and provenance records (code hash, data hash, versions, timing) |
+| **Rich output** | HTML tables, PNG/SVG plots from R and EViews rendered inline |
+| **Honest about limits** | Capability matrix reports what each engine can do *on this machine*, not in theory |
+
+---
+
+## Installation
+
+```bash
+pip install econenv
+```
+
+Optional extras — install only what you use:
+
+```bash
+pip install "econenv[stata]"    # helper for locating PyStata
+pip install "econenv[eviews]"   # comtypes, Windows only
+pip install "econenv[arrow]"    # fast Arrow transfer to R
+pip install "econenv[all]"
+```
+
+Then, in a notebook:
+
+```python
+%load_ext econenv
+%econ doctor
+```
+
+### Requirements
+
+| | Required | Notes |
+|---|---|---|
+| Python | 3.9+ | the host kernel |
+| pandas, numpy, IPython | yes | installed automatically |
+| R | optional | 4.0+; EconEnv finds it, no PATH setup needed |
+| Stata | optional | **17 or newer** — PyStata ships with Stata 17+ |
+| EViews | optional | **Windows only**; automation is COM-based |
+| `comtypes` | for EViews | `pip install "econenv[eviews]"` |
+| `rpy2` | never required | no Windows wheels; EconEnv's subprocess backend replaces it |
+
+---
+
+## Engine setup
+
+EconEnv discovers installations automatically — environment variables, `PATH`,
+the Windows registry, then the usual install roots. You should not need to
+configure anything. When you do:
+
+```python
+%econ config r.home      "C:/Program Files/R/R-4.5.2"
+%econ config stata.home  "C:/Program Files/Stata19"
+%econ config stata.edition mp
+%econ config eviews.progid EViews14.Manager
+```
+
+Or persistently, in `~/.econenv/config.toml`:
+
+```toml
+[r]
+home = "C:/Program Files/R/R-4.5.2"
+
+[stata]
+home = "C:/Program Files/StataNow19"
+edition = "mp"
+
+[eviews]
+progid = "EViews14.Manager"
+```
+
+Environment variables work too: `ECONENV_STATA_EDITION=mp`, `R_HOME`,
+`STATA_HOME`.
+
+**A note on R and Windows.** rpy2 publishes no Windows wheels, so EconEnv's
+default R backend is a persistent `Rterm` child process driven over a private
+protocol — no compiler, no `R_HOME` gymnastics. Where rpy2 *is* installed
+(usually Linux and macOS) EconEnv uses it, and loads **rpy2's own** `%R`/`%%R`
+magics rather than shadowing them.
+
+---
+
+## Examples
+
+### Move data without touching a file
+
+```python
+econenv.push("stata", "default", df)      # Python  → Stata
+econenv.move("stata", "r", "default")     # Stata   → R
+back = econenv.pull("r", "econenv_ols_data")
+```
+
+### Keep the metadata
+
+```python
+%%R -i panel -o results
+library(plm)
+fit <- plm(y ~ x, data = panel, index = c("id", "year"), model = "within")
+results <- as.data.frame(summary(fit)$coefficients)
+```
+
+`panel`'s MultiIndex is recognised as (entity, time); `results` comes back with
+its R types intact.
+
+### See what a transfer cost
+
+```python
+econenv.push("eviews", "wf", df)
+```
+
+```
+UserWarning: EconEnv push -> eviews: [warning] region: categorical stored as
+integer codes; EViews has no factor type
+```
+
+### Diagnose
+
+```bash
+econenv doctor
+```
+
+```
+✔ PASS    Python: 3.11.0
+✔ PASS    R installation: C:\Program Files\R\R-4.5.2 (R 4.5.2)
+! WARNING Multiple R versions: 4.5.2, 4.4.3
+              → EconEnv picks the newest. Pin one with `%econ config r.home ...`.
+✔ PASS    PyStata: C:\Program Files\StataNow19\utilities\pystata
+! WARNING COM version binding: several EViews versions are installed
+              → Pin one: `%econ config eviews.progid EViews14.Manager`.
+```
+
+More in [`examples/`](examples/):
+
+1. Quick start
+2. Python + R
+3. Python + Stata
+4. Python + EViews
+5. All four engines
+6. The same OLS in four engines
+7. Data transfer and type fidelity
+8. Time series
+9. Panel data
+
+---
+
+## Project status
+
+**v0.1 — alpha.** Execution, engine management, the data bridge, results,
+graphs, diagnostics, snapshots and cross-engine OLS comparison are implemented
+and tested. The API may still change before v1.0.
+
+What is verified, and on what:
+
+| | Verified |
+|---|---|
+| Python engine | yes, in CI |
+| R engine (subprocess) | yes, against R 4.5.2 on Windows |
+| Stata engine | yes, against StataNow 19.5 MP + PyStata 0.1.2 |
+| EViews engine | yes, against EViews 13 via COM on Windows |
+| R engine (rpy2) | **not** verified — no rpy2 on the development machine |
+| Linux / macOS | **not** verified — the design supports them; nobody has run them yet |
+
+Where something is untested, this README and the docs say so. See
+[`docs/audit/PHASE0_TECHNOLOGY_AUDIT.md`](docs/audit/PHASE0_TECHNOLOGY_AUDIT.md)
+for the measured evidence behind every technical decision.
+
+## Roadmap
+
+| Version | Scope |
+|---|---|
+| **v0.1** | Execution + engine management + data bridge + results + graphs + diagnostics ✅ |
+| v0.2 | Broader type coverage, Stata value labels, EViews alpha/matrix transfer, Arrow everywhere |
+| v0.3 | Model registry beyond OLS: logit, probit, IV, panel FE/RE |
+| v0.4 | Time-series and cointegration estimators; richer comparison reports |
+| v0.5 | Full provenance capture and run manifests |
+| v1.0 | Stable public API, documented multi-engine workflow, JupyterLab cell-toolbar extension |
+
+Graphs were pulled forward from v0.3 into v0.1: plot capture is a property of the
+transport layer, and retrofitting it later would have meant touching every
+adapter twice.
+
+---
+
+## Platform support
+
+| | Python | R | Stata | EViews |
+|---|---|---|---|---|
+| **Windows** | ✅ | ✅ | ✅ | ✅ |
+| **Linux** | ✅ | ✅ | ✅ | ✖ COM is unavailable |
+| **macOS** | ✅ | ✅ | ✅ | ✖ COM is unavailable |
+
+The absence of EViews never blocks installation or use of the others. On
+non-Windows platforms the EViews engine reports itself unavailable and everything
+else works normally.
+
+---
+
+## Commercial software disclaimer
+
+**EconEnv contains, bundles and redistributes no part of Stata or EViews** — no
+binaries, no libraries, no licence files, no serial numbers, no activation keys.
+
+EconEnv locates software already installed on your machine and drives it through
+each vendor's own documented automation interface. You are responsible for
+obtaining, installing and licensing Stata and EViews, and for complying with
+those licences, including any restriction on concurrent sessions, server
+deployment or automated use.
+
+Stata® is a registered trademark of StataCorp LLC. EViews® is a registered
+trademark of IHS Global Inc. R is free software from the R Foundation. None of
+them endorses or is affiliated with this project.
+
+---
+
+## Troubleshooting
+
+Start with `econenv doctor` — it names the problem and the fix. Common ones are
+in [`docs/troubleshooting.md`](docs/troubleshooting.md), including:
+
+* Stata says the edition is wrong
+* EViews connects to the wrong version
+* R starts but never becomes ready
+* `pyeviews` fails to import (it is not needed)
+* Values arrive in EViews as all-NA
+
+## Contributing
+
+Issues and pull requests are welcome. See
+[`docs/development.md`](docs/development.md) for the layout, the test markers
+(`-m "not stata and not eviews"` runs everything that needs no licence) and how
+to write a new engine adapter.
+
+## Citation
+
+If EconEnv is part of your research workflow, please cite it — see
+[`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT — see [LICENSE](LICENSE). The MIT grant covers EconEnv's own source only and
+confers no rights in Stata, EViews or R.
+
+## Author
+
+**Dr Merwan Roudane** · [github.com/merwanroudane](https://github.com/merwanroudane)