軟件教程 | Stata17新特性之Pystata的配置與應用
引言：每一門程序語言都有自己的特點，或者說有其擅長的領域，對于同一項工作的不同部分，如果我們能夠合理搭配使用不同的程序語言或者軟件，就可以極大提高我們的工作效率。從計量統(tǒng)計分析的角度來說，我們可以將這一項工作分為數(shù)據(jù)處理與統(tǒng)計分析兩個部分，在數(shù)據(jù)處理方面?Python?是一個不錯的工具，而在統(tǒng)計分析方面使用?Stata?顯然會更加方便，因此如果能夠找到一個在二者之間進行交互的方法，將極大提高我們的數(shù)據(jù)分析效率。基于以上考慮，從?Stata16?以來，Stata?與?Python?的交互功能就開始日益完善，現(xiàn)在我們可以使用 Stata17 中的?PyStata?來便捷地完成這一項工作。
目錄：
1. PyStata 的基本介紹
1.1 PyStata 簡介
1.2 使用條件
1.3 配置步驟
2. PyStata 交互的實現(xiàn)方式
2.1 使用魔法指令實現(xiàn)交互
2.2 使用 `pystata.stata` 函數(shù)實現(xiàn)交互
2.3 `Stata Function Interface（sfi）` 簡介
1. PyStata 的基本介紹
1.1 PyStata 簡介
PyStata 是 Stata17 中引入的一個新概念，它涵蓋了所有 Stata 和 Python 的交互方式。事實上從 Stata16 開始，我們就可以在 Stata 中調用 Python 代碼，并通過 Stata 函數(shù)接口（ sfi 模塊）實現(xiàn) Python 與 Stata 核心功能的交互；但 Stata17 通過允許我們通過導入一個新的 Python 包（pystata）從一個獨立的 Python 環(huán)境中調用 Stata ，這大大擴展二者的交互功能，使我們可以在基于或支持 IPython 內核的環(huán)境中（例如：Jupyter Notebook 、Jupyter Lab 、Spyder 、PyCharm 、VScode 等）更加方便地調用 Stata 和 Mata。
1.2 使用條件
ⅰ. 安裝正版 Stata17 軟件（必須具備有效的許可證，否則無法調用）
ⅱ. 擁有基于或支持 IPython 內核的 Python 環(huán)境（建議使用 Jupyter Lab 或 VScode）
1.3 配置步驟
Step 01：在 Python 環(huán)境中安裝 stata_setup 模塊
Step 02：在 Python 環(huán)境中導入 stata_setup 模塊，并關聯(lián) Stata17
2. PyStata 交互的實現(xiàn)方式
2.1 使用魔法指令實現(xiàn)交互
2.1.1 cell magic 基本指令
注意：?cell magic 指令需要放在 cell 中的第一行才會生效
在一個 cell 的第一行輸入魔法指令?%%stata?，接著在該 cell 中就可以直接運行 Stata 語句了
2.1.2 line magic 基本指令
如果你只是想在某一行運行一個單獨的 Stata 語句，而在其他行運行 Python 語句，那么就可以使用line magic 指令，只需在某一行輸入魔法指令?%stata?，后面跟上想要運行的 Stata 語句即可。
2.1.3 cell magic 指令的參數(shù)功能
2.1.3.1?-eret、-ret?與?-sret（可實現(xiàn)數(shù)據(jù)傳遞）
%%stata?magic 命令提供了幾個參數(shù)，可用于控制 Stata 命令的執(zhí)行以及在 Stata 和 Python 之間傳遞數(shù)據(jù)
例如：我們可以使用?-eret、-ret?或?-sret?參數(shù)將 Stata 運行結果中的?e（）、r（）?或?s（）?結果傳遞到 Python 變量中；但需要注意的是，此命令默認保存和傳遞的是 Stata 中最后一條命令的運行結果。
該指令默認獲取和傳遞的數(shù)據(jù)將以字典列表的形式儲存，我們可以指定索引直接調用其中的任意一項數(shù)據(jù)。
運用實例：?獲取當前 Stata 所使用數(shù)據(jù)集中的所有變量名，然后通過stata.pdataframe_from_data()函數(shù)將 Stata 數(shù)據(jù)集輸出到 Python 中
2.1.3.2?-d（加載外部數(shù)據(jù)到 Stata ）
我們也可以通過指定?%%stata?magic 指令的?-d?參數(shù)，將?NumPy?數(shù)組或?pandas DataFrame?加載到 Stata 中，使其成為當前的工作數(shù)據(jù)集
注意：此數(shù)據(jù)集會替換當前 Stata 內存中的數(shù)據(jù)集，并在下一個cell中仍然可用
應用實例：?導入一個?df?數(shù)據(jù)集，并使用 Python 中的?df?數(shù)據(jù)集作為當前的 Stata 數(shù)據(jù)集。
2.1.3.3?-f（加載多個外部數(shù)據(jù)到 Stata 中的不同 Frame）
我們還可以通過指定?-f?參數(shù)一次將多個?NumPy?數(shù)組或?pandas DataFrame?加載到 Stata 中，這會將使得每個數(shù)組或?DataFrame?加載到 Stata 中的單獨Frame中
注意：此數(shù)據(jù)集會替換當前 Stata 內存中的數(shù)據(jù)集，并在下一個cell中仍然可用
應用實例：
2.2 使用?pystata.stata?函數(shù)實現(xiàn)交互
2.2.1 單行 stata 指令運算
2.2.2 多行 stata 指令運算
2.2.3?pystata.stata?中的交互函數(shù)
2.2.3.1?get_return（）、get_ereturn（）和?get_sreturn（）（參數(shù)傳遞）
可以使用?get_return（）、get_ereturn（）?和?get_sreturn（）?函數(shù)將 Stata 的?r（）、e（）?和?s（）?結果存儲為 Python 中的字典。
應用實例：
2.2.3.2?stata.pdataframe_from_data()（導出 Stata 當前數(shù)據(jù)集到 Python）
也可以使用?stata.pdataframe_from_data()?將 Stata 數(shù)據(jù)集作為?Numpy?數(shù)組或?pandas DataFrames?傳遞到 Python 中
應用實例：
2.2.3.3?stata.pdataframe_to_data()（加載外部數(shù)據(jù)到 Stata ）
還可以使用?stata.pdataframe_to_data()?將數(shù)據(jù)從 Python 讀取到 Stata 中，使其成為當前數(shù)據(jù)集或將其加載到 Stata 中的特定?Frame?中
應用實例：
將上面的?pd.df?數(shù)據(jù)集?myauto?加載到 Stata 中，使其成為當前數(shù)據(jù)集，并列出前三個觀測值（此處參數(shù)?force=True?指的是在加載?Frame?之前清空 Stata 的當前內存）
2.2.3.4 其他?pystata.stata?函數(shù)介紹
run(cmd[, quietly, echo, inline])：運行一行或一組 Stata 命令。
nparray_to_data(arr[, prefix, force])：將 Numpy數(shù)組加載到 Stata 的內存中，使其成為當前數(shù)據(jù)集。
pdataframe_to_data(df[, force])：將 pandas DataFrame 加載到 Stata 的內存中，使其成為當前數(shù)據(jù)集。
nparray_from_data([var, obs, selectvar, …])：將當前 Stata 數(shù)據(jù)集中的值導出到 Numpy 數(shù)組中。
pdataframe_from_data([var, obs, selectvar, …])：將當前 Stata 數(shù)據(jù)集中的值導出到 pandas DataFrame 。
nparray_to_frame(arr, stfr[, prefix, force])：將 Numpy 數(shù)組加載到 Stata 中的指定 Frame 中。
pdataframe_to_frame(df, stfr[, force])：將pandas DataFrame加載到 Stata 中的指定Frame中。
nparray_from_frame(stfr[, var, obs, …])：將值從 Stata Frame 中導出到 Numpy 數(shù)組中。
pdataframe_from_frame(stfr[, var, obs, …])：將值從Stata Frame 中導出到 pandas DataFrame 。
get_return()：檢索當前的 r（） 結果并將其存儲在 Python 字典中。
get_ereturn()：檢索當前的 e（） 結果并將其存儲在 Python 字典中。
get_sreturn()：檢索當前的 s（） 結果并將其存儲在 Python 字典中。
官方文檔:?https://www.stata.com/python/pystata/notebook/Quick%20Start0.html
2.3?Stata Function Interface（sfi）?簡介
2.3.1?sfi?接口函數(shù)簡介
sfi?模塊允許用戶將 Python 的功能與 Stata 的核心功能進行交互。該模塊可以交互使用，也可以在?do?文件和?ado?文件中使用，在模塊中，定義了?Class?用來訪問?Stata 特征、當前數(shù)據(jù)集、Frame、日期和時間、宏、標量、矩陣、值標簽、全局Mata矩陣、缺失值等。
Class Summary：
Characteristic (sfi.Characteristic)
Data (sfi.Data)
Datetime (sfi.Datetime)
Frame (sfi.Frame)
Macro (sfi.Macro)
Mata (sfi.Mata)
Matrix (sfi.Matrix)
Missing (sfi.Missing)
Platform (sfi.Platform)
Preference (sfi.Preference)
Scalar (sfi.Scalar)
SFIToolkit (sfi.SFIToolkit)
StrLConnector (sfi.StrLConnector)
ValueLabel (sfi.ValueLabel)
Exception Summary：
FrameError (sfi.FrameError)
SFIError (sfi.SFIError)
官方文檔：?https://www.stata.com/python/api17/index.html
2.3.2 常用?sfi.Data?函數(shù)示例
