Getting Started¶

Installation¶

uv add aind-behavior-vr-foraging-packaging

uv pip install aind-behavior-vr-foraging-packaging

pip install aind-behavior-vr-foraging-packaging

uv pip install "git+https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging.Packaging.git"

Quick start — sites table¶

Load a raw session directory and compute the sites table (one row per site):

from aind_behavior_vr_foraging.data_contract import dataset
from aind_behavior_vr_foraging_packaging.pipeline.session import resolve_site_table_processor

ds = dataset("path/to/session")  # load the raw session
sites_df = resolve_site_table_processor(ds).compute()  # version-dispatch automatic

print(f"{len(sites_df)} sites, {sites_df['has_reward'].sum()} rewarded")
sites_df.to_parquet("sites.parquet")  # optional: persist to disk

resolve_site_table_processor automatically picks the current or legacy SiteTableProcessor based on the dataset's schema version.

Quick start — all tables at once¶

To produce every table in a single call, use process_session. It writes one parquet per processor and returns them keyed by name:

from aind_behavior_vr_foraging.data_contract import dataset
from aind_behavior_vr_foraging_packaging.pipeline.session import process_session

ds = dataset("path/to/session")
results = process_session(ds, output_dir="output/")
# → output/sites.parquet, output/position_velocity.parquet, …

print(results.keys())
# dict_keys(['session', 'sites', 'position_velocity', 'licks', 'sniffing',
#            'software_events', 'events'])

Quick start — CLI export¶

Install the CLI tool with uv:

uv tool install aind-behavior-vr-foraging-packaging

Then export a folder of raw session directories (--input-dir must contain one subdirectory per session):

vr-foraging-packaging batch --input-dir /data/raw --output-dir /data/export

The export directory receives:

/data/export/
├── session.parquet          # session catalogue (one row per session)
├── sites.parquet            # aggregated sites table (all sessions)
└── sessions/
    └── <session_id>/
        ├── sites.parquet
        ├── position_velocity.parquet
        └── …

Subcommands¶

Swap batch for session or aggregate to run those:

# One session
vr-foraging-packaging session --input-dir /data/raw/behavior_123_2025-01-01 --write-nwb

# Aggregate later, re-processing nothing
vr-foraging-packaging aggregate --input-dir /data/export/sessions --output-dir /data/export

Run vr-foraging-packaging <command> --help for that command's full flag reference, or see the CLI API reference.

Prefer to try it without installing? uvx runs it directly — since the command name differs from the package name, pass it via --from:

uvx --from aind-behavior-vr-foraging-packaging \
    vr-foraging-packaging batch --input-dir /data/raw --output-dir /data/export

Next steps¶