Analytics

Pyronear Analytics is a workspace for operational data analysis across Pyronear systems. It turns station telemetry, camera metadata, backend records, and platform usage signals into reviewable artifacts for monitoring, product decisions, and public-facing tools.

The root analytics package provides the pyro-analytics CLI. Domain packages under packages/* own the analysis code for a specific workflow.

• Getting started
  • Prerequisites
  • Installation
• Usage
  • Pyromap camera workflow
• Examples
  • Camera demo data
• Documentation
• Contributing
  • Workspace layout
  • Quality checks
  • Continuous integration
• Credits

Getting started

Prerequisites

• Python 3.12 or 3.13
• uv

This workspace uses:

• Dependency and environment management: uv
• Lint and format: ruff
• Tests: pytest
• Type checks: mypy
• Local checks: pre-commit

Installation

Clone the repository, install the locked workspace, install Git hooks, and run the test suite:

make setup

Usage

The workspace is organized around small analytics workflows that run from the root pyro-analytics CLI. Workflow packages own domain logic; cross-cutting packages, such as sources, stay focused on reusable ingestion primitives.

The first shipped workflow is Pyromap, which publishes camera coverage data for map consumers. Start with the quickstart to run it locally with fixture data.

Pyromap camera workflow

Pyromap is the camera publishing workflow in this workspace. It turns raw camera records into camera-cells.geojson, a public GeoJSON artifact for map consumers.

This workflow is also the best place to inspect the repository's main boundaries: CLI wiring, ingestion, transformation, orchestration, and publication.

• Run a local fixture publish with the quickstart.
• Operate API-to-S3 publication with the camera workflow runbook.
• Review data boundaries in the Pyronear API and Pyromap Artifact contracts.

Examples

Camera demo data

The repository includes synthetic demo camera data for contributors who want to inspect realistic artifact shapes before changing code:

• examples/cameras/demo-api-cameras.json: synthetic API-style camera records.
• examples/cameras/demo-camera-cells.geojson: generated public camera-cell artifact.

Use these files when reviewing map behavior, privacy-preserving cell shifts, or the shape of the published GeoJSON without live API access. Regeneration commands live in the camera workflow runbook.

Useful contribution paths:

• Add a new analysis package under packages/* for telemetry or platform usage data.
• Extend packages/sources with a reusable backend data source.
• Add example datasets that make a new analysis flow easy to inspect locally.
• Improve docs with screenshots, expected outputs, or operational caveats from real deployments.

Documentation

Project documentation lives in docs. Start with the quickstart for local setup, use the Pyromap runbooks for publication tasks, and use the API and artifact contracts to understand data boundaries.

Build the Furo documentation locally with:

make build-docs

Contributing

Contributions are welcome across data ingestion, telemetry analysis, operational reporting, documentation, and repository tooling. Until a dedicated CONTRIBUTING.md exists, use the checks below before opening a pull request.

Workspace layout

• src/analytics/: repository CLI package and Typer app entrypoint
• packages/: workspace packages, added as packages/*
• packages/sources/: reusable dlt source definitions for backend ingestion
• packages/pyromap/: Pyromap ingestion execution, transformation, publication, and Prefect orchestration code
• tests/: root CLI and workspace configuration tests
• pyproject.toml: lint/type/test/coverage configuration

The root analytics package is command wiring only. Domain implementation belongs in workspace members under packages/*. Cross-cutting packages should not own orchestration entrypoints.

Quality checks

Common contributor commands:

uv run ruff format .
uv run ruff check .
uv run mypy
uv run pytest --cov=analytics --cov=sources --cov=pyromap
uv run pyro-analytics --help

Ruff uses target-version = "py312", mypy strict settings are enabled by default, and coverage uses branch tracking for the root CLI package and workspace package sources. If you relax any strictness defaults, document the rationale in this README so team expectations stay explicit.

Continuous integration

GitHub Actions runs four independent checks on pull requests and pushes to main:

• format: uv run ruff format . --check
• lint: uv run ruff check .
• type: uv run mypy
• test: uv run pytest

Each job installs the locked workspace with uv on Python 3.13, matching the supported runtime range declared in pyproject.toml.

Credits

This project is developed and maintained by Pyronear contributors and volunteers working on open wildfire monitoring infrastructure.