Differences between revisions 12 and 14 (spanning 2 versions)

Stata Python

Stata supports calling out to an embedded Python interpretter.

Contents

Stata Python

Installation

To list recognized Python environments, try python search. If an valid environment is known to exist but was not recognized, try:

python set exec "C:\path\to\python\installation"

To manipulate (i.e., append or prepend) the PYTHONPATH environment variable, try:

python set userpath "C:\foo" "C:\bar" "C:\baz"
python set userpath "C:\foo" "C:\bar" "C:\baz", prepend

To make these settings permanent, add the permanent option.

Usage

Much like Mata, there is a Python scope.

python: print("Hello, world")

Subsessions

Within an interactive Stata session, enter a Python interactive subsession with the -python- command.

. // This is an interactive Stata session
. local int_var = 3

. local str_var = "This is a Stata string"

.
. // Now start the Python subsession
. python
---------------------------------------- python (type end to exit) -----------
>>>
>>> myint = 3
>>> mystr = "This is a Python string
>>>
>>> # Stata macros evaluate here
>>> `int_var'
3
>>> "`str_var'".split(" ")
['This', 'is', 'a', 'Stata', 'string']
>>>
>>> # Call back out to the Stata session
>>> stata: webuse auto, clear

Programs

Within an ado file, run Python code like:

python:
import sqlite3
import pandas as pd

con = sqlite3.connect("`a'")
df = pd.read_sql_query("SELECT * from `b'", con)
con.close()
end

Note that objects in the __main__ namespace are retained across Python sessions. If the con sqlite3.Connection object was not closed, it would have remained in memory until the Stata process ended.

Best practices for bundling Python in an ado file are:

Write as a function to be called, not as a script that evaluates immediately
Write an accompanying Stata program to wrap it, and handle everything user-facing there
Call the function from a scope

program varsum
    version 16.0
    syntax varname [if] [in]

    python: _varsum("`varlist'", "`touse'")
    display as txt " sum of ‘varlist’: " as res r(sum)
end

python:
from sfi import Data, Scalar
def _varsum(varname, touse):
    x = Data.get(varname, None, touse)
    Scalar.setValue("r(sum)", sum(x))
end

. webuse auto
(1978 Automobile Data)

. varsum price
sum of price: 456229

. varsum price if foreign
sum of price: 140463

Stata Interoperability

To move data between Python and Stata processes, use the sfi module.

python:

import pandas as pd
from sfi import Data

# initialize N cases
Data.setObsTotal(len(df))

# initialize variables
Data.addVarDouble("id")
Data.addVarStr("name",5)

# copy columnar data
Data.store("id", None, df["id"], None)
Data.store("zipcode", None, df["name"], None)

# free memory
del df

end

This module can be imported into both programs and interactive sessions. It is not a publicly available module.

-  ⇤ ← Revision 12 as of 2023-06-09 15:35:23 → 
  Size: 2721
  Editor: DominicRicottone
  Comment:
+   ← Revision 14 as of 2025-10-24 16:20:01 → ⇥
  Size: 3359
  Editor: DominicRicottone
  Comment: Rewrite
-Deletions are marked like this.
+Additions are marked like this.
 Line 13:
-Most system configuration is done with the '''`python set`''' command.

Stata can list recognized Python environments with `python search`. To add an unrecognized environment, try:
+To list recognized Python environments, try `python search`. If an valid environment is known to exist but was not recognized, try:
-Line 21:
+Line 19:
-To prepend or append to the `PYTHONPATH`, use:
+To manipulate (i.e., append or prepend) the `PYTHONPATH` environment variable, try:
-Line 24:
+Line 22:
-python set userpath "C:\foo" "C:\bar" "C:\baz", [prepend]
+python set userpath "C:\foo" "C:\bar" "C:\baz"
python set userpath "C:\foo" "C:\bar" "C:\baz", prepend
-Line 35:
+Line 34:
+Much like [[Stata/Mata|Mata]], there is a '''Python scope'''.

{{{
python: print("Hello, world")
}}}
-Line 37:
+Line 41:
-=== REPL ===
-Line 39:
+Line 42:
-A Python REPL is entered with the `python` command alone. It prints to the screen a reminder that the `end` command is used to exit the environment.
+=== Subsessions ===
-Line 41:
+Line 44:
-Stata local variables are accessed with quotations.
+Within an interactive Stata session, enter a Python interactive subsession with the '''`-python-`''' command.
-Line 44:
+Line 47:
+. // This is an interactive Stata session
-Line 45:
+Line 49:
-Line 46:
+Line 51:
+.
. // Now start the Python subsession
-Line 48:
+Line 56:
+>>>
>>> myint = 3
>>> mystr = "This is a Python string
>>>
>>> # Stata macros evaluate here
-Line 52:
+Line 65:
-}}}

Within the REPL, prefix a Stata command with `stata:`.

{{{
+>>>
>>> # Call back out to the Stata session
-Line 62:
+Line 72:
-=== SFI ===
+=== Programs ===
-Line 64:
+Line 74:
-A foreign function interface module is also available.
+Within an [[Stata/AdoFiles|ado file]], run Python code like:
-Line 67:
+Line 77:
-from sfi import Data
pymake = Data.get('make')
# do something
}}}
+python:
import sqlite3
import pandas as pd
-Line 72:
+Line 81:
-This can be used within a REPL as shown above.



=== Scope ===

A '''Python scope''' can be entered with `python:`. This Python environment lasts only until the end of the statement.

To submit multiple statements on a scope, delimit them with semicolons.



=== Do Files ===

While an interactive `python:` scope lasts only until the end of the statement, a do file `python:` scope continues until explicitly terminated by the `end` command.

{{{
webuse auto
python:
from sfi import Data
pymake = Data.get(’make’)
# do something
+con = sqlite3.connect("`a'")
df = pd.read_sql_query("SELECT * from `b'", con)
con.close()
-Line 97:
+Line 87:
-A common design pattern is to define Python functions within an [[Stata/AdoFiles|ado file]] with the primary Stata function being a thin interface for them.
+Note that objects in the `__main__` namespace are retained across Python sessions. If the `con` [[Python/Sqlite3|sqlite3.Connection]] object was not closed, it would have remained in memory until the Stata process ended.

Best practices for bundling Python in an ado file are:
 * Write as a function to be called, not as a script that evaluates immediately
 * Write an accompanying Stata program to wrap it, and handle everything user-facing there
 * Call the function from a scope
-Line 132:
+Line 127:
+== Stata Interoperability ==

To move data between Python and Stata processes, use the `sfi` module.

{{{
python:

import pandas as pd
from sfi import Data

# initialize N cases
Data.setObsTotal(len(df))

# initialize variables
Data.addVarDouble("id")
Data.addVarStr("name",5)

# copy columnar data
Data.store("id", None, df["id"], None)
Data.store("zipcode", None, df["name"], None)

# free memory
del df

end
}}}

This module can be imported into both programs and interactive sessions. It is not a publicly available module.

----

Diff for "Stata/Python"