nbstata 用户指南

在 Jupyter 和 Quarto 中使用 Stata

前提条件

Stata

需要已安装并激活许可证的 Stata 17+。

Python

nbstata 底层依赖 pystata(一个Python的Stata接口库)，因此 stata 命令行工具必须能正常运行。

需要 Python 3.10 或更高版本。不同 Stata 版本对 Python 的兼容性如下：

Stata 版本 兼容的 Python 版本
Stata 18–19.5 Python 3.10–3.14（Python 3.14 需要 2025 年 11 月 12 日及之后的 Stata 更新）

推荐使用 Anaconda 或 Miniconda 发行版，安装和管理 Python 环境更方便。

安装

基本安装

在python环境中安装nbstata：

pip install nbstata
python -m nbstata.install [--sys-prefix] [--prefix PREFIX] [--conf-file]

安装选项说明：

  • --sys-prefix：将内核安装到 sys.prefix 路径（适用于 virtualenv / conda 环境）
  • --prefix PREFIX：指定自定义安装路径
  • --conf-file：创建配置文件

配置文件位置：

  • 使用 --sys-prefix 或 --prefix 时：[sys.prefix]/etc/nbstata.conf
  • 默认位置：~/.config/nbstata/nbstata.conf
  • 旧版位置（仍支持）：~/.nbstata.conf

举例：在conda环境中安装nbstata：

conda create -n nbstata python=3.10
conda activate nbstata
pip install nbstata
python -m nbstata.install --sys-prefix

安装完成后，可以在conda环境中使用nbstata：

升级

pip install nbstata --upgrade

升级时无需重新运行安装脚本。

语法高亮（可选）

pip install jupyterlab_stata_highlight2

配置

配置项写在配置文件的 [nbstata] 段中。部分选项也可在运行时通过 %set 魔法命令修改。

设置项 默认值 类型 说明
stata_dir 自动检测 路径 Stata 安装目录
edition 'be' 'be'、'se'、'mp' Stata 版本
splash False 布尔值 是否显示 Stata 启动信息
graph_format 'png' 'png'、'pdf'、'svg'、'pystata' 图形输出格式
graph_width 5.5in 数值或 "default" 图形宽度
graph_height 4in 数值或 "default" 图形高度
echo None True / False / None 命令回显行为
missing '.' 字符串或 'pandas' 缺失值显示格式
browse_auto_height True 布尔值 浏览窗口是否自动调整高度

配置文件示例：

[nbstata]
stata_dir = /Applications/StataNow/StataMP  # Stata 安装路径，nbstata 通过此路径调用 Stata 引擎
splash = True                               # 启动时是否显示 Stata 欢迎信息（版本号、许可证等）
graph_format = pystata                      # 图形输出格式：png（默认）、svg、pdf、pystata（使用 Stata 原生渲染）
graph_width = default                       # 图形宽度，default 表示使用 Stata 默认值；也可指定如 5.5in、300px、7.2cm
graph_height = default                      # 图形高度，单位同上
echo = False                                # 是否在输出中回显 Stata 命令本身（详见下方说明）

echo 选项详解

echo 控制的是命令本身是否出现在输出中，而非命令的运行结果：

  • True：回显所有命令——输出中既显示你输入的 Stata 命令，也显示命令的运行结果
  • False：抑制命令回显——输出中只显示运行结果，不显示命令本身（Stata 18.5+ 完全支持；更早版本中多行命令仍会回显）
  • None（默认）：使用 nbstata 自定义机制抑制命令回显，效果类似 False，但兼容所有 Stata 版本

在 Jupyter Notebook 中使用 Stata

安装完成后，有两种方式使用 nbstata：在 JupyterLab 中，或在 VSCode 中。

方式一：JupyterLab

jupyter lab

指定工作目录：

jupyter lab --notebook-dir "你的路径"

新建 Notebook 时，选择 nbstata 内核即可在单元格中编写和执行 Stata 代码。

方式二：VSCode（推荐）

如果你已经习惯在 VSCode 中编写 Stata Do 文件，那么直接在 VSCode 中使用 Jupyter Notebook 是更流畅的选择。

1. 安装 VSCode 扩展

在扩展商店（Ctrl+Shift+X）中安装以下扩展：

  • Python（Microsoft 官方）
  • Jupyter（Microsoft 官方）

2. 选择 Python 解释器

