# r-spatialecology/landscapemetrics architecture

> Architecture diagram of the GitHub repository r-spatialecology/landscapemetrics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/r-spatialecology/landscapemetrics
- Repository: https://github.com/r-spatialecology/landscapemetrics

## Overview

Based on your analysis of the file structure and the README, this project is an R package—specifically, an open‐source tool designed to compute landscape metrics for categorical landscape patterns. It serves as a reproducible and tidy workflow that offers functions to calculate a wide range of metrics (patch, class, and landscape level) similar to what FRAGSTATS does, and integrates performance-critical routines via C++ (using Rcpp).

##### Main Components
- R Interface Layer:
- This is where the majority of the functionality lies (the R/ directory). Each script implements functions that follow a naming convention (e.g., lsm_p_enn, lsm_c_area_cv, etc.). They’re the entry point for users.
- “utility functions” (prefixed with get_ and show_) that support data processing and visualization.
- C++ Integration Layer (Native Code):
- The src/ directory holds the C++ source files that accelerate the core spatial computations (e.g., rcpp_get_boundaries.cpp, rcpp_get_coocurrence_matrix.cpp, etc.). These are connected to the R functions to provide performance benefits.
- Testing and Quality Assurance:
- The tests folder (and testthat subdirectories) and continuous integration workflow files (.github/workflows) ensure code reliability and coverage.
- Documentation and Vignettes:
- Documentation is maintained in the vignettes, man, and README files. These guide usage and explain the design.
- Data and Examples:
- The data-raw/ and data/ directories hold example landscapes and reference data used for testing and demonstration.
- Configuration and Build:
- Files like DESCRIPTION, NAMESPACE, .Rbuildignore, and other CI/CD configuration files outline packaging requirements and deployment steps.

##### Relationships and Data Flow
- User Input → Data Handling: The user provides a spatial input (via terra’s SpatRaster or stars objects).
- Validation & Preprocessing: Data is passed to helper functions like check_landscape() to ensure proper resolution and format.
- Metric Calculation: The main functions (beginning with lsm_) compute metrics. They are organized on levels (patch, class, landscape) and are implemented in R, but delegate heavy computation to the C++ layer when necessary.
- Wrapping & Aggregation: The calculate_lsm() wrapper collects individual metric computations and returns a tidy tibble.
- Visualization: Utility functions (starting with show_) use the computed metrics to generate plots or visual outputs.
- Testing & CI/CD: Automated tests via testthat ensure that changes in the functions, including the native C++ routines, continue to produce the expected outputs. Integration with GitHub Actions (in the .github/workflows files) supports continuous testing and deployment.

##### Architectural Patterns & Design Principles
- Modular design: Functions are broken down into many small R scripts (each file targeting one metric or helper functionality) and further segmented into C++ modules.
- Extensibility: There is an evident pattern (a consistent naming scheme and modular file placement) that makes it straightforward to contribute new metrics or enhancements.
- Testing: A robust test suite is integrated in the tests directory, emphasizing the package’s commitment to reliability.

