Programmatic Access

CAMPFIRE ships a Python package with three entry points that share the same authentication and local data layout. Pick the one that matches how you work.

What it gives youWhen to use it
CLI (campfire)Catalog sync + bulk FITS download to a local directoryPull data once, then work with your own scripts / pandas / astropy
Python client (Campfire)Interactive querying, lazy spectrum loading, plotting, calibration & stackingNotebook analysis, custom selections, multi-step workflows
REST APIHTTP endpoints with signed URL downloadsNon-Python clients, lightweight integrations

The CLI and Python client are siblings — same install, same credentials, same on-disk layout. Anything you campfire sync is immediately queryable from Campfire(), and anything you cf.download() is immediately readable by the pipeline tools.

Install#

bash
pip install \
  "campfire-layout @ git+https://github.com/hollisakins/campfire.git#subdirectory=layout" \
  "campfire @ git+https://github.com/hollisakins/campfire.git#subdirectory=python/"

The base install covers the CLI, the Python client, NIRCam cutouts, calibration, and stacking. Optional extras add to the campfire requirement:

bash
pip install \
  "campfire-layout @ git+https://github.com/hollisakins/campfire.git#subdirectory=layout" \
  "campfire[all] @ git+https://github.com/hollisakins/campfire.git#subdirectory=python/"
  • [plotting] — interactive Plotly figures
  • [specutils] — specutils interoperability
  • [all] — both of the above

First five minutes#

bash
campfire login                    # browser-based OAuth
campfire sync                     # pulls full catalog (metadata only, ~seconds)
campfire download --obs ember_uds_p4   # bulk-fetch a selection's FITS (--program / --field / --all also work)

campfire download (alias campfire pull) grabs FITS in bulk up front; the Campfire client below also downloads lazily on first access, so the bulk step is optional. See the CLI Reference for every filter and option.

python
from campfire import Campfire

cf = Campfire()
obj = cf.get_object('J141934.14+525238.7')   # public RUBIES-EGS LRD at z=6.69
print(obj)
# Object(J141934.14+525238.7, z=6.6900, egs)
#   12 spectra (G140H, G140M, G235H, G395H, G395M, PRISM)
#   tags: blagn, hae, lrd, o3e
#   Photometry(11 bands, UNICORN EGS v0.9)

obj.spectra[0].plot()              # quick-look matplotlib
cf.plot_cutout(obj.object_id)      # NIRCam RGB + shutter overlay

Walk through it step-by-step in Getting Started, or jump to the Recipes for end-to-end task examples.

Where things live#

The CLI and Python client share a single data directory. $CAMPFIRE_ROOT (or ~/campfire/ if unset) holds:

code
$CAMPFIRE_ROOT/
├── meta/
│   ├── campfire.db        # local catalog (queried by Campfire client)
│   ├── objects.csv        # exported on every sync — open with pandas/astropy
│   ├── spectra.csv
│   └── photometry.csv
└── products/
    └── <observation>/     # downloaded FITS files
        └── *_spec.fits

Credentials are stored separately at ~/.campfire/credentials and cover all three entry points.

Reference#