# OpenFlock Survey

OpenFlock Survey is an open-source toolkit for collecting and managing citizen-science bird observations. Volunteers can record species, counts, locations, survey effort, and optional notes using a simple command-line workflow. Project coordinators can validate submissions and export consistent datasets for analysis.

> OpenFlock supports community monitoring and education. Records should not be treated as authoritative evidence of species presence without expert review.

## Features

- Record complete survey checklists or incidental sightings
- Capture coordinates, date, duration, distance, and observer count
- Validate species names against a configurable checklist
- Store observations locally in SQLite
- Import observations from CSV
- Export analysis-ready CSV or JSON
- Flag unusual counts and out-of-range observations for review
- Hide coordinates for sensitive species
- Work offline in the field and synchronize later

## Requirements

- Python 3.10 or newer
- `pip` or another Python package installer
- Git, if installing from source

## Install

Clone the repository and create a virtual environment:

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

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

On Windows PowerShell, activate the environment with:

```powershell
.venv\Scripts\Activate.ps1
```

Install the application:

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

Confirm that it is available:

```bash
openflock --version
```

## Usage

Initialize a local project:

```bash
openflock init
```

Start an interactive survey:

```bash
openflock survey
```

You will be prompted for the site, date, location, survey effort, and observations. Use `X` for an unidentified species and add details in the notes field when possible.

Record a single incidental sighting:

```bash
openflock add \
  --species "Red-tailed Hawk" \
  --count 1 \
  --latitude 43.6532 \
  --longitude -79.3832 \
  --observed-at "2026-05-12T08:15:00-04:00"
```

Import observations from a CSV file:

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

The first row must contain column names. At minimum, each record requires `species`, `count`, `latitude`, `longitude`, and `observed_at`.

Validate pending records:

```bash
openflock validate
```

Export approved observations:

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

For all available commands and options:

```bash
openflock --help
openflock survey --help
```

## Configuration

OpenFlock reads configuration from `openflock.toml` in the current directory. Create the default file with `openflock init`, then adjust it for your survey area:

```toml
[project]
name = "Harbour Spring Bird Survey"
timezone = "America/Toronto"
default_observer_count = 1

[data]
database = ".openflock/survey.db"
species_checklist = "config/species.csv"
export_directory = "exports"

[validation]
require_coordinates = true
maximum_count_without_review = 100
flag_species_outside_date_range = true

[privacy]
coordinate_precision = 4
hide_sensitive_species = true
sensitive_species_file = "config/sensitive-species.txt"

[sync]
enabled = false
endpoint = "https://survey.example.org/api"
```

Configuration values can also be supplied through environment variables. Prefix the uppercase setting path with `OPENFLOCK_` and separate sections with double underscores:

```bash
export OPENFLOCK_PROJECT__TIMEZONE="America/Vancouver"
export OPENFLOCK_DATA__DATABASE="/path/to/survey.db"
export OPENFLOCK_SYNC__ENABLED="true"
export OPENFLOCK_SYNC__TOKEN="replace-with-your-token"
```

Environment variables override values in `openflock.toml`. Do not commit access tokens, participant contact information, or precise locations for sensitive species.

## Data Quality and Responsible Surveying

Follow the survey protocol provided by your project coordinator. Record all species detected during complete checklists, include zero-observation surveys when requested, and avoid estimating precise counts when visibility is poor.

Keep a safe distance from nests and roosts. Do not use playback unless the study protocol explicitly permits it, and follow local access rules and wildlife regulations.

## License

This project is licensed under the MIT License. Survey data may be distributed under separate terms chosen by the participating organization.