Coffea-casa — An Analysis Facility for the Columnar Object Framework For Effective Analysis

GitHub issues GitHub pull requests

About Coffea-casa

Coffea-casa is an analysis facility (AF) that provides services for "low latency columnar analysis", enabling rapid processing of HEP data in a column-wise fashion with coffea. Its services, based on Dask and Jupyter, aim to dramatically lower time to insight and provide an easily scalable, user-friendly computational environment.

The facility runs on Kubernetes (JupyterHub via Zero to JupyterHub) and scales Dask workers out onto dedicated resources and onto resources allocated via fair share through HTCondor (e.g. the Nebraska Tier-2). It also handles single sign-on, token-based authentication and authorization for data access (XRootD / XCache), and ships a curated software stack for analysis.

Production instances:

coffea.casa — CMS AF at UNL (CMS AuthZ / IAM tokens)
coffea-opendata.casa — open-data instance
coffea.af.uchicago.edu — ATLAS AF at UChicago

User documentation: https://coffea-casa.readthedocs.io. Examples live in docs/gallery and in coffea-casa-tutorials.

What's in this repository

Path	Contents
`coffea_casa/`	`coffea_casa` Python package (`CoffeaCasaCluster`, a dask-jobqueue HTCondor cluster for the AF), published to PyPI
`docker/`	Dockerfiles and environment files for the notebook/scheduler and worker images (details)
`charts/coffea-casa/`	Helm chart (JupyterHub + coffea-casa configuration)
`docs/`	Sphinx documentation (ReadTheDocs) and the example notebook gallery
`ci/`, `tests/`, `tests-charts/`	Image structure tests, spawn/smoke tests, chart tests

The `coffea_casa` Python package

pip install coffea-casa

Inside a coffea-casa notebook, the Dask JupyterLab extension starts a CoffeaCasaCluster for you. To create one manually:

from coffea_casa import CoffeaCasaCluster
from dask.distributed import Client

cluster = CoffeaCasaCluster()  # no workers are submitted until you scale
cluster.adapt(minimum=0, maximum=20)
client = Client(cluster)

See the API docs for all options.

Docker images

Images are published to the OSG Harbor registry under hub.opensciencegrid.org/coffea-casa. They are built on top of the coffea base images (coffeateam/coffea-*-almalinux9):

Image	Role
`cc-dask-alma9`	Single-user notebook / Dask scheduler image (JupyterLab, Dask labextension, code-server, …)
`cc-analysis-alma9`	Slim Dask worker image
`cc-dask-combine-alma9`	`cc-dask-alma9` + ROOT and CMS Combine
`cc-analysis-combine-alma9`	`cc-analysis-alma9` + ROOT and CMS Combine

cc-dask-alma9 and cc-analysis-alma9 are built for several coffea flavours:

Flavour	Base image	Python
`noml` (default)	`coffeateam/coffea-almalinux9-noml`	3.12
`dak`	`coffeateam/coffea-dak-almalinux9` (coffea with dask-awkward)	3.12
`full`	`coffeateam/coffea-almalinux9`	3.12
`0.7`	`coffeateam/coffea-0.7-almalinux9` (legacy coffea 0.7.x)	3.11

Tags have the form <version>-<flavour> (e.g. cc-dask-alma9:2026.10.12-dak); the default noml flavour is also published under the bare <version> tag. Base image versions are bumped automatically by a daily workflow that opens a PR.

See docker/README.md for build arguments and how to build images locally.

Helm chart

helm repo add coffea-casa https://coffeateam.github.io/coffea-casa
helm repo update
helm search repo coffea-casa

See the chart README, the deployment guide and the local (k3d / minikube) deployment guide.

Versioning and releases

Coffea-casa uses calendar versioning (YYYY.MM.DD, with a .N suffix for further releases on the same day). Releasing is automated with GitHub Actions — there are no version numbers to bump by hand:

