Getting started

Setting up a computing environment for the book’s exercises

Set up a browser notebook or a local Python environment, run a small example, and choose model access suited to your data and research task.

Set up an environment for retrieving data, coding text, fitting models, and building figures. You do not need an existing programming setup.

Start with Colab to try the examples without installing software, including on a locked-down institutional laptop. Set up locally for data you cannot upload to a third party, a large corpus, or a permanent environment you control.

You do not need Python to use this book

The book explains research tasks independently of a programming language. This site uses Python for its examples, including text models and network analysis. If you work in R or Stata, use the examples to understand the steps and check which tools in your environment support them. The tool guides include R options.

Route 1: Zero-install with Google Colab

Google Colab runs Python notebooks in your browser on Google’s machines. You can try the example below using its free service without installing a local environment. Availability and resource limits vary, so check the Colab FAQ before planning a longer run.

First run, start to finish:

  1. Go to colab.research.google.com and sign in with a Google account.
  2. Choose File → New notebook.
  3. Click into the empty code cell, paste the lines below, and press Shift+Enter.
import pandas as pd

papers = pd.DataFrame({
    "doc_id": ["d001", "d002", "d003"],
    "title": ["Access barriers in rural districts",
              "A scalable optimization framework",
              "Community-based participation and equity"],
    "year": [2019, 2021, 2022],
})

papers["title_length"] = papers["title"].str.split().str.len()
papers

If a small table appears underneath the cell, you have run your first data transformation. Later exercises may require extra packages, but this is enough to begin working with tables.

What to know before you rely on it:

  • Sessions are temporary. A Colab machine is reclaimed after a period of inactivity and everything in its local storage disappears. Save anything you care about to Google Drive (from google.colab import drive; drive.mount('/content/drive')) or download it.
  • Check where your data may be processed. Do not put confidential, restricted, or IRB-protected material into a hosted notebook without checking your institution’s rules and the terms of the service. This is a research-ethics question, not just an IT one (see Chapter 11).
  • Install extra packages per session with !pip install packagename at the top of the notebook. It has to be rerun each time the session restarts.

Route 2: A local environment

A local setup lets you manage the files and software on your own computer. The steps below use Miniconda, which installs Python and a package manager together and does not disturb any Python your operating system already depends on.

  1. Install Miniconda from the official installer page for your operating system.

  2. Create a project environment. Open a terminal (Terminal on macOS/Linux, Anaconda Prompt on Windows) and run:

    conda create -n cssprimer python=3.11
conda activate cssprimer

    The environment name appears in your prompt when it is active. Activate it every time you work on this project.

  3. Install the packages used in the introductory examples:

    pip install pandas pyarrow scikit-learn matplotlib seaborn \
            jupyterlab networkx requests

    Add model-specific packages when you reach the relevant exercise. Installing them in a separate environment can make dependency problems easier to isolate.

  4. Start JupyterLab and create a notebook to check the install:

    jupyter lab

    Run the pandas example from the Colab section above.

  5. Record what you installed. From the active environment:

    pip freeze > requirements.txt

    Save this file with the project, along with your Python version and operating system. pip freeze records installed package versions; it does not produce a full lock file. Test those requirements in a fresh environment before claiming the analysis can be reproduced.

Editors

Use JupyterLab for the notebook examples, or VS Code with the Python and Jupyter extensions to edit scripts and notebooks alongside project files. Chapter 2’s recording shows a study built from an empty folder: what working with an agent actually looks like.

R and Stata users

The equivalent moves are renv::init() for a project-local R library plus renv::snapshot() for the lock file, or a documented version statement and package list in Stata. The principle from Chapter 9 is identical across languages: pin what you installed, record it in the project, and never rely on “latest version.”

Getting access to an AI model

Several exercises (Chapter 4’s screening, Chapter 6’s LLM coding, Chapter 8’s validity audit) call a language model. Choose access based on your budget, data, and institution.

Option A: Your institution’s provided access

Ask your library, research computing group, or IT service desk what model access your institution provides. Check whether the agreement covers your data and whether it includes an API for batch coding; access to a chat interface may not include that capability.

Option B: A commercial API

Providers such as OpenAI, Anthropic, and aggregators such as OpenRouter (one interface across many models) sell access by usage. Estimate the cost from a small batch using the model and prompt you intend to use. Long abstracts, repeated calls, and validation runs all contribute to the total.

Handling keys safely. An API key is a credential that can spend your money. Never paste one into a notebook cell, a script you will commit, or a chat window. Put it in an environment variable or a .env file that is listed in your .gitignore:

import os
api_key = os.environ["OPENAI_API_KEY"]   # set in your shell, not in the code

Controlling cost. Check the provider’s budget controls and whether they stop requests or only send alerts. Begin with a small set of documents, inspect the labels and usage, and scale up after the prompt has been audited (Chapter 6).

Option C: A local open-weight model

Ollama can run downloaded models on your computer. For local processing, choose a local model and follow its local-only configuration instead of using cloud features. Check the hardware requirements and evaluate the model on your coding task before committing to it.

Record the model identifier, the downloaded model’s digest, and the Ollama version. A reusable model name alone is not a permanent record of the files used.

# after installing Ollama
ollama pull llama3.1
ollama run llama3.1 "Summarize the following abstract in one sentence: ..."
Whatever you choose, record it

Model name, version, date, and settings are part of your method, not incidental configuration. Chapter 6 develops this as the promptbook; Chapter 9 explains why an undocumented model version can make an analysis impossible to reproduce.

Where to go next