These are notebook tutorials for retrieving and analyzing data from Bluesky/ATProto, available in two parallel implementations: Python Jupyter notebooks (in Notebooks/) and R Markdown documents (in RMarkdown/) that perform the same analyses with bskyr and the tidyverse.
Each tutorial after Part 00 pairs a set of Bluesky API endpoints with a data science method and a computational social science research design. See OUTLINE.md for the full intellectual outline — motivations, endpoints, methods, research designs, ethics, limitations, and related Twitter scholarship for every part.
| Part | Python (Jupyter) | R (R Markdown) | Focus |
|---|---|---|---|
| 00 | Introduction | Rmd | setup, authentication, profiles, feeds, follows, posting |
| 01 | Collecting Data at Scale | Rmd | pagination, rate limits, research ethics |
| 02 | Searching and Snowballing | Rmd | search, facets, snowball sampling into a post archive |
| 03 | Social Network Analysis | Rmd | follow graphs, ego networks, centrality, communities |
| 04 | Threads, Engagement, and Diffusion | Rmd | reply trees, cascades, engagement distributions |
| 05 | Time Series and Causal Inference | Rmd | posting rhythms, event studies, ITS, DiD |
| 06 | Natural Language Processing | Rmd | tokenization, sentiment, topic models |
| 07 | Analyzing Visual Content | Rmd | image embeds, alt text, image corpora |
| 08 | LLMs as Research Assistants | Rmd | LLM annotation, validation against gold labels |
| 09 | Algorithmic Curation and Governance | Rmd | custom feeds, lists, starter packs, labelers |
| 10 | Real-Time Streams and Bots | Rmd | Jetstream/firehose, real-time monitoring, bot design |
Each Python Part 01–10 directory is self-contained: the notebook (committed with executed outputs), a shared bsky_client.py connection helper, part-specific helper modules, and small saved datasets in data/. Each R part directory contains the R Markdown source and a shared bsky_client.R credential helper; knit the documents locally to execute them (without credentials they knit prose-only).
Python. Install the dependencies (a package manager like Anaconda is recommended):
python3 -m pip install -r requirements.txtR (4.3 or later):
install.packages(c("bskyr", "tidyverse", "jsonlite", "igraph",
"tidytext", "topicmodels", "rmarkdown",
"digest", "websocket")) # websocket only for Part 10
install.packages(c("sandwich", "lmtest")) # optional: HAC errors in Part 05Authentication: save your handle and an app password as atproto.json in the repository root (it is gitignored — never commit credentials):
{"handle": "your-handle.bsky.social", "password": "your-app-password"}Both implementations read this same file. For the Python notebooks authentication is optional: without credentials they fall back to Bluesky's public AppView, where read endpoints work and cells that require authentication (search, notifications, posting) skip themselves with an explanation. For the R documents authentication is effectively required to execute the API chunks, because bskyr authenticates every call; without credentials the documents still knit, prose-only.
The main libraries used are:
- Python: Jupyter Notebook, ATProto SDK, Pandas, Numpy, Matplotlib, NetworkX, statsmodels, scikit-learn
- R: R Markdown, bskyr, the tidyverse, igraph, tidytext, topicmodels
Contributions are welcome! Please read CONTRIBUTING.md for how to report bugs, propose new notebooks, and submit pull requests, and our Code of Conduct for community expectations. AGENTS.md documents the project layout, notebook conventions, API environment facts, and how to re-execute notebooks.
- OAuth-based authentication
- Developing and publishing a custom feed generator
- Working with PDS repositories and CAR files directly
- Agent-based simulation calibrated on Bluesky data