Metadata-Version: 2.4
Name: beekeeping
Version: 0.3.4
Summary: Manage video metadata for animal behaviour experiments
Author-email: Sofia Miñano <s.minano@ucl.ac.uk>, Nikoloz Sirmpilatze <niko.sirbiladze@gmail.com>, Sam Cunliffe <s.cunliffe@ucl.ac.uk>, Adam Tyson <code@adamltyson.com>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/neuroinformatics-unit/beekeeping
Project-URL: Bug tracker, https://github.com/neuroinformatics-unit/beekeeping/issues
Project-URL: Source code, https://github.com/neuroinformatics-unit/beekeeping
Project-URL: User support, https://github.com/neuroinformatics-unit/beekeeping/issues
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Requires-Python: >=3.11.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: dash
Requires-Dist: dash-bootstrap-components
Requires-Dist: PyYAML
Requires-Dist: openpyxl
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: dash[testing]; extra == "dev"
Requires-Dist: tox; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: setuptools-scm; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: pandas-stubs; extra == "dev"
Dynamic: license-file

[![License](https://img.shields.io/badge/License-BSD_3--Clause-orange.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![CI](https://img.shields.io/github/actions/workflow/status/SainsburyWellcomeCentre/beekeeping/test_and_deploy.yml?label=CI)](https://github.com/neuroinformatics-unit/beekeeping/actions)
[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json)](https://github.com/astral-sh/ruff)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)

# `beekeeping` 🐝
Manage video metadata for animal behaviour experiments.

## Overview

`beekeeping` is a web-based dashboard built with [Dash-Plotly](https://dash.plotly.com/) for managing video metadata in animal behaviour experiments. It provides an intuitive interface for creating, editing, and organizing metadata files associated with experimental videos.

**Key Features:**
- Upload and manage project configurations
- Interactive metadata table with editing capabilities
- Bulk import from spreadsheets (CSV/Excel)
- Automatic detection of videos missing metadata
- Export metadata as YAML files
- Responsive web interface with Bootstrap theming

It is based on an earlier codebase called [WAZP](https://sainsburywellcomecentre.github.io/WAZP/), but focuses specifically on metadata management.

## Installation

Install `beekeeping` inside a [conda](https://docs.conda.io/en/latest/) environment:

```sh
conda create -n beekeeping-env -c conda-forge python=3.12
conda activate beekeeping-env
git clone https://github.com/neuroinformatics-unit/beekeeping.git
cd beekeeping
pip install .
```

## Getting Started

1. **Launch the application**
   ```bash
   start-beekeeping
   ```
   The app opens in your browser at `http://localhost:8050`

2. **Upload Project Configuration**
   - Navigate to the **Home** page
   - Upload your `project_config.yaml` file containing:
     ```yaml
     videos_dir_path: /path/to/your/videos
     metadata_fields_file_path: /path/to/metadata_fields.yaml
     metadata_key_field_str: File
     ```

3. **Manage Video Metadata**
   - Navigate to the **Metadata** page to view/edit your video metadata table
   - Each row represents one video file's metadata

### Core Operations

#### **Viewing and Editing Metadata**
- **Browse**: Scroll through the paginated table (25 rows per page)
- **Sort**: Click column headers to sort data
- **Hide/Show columns**: Use column visibility controls
- **Edit**: Click any editable cell to modify values directly
- **Row selection**: Click checkboxes to select rows for batch operations

#### **Adding Missing Videos**
- Click **"Check for missing metadata files"**
- The app scans your videos directory and adds rows for videos without `.metadata.yaml` files
- File extensions supported: `.avi`, `.mp4`

#### **Manual Data Entry**
- Click **"Add empty row"** to create a new metadata entry
- Fill in the fields as needed
- The filename field links to your video file

#### **Batch Operations**
- **Select All/Unselect All**: Mass row selection controls
- **Export Selected**: Click "Export selected rows as yaml" to save `.metadata.yaml` files for selected videos
- **Import from Spreadsheet**: Upload CSV/Excel files to bulk generate metadata files

#### **Spreadsheet Import Process**
1. Prepare your spreadsheet (CSV or Excel) with columns matching your metadata fields
2. Click **"Generate yaml files from spreadsheet"**
3. Upload your file
4. The app will:
   - Match spreadsheet columns to metadata fields
   - Add missing columns with empty values
   - Only process rows with corresponding video files
   - Generate `.metadata.yaml` files in your videos directory
   - Show confirmation with count of files generated

## License

⚖️ [BSD 3-Clause](https://opensource.org/licenses/BSD-3-Clause)
