# OpenFlock Survey

OpenFlock Survey is an open-source toolkit for collecting and validating citizen-science bird observations. It supports repeatable point counts, incidental sightings, and backyard surveys while capturing the location, time, effort, and weather data needed for meaningful analysis.

The project is designed for local bird clubs, conservation groups, schools, and community researchers. Observations are stored locally as portable CSV files and can be reviewed before submission to a shared dataset.

## Features

- Guided point-count and incidental-observation workflows
- Species lookup by common or scientific name
- GPS coordinates with optional manual location entry
- Survey effort, distance, count, behavior, and breeding-code fields
- Weather and habitat metadata
- Offline data collection with later export
- Duplicate and incomplete-record warnings
- CSV and GeoJSON export
- Configurable species lists, survey protocols, and validation rules
- Privacy controls for sensitive species and private locations

## Requirements

- Python 3.11 or later
- `pip`
- A modern web browser

## Installation

Clone the repository and create a virtual environment:

```bash
git clone https://github.com/openflock/openflock-survey.git
cd openflock-survey

python -m venv .venv
source .venv/bin/activate
```

On Windows, activate the environment with:

```powershell
.venv\Scripts\activate
```

Install the application:

```bash
pip install -e .
```

Copy the example configuration:

```bash
cp config.example.toml config.toml
```

Initialize the local database:

```bash
openflock init
```

## Usage

Start the local survey application:

```bash
openflock serve
```

Open `http://127.0.0.1:8080` in a browser.

To begin a survey:

1. Select a survey protocol and site.
2. Confirm the date, start time, observer, and location.
3. Record each species detected, including count and detection method.
4. Add effort, habitat, and weather details.
5. Review validation warnings and complete the survey.
6. Export the records or submit them to the configured project endpoint.

Import observations collected with the CSV template:

```bash
openflock import observations.csv
```

Validate records without changing the database:

```bash
openflock validate observations.csv
```

Export approved observations:

```bash
openflock export --format csv --output exports/observations.csv
openflock export --format geojson --output exports/observations.geojson
```

Run the test suite:

```bash
pytest
```

## Configuration

OpenFlock reads settings from `config.toml`. Environment variables prefixed with `OPENFLOCK_` override file-based settings.

```toml
[project]
name = "Spring Migration Survey"
timezone = "America/Toronto"
default_protocol = "point-count"
data_directory = "./data"

[server]
host = "127.0.0.1"
port = 8080
debug = false

[survey]
default_duration_minutes = 10
require_effort = true
require_weather = true
allow_incidental_observations = true
species_list = "./config/species.csv"

[location]
coordinate_system = "WGS84"
gps_accuracy_warning_meters = 50
round_public_coordinates_to_km = 1

[privacy]
hide_sensitive_species = true
hide_private_sites = true
embargo_days = 30

[export]
include_observer_email = false
date_format = "%Y-%m-%d"
```

Common environment-variable overrides include:

```bash
export OPENFLOCK_PROJECT__TIMEZONE="America/Vancouver"
export OPENFLOCK_SERVER__PORT=9000
export OPENFLOCK_PRIVACY__EMBARGO_DAYS=60
```

Species lists must be UTF-8 CSV files containing at least `common_name`, `scientific_name`, and `taxon_code` columns. Optional columns include `family`, `season`, `region`, and `sensitive`.

Never publish exact coordinates for nests, threatened species, or observations made on private property without permission. Review local wildlife-reporting guidance before sharing a dataset.