# wildlife-dynamics/ecoscope architecture

> Architecture diagram of the GitHub repository wildlife-dynamics/ecoscope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wildlife-dynamics/ecoscope
- Repository: https://github.com/wildlife-dynamics/ecoscope

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    subgraph "External Data Sources"
        ER_SVC["EarthRanger API"]:::external
        GEE_SVC["Google Earth Engine"]:::external
        RAST_SVC["Raster/Vector Files"]:::external
        MB_SVC["MoveBank API"]:::external
    end

    %% I/O Layer
    subgraph "I/O Layer"
        ER_py["earthranger.py"]:::io
        ERU_py["earthranger_utils.py"]:::io
        EEIO_py["eeio.py"]:::io
        EETOOLS_py["eetools.py"]:::io
        RAS_py["raster.py"]:::io
        SMART_py["smartio.py"]:::io
        IO_UTIL_py["utils.py"]:::io
    end

    %% Core Data Model
    subgraph "Core Data Model"
        DC_py["_dataclasses.py"]:::base
        EDF_py["ecodataframe.py"]:::base
        ST_py["straightrack.py"]:::base
        BASE_UTIL_py["utils.py"]:::base
    end

    %% Analysis Layer
    subgraph "Analysis Layer"
        ASTR_py["astronomy.py"]:::analysis
        CLF_py["classifier.py"]:::analysis
        ECOG_py["ecograph.py"]:::analysis
        FD_py["feature_density.py"]:::analysis
        GF_py["geofence.py"]:::analysis
        GEO_sp_py["geospatial.py"]:::analysis
        IMMO_py["immobility.py"]:::analysis
        PCT_py["percentile.py"]:::analysis
        SEAS_py["seasons.py"]:::analysis
        subgraph "UD Subpackage"
            UD_py["etd_range.py"]:::analysis
        end
    end

    %% Mapping & Plotting
    subgraph "Mapping & Plotting"
        MAP_py["map.py"]:::mapping
        PLOT_py["plot.py"]:::plotting
    end

    %% Contrib
    subgraph "Contrib Extensions"
        GEEMAP_py["geemap.py"]:::contrib
    end

    %% Core Entry Points
    subgraph "Entry Points"
        RELOC_py["relocations.py"]:::base
        TRAJ_py["trajectory.py"]:::base
    end

    %% Notebooks & Documentation
    subgraph "Notebooks & Docs"
        NB["Jupyter Notebooks"]:::docs
        DOC_RST["index.rst"]:::docs
        GUI_md["ecoscope_gui.md"]:::docs
        CONF_py["conf.py"]:::docs
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        GH_WF[".github/workflows"]:::cicd
        RECIPE_yml["ecoscope.yaml"]:::cicd
        PYPROJ["pyproject.toml"]:::cicd
        ENV_yml["environment.yml"]:::cicd
    end

    %% Data Flow
    ER_SVC -->|raw data| ER_py
    GEE_SVC -->|raw data| EEIO_py
    RAST_SVC -->|raw data| RAS_py
    MB_SVC -->|raw data| SMART_py

    ER_py -->|EcoDataFrame| EDF_py
    ERU_py -->|helpers| EDF_py
    EEIO_py -->|GeoDataFrame| EDF_py
    EETOOLS_py -->|tools| EDF_py
    RAS_py -->|GeoDataFrame| EDF_py
    SMART_py -->|smart I/O| EDF_py
    IO_UTIL_py -->|utils| EDF_py

    EDF_py --> DC_py
    EDF_py --> ST_py
    EDF_py --> BASE_UTIL_py

    EDF_py --> ASTR_py
    EDF_py --> CLF_py
    EDF_py --> ECOG_py
    EDF_py --> FD_py
    EDF_py --> GF_py
    EDF_py --> GEO_sp_py
    EDF_py --> IMMO_py
    EDF_py --> PCT_py
    EDF_py --> SEAS_py
    EDF_py --> UD_py

    ASTR_py --> MAP_py
    CLF_py --> PLOT_py
    ECOG_py --> MAP_py
    GF_py --> MAP_py
    IMMO_py --> PLOT_py
    SEAS_py --> PLOT_py
    FD_py --> PLOT_py
    UD_py --> MAP_py

    %% Entry Points orchestrate flow
    RELOC_py --> ER_py
    RELOC_py --> ASTR_py
    RELOC_py --> MAP_py
    TRAJ_py --> RAS_py
    TRAJ_py --> GF_py
    TRAJ_py --> PLOT_py

    %% Notebooks use layers
    NB -.-> ER_py
    NB -.-> EDF_py
    NB -.-> ASTR_py
    NB -.-> MAP_py
    NB -.-> PLOT_py

    %% Docs reference API
    DOC_RST -.-> ER_py
    DOC_RST -.-> EDF_py
    DOC_RST -.-> ASTR_py

    %% CI/CD support
    GH_WF -.->|run tests/docs| NB
    GH_WF -.->|build docs| DOC_RST
    GH_WF -.->|publish| PYPROJ

    PYPROJ -.-> RECIPE_yml
    RECIPE_yml -.-> ENV_yml

    %% Click Events
    click ER_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/io/earthranger.py"
    click ERU_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/io/earthranger_utils.py"
    click EEIO_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/io/eeio.py"
    click EETOOLS_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/io/eetools.py"
    click RAS_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/io/raster.py"
    click SMART_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/io/smartio.py"
    click IO_UTIL_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/io/utils.py"
    click DC_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/base/_dataclasses.py"
    click EDF_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/base/ecodataframe.py"
    click ST_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/base/straightrack.py"
    click BASE_UTIL_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/base/utils.py"
    click ASTR_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/astronomy.py"
    click CLF_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/classifier.py"
    click ECOG_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/ecograph.py"
    click FD_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/feature_density.py"
    click GF_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/geofence.py"
    click GEO_sp_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/geospatial.py"
    click IMMO_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/immobility.py"
    click PCT_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/percentile.py"
    click SEAS_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/seasons.py"
    click UD_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/analysis/UD/etd_range.py"
    click MAP_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/mapping/map.py"
    click PLOT_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/plotting/plot.py"
    click GEEMAP_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/contrib/geemap.py"
    click RELOC_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/relocations.py"
    click TRAJ_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/ecoscope/trajectory.py"
    click NB "https://github.com/wildlife-dynamics/ecoscope/tree/master/doc/source/notebooks/"
    click DOC_RST "https://github.com/wildlife-dynamics/ecoscope/blob/master/doc/source/index.rst"
    click GUI_md "https://github.com/wildlife-dynamics/ecoscope/blob/master/doc/source/ecoscope_gui.md"
    click CONF_py "https://github.com/wildlife-dynamics/ecoscope/blob/master/doc/source/conf.py"
    click GH_WF "https://github.com/wildlife-dynamics/ecoscope/tree/master/.github/workflows/"
    click RECIPE_yml "https://github.com/wildlife-dynamics/ecoscope/blob/master/publish/recipes/release/ecoscope.yaml"
    click PYPROJ "https://github.com/wildlife-dynamics/ecoscope/blob/master/pyproject.toml"
    click ENV_yml "https://github.com/wildlife-dynamics/ecoscope/blob/master/environment.yml"

    %% Styles
    classDef external fill:#a2d5c6,stroke:#333,stroke-width:1px
    classDef io fill:#90c2e7,stroke:#333,stroke-width:1px
    classDef base fill:#82c0cc,stroke:#333,stroke-width:1px
    classDef analysis fill:#b29dd9,stroke:#333,stroke-width:1px
    classDef mapping fill:#f5d76e,stroke:#333,stroke-width:1px
    classDef plotting fill:#f5d76e,stroke:#333,stroke-width:1px
    classDef contrib fill:#f8bbd0,stroke:#333,stroke-width:1px
    classDef docs fill:#ffe08a,stroke:#333,stroke-width:1px
    classDef cicd fill:#f386a1,stroke:#333,stroke-width:1px
```
