Howler

A production-ready application for tracking and analyzing wolf (Canis lupus) sightings and movements across multiple data sources — with ML-powered behavior prediction.

Features

• Multi-Source Data Integration: Fetch wolf sightings from GBIF, iNaturalist, IUCN, and Movebank
• Advanced Analysis: Pack territory detection (DBSCAN), movement analysis, and temporal pattern detection
• Machine Learning: Behavior prediction (stationary, territorial, linear, random, central-place), next-location forecasting, and activity pattern analysis
• Interactive Maps: Full map capabilities with OpenStreetMap tiles, zoom/pan controls, and multiple layers
• Multiple Interfaces: CLI, TUI (Terminal UI), GUI (Desktop), Web App, and Mobile App
• Data Management: Filter, search, export (CSV, GeoJSON, KML), and import wolf sighting data
• Cross-Platform: Runs on Linux, macOS, Windows, iOS, and Android

Installation

From Source

git clone https://github.com/realgoldfang/howler.git
cd howler
cargo build --release

Using Cargo

cargo install howler-cli
cargo install howler-tui
cargo install howler-gui

Pre-built Binaries

Download pre-built binaries from the Releases page.

Quick Start

CLI

# Fetch wolf sightings from all sources
howler-cli --fetch

# Generate a report
howler-cli --report

# Fetch from specific source
howler-cli --fetch --source gbif --limit 100

TUI (Terminal UI)

howler-tui

GUI (Desktop)

howler-gui

Web App

cd web-app
npm install
npm run dev

Opens at http://localhost:5173 with dashboard, map, analysis, ML predictions, and settings.

Mobile App (React Native / Expo)

cd mobile-app
npm install
npx expo start

Scan the QR code with Expo Go on iOS or Android.

Configuration

Howler uses environment variables for API key configuration:

# Movebank credentials (for GPS tracking data)
export MOVEBANK_USERNAME="your_username"
export MOVEBANK_PASSWORD="your_password"

# iNaturalist API token (optional — requires 5-month-old account with 10+ observations)
export INATURALIST_TOKEN="your_token"

# IUCN API token (optional — register at https://api.iucnredlist.org/users/sign_up)
export IUCN_TOKEN="your_token"

All sources are optional. Howler works without any API keys — it just uses GBIF (which is free and open).

API Key Acquisition

Movebank:

1. Register at movebank.org
2. Create an account and request access to studies
3. Use your username and password

iNaturalist:

1. Register at inaturalist.org
2. Go to your account settings and create an API application
3. Copy the access token

IUCN:

1. Register at api.iucnredlist.org
2. Request an API token
3. Use the token in your environment

Usage Examples

Fetching Data

# Fetch from all sources
howler-cli --fetch

# Fetch specific number of sightings
howler-cli --fetch --limit 50

# Fetch from specific source
howler-cli --fetch --source gbif

Exporting Data

# Export to CSV
howler-cli --export --format csv --output sightings.csv

# Export to GeoJSON
howler-cli --export --format geojson --output sightings.geojson

# Export to KML (Google Earth)
howler-cli --export --format kml --output sightings.kml

Filtering Data

# Filter by date range
howler-cli --filter --start-date 2023-01-01 --end-date 2023-12-31

# Filter by source
howler-cli --filter --source gbif

# Filter by species
howler-cli --filter --species "Canis lupus"

Machine Learning

Howler includes an ML module for wolf behavior prediction using random forest classification and linear regression.

Behavior Classification

use howler_core::ml::{BehaviorModel, BehaviorFeatures, BehaviorType};

let model = BehaviorModel::new();
let features = BehaviorFeatures::from_sightings(&sightings);
let prediction = model.predict_behavior(&features);

match prediction.behavior_type {
    BehaviorType::Territorial => println!("Pack territory behavior"),
    BehaviorType::Linear => println!("Dispersal/migration pattern"),
    BehaviorType::CentralPlace => println!("Den-based activity"),
    // ...
}

