Skip to content

README.md

Latest commit

 

History

History
128 lines (101 loc) · 5.94 KB

README.md

File metadata and controls

128 lines (101 loc) · 5.94 KB

PyBehaviorLog 0.9.5

CI CodeQL Dependabot Updates Release Drafter Quality Gate Status

PyBehaviorLog is an ASGI-first behavioral observation platform built with Django 6.0.5. It is designed for research teams who need video-assisted coding, live observations, structured ethograms, review workflows, and exportable analytics without being locked into a desktop-only workflow.

What is in this version

This version extends the earlier CowLog/BORIS-inspired foundations with:

  • projects, role-based memberships, videos, and observation sessions
  • point and state behaviors with keyboard bindings
  • modifiers, subjects, subject groups, and independent variables
  • synchronized videos and live observation sessions
  • annotations, review states, and audit trail entries
  • JSON, CSV, TSV, XLSX, BORIS-compatible project/session exports, and reproducibility bundles
  • CowLog-compatible plain-text coding result import/export
  • broader BORIS project import support for list- and mapping-based payload shapes
  • BORIS-inspired behavioral sequence, TextGrid, binary-table, and compatibility-report exports
  • an inline event editor in the session player with timeline-linked selection and quick nudging tools
  • a one-click helper to close unpaired state events during review
  • project-level analytics, transition summaries, and subject-based statistics
  • multilingual interface support limited to English, Arabic, Chinese, Spanish, French, and Russian
  • ASGI deployment with Granian
  • PostgreSQL 18 + Redis 8 container stack
  • Argon2 password hashing
  • database-backed sessions
  • Django CSP middleware support
  • unit tests, coverage gate, pre-commit, and GitHub Actions CI
  • built-in BORIS/CowLog round-trip certification fixtures and comparison helpers
  • BORIS-style CSV/TSV/XLSX session imports
  • media diagnostics with relative media paths and lightweight waveform/spectrogram previews for compatible audio files
  • HTML and SQL session exports for downstream review pipelines
  • player-side review note autosave and event-editor undo/redo history
  • server-side undo/redo backed by database sessions for create/update/delete event operations
  • more faithful BORIS-style tabular imports with start/stop intervals, annotation rows, and broader header aliases
  • deeper image-sequence diagnostics for picture-based observations and relative-path exports
  • BORIS 9.12.1 compatibility updates: native .boris project JSON import, BORIS tabular exports with metadata preambles, BORIS-style aggregated event TSV export, FERAL JSON export, and TextGrid point-event tiers
  • native .boris export profiles for BORIS 7, BORIS 8, and BORIS 9 from both project and session screens
  • BORIS 9.x-style tabular event TSV export from the session screen
  • hardened native BORIS imports for image observations and modifier tokens with shortcut suffixes or None placeholders
  • native .boris IMAGES export for image-only observation sessions
  • native .boris media frame counts when FPS and media duration are known
  • BORIS 9 native media_info.display output for player visualization compatibility
  • BORIS 8/9 native observation interval metadata while keeping BORIS 7 output lean
  • BORIS 9 native media playback defaults for scan sampling and image display duration

Runtime stack

  • Python 3.13+
  • Django 6.0.5
  • Granian (ASGI server)
  • PostgreSQL 18
  • Redis 8
  • psycopg 3 with connection pooling
  • openpyxl for spreadsheet exports
  • argon2-cffi for password hashing

Quick start (local SQLite fallback)

python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
granian --interface asgi --host 127.0.0.1 --port 8000 config.asgi:application

For ASGI-parity in local development, use Granian (instead of the Django dev server) as shown above.

Quick start with Docker

cp .env.example .env
docker compose up --build

The default Docker stack starts:

  • web: Django on Granian / ASGI
  • db: PostgreSQL 18
  • redis: Redis 8

Development workflow

pip install -r requirements-dev.txt
pre-commit install
python manage.py test
coverage run manage.py test
coverage report --fail-under=80

Language support

PyBehaviorLog exposes a focused LANGUAGES list in the interface selector limited to the project languages requested for deployment: English, Arabic, Chinese, Spanish, French, and Russian.

The application uses Django's i18n infrastructure (LocaleMiddleware, the set_language endpoint, locale paths, and translatable templates) so translations can continue to evolve without changing the architecture.

Repository quality controls

The repository includes:

  • .pre-commit-config.yaml
  • .github/workflows/ci.yml
  • coverage configuration with an 80% gate on the tracker app
  • a trimmed dependency set limited to the packages actually used by the project

Documentation

Additional English documentation is available in:

  • docs/architecture.md
  • docs/deployment.md
  • docs/compatibility.md
  • docs/certification.md
  • docs/compatibility_matrix.md
  • docs/native_boris_matrix.md
  • docs/dealhost.md

License

This repository is marked as AGPL-3.0-only.