zap-model

Data processing and modeling for zapbench data.

Environment setup

Linux (CUDA)

conda env create -f envs/environment.linux.yaml
conda activate zap-model
pip install --no-deps git+https://github.com/ahrens-fish-lab/fishFuncEM.git@422bb2a
pip install -e .
pre-commit install

macOS

conda env create -f envs/environment.mac.yaml
conda activate zap-model
pip install --no-deps git+https://github.com/ahrens-fish-lab/fishFuncEM.git@422bb2a
pip install -e .
pre-commit install

Note: conda env creation may take a while due to pip building some packages from source.

Data paths

Copy the example paths file and fill in your local paths:

cp src/zap_model/local_paths.example.py src/zap_model/local_paths.py

Variable	Purpose	Used by
ZAPBENCH_LOCAL_PATH	Local root for zapbench release data (read-only)	configs, build_cell_ephys_index.py
ZAPBENCH_GCS_URI	GCS root for remote data	build_cell_ephys_index.py
OUTPUT_DATA_DIR	Writable root for generated data	data/config.py, data/ephys.py, scripts
TRAINING_DIR	Training run output directory	TrainingConfig

Verify setup

After configuring local_paths.py and setting your neuprint credentials, run:

python scripts/verify_setup.py

This checks that local_paths.py exists, its paths are valid, and neuprint can be queried. Requires NEUPRINT_TOKEN or NEUPRINT_APPLICATION_CREDENTIALS in your environment (see fishfuncem docs).

The local_paths.py file is gitignored. These variables provide defaults for config fields (ActivityConfig.traces_path, NeuprintConfig.data_dir) and are used directly in scripts.

fishfuncem

fishfuncem is installed with --no-deps because its pyproject.toml pins strict version ranges (e.g. numpy<2, python<3.12) that conflict with our stack. Its actual runtime dependencies are listed explicitly in the conda env files.

Contributing

Linting and formatting

We use ruff for linting and formatting. Install the ruff VS Code extension (recommended in .vscode/extensions.json) and enable format-on-save:

"[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
}

Configuration lives in pyproject.toml (line length 100, strict rule set).

Pre-commit hooks

Install the git hooks after setting up your environment:

pre-commit install

This runs ruff check + format on every commit and rejects files > 1 MB.

Tests

Run all tests with:

make test

Tests have a 10-second timeout. Keep tests lightweight — no network calls, no large data loads.

Place test files next to the module they test: module.py is tested by module_test.py in the same directory. This keeps tests discoverable in the file tree.

Commits

Use conventional commits:

• feat: — new feature or capability
• fix: — bug fix
• refactor: — code restructuring without behavior change
• build: — dependency or build system changes
• chore: — maintenance (CI, configs, tooling)

Keep messages short and high-level. State the motivation, not a list of files changed.