按 Ctrl+Shift+P（macOS: Cmd+Shift+P），输入 Python: Select Interpreter，选择安装了 nbstata 的 Python 环境路径，例如：

  • conda 环境：~/miniconda3/envs/nbstata/bin/python
  • venv 环境：~/myenv/bin/python

3. 创建并使用 Notebook

  1. 按 Ctrl+Shift+P，输入 Jupyter: Create New Blank Notebook
  2. 在 Notebook 右上角的内核选择器中，选择 nbstata
  3. 在单元格中编写 Stata 代码，按 Shift+Enter 执行

4. 验证安装

在 Notebook 单元格中运行：

display "Hello, Jupyter with Stata!"

也可以在终端中确认内核已正确注册：

jupyter kernelspec list

输出中应包含 nbstata 条目。

VSCode 的优势
  • 无需切换工具——编辑 .do 文件和 Jupyter Notebook 在同一个窗口中完成
  • 支持 Git 版本控制、终端、文件浏览器等功能
  • Notebook 的 .ipynb 文件可以直接用 Quarto 渲染为 HTML 或 PDF

魔法命令

魔法命令以 % 开头，也可用 *% 前缀（兼容 .do 文件）。所有魔法命令均支持 -h 查看帮助。

%browse、%head、%tail：数据浏览

%browse [变量列表] [if] [in] [, nolabel noformat]
%head [N] [变量列表] [if] [, nolabel noformat]
%tail [N] [变量列表] [if] [, nolabel noformat]
  • %browse：交互式查看数据
  • %head / %tail：显示前/后 5 行（或指定 N 行）
  • nolabel：不使用值标签
  • noformat：不使用 Stata 格式

对于数据框（frame），使用对应的 %frbrowse、%frhead、%frtail：

%frbrowse alt_frame
%frhead alt_frame: if var1 == 1, nolabel

%locals：查看局部宏

列出所有局部宏及其值，格式与 Stata 的 macro list 一致。无需参数。

%delimit：查看当前命令分隔符

显示当前分隔符是 cr（回车）还是 ;（分号）。#delimit ; 的设置会跨单元格持续生效，直到执行 #delimit cr。

[1]: %delimit
     当前 Stata 命令分隔符: cr

[2]: #delimit ;
     delimiter now ;

[3]: %delimit
     当前 Stata 命令分隔符: ;

%help：查看帮助

%help 命令或主题名称

以富文本格式显示 Stata 帮助文档，包含可点击的相关主题链接。

%set 和 %%set：修改运行时配置

%set graph_format = svg

%%set
echo = True
missing = N/A

可修改的选项：graph_format、graph_width、graph_height、echo、missing。

在 .do 文件中使用时，用 /* 和 */ 包裹 %%set 的内容：

%%set
/*
echo = True
missing = N/A
*/

%status：查看状态

显示 Stata 状态和当前配置值。无需参数。

%%echo、%%noecho、%%quietly：单元格级输出控制

  • %%echo：仅在当前单元格中回显所有命令
  • %%noecho：仅在当前单元格中抑制回显
  • %%quietly：抑制所有输出，包括图形
%%echo
disp 1
disp 2

%%noecho
disp 1
disp 2

%%quietly
disp 1
disp 2

注意事项

  • #delimit ; 在一个单元格中设置后，会持续影响后续单元格，直到执行 #delimit cr
  • 当 echo = None（默认）时，如果某个代码单元格表现异常，可在单元格顶部添加 %%echo 来诊断问题
  • 对于 Stata 18.5+，推荐设置 echo = False 以获得更简洁的行为
  • more 和 pause 命令在笔记本中不可用，请保持默认设置（set more off、pause off）
  • 输出宽度不会自动调整，需手动设置：set linesize 130

Quarto 集成

在 .qmd 文件的 YAML 头部添加：

jupyter: nbstata

在 .qmd 文件中使用 *| 前缀设置单元格选项。

内联计算

语法：`{stata} [%格式] 表达式`

示例：



每增加一个单位的 mpg，价格*降低* $`{stata} %5.2f abs(_b[mpg])` 美元。

输出效果：“每增加一个单位的 mpg，价格降低 $238.89 美元。”

内联代码中不能使用局部宏

由于反引号 ` 与 Quarto 语法冲突，Stata 的局部宏（如 `x'）无法在内联代码中使用。请改用全局宏或标量（scalar）：

scalar mpg_coef = string(abs(_b[mpg]), "%5.2f")

然后通过以下方式引用：`{stata} mpg_coef`

参考文献