= Stata Python =

Stata supports calling out to an embedded [[Python]] interpretter.

<<TableOfContents>>

----



== 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 [[Stata/Mata|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 [[Stata/AdoFiles|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` [[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

{{{
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.

----



== See also ==

[[https://www.stata.com/manuals/ppystataintegration.pdf|Stata manual on PyStata integration]]



----
CategoryRicottone