Scott OatleySociology / UCL
← Guides

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.

    On a very old macOS that cannot be updated, Jupyter may fail with “Segmentation Fault 11”. The fix is pip install pyobjc-core pyobjc-framework-cocoa --force-reinstall.

    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.

    
      

    Not sure where Stata is installed? In Stata, type display c(sysdir_stata) and paste the folder it shows. On macOS, check the folder name in Applications, as recent versions are often installed as plain “Stata”.

    3Kernels and cells

    Two terms matter:

    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.

    Run each cell
    use "ncds_occupation_coding.dta", clear
    %%stata use "ncds_occupation_coding.dta", clear

    Outputs are illustrative of what Jupyter shows; no code is actually run.

    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.

    Supported here: # headings, **bold**, *italic*, `code`, numbered and bulleted lists, and > quotes. Jupyter also supports tables, links, images and LaTeX equations.

    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.

    Key (command mode)Action
    ↑ / ↓Move between cells
    A / BInsert a cell above / below
    M / YMake the cell Markdown / code
    D then DDelete the cell
    ZUndo the last deletion
    Enter / EscEdit mode / command mode

    7Check yourself

    8Workshop files