Restructure into a tested package and add the browser dashboard

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [develop, main]
+  push:
+    branches: [develop, main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: |
+          ruff check src tests
+          ruff format --check src tests
+      - name: Test
+        run: pytest
+
+  site:
+    name: Site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+      - name: Test
+        run: node --test "tests/web/*.test.mjs"

.github/workflows/pages.yml

@@ -0,0 +1,41 @@
+name: Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - name: Build the analysis package into the site
+        run: pip wheel . --no-deps --wheel-dir docs/package
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -319,4 +319,7 @@ data/species/*.geojson
 !data/README.md
 !results/README.md
 !images/README.md
-!docs/README.md
+!docs/README.md
+# Analysis package built into the site (see `make site` and the Pages workflow)
+docs/package/
+results/*.pkl

CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- `bee_migration` package under `src/` with `climate`, `analysis`, `prediction`,
+  `evidence`, `charts` and `reports` modules
+- `bee-migration` command (`analyze`, `predict`, `charts`, `all`) with `--data`,
+  `--root` and `--seed` options
+- Test suite under `tests/`
+- Browser dashboard under `docs/`: the package runs in the page through Pyodide
+  and draws trends, correlations, model accuracy and forecasts
+- Field data chapter with observed temperatures (Open-Meteo, ERA5) and the mean
+  latitude of bee records (GBIF), parsed by `bee_migration.sources`
+- `CI` workflow (lint and tests) and `Pages` workflow (site deployment from `main`)
+- Git Flow branching guide in `CONTRIBUTING.md`
+
+### Changed
+- Models are evaluated on the most recent years, held out chronologically, and
+  tuned with time-ordered cross-validation
+- Feature importance is measured by permutation for every model
+- Climate stress index is expressed in regional standard deviations
+- Project metadata, pytest and ruff configuration consolidated in `pyproject.toml`
+
+### Fixed
+- Prediction features no longer include the same-year change of the target
+- Lagged correlations now compare temperature with bee abundance in later years
+- A missing `--data` file is reported as an error instead of silently falling
+  back to simulated data
+- Compatibility with pandas 3
+
+### Removed
+- Trained model files from version control; `bee-migration predict` recreates them
+- Simulated seasonality figures and percentile clipping of observations
+- Generated literature reports; the figures they quoted live in
+  `bee_migration.evidence.literature`
+
 ## [1.0.0] - 2024-01-21
 
 ### Added

CONTRIBUTING.md

@@ -21,10 +21,10 @@ This project adheres to a code of conduct that promotes a welcoming and inclusiv
 
 1. Fork the repository
 2. Clone your fork: `git clone https://github.com/your-username/Bees.git`
-3. Create a new branch: `git checkout -b feature/your-feature-name`
+3. Create a new branch from `develop`: `git switch -c feature/your-feature-name develop`
 4. Make your changes
 5. Test your changes
-6. Submit a pull request
+6. Submit a pull request against `develop`
 
 ## Development Setup
 
@@ -88,19 +88,14 @@ pytest tests/test_specific_module.py
 - Follow PEP 8 guidelines
 - Use meaningful variable and function names
 - Add docstrings to all functions and classes
-- Maximum line length: 88 characters (Black formatter)
+- Maximum line length: 88 characters (ruff formatter)
 
 ### Code Formatting
 
 ```bash
-# Format code with Black
-black src/
-
-# Sort imports with isort
-isort src/
-
-# Lint with flake8
-flake8 src/
+# Format and lint with ruff
+ruff format src/ tests/
+ruff check src/ tests/
 ```
 
 ### Documentation Style
@@ -227,12 +222,36 @@ When requesting features, include:
 
 ## Development Workflow
 
-### Branch Naming
+### Branches
+
+The project follows Git Flow:
+
+| Branch | Purpose | Receives changes from |
+|--------|---------|-----------------------|
+| `main` | Released code; every push deploys the site | `release/*` and `hotfix/*` pull requests |
+| `develop` | Integration of finished work | `feature/*`, `fix/*`, `docs/*`, `refactor/*` pull requests |
+| `feature/description` | New features | branched from `develop` |
+| `fix/description` | Bug fixes | branched from `develop` |
+| `docs/description` | Documentation updates | branched from `develop` |
+| `refactor/description` | Code refactoring | branched from `develop` |
+| `release/x.y.z` | Release preparation | branched from `develop`, merged into `main` and back into `develop` |
+| `hotfix/description` | Urgent fix of released code | branched from `main`, merged into `main` and `develop` |
 
-- `feature/description`: New features
-- `fix/description`: Bug fixes
-- `docs/description`: Documentation updates
-- `refactor/description`: Code refactoring
+Nothing is pushed directly to `main` or `develop`. Every change arrives through
+a pull request, and the `CI` workflow (lint and tests for Python, tests for the
+site) must pass before it is merged.
+
+```bash
+# Work on something
+git switch -c feature/my-change develop
+# ...commit...
+git push -u origin feature/my-change
+gh pr create --base develop
+
+# Release what is on develop
+git switch -c release/1.1.0 develop
+gh pr create --base main
+```
 
 ### Code Review Process
 

Makefile

@@ -11,7 +11,7 @@ help:
 	@echo "  test         - Run tests"
 	@echo "  test-cov     - Run tests with coverage"
 	@echo "  lint         - Run linting checks"
-	@echo "  format       - Format code with black and isort"
+	@echo "  format       - Format code with ruff"
 	@echo "  clean        - Clean temporary files"
 	@echo "  run-analysis - Run complete bee migration analysis"
 	@echo "  generate-charts - Generate all scientific charts"
@@ -22,11 +22,11 @@ help:
 # Installation
 install:
 	@echo "Installing production dependencies..."
-	pip install -r requirements.txt
+	pip install -e .
 
-install-dev: install
+install-dev:
 	@echo "Installing development dependencies..."
-	pip install -r requirements-dev.txt
+	pip install -e ".[dev]"
 
 # Environment setup
 setup-env:
@@ -49,7 +49,7 @@ test:
 
 test-cov:
 	@echo "Running tests with coverage..."
-	pytest tests/ -v --cov=src --cov-report=html --cov-report=term
+	pytest tests/ -v --cov-report=html
 
 test-fast:
 	@echo "Running fast tests..."
@@ -58,18 +58,16 @@ test-fast:
 # Code quality
 lint:
 	@echo "Running linting checks..."
-	flake8 src/ tests/
-	mypy src/
+	ruff check src/ tests/
 
 format:
 	@echo "Formatting code..."
-	black src/ tests/
-	isort src/ tests/
+	ruff format src/ tests/
+	ruff check --fix src/ tests/
 
 format-check:
 	@echo "Checking code format..."
-	black --check src/ tests/
-	isort --check-only src/ tests/
+	ruff format --check src/ tests/
 
 # Security
 security:
@@ -80,21 +78,25 @@ security:
 # Analysis and charts
 run-analysis:
 	@echo "Running complete bee migration analysis..."
-	cd src && python bee_analysis.py
-	cd src && python bee_migration_analysis.py
-	cd src && python comparative_analysis.py
+	bee-migration analyze
 
 generate-charts:
 	@echo "Generating all scientific charts..."
-	cd src && python generate_charts_english.py
-
-generate-charts-pt:
-	@echo "Generating charts in Portuguese..."
-	cd src && python generate_charts.py
+	bee-migration charts
 
 run-predictor:
 	@echo "Running migration predictor..."
-	cd src && python bee_migration_predictor.py
+	bee-migration predict
+
+# Site
+site:
+	@echo "Building the analysis package into the site and serving it..."
+	pip wheel . --no-deps --wheel-dir docs/package
+	python -m http.server 8000 --bind 127.0.0.1 --directory docs
+
+test-site:
+	@echo "Running site tests..."
+	node --test "tests/web/*.test.mjs"
 
 # Data processing
 process-data: