Jupyter for social research: an interactive guide
Code, results and explanation in one document, with Stata running inside it
Companion to the workshop Jupyter Notebook: Improving Workflow for Social Science Research, Edinburgh, October 2023.
A do-file holds code and short comments; results live elsewhere, in a log or the Results window. A Jupyter Notebook keeps code, output, formatted explanation, equations and references together, runs cells in any order, and supports more than 40 languages, including Stata, R and Python. That makes it easier for someone else to follow your work, and for you to return to it.
1Installing Jupyter
Jupyter needs Python (version 3.3 or later). There are two routes. Choose yours to see the steps.
Jupyter opens in your web browser at an address containing localhost. That is not a website: the notebook is being served from your own computer, so your data stay on your machine.
2Connecting Stata (Stata 17 or later)
First install the bridge in a terminal: pip install --upgrade --user stata_setup. Then, in the first cell of a notebook, point it at your Stata installation. Fill in your details to build that cell.
3Kernels and cells
Two terms matter:
- A kernel is the engine that runs the notebook’s code. One notebook has one kernel.
- A cell is a box in the notebook. Code cells hold code and show its output underneath. Markdown cells hold formatted text: the explanation that a do-file comment cannot carry.
Every notebook is saved as an .ipynb file. Jupyter also saves a checkpoint every 120 seconds, which you can return to with File → Revert to Checkpoint.
4The %%stata rule
Because a notebook can mix languages, each cell runs in Python unless told otherwise. A cell meant for Stata must start with %%stata. Run the cells below to see what happens with and without it.
5Markdown: explaining what you did and why
The workshop’s example is a study of how parental social class affects young people’s employment in the NCDS. It needs datasets merged across sweeps and an ID variable renamed because its capitalisation differs between files. Done silently in a do-file, that is confusing for anyone reading it. A Markdown cell explains it properly. Edit the text on the left; the right shows how the cell renders.
6Keyboard shortcuts
A notebook has two modes. In edit mode you type into a cell. In command mode single keys act on whole cells. Press Esc for command mode and Enter to go back to editing. Click the practice notebook, then try the keys.
7Check yourself
8Workshop files
- Training materials (PDF) and slides
- Notebooks made this way: the missing data comparison notebook and the missing data simulation notebook