# rvalavi/blockcv architecture

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

- Interactive diagram: https://gitdiagram.com/rvalavi/blockcv
- Repository: https://github.com/rvalavi/blockcv

## Overview

blockCV is an R package for creating spatially or environmentally separated cross-validation folds and evaluating their suitability for spatial prediction. The main workflow is to provide spatial observations and optional raster or prediction-domain data, choose a fold strategy, then inspect fold balance, spatial separation, and environmental extrapolation; folds can also be visualised. Separate capabilities estimate spatial autocorrelation and explore block sizes. The README documents the feature relationships; the sampled source shows the registered C++ routines and their matrix helper, but not the R implementations or their internal calls.

Main entry points: [`R/cv_spatial.R`](https://github.com/rvalavi/blockcv/blob/master/R/cv_spatial.R) (Spatial blocks), [`R/cv_cluster.R`](https://github.com/rvalavi/blockcv/blob/master/R/cv_cluster.R) (Clustering folds), [`R/cv_group.R`](https://github.com/rvalavi/blockcv/blob/master/R/cv_group.R) (Group folds), [`R/cv_buffer.R`](https://github.com/rvalavi/blockcv/blob/master/R/cv_buffer.R) (Buffer folds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_folds["Fold construction"]
  node_cv_spatial["Spatial blocks<br/>[cv_spatial.R]"]
  node_cv_cluster["Clustering folds<br/>[cv_cluster.R]"]
  node_cv_group["Group folds<br/>[cv_group.R]"]
  node_cv_buffer["Buffer folds<br/>[cv_buffer.R]"]
  node_cv_nndm["LOO NNDM<br/>[cv_nndm.R]"]
  node_cv_knndm["K-fold NNDM<br/>[cv_knndm.R]"]
  node_fold_object["Fold results"]
end

subgraph group_diagnostics["Fold diagnostics"]
  node_cv_summary["Fold summary<br/>[cv_summary.R]"]
  node_cv_distance["Distance check<br/>[cv_distance.R]"]
  node_cv_similarity["Similarity check<br/>[cv_similarity.R]"]
end

subgraph group_scale["Spatial scale"]
  node_cv_spatial_autocor["Autocorrelation"]
  node_cv_block_size["Block-size explorer<br/>[cv_block_size.R]"]
end

subgraph group_visualization["Visualization"]
  node_cv_plot["Fold plots<br/>[cv_plot.R]"]
end

subgraph group_numerics["Numerical routines"]
  node_rcpp_exports["Rcpp dispatch<br/>[RcppExports.cpp]"]
  node_nndm_cpp["NNDM routine<br/>[nndm.cpp]"]
  node_similarity_cpp["Similarity routine<br/>[similarity.cpp]"]
  node_matrix_helper["Matrix helper"]
end

node_analyst(("Analyst"))
node_spatial_data(("Spatial inputs"))

node_analyst -->|"chooses strategy"| node_cv_spatial
node_analyst -->|"chooses strategy"| node_cv_cluster
node_analyst -->|"chooses strategy"| node_cv_group
node_analyst -->|"chooses strategy"| node_cv_buffer
node_analyst -->|"chooses strategy"| node_cv_nndm
node_analyst -->|"chooses strategy"| node_cv_knndm
node_spatial_data -->|"supplies observations"| node_cv_spatial
node_spatial_data -->|"supplies observations"| node_cv_cluster
node_spatial_data -->|"supplies observations"| node_cv_group
node_spatial_data -->|"supplies observations"| node_cv_buffer
node_spatial_data -->|"supplies prediction domain"| node_cv_nndm
node_spatial_data -->|"supplies prediction domain"| node_cv_knndm
node_cv_spatial -->|"creates folds"| node_fold_object
node_cv_cluster -->|"creates folds"| node_fold_object
node_cv_group -->|"creates folds"| node_fold_object
node_cv_buffer -->|"creates folds"| node_fold_object
node_cv_nndm -->|"creates folds"| node_fold_object
node_cv_knndm -->|"creates folds"| node_fold_object
node_fold_object -->|"summarised by"| node_cv_summary
node_fold_object -->|"checked by"| node_cv_distance
node_fold_object -->|"checked by"| node_cv_similarity
node_fold_object -->|"visualised by"| node_cv_plot
node_analyst -->|"explores scale"| node_cv_spatial_autocor
node_analyst -->|"explores scale"| node_cv_block_size
node_rcpp_exports -->|"dispatches to"| node_nndm_cpp
node_rcpp_exports -->|"dispatches to"| node_similarity_cpp
node_nndm_cpp -->|"uses"| node_matrix_helper
node_similarity_cpp -->|"uses"| node_matrix_helper

click node_cv_spatial "https://github.com/rvalavi/blockcv/blob/master/R/cv_spatial.R"
click node_cv_cluster "https://github.com/rvalavi/blockcv/blob/master/R/cv_cluster.R"
click node_cv_group "https://github.com/rvalavi/blockcv/blob/master/R/cv_group.R"
click node_cv_buffer "https://github.com/rvalavi/blockcv/blob/master/R/cv_buffer.R"
click node_cv_nndm "https://github.com/rvalavi/blockcv/blob/master/R/cv_nndm.R"
click node_cv_knndm "https://github.com/rvalavi/blockcv/blob/master/R/cv_knndm.R"
click node_cv_summary "https://github.com/rvalavi/blockcv/blob/master/R/cv_summary.R"
click node_cv_distance "https://github.com/rvalavi/blockcv/blob/master/R/cv_distance.R"
click node_cv_similarity "https://github.com/rvalavi/blockcv/blob/master/R/cv_similarity.R"
click node_cv_plot "https://github.com/rvalavi/blockcv/blob/master/R/cv_plot.R"
click node_cv_spatial_autocor "https://github.com/rvalavi/blockcv/blob/master/R/cv_spatial_autocor.R"
click node_cv_block_size "https://github.com/rvalavi/blockcv/blob/master/R/cv_block_size.R"
click node_rcpp_exports "https://github.com/rvalavi/blockcv/blob/master/src/RcppExports.cpp"
click node_nndm_cpp "https://github.com/rvalavi/blockcv/blob/master/src/nndm.cpp"
click node_similarity_cpp "https://github.com/rvalavi/blockcv/blob/master/src/similarity.cpp"
click node_matrix_helper "https://github.com/rvalavi/blockcv/blob/master/src/Lightweight_matrix.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cv_spatial,node_cv_cluster,node_cv_group,node_cv_buffer,node_cv_nndm,node_cv_knndm,node_fold_object toneBlue
class node_cv_summary,node_cv_distance,node_cv_similarity toneAmber
class node_cv_spatial_autocor,node_cv_block_size toneMint
class node_cv_plot toneRose
class node_rcpp_exports,node_nndm_cpp,node_similarity_cpp,node_matrix_helper,node_analyst,node_spatial_data toneIndigo
```

## Components

### Fold construction

- [Spatial blocks](https://github.com/rvalavi/blockcv/blob/master/R/cv_spatial.R): `R/cv_spatial.R`
- [Clustering folds](https://github.com/rvalavi/blockcv/blob/master/R/cv_cluster.R): `R/cv_cluster.R`
- [Group folds](https://github.com/rvalavi/blockcv/blob/master/R/cv_group.R): `R/cv_group.R`
- [Buffer folds](https://github.com/rvalavi/blockcv/blob/master/R/cv_buffer.R): `R/cv_buffer.R`
- [LOO NNDM](https://github.com/rvalavi/blockcv/blob/master/R/cv_nndm.R): `R/cv_nndm.R`
- [K-fold NNDM](https://github.com/rvalavi/blockcv/blob/master/R/cv_knndm.R): `R/cv_knndm.R`
- **Fold results**

### Fold diagnostics

- [Fold summary](https://github.com/rvalavi/blockcv/blob/master/R/cv_summary.R): `R/cv_summary.R`
- [Distance check](https://github.com/rvalavi/blockcv/blob/master/R/cv_distance.R): `R/cv_distance.R`
- [Similarity check](https://github.com/rvalavi/blockcv/blob/master/R/cv_similarity.R): `R/cv_similarity.R`

### Spatial scale

- [Autocorrelation](https://github.com/rvalavi/blockcv/blob/master/R/cv_spatial_autocor.R): `R/cv_spatial_autocor.R`
- [Block-size explorer](https://github.com/rvalavi/blockcv/blob/master/R/cv_block_size.R): `R/cv_block_size.R`

### Visualization

- [Fold plots](https://github.com/rvalavi/blockcv/blob/master/R/cv_plot.R): `R/cv_plot.R`

### Numerical routines

- [Rcpp dispatch](https://github.com/rvalavi/blockcv/blob/master/src/RcppExports.cpp): `src/RcppExports.cpp`
- [NNDM routine](https://github.com/rvalavi/blockcv/blob/master/src/nndm.cpp): `src/nndm.cpp`
- [Similarity routine](https://github.com/rvalavi/blockcv/blob/master/src/similarity.cpp): `src/similarity.cpp`
- [Matrix helper](https://github.com/rvalavi/blockcv/blob/master/src/Lightweight_matrix.h): `src/Lightweight_matrix.h`

### Other components

- **Analyst**
- **Spatial inputs**

## Connections

- Analyst → Spatial blocks: chooses strategy (evidence: `README.md`)
- Analyst → Clustering folds: chooses strategy (evidence: `README.md`)
- Analyst → Group folds: chooses strategy (evidence: `README.md`)
- Analyst → Buffer folds: chooses strategy (evidence: `README.md`)
- Analyst → LOO NNDM: chooses strategy (evidence: `README.md`)
- Analyst → K-fold NNDM: chooses strategy (evidence: `README.md`)
- Spatial inputs → Spatial blocks: supplies observations (evidence: `README.md`)
- Spatial inputs → Clustering folds: supplies observations (evidence: `README.md`)
- Spatial inputs → Group folds: supplies observations (evidence: `README.md`)
- Spatial inputs → Buffer folds: supplies observations (evidence: `README.md`)
- Spatial inputs → LOO NNDM: supplies prediction domain (evidence: `README.md`)
- Spatial inputs → K-fold NNDM: supplies prediction domain (evidence: `README.md`)
- Spatial blocks → Fold results: creates folds (evidence: `README.md`)
- Clustering folds → Fold results: creates folds (evidence: `README.md`)
- Group folds → Fold results: creates folds (evidence: `README.md`)
- Buffer folds → Fold results: creates folds (evidence: `README.md`)
- LOO NNDM → Fold results: creates folds (evidence: `README.md`)
- K-fold NNDM → Fold results: creates folds (evidence: `README.md`)
- Fold results → Fold summary: summarised by (evidence: `README.md`)
- Fold results → Distance check: checked by (evidence: `README.md`)
- Fold results → Similarity check: checked by (evidence: `README.md`)
- Fold results → Fold plots: visualised by (evidence: `README.md`)
- Analyst → Autocorrelation: explores scale (evidence: `README.md`)
- Analyst → Block-size explorer: explores scale (evidence: `README.md`)
- Rcpp dispatch → NNDM routine: dispatches to (evidence: `src/RcppExports.cpp`)
- Rcpp dispatch → Similarity routine: dispatches to (evidence: `src/RcppExports.cpp`)
- NNDM routine → Matrix helper: uses (evidence: `src/nndm.cpp`)
- Similarity routine → Matrix helper: uses (evidence: `src/similarity.cpp`)
