Skip to content
This site documents the development version of Orcapod (the main branch), which may differ from the latest release. For the releases, see PyPI and the changelog.

Tutorial

This tutorial teaches Orcapod by building one small analysis from start to finish. It is written for scientists who are comfortable with Python and have not used Orcapod before. You can work through it on your own, at your own pace, on a laptop.

Each part takes about 20 minutes: a few minutes of reading, samples to run, and two or three exercises. Every exercise has a solution you can unfold. Every sample on these pages is run by Orcapod's test suite, so what a page shows is what the library prints.

A pipeline that takes a small extracellular-recording dataset and computes, for every recording session, the mean firing rate of its units. Along the way you will store the results in a database, re-run the pipeline so that only new work is computed, read and write files, and trace a result back to the rows it came from.

The data is synthetic. A short script generates it on your machine; nothing is downloaded and no real recordings are involved. It imitates a tiny study:

  • 4 mice, two wildtype and two knockout
  • 2 recording sessions per mouse
  • 2 probes per session (imec0 in V1, imec1 in CA1)
  • 4 sorted units per probe
workshop_data/
subjects.csv one row per mouse: subject_id, sex, age_weeks, genotype
sessions.csv one row per session: subject_id, session, date, duration_s
units.csv one row per unit: subject_id, session, probe, unit,
region, depth_um, n_spikes
sessions/
mouse_01_s1/
notes.txt
spikes_imec0.csv one row per spike: time_s, unit
spikes_imec1.csv
mouse_01_s2/
...

27 files, about 0.4 MB. Part 0 shows how to generate it.

Part You learn Time
0. Setup Install Orcapod, check it works, generate the dataset 10 min
1. Your first stream Sources, tag and data columns, looking at a stream 20 min
2. Computing with function pods Turning a Python function into a pipeline step 20 min
3. Reshaping with operators Joining, filtering, renaming 20 min
4. Many rows into one Grouping rows and computing over the group 20 min
5. Keeping results PipelineJob: run a pipeline against a database 20 min
6. Re-runs and caching What is recomputed, and what is not 20 min
7. Working with files Functions that read and write files 20 min
8. Inspecting and tracing Where a result came from 20 min
9. When things go wrong Reading errors; failures inside a run 15 min
10. Where next Features this tutorial did not cover optional

Parts 0 to 6 are the core and should be done in order. Parts 7 to 10 can be read in any order afterwards.

Type or paste each sample into a Python session, a notebook, or a script, in the order shown. Within one page, later samples use names defined by earlier ones. Each page starts from scratch, so you can stop after any part and pick up at the next one later.

Lines starting with # directly under a print(...) show what it prints. Where a value differs from run to run (a hash, a timestamp), the page shows ... in its place.

If something fails, look at Troubleshooting first.