Differences between revisions 12 and 13

Stata Python

Stata supports calling out to an embedded Python interpretter.

Contents

Stata Python

Installation

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:

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

To prepend or append to the PYTHONPATH, use:

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

To make these settings permanent, add the permanent option.

Usage

Interactive Prompt

Within a Stata interactive session, enter a Python interactive subsession with the python command. For example:

Stata local variables are accessed with quotations.

. local int_var = 3
. local str_var = "This is a Stata string"
. python
---------------------------------------- python (type end to exit) -----------
>>> `int_var'
3
>>> "`str_var'".split(" ")
['This', 'is', 'a', 'Stata', 'string']

A Stata command can be used by prefixing with stata:.

>>> stata: webuse auto, clear

Scope

To interactively run a single Python command and immediately return to the Stata session, use the python: command instead. Note the colon (:).

python: print("Hello, world")

Programs

Use Python within an ado file with the python: command. Much like a Stata program or an interactive Python session, all lines between python: and end will be interpretted by the Python subsession. For example:

python:

import sqlite3
import pandas as pd

con = sqlite3.connect("example.db")
df = pd.read_sql_query("SELECT * from example", 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.

Interface Module

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.

Mixing Python and Stata Programs

When designing a generalized Python program for use from within Stata, the predominant design pattern is:

create an ado file and Stata program that handles all interfacing with the end user
define a minimal Python function
- this function will live in the ado file's namespace, not __main__, so it won't pollute an end user's session
call the Python function with 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

-  ⇤ ← Revision 12 as of 2023-06-09 15:35:23 → 
  Size: 2721
  Editor: DominicRicottone
  Comment:
+   ← Revision 13 as of 2023-09-26 18:26:25 → ⇥
  Size: 3711
  Editor: DominicRicottone
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 37:
-=== REPL ===
+=== Interactive Prompt ===
 Line 39:
-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.
+Within a Stata interactive session, enter a Python interactive subsession with the `python` command. For example:
 Line 54:
-Within the REPL, prefix a Stata command with `stata:`.
+A Stata command can be used by prefixing with `stata:`.
 Line 62:
-=== SFI ===
+=== Scope ===
 Line 64:
-A foreign function interface module is also available.
+To interactively run a single Python command and immediately return to the Stata session, use the `python:` command instead. Note the colon (`:`).
 Line 67:
-from sfi import Data
pymake = Data.get('make')
# do something
+python: print("Hello, world")
-Line 71:
+Line 69:
-This can be used within a REPL as shown above.
-Line 76:
+Line 72:
-=== Scope ===
+=== Programs ===
-Line 78:
+Line 74:
-A '''Python scope''' can be entered with `python:`. This Python environment lasts only until the end of the statement.
+Use Python within an [[Stata/AdoFiles|ado file]] with the `python:` command. Much like a [[Stata/Programs|Stata program]] or an interactive Python session, all lines between `python:` and `end` will be interpretted by the Python subsession. For example:
-Line 80:
+Line 76:
-To submit multiple statements on a scope, delimit them with semicolons.
+{{{
python:

import sqlite3
import pandas as pd

con = sqlite3.connect("example.db")
df = pd.read_sql_query("SELECT * from example", 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.
-Line 84:
+Line 93:
-=== Do Files ===
+=== Interface Module ===
-Line 86:
+Line 95:
-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.
+To move data between Python and Stata processes, use the `sfi` module.
-Line 89:
+Line 98:
-webuse auto
-Line 91:
+Line 99:
+import pandas as pd
-Line 92:
+Line 102:
-pymake = Data.get(’make’)
# do something
+# 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
-Line 97:
+Line 120:
-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.
+This module can be imported into both programs and interactive sessions. It is not a publicly available module.



=== Mixing Python and Stata Programs ===

When designing a generalized Python program for use from within Stata, the predominant design pattern is:

 * create an ado file and Stata program that handles all interfacing with the end user
 * define a minimal Python function
   * this function will live in the ado file's namespace, not `__main__`, so it won't pollute an end user's session
 * call the Python function with a scope

Diff for "Stata/Python"