{"id":16054972,"url":"https://github.com/tiesdekok/ipystata","last_synced_at":"2025-04-05T13:09:44.806Z","repository":{"id":36605053,"uuid":"40911220","full_name":"TiesdeKok/ipystata","owner":"TiesdeKok","description":"Enables the use of Stata together with Python via Jupyter (IPython) notebooks.","archived":false,"fork":false,"pushed_at":"2023-09-28T17:28:17.000Z","size":14959,"stargazers_count":196,"open_issues_count":10,"forks_count":69,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-05T13:09:38.828Z","etag":null,"topics":["jupyter","jupyter-notebook","notebook","python","stata"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TiesdeKok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2015-08-17T16:41:32.000Z","updated_at":"2025-03-27T13:17:04.000Z","dependencies_parsed_at":"2024-04-17T23:58:31.732Z","dependency_job_id":"d5ef49f5-3857-414c-a3c8-a15eb103ebc9","html_url":"https://github.com/TiesdeKok/ipystata","commit_stats":{"total_commits":61,"total_committers":6,"mean_commits":"10.166666666666666","dds":0.5245901639344263,"last_synced_commit":"26930bc1c743f0c74e15f50dcf116010f8504324"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TiesdeKok%2Fipystata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TiesdeKok%2Fipystata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TiesdeKok%2Fipystata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TiesdeKok%2Fipystata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TiesdeKok","download_url":"https://codeload.github.com/TiesdeKok/ipystata/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jupyter","jupyter-notebook","notebook","python","stata"],"created_at":"2024-10-09T02:05:07.659Z","updated_at":"2025-04-05T13:09:44.709Z","avatar_url":"https://github.com/TiesdeKok.png","language":"Jupyter Notebook","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=2UKM4JREAPTBG"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n   \u003cimg src=\"https://i.imgur.com/2FSNsj4.png\" alt=\"Combine Python with Stata using IPyStata\" title=\"Combine Python with Stata using IPyStata\" /\u003e\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e  \n \u003ca href=\"https://gitter.im/TiesdeKok/ipystata\"\u003e\u003cimg src=\"https://img.shields.io/gitter/room/nwjs/nw.js.svg\"\u003e\u003c/a\u003e\n \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\"\u003e\u003c/a\u003e\n \u003ca href=\"https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=2UKM4JREAPTBG\"\u003e\u003cimg src=\"https://img.shields.io/badge/buy%20me%20a-coffee-yellow.svg\"\u003e\u003c/a\u003e\n \n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003cb\u003e:warning:This repository is in archive mode due to my new role. Issues are not monitored.\u003c/b\u003e\u003cbr\u003e\u003cbr\u003e\n  \u003cstrong\u003eIPyStata\u003c/strong\u003e enables the use of Stata together with Python via Jupyter (IPython) notebooks. \u003cbr\u003e \u003cbr\u003e\n  \u003cspan\u003e\u003cstrong\u003eAuthor:\u003c/strong\u003e Ties de Kok (\u003ca href=\"http://www.TiesdeKok.com\"\u003ePersonal Page\u003c/a\u003e)\u003c/span\u003e\u003cbr\u003e\n  \u003cspan\u003e\u003cstrong\u003ePyPi: \u003c/strong\u003e\u003ca href=\"https://pypi.python.org/pypi/ipystata \"\u003ehttps://pypi.python.org/pypi/ipystata \u003c/a\u003e\u003c/span\u003e\u003cbr\u003e\n  \u003cspan\u003e\u003cstrong\u003eDocumentation: \u003c/strong\u003e\u003ca href=\"http://nbviewer.ipython.org/github/TiesdeKok/ipystata/blob/master/ipystata/Example.ipynb\"\u003eExample notebook\u003c/a\u003e\u003c/span\u003e\n\u003c/p\u003e\n\n## Table of contents\n\n  * [Get IPyStata](#getipystata)\n  * [Setup IPyStata](#setup)\n  \t* [Windows](#setupwindows)   \n  \t* [Unix (Linux, Mac OS)](#setupunix)\t \n  * [Using IPyStata](#usingipystata)\n  * [Changelog](#changelog)\n  * [Questions?](#questions)\n  * [License](#license)\n  * [Special thanks](#specialthanks)\n\n\u003ch2 id=\"getipystata\"\u003eGet IPyStata\u003c/h2\u003e\n\n### **You can install IPyStata 0.3.0 using:**\n\n    pip install ipystata\n    \nAlternative, get 4.X version from Github:\n\n    pip install git+https://github.com/TiesdeKok/ipystata\n   \n### **You can update a previous installation using:**\n\n    pip install ipystata --upgrade --force-reinstall\n    \n### **Dependencies**\nPython 2.7 or 3.x  \nIPython 3 or 4+ (http://ipython.org/)  \nPandas **0.17.x +** (http://pandas.pydata.org/) (I recommend to use a distribution like Anaconda)  \nRecent version of Stata (13+ preferably) (http://www.stata.com/)  \n\n\u003ch2 id=\"setup\"\u003eSet up IPyStata\u003c/h2\u003e\n\n#### **Modes of operation:**\nIPyStata can communicate with Stata using two different techniques:  \n\n1. **Stata Automation**, works on --\u003e Windows\n2. **Stata Batch mode**, works on --\u003e Windows, Mac OS X, and Linux\n\nThe `Stata Automation` mode has a richer feature set compared to the `Stata Batch mode`.  \nUnfortunately, Stata only supports `Stata Automation` for Stata instances running on a Windows OS.\n\nFor Windows `Stata Automation` is set as default but it is possible to set it to use `Stata Batch mode` instead.  \nFor Unix operating systems (OS X and Linux) it is only possible to use IPyStata in `Stata Batch mode`.\n\n\u003ch3 id=\"setupwindows\"\u003eWindows setup (Stata Automation)\u003c/h3\u003e\n\n#### Register your Stata instance:\n1. Go to your Stata installation directory and either:\n\n    -  Shift + Right-Click --\u003e click \"*Open command window here*\"  \n       **or**\n    - Open command window (search for \"*cmd*\") and type:  \n       `cd C:\\Program Files (x86)\\Stata14`      (Obviously change it to your Stata directory)  \n\n2. Look up the name of your Stata executable (e.g. `StataMP-64.exe`) and in your command window type:  \n`StataMP-64.exe /Register`\n\n#### Troubleshooting:\n**I get a `com error` when using IPyStata in `Stata Automation` mode?**\n\n\u003e IPyStata cannot communicate with Stata. This error indicates that the registration of Stata was unsuccessful.  \n\u003e **A potential solution:**  try to register again but make sure to run the CMD window as administrator.\n\n**Do I have to register Stata everytime I want to use IPyStata?**\n\u003e No, you only have to register your Stata instance once unless you want to change your Stata installation.\n\n*For more detailed instructions see [this page](http://www.stata.com/automation/#createmsapp).*\n\n\u003ch3 id=\"setupunix\"\u003e Linux / Mac OS setup (Stata Batch mode)\u003c/h3\u003e\n\nThe Batch mode approach works on Windows, Mac OS, and Linux\n#### Set installation directory for Stata:\nThe first step is to tell IPyStata where it can find the Stata installation, use the following commands: \n\n    In[1]: import ipystata  \n    In[2]: from ipystata.config import config_stata  \n    In[3]: config_stata('Path to your Stata executable')  \n\n**Note:** you need to restart the Jupyter Notebook kernel after setting a new Stata installation!\n\nYou can find the Stata executable in the installation directory of Stata, for example:\n\n    Windows  --\u003e 'C:\\Program Files (x86)\\Stata14\\StataSE-64.exe'\n    Mac OS X --\u003e '/Applications/Stata/StataSE.app/Contents/MacOS/stataSE'\n    Linux    --\u003e '/home/user/stata14/stata-se'\n\n#### Configure IPyStata to use the Stata Batch Mode on Windows:\nIt is possible to use `config_stata` to configure IPyStata to use the `Stata Batch Mode` on Windows instead of the default `Stata Automation` mode. See the example below:\n\n    In[1]: import ipystata  \n    In[2]: from ipystata.config import config_stata  \n    In[3]: config_stata('Path to your Stata executable', force_batch=True) \n\n**Note:** This is only advisable if you have a portable Stata installation that you cannot register or if you want to use IPyStata on a Windows server.   \nThe `Stata Automation` method is in most other cases a better option.\n    \n#### Troubleshooting:\n**I set the installation directory but IPyStata still does not work?**\n\n\u003e The new Stata installation is only initialized after a complete kernel restart.   \n\u003e **A potential solution:**  in the Jupyter Notebook click `kernel` --\u003e `restart`\n\n**Do I have to configure my Stata installation everytime I want to use IPyStata?**\n\u003e No, you only have to configure your Stata executable once unless you want to change your Stata installation.\n\n\u003ch2 id=\"usingipystata\"\u003eUsing IPyStata\u003c/h2\u003e\n\n#### **Before you get started:**\nIf you use `Stata Automation` --\u003e Make sure that you have a registered Stata instance: [Windows](#setupwindows)   \nIf you use `Stata Batch Mode` --\u003e Make sure that you have configured your Stata installation: [Unix (Linux, Mac OS)](#setupunix)\n\n#### **Using IPyStata:**\n\nYou can use IPyStata using the `%%stata` cell magic.  \nSee the [**basic instructions**](#basic-instructions) below or the [**example notebook**](http://nbviewer.ipython.org/github/TiesdeKok/ipystata/blob/master/ipystata/Example.ipynb).  \nExample notebook for Mac OS X and Linux users: [batch mode notebook](http://nbviewer.ipython.org/github/TiesdeKok/ipystata/blob/master/ipystata/Example_batch.ipynb)  \n\n**Note:** most intermediate files are stored in the `.ipython/stata` directory.\n\nIf you use `Stata Automation`: \nSeveral options are included to manage your sessions, see the [**session manager**](#session-manager) section.\n\n#### **Basic instructions:**\n\nIPyStata is imported and loaded using `import ipystata`.\nA cell with Stata code is defined by the cell magic `%%stata`.\n\nFor example:\n\n    In[1]: import ipystata  \n    In[2]: %%stata  \n           display \"Hello, I am printed in Stata.\"  \n\n\n### **Arguments:**\n    \nSend a Pandas dataframe to be used in the Stata session (**Both methods**):  \n\n    -d --data  \n    In[1]: %%stata -d dataframe  \n    \nDefine the DTA version internally, by default set to 114 (**Both methods**):  \n\n    -vr --version  \n    In[1]: %%stata -d dataframe -vr 118 \n\nReturn the dataset from Stata after code execution and load it into a Pandas dataframe (**Both methods**):  \n\n    -o --output  \n    In[1]: %%stata -o dataframe  \n\nInput Python lists and load them into Stata as macros (**Both methods**):  \n\n    -i --input  \n    In[1]: example_list = ['var_1', 'var_2']  \n    In[2]: %%stata -i example_list  \n           display \"`example_list'\"\n\nGraph will automatically display and multiple graphs are possible (**Only for `Stata Automation`!**):   \nIf you want to show multiple graphs, you have to make sure to use the , name(.., replace)argument in your Stata code.   \nthe order is not guaranteed to be the same as the generation order. Recommended to use the title() argument when showing multiple graphs.   \n\nIt is possible to prevent graphs from showing using the `-nogr` or `--nograph` arguments.\n\nIf you want a Stata graph as an output of a IPyStata cell you can use the following argument (**Only for `Stata Batch Mode`!**):\n\n    -gr --graph  \n    In[1]: %%stata -gr\n**Note:** *Graph export is only partially supported by Stata if the OS has no GUI. To work around this problem the figures are shown in PDF-format if you use Stata Batch Mode. See: [Statalist](http://www.stata.com/statalist/archive/2011-07/msg00536.html)*\n\nPrevents any output from being shown below the cell (**Both methods**):  \n\n    -np --noprint  \n    In[1]: %%stata -np  \n\nFor inspection purposes it is possible to open the Stata window instead of running it quietly (**Both methods**):\n\n    -os --openstata  \n    In[1]: %%stata -os  \n**Note:** *this only works on Windows and Mac OS X.*\n\nDefine a session to execute the code with (**Only for `Stata Automation`!**):\n\n    -s --session\n    In[1]: %%stata -s session_name\n(Note: if no `session` argument is provided the main session is used.)\n\nSet your Python working directory to the Stata session (**Only for `Stata Automation`!**) :\n\n    -cwd --changewd\n    In[1]: %%stata -cwd\n\nSet code in the cell to run in Mata (**Only for `Stata Automation`!**) :\n\n    -m --mata\n    In[1]: %%stata -m\n\nRetrieve user-defined macros from Stata into a   Python dictionary: `macro_dict` (**Only for `Stata Automation`!**):\n\n    -gm --getmacro    \n    In[1]: %%stata -gm macro_1 -gm macro_2  \n           local macro_1 item1 item2\n           local macro_2 item3 item4\n    In[2]: macro_dict['macro_1']\n    In[3]: macro_dict['macro_2']\n\nSet a working directoy to use while executing this cell  (**Only for `Stata Batch Mode`!**) :\n\n    -cwd --changewd\n    In[1]: %%stata -cwd '~/folder'\n\n### **Session manager (Stata Automation users only):**\n\nIPyStata 0.2 introduces the possibility to use many different Stata sessions that by default run in the background. In order to avoid using unnecessary system resources several tools and automatic cleanup routines are included.\n\n#### Tools:\n\nDisplay all active Stata sessions:\n\n    In[1]: %%stata\n           sessions\nReveal all Stata sessions:\n\n    In[1]: %%stata\n           reveal all        \nHide all Stata sessions:\n\n    In[1]: %%stata\n           hide all      \nClose all Stata sessions initiated by IPyStata:\n\n    In[1]: %%stata\n           close\nClose all Stata sessions (**Warning! This closes \u003cu\u003eall\u003c/u\u003e Stata windows**):\n\n    In[1]: %%stata\n           close all\n#### Automatic clean-up routines:\n\n- At import/load all Stata sessions initiated by a previous IPyStata import are terminated.\n- When IPyStata is unloaded it tries to close all Stata sessions that it created.\n\n\u003ch2 id=\"changelog\"\u003eChangelog\u003c/h2\u003e\n\n\n### What is new in 0.4:   \nMinor improvements for line width in the log files and added support for UTF-8 encoding in Stata files (requires Pandas 1.0+ to work!).\n\n### What is new in 0.3:\nThe `Stata Automation` method introduced in IPyStata 0.2 only works on Windows, this release adds support for the Mac OS X and Linux operating systems using the `Stata Batch Mode` approach. \n\nThe execution methods are determined by IPyStata, non-Windows users will automatically use the `Stata Batch Mode` technique.   \nFor Windows users the default method is `Stata Automation`, but it is possible to configure IPyStata to use the `Stata Batch Mode` instead. \n\n### What is new in 0.2:\n\nAfter a discussion with James Fielder I decided to overhaul my initial code to have it interact with Stata using Automation instead of the batch mode. This approach is inspired by James his Stata-Kernel, check out the awesome early development version here: https://github.com/jrfiedler/stata-kernel.\n\n\u003e **Pros:**\n\u003e\n\u003e - Extra functionality:\n\u003e     - Persistent Stata sessions. (*Just as-if you were using Stata directly!*)\n\u003e     - Multiple Stata sessions in one notebook.\n\u003e     - Allows IPystata to  retrieve macros directly from Stata into Python.\n\u003e - This approach is more idiomatic as it allows for direct interaction with Stata.\n\u003e - Keeps my Stata magic functionality consistent with the Stata kernel by James Fiedler.\n\u003e\n\u003e **Cons:**\n\u003e\n\u003e - Windows only (Stata Automation is Windows only).\n\u003e - Requires the user to register their Stata client.\n\u003e - Requires recent Stata version (13 / 14).\n\u003e\n\u003e **Bug fixes and other improvements:**\n\u003e\n\u003e - Improved the output display functionality:\n\u003e  - Loops should now be displayed correctly.\n\u003e  - Fixed inconsistent white spaces at the begin / end of output.\n\u003e - Internal file-handling changed to using absolute paths, working directory functionality is now explicitly included in the -cwd argument.\n\u003e - Package is compatible for both Python 2.7.x and Python 3.x.\n\u003e - **Plots are now supported using the `-gr` or `--graph` arguments (added in 0.2.1)**\n\u003e - **Both IPython 3 and IPython 4 are now supported (added in 0.2.2)**\n\u003e - **Fixed error when replacing dataset in Stata + single item to macro now possible (added in 0.2.3)**\n\u003e\n\u003e **Todo:**\n\u003e\n\u003e - ~~Add an option for non-Windows users that uses the batch mode functionality.~~\n\u003e - Explore the possibilities of asynchronous Stata code execution using different sessions.\n\u003e - Improve Stata syntax highlighting.\n\n\n## Syntax Highlighting\n\nExperimental support for Stata syntax highlighting is included. CodeMirror does not have a Stata mode, hence the R mode is modified to accomodate Stata code. Setup instructions are below:\n\nFind your notebook package installation folder. For example:\n\nIf you are using IPython 3 go to the folder `IPython`, for IPython 4 go to the folder `notebook`:\n\n    C:\\Users\\*User*\\AppData\\Local\\Enthought\\Canopy\\User\\Lib\\site-packages\\IPython\n    C:\\Users\\*User*\\Anaconda\\Lib\\site-packages\\IPython\n\n    C:\\Users\\*User*\\AppData\\Local\\Enthought\\Canopy\\User\\Lib\\site-packages\\notebook\n    C:\\Users\\*User*\\Anaconda\\Lib\\site-packages\\notebook\n\n\nIn the `IPython` folder **(IPython 3 users)** go to the following directory:\n\n    \\IPython\\html\\static\\components\\codemirror\\mode\n\nIn the `notebook` folder **(IPython 4 users)** go to the following directory:\n\n    \\notebook\\static\\components\\codemirror\\mode\\\n\nCreate a new folder in the \"mode\" folder called 'stata'\n\n    \\IPython\\html\\static\\components\\codemirror\\mode\\stata\n**or**\n\n    \\notebook\\static\\components\\codemirror\\mode\\stata\n\nCopy **stata.js** from the ipystata folder (see Github) into the newly created 'stata' folder.\n\nYou can then enable syntax highlighting by running the following code in a Jupyter Notebook cell and restarting the kernel:  \n\n    import ipystata  \n    from ipystata.config import config_syntax_higlight    \n    config_syntax_higlight(True)    \n    \n\u003ch2 id=\"questions\"\u003eQuestions?\u003c/h2\u003e\n\nIf you have questions or experience problems please use the `issues` tab of this repository.   \nYou can also e-mail me at t.c.j.dekok [at] tilburguniversity.edu .\n\n\u003ch2 id=\"license\"\u003eLicense\u003c/h2\u003e  \n\n[MIT](LICENSE) - Ties de Kok - 2017\n\n\u003ch2 id=\"specialthanks\"\u003eSpecial mentions\u003c/h2\u003e\n\nThis project is inspired by and based on the excelent work of:  \n\n- Rpy2 (https://pypi.python.org/pypi/rpy2)\n- Fortran Magic (https://pypi.python.org/pypi/fortran-magic)\n- Stata-Kernel (https://github.com/jrfiedler/stata-kernel)\n\nContributors:  \n[**@Pacbard**](https://github.com/pacbard)   \n[**@bquistorff**](https://github.com/bquistorff) \n\n## Disclaimer\n\nThis project is not affiliated with or endorsed by Statacorp.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiesdekok%2Fipystata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiesdekok%2Fipystata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiesdekok%2Fipystata/lists"}