# OpenFlock Survey

OpenFlock Survey is an open-source citizen-science project for collecting standardized bird observations from volunteers. Participants record species, counts, survey effort, location, and weather conditions through a command-line tool or CSV import. Researchers and community organizers can then validate and export the records for analysis.

The project is designed for repeatable point-count surveys, but it also supports incidental observations. It is not a substitute for emergency wildlife reporting; injured or distressed birds should be reported to a local wildlife rehabilitation service.

## Features

- Record point-count and incidental bird observations
- Capture survey duration, distance, weather, and observer notes
- Resolve coordinates from GPS input or named survey sites
- Import observations from a CSV template
- Validate species codes, dates, counts, and coordinates
- Flag unusual sightings for expert review
- Store data locally in SQLite
- Export filtered datasets as CSV or GeoJSON
- Remove observer names and reduce coordinate precision for public exports
- Operate offline during fieldwork

## Requirements

- Python 3.11 or later
- Git
- Optional: a GPS-capable device for field coordinates

## Install

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 PowerShell, activate the environment with:

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

Install the application:

```bash
python -m pip install --upgrade pip
pip install -e .
```

Confirm that the CLI is available:

```bash
openflock --version
```

## Usage

Initialize a local survey database:

```bash
openflock init
```

Add a named survey site:

```bash
openflock site add river-trail \
  --name "River Trail Wetland" \
  --latitude 43.6421 \
  --longitude -79.3774
```

Start a 10-minute point count:

```bash
openflock survey start \
  --site river-trail \
  --protocol point-count \
  --duration 10
```

Record observations:

```bash
openflock observe --species AMRO --count 3
openflock observe --species BCCH --count 2 --notes "Calling from cedar grove"
```

Finish the active survey:

```bash
openflock survey finish \
  --weather clear \
  --wind 2 \
  --temperature 18
```

List recent surveys:

```bash
openflock survey list --since 2026-05-01
```

### CSV Import

Download or copy the import template:

```bash
openflock template csv > observations.csv
```

Required columns are:

```text
observed_at,species_code,count,latitude,longitude
```

Optional columns include `observer`, `site`, `protocol`, `duration_minutes`, `weather`, and `notes`.

Validate and import the file:

```bash
openflock import observations.csv --dry-run
openflock import observations.csv
```

Rows with invalid species codes, impossible counts, malformed dates, or coordinates outside valid ranges are rejected and written to an error report.

### Export

Export reviewed records as CSV:

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

Create a privacy-preserving GeoJSON dataset for public use:

```bash
openflock export \
  --format geojson \
  --public \
  --coordinate-precision 2 \
  --output exports/public-observations.geojson
```

## Configuration

OpenFlock reads configuration from `openflock.toml` in the current directory. Create a starter file with:

```bash
openflock config init
```

Example configuration:

```toml
[project]
name = "Harbour Spring Bird Count"
timezone = "America/Toronto"
default_protocol = "point-count"
default_duration_minutes = 10

[database]
path = "data/openflock.sqlite3"

[taxonomy]
checklist = "ebird-clements"
allow_unlisted_species = false

[validation]
maximum_count = 10000
require_coordinates = true
flag_out_of_season = true

[privacy]
store_observer_names = true
public_coordinate_precision = 2
hide_sensitive_species = true

[export]
directory = "exports"
include_unreviewed = false
```

Configuration values can also be supplied through environment variables. Prefix each setting with `OPENFLOCK_` and separate nested keys with double underscores:

```bash
export OPENFLOCK_PROJECT__TIMEZONE="America/Vancouver"
export OPENFLOCK_DATABASE__PATH="/var/lib/openflock/surveys.sqlite3"
export OPENFLOCK_PRIVACY__STORE_OBSERVER_NAMES="false"
```

Settings are applied in the following order, from lowest to highest priority:

1. Built-in defaults
2. `openflock.toml`
3. Environment variables
4. Command-line options

Never commit participant names, precise locations for sensitive species, API tokens, or production databases to version control. Use public exports when sharing data outside the survey team.

## Data Quality

Before publishing a dataset, survey coordinators should review:

- Observations flagged as rare, out of season, or unusually numerous
- Duplicate records from repeated imports
- Surveys with missing effort or weather information
- Records outside the project area
- Free-text notes that may contain personal information

Automated validation catches common errors, but it does not confirm species identification. Photographs, audio recordings, and detailed field notes should be retained when available.