How r-spatialecology/landscapemetrics works
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.