How wildlife-dynamics/ecoscope works
Project type and purpose
• Ecoscope is an open-source Python library for animal-tracking, environmental and conservation data analyses.
• It provides:
• Data I/O connectors (EarthRanger, Google Earth Engine, MoveBank, raster, GeoPandas)
• Movement-data analysis (relocations, trajectories, home ranges, geofencing, immobility, etc.)
• Visualization (EcoMap, EcoPlot)
• Environmental analyses (seasonality, remote-sensing anomalies)
• Covariate labeling (day/night, seasons, GEE imagery)
• It ships as a modular library, with notebooks, documentation, tests and CI/CD pipelines.
File structure
• Top-level package “ecoscope” with subpackages:
• io — data ingestion adapters
• base — dataclasses, custom DataFrame (“EcoDataFrame”), utilities
• analysis — algorithms (UD, ecology, feature density, seasons, etc.)
• mapping — map rendering utilities
• plotting — plotting routines
• contrib — optional extensions
• relocations.py & trajectory.py — core entry points
• Documentation (Sphinx) under doc/source
• Jupyter notebooks under doc/source/notebooks and nb-tests
• CI/CD workflows (.github/workflows) & publishing recipes (publish/recipes)
• Tests & reference/sample data under tests/
README for additional insights
• Describes the analysis domains, I/O sources, visualization tools.
Main components & interactions
a. Components
1. External Data Sources & Services
• EarthRanger API
• Google Earth Engine
• Raster/vector files (GeoTIFF, GeoPackage)
• MoveBank API
2. I/O Layer (ecoscope.io)
• earthranger.py, eeio.py, raster.py, smartio.py, utils
• Produces EcoDataFrames or GeoDataFrames
3. Core Data Model (ecoscope/base)
• Data classes, EcoDataFrame, utilities, straighttrack
4. Analysis Layer (ecoscope/analysis)
• Modules for UD, geofence, immobility, seasons, classifiers, etc.
• Consume EcoDataFrame, produce result tables or spatial features
5. Mapping & Plotting
• mapping/map.py — spatial visualization
• plotting/plot.py — time-series & summary plots
6. Contrib (ecoscope/contrib)
• geemap integration
7. Notebooks & Docs
• Jupyter notebooks demonstrating workflows
• Sphinx docs showing APIs & examples
8. CI/CD & Packaging
• GitHub workflows (lint, tests, mypy, publishing)
• publish/recipes for conda packaging
b. Relationships and Data Flows
• External Data → I/O Layer → EcoDataFrame
• EcoDataFrame → Analysis Layer → analysis outputs (features, metrics)
• Analysis outputs → Mapping/Plotting → visual outputs (maps, plots)
• Notebooks orchestrate I/O → Analysis → Plotting
• Docs reference API, notebooks, tests validate functionality
• CI workflows run tests, type checks, build docs, publish package
c. Architectural patterns & design principles
• Layered architecture: I/O → Core Data Model → Analysis → Presentation
• Separation of concerns: each subpackage focused on one responsibility
• Extensibility via contrib and clear plugin points in I/O and analysis
• Use of custom DataFrame subclass for uniform handling of spatial & temporal data
d. Key technologies & libraries
• Python 3.x, pandas, geopandas, numpy, shapely, rasterio
• EarthRanger SDK, Google Earth Engine Python API
• Jupyter, Sphinx, pytest, pre-commit, GitHub Actions
• Packaging: pyproject.toml, conda recipes
Final advice
• Be as granular as possible: break “analysis” into submodules (UD, geofence, seasons, etc.) if desired.
• Versioned external dependencies (pandas, geopandas, EarthEngine).
• CI/CD below or aside the core stack to show support functions.
• Use directional flow from left (data sources) to right (outputs) or top (input) to bottom (output) for clarity.