##### Key Technologies and Components
- R: The primary language used for exposing the API and tying everything together.
- Rcpp: For bridging R with native C++ to improve performance.
- terra and sf (and optionally stars): These spatial libraries are central in handling raster data.
- GitHub Actions and Codecov: They ensure continuous integration and code coverage.
- CRAN-Based Packaging: Ensured by the project’s inclusion of DESCRIPTION, NAMESPACE, and associated documentation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Flow
    Input("User Input (Spatial Data)"):::input
    R_Validation("Data Validation (check_landscape)"):::rlayer
    R_GET("Utility Functions (get_*)"):::rlayer
    R_LSM("Metric Calculation (lsm_* functions)"):::rlayer
    WrapperAgg("Wrapper Aggregation (calculate_lsm)"):::rlayer
    R_SHOW("Visualization (show_* functions)"):::rlayer

    %% C++ Integration Layer
    CPP_Boundaries("Rcpp: Boundaries"):::cpp
    CPP_Neighborhood("Rcpp: Neighborhood"):::cpp

    %% Supporting Layers
    Testing("Unit Tests (testthat)"):::testing
    CI("CI Workflows"):::testing
    DOC("Documentation/Vignettes"):::doc
    READ("README & Manuals"):::doc
    DataRaw("Raw Data Examples"):::data
    DataProc("Processed Data"):::data
    Desc("DESCRIPTION"):::config
    Namespace("NAMESPACE"):::config
    RBuild(".Rbuildignore"):::config
    License("LICENSE"):::config

    %% Data Flow Connections
    Input -->|"provides"| R_Validation
    R_Validation -->|"preprocesses"| R_GET
    R_GET -->|"triggers"| R_LSM
    R_LSM -->|"aggregates"| WrapperAgg
    WrapperAgg -->|"visualizes"| R_SHOW

    %% C++ Delegation
    R_LSM -->|"delegates"| CPP_Boundaries
    R_LSM -->|"delegates"| CPP_Neighborhood

    %% Testing and CI Support
    WrapperAgg -->|"validated_by"| Testing
    WrapperAgg -->|"validated_by"| CI

    %% Documentation and Manuals
    R_SHOW -->|"documented_in"| DOC
    R_SHOW -->|"documented_in"| READ

    %% Configuration and Build Files (supporting overall lifecycle)
    WrapperAgg -->|"config_in"| Desc
    WrapperAgg -->|"config_in"| Namespace
    WrapperAgg -->|"config_in"| RBuild
    WrapperAgg -->|"config_in"| License

    %% Data and Examples (used for testing/demonstration)
    Input -.->|"sample_data"| DataRaw
    Input -.->|"sample_data"| DataProc

    %% Styles
    classDef input fill:#f9f,stroke:#333,stroke-width:2px;
    classDef rlayer fill:#bbf,stroke:#333,stroke-width:2px;
    classDef cpp fill:#cfc,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffc,stroke:#333,stroke-width:2px;
    classDef doc fill:#fcf,stroke:#333,stroke-width:2px;
    classDef data fill:#cff,stroke:#333,stroke-width:2px;
    classDef config fill:#fdd,stroke:#333,stroke-width:2px;

    %% Click Events for R Interface Layer
    click R_LSM "https://github.com/r-spatialecology/landscapemetrics/blob/main/R/lsm_p_area.R"
    click R_GET "https://github.com/r-spatialecology/landscapemetrics/blob/main/R/get_boundaries.R"
    click R_SHOW "https://github.com/r-spatialecology/landscapemetrics/blob/main/R/show_lsm.R"

    %% Click Events for C++ Integration Layer
    click CPP_Boundaries "https://github.com/r-spatialecology/landscapemetrics/blob/main/src/rcpp_get_boundaries.cpp"
    click CPP_Neighborhood "https://github.com/r-spatialecology/landscapemetrics/blob/main/src/rcpp_create_neighborhood.cpp"

    %% Click Events for Testing and CI
    click Testing "https://github.com/r-spatialecology/landscapemetrics/tree/main/tests/testthat"
    click CI "https://github.com/r-spatialecology/landscapemetrics/blob/main/.github/workflows/R-CMD-check.yaml"

    %% Click Events for Documentation and Vignettes
    click DOC "https://github.com/r-spatialecology/landscapemetrics/tree/main/vignettes/"
    click READ "https://github.com/r-spatialecology/landscapemetrics/blob/main/README.md"

    %% Click Events for Data and Examples
    click DataRaw "https://github.com/r-spatialecology/landscapemetrics/blob/main/data-raw/01_example_landscape.R"
    click DataProc "https://github.com/r-spatialecology/landscapemetrics/blob/main/data/augusta_nlcd.rda"

    %% Click Events for Configuration and Build Files
    click Desc "https://github.com/r-spatialecology/landscapemetrics/tree/main/DESCRIPTION"
    click Namespace "https://github.com/r-spatialecology/landscapemetrics/tree/main/NAMESPACE"
    click RBuild "https://github.com/r-spatialecology/landscapemetrics/blob/main/.Rbuildignore"
    click License "https://github.com/r-spatialecology/landscapemetrics/blob/main/LICENSE.md"
```