Next-Location Prediction

let location_pred = model.predict_next_location(&features);
println!(
    "Predicted: ({}, {}) in {} hours",
    location_pred.latitude, location_pred.longitude, location_pred.time_horizon_hours
);

Supported Behavior Types

Type	Description
Stationary	Wolf remains in small area (< 1km radius)
Territorial	Circular/area-restricted movement
Linear	Directed movement (dispersal/migration)
Random	No discernible pattern
CentralPlace	Activity centered on den site

Project Structure

howler/
├── howler-core/      # Core library: data models, API clients, ML, analysis
├── howler-cli/       # Command-line interface
├── howler-tui/       # Terminal user interface (Ratatui)
├── howler-gui/       # Desktop GUI (Iced)
├── web-app/          # React + Vite web application
├── mobile-app/       # React Native (Expo) mobile application
├── shared/           # Shared TypeScript types and API client
├── fixtures/         # Test fixtures
├── docs/             # Documentation
└── .github/          # CI/CD workflows

Development

Prerequisites

• Rust 1.70 or later
• Node.js 18+ (for web/mobile apps)
• Expo CLI (for mobile app)

Building

# Build all Rust crates
cargo build --workspace

# Build web app
cd web-app && npm install && npm run build

# Build mobile app
cd mobile-app && npm install && npx expo start

Testing

# Run all Rust tests
cargo test --all-features --workspace

# Run with coverage
cargo tarpaulin --workspace

Code Quality

# Format
cargo fmt

# Lint
cargo clippy -D warnings

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (cargo test --all-features --workspace)
5. Run linters (cargo fmt && cargo clippy -D warnings)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under either of:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

Data Sources

• GBIF: Global Biodiversity Information Facility - https://www.gbif.org
• iNaturalist: Citizen science observations - https://www.inaturalist.org
• IUCN: International Union for Conservation of Nature - https://www.iucnredlist.org
• Movebank: Animal tracking data - https://www.movebank.org

Acknowledgments

• GBIF for providing occurrence data
• iNaturalist for citizen science observations
• IUCN for conservation status data
• Movebank for GPS tracking data
• The Rust community for excellent tools and libraries
• linfa for machine learning primitives

Support

• Issues: GitHub Issues
• Documentation: docs/
• Discussions: GitHub Discussions

Roadmap

Completed

• Multi-source data integration (GBIF, iNaturalist, IUCN, Movebank)
• DBSCAN territory detection
• Movement and temporal analysis
• CLI, TUI, and GUI interfaces
• Data export (CSV, GeoJSON, KML) and import
• Machine learning for behavior prediction
• Web application (React + Vite)
• Mobile application (React Native / Expo)
• Real-time data streaming (WebSocket + Axum server)
• Multi-user collaboration (auth, annotations, ratings)
• Offline map tiles for mobile
• Auto-fetch on network connectivity

Maps

• Real map tiles for web app (Leaflet / MapLibre)
• Map layers (satellite, terrain, topographic)
• Territory boundary drawing and editing tools
• Heatmap visualization for sighting density

Data

• Photo attachments for sightings
• Weather data integration (precipitation, temperature at sighting location)
• Historical comparison (year-over-year trends)
• CSV/GeoJSON/KML export from web and mobile apps

Machine Learning

• Species identification from photos
• Population density modeling
• Migration pattern forecasting
• Anomaly detection for unusual sighting patterns

User Experience

• Push notifications for new sightings in area
• Field data collection mode (offline-first, sync later)
• Onboarding tutorial for new users
• PDF report export
• Dark mode for mobile app
• Accessibility improvements (screen reader, contrast)

Infrastructure

• Docker setup for easy deployment
• Database migrations system
• API rate limiting and caching layer
• Structured logging and monitoring
• Error tracking and reporting

Social

• Data sharing between users / public feed
• Comments and discussion on sightings
• User profiles and contribution tracking
• Share sightings to social media