Every push to master is automatically tagged with the next CalVer tag.
- Images whose sources changed are published as :development / :development-<flavour>.
- The Helm chart is published to https://coffeateam.github.io/coffea-casa if charts/ changed. Since Helm requires SemVer, the chart version maps the tag to YYYY.MMDD.N (e.g. 2026.10.12 → 2026.1012.0); appVersion is the exact git tag.
Publishing a GitHub Release from a tag (releases):
- builds, tests and publishes all images as :<tag> / :<tag>-<flavour>;
- publishes the coffea_casa package to PyPI (version derived from the tag);
- republishes the Helm chart.

Pull requests build and test images and the chart without publishing anything.

Analysis repositories using coffea-casa

BTVNanoCommissioning — commissioning studies in the CMS BTV POG based on (custom) NanoAOD samples
SUEPCoffea_dask — SUEP analysis using fastjet with awkward input from PFNano NanoAOD samples
hgg-coffea — tools for running the CMS Higgs to two photons analysis on NanoAOD

References

M. Adamec, G. Attebury, K. Bloom, B. Bockelman, C. Lundstedt, O. Shadura and J. Thiltges, Coffea-casa: an analysis facility prototype, arXiv:2103.01871 (2021).
PyHEP 2020 coffea-casa proceedings:
PyHEP 2020 introductory talk: YouTube

Contact us

Questions and feedback are welcome in GitHub Discussions, GitHub Issues, or the IRIS-HEP Slack.

Metadata

Release files for coffea-casa 2026.10.12.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for coffea-casa 2026.10.12.3
File	Size	Uploaded
coffea_casa-2026.10.12.3.tar.gz	8.8 MB	Oct 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for coffea-casa 2026.10.12.3
File	Interpreter	ABI	Platform	Reset
coffea_casa-2026.10.12.3-py3-none-any.whl 17.4 kB Oct 12, 2026	Python 3	none	any	Details

Total release size: 8.8 MB

Release files / coffea_casa-2026.10.12.3.tar.gz

Download URL	coffea_casa-2026.10.12.3.tar.gz
Size	8.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`ab0b7b5f289793791061abb52385c4d83df14091ca263a347235f9a059676cd7`
BLAKE2b-256 checksum How to use checksums	`471f32fe3055309a88f7d73c76db0f276cd6c880b2b5748e17daaec87f9bf147`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/CoffeaTeam/coffea-casa
Publishing commit: github.com/CoffeaTeam/coffea-casa/tree/043fed8ce8dc583722054721b2edc0edb1d8c21e

Workflow

Publishing configuration: github.com/CoffeaTeam/coffea-casa/blob/043fed8ce8dc583722054721b2edc0edb1d8c21e/.github/workflows/pypi-tag-deploy.yml
Publishing logs: github.com/CoffeaTeam/coffea-casa/actions/runs/38276181351/attempts/1

Artifact

Subject: coffea_casa-2026.10.12.3.tar.gz
SHA-256 checksum: ab0b7b5f289793791061abb52385c4d83df14091ca263a347235f9a059676cd7 Verifying attestations

Release files / coffea_casa-2026.10.12.3-py3-none-any.whl

Download URL	coffea_casa-2026.10.12.3-py3-none-any.whl
Size	17.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a45536225ec7e6d28625465252934d0a610645aec85652a9093f731ef05f5bdb`
BLAKE2b-256 checksum How to use checksums	`bac8a589d78b12f514f86f457fc927a43160f93f8fc91aad8ef03c8e5631b695`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/CoffeaTeam/coffea-casa
Publishing commit: github.com/CoffeaTeam/coffea-casa/tree/043fed8ce8dc583722054721b2edc0edb1d8c21e

Workflow

Publishing configuration: github.com/CoffeaTeam/coffea-casa/blob/043fed8ce8dc583722054721b2edc0edb1d8c21e/.github/workflows/pypi-tag-deploy.yml
Publishing logs: github.com/CoffeaTeam/coffea-casa/actions/runs/38276181351/attempts/1

Artifact

Subject: coffea_casa-2026.10.12.3-py3-none-any.whl
SHA-256 checksum: a45536225ec7e6d28625465252934d0a610645aec85652a9093f731ef05f5bdb Verifying attestations