Getting Started with XGeoRTR

XGeoRTR is explainable geometry backend infrastructure for workflows that need portable analytic state. It standardizes analytic outputs into xgeo_state objects with:

geometry
attributes
indices
selection
level-of-detail summaries
selected backend tables
metadata

Packages such as shapViz3D, rTDA3D, and renderer frontends consume this backend state downstream. XGeoRTR does not include use-case presentation code or front-end adapters.

Create an `xgeo_state`

library(XGeoRTR)

demo_path <- system.file("extdata", "spatial_demo.csv", package = "XGeoRTR")
demo_tbl <- utils::read.csv(demo_path, stringsAsFactors = FALSE)

state <- as_xgeo_state(
  demo_tbl,
  x_col = "x",
  y_col = "y",
  z_col = "z",
  value_col = "value",
  feature_col = "feature",
  method = "spatial-field-demo",
  meta = list(source = "synthetic-demo", sample_id = "grid-01")
)

state
#> <xgeo_state>
#>   structure:    spatial
#>   method:       spatial-field-demo
#>   points:       16
#>   features:     16
#>   embeddings:   1 (active: spatial)
#>   diagnostics:  0
#>   lod bundles:  0
summary(state)
#> <summary.xgeo_state>
#>   structure:      spatial
#>   method:         spatial-field-demo
#>   points:         16
#>   features:       16
#>   explanations:   16
#>   embeddings:     1 (active: spatial)
#>   diagnostics:    0 (active: none)
#>   lod bundles:    0 (active: none)
#>   selected points:0
#>   selected feats: 0

Compute backend state operators

state <- compute_xgeo_embedding(state, method = "pca", source = "points", dims = 2)
state <- set_active_embedding(state, "pca_points")
state <- compute_xgeo_diagnostics(state, embedding = "pca_points", source = "points", k = 3)
state <- build_xgeo_lod(state, embedding = "pca_points", levels = c(8L, 16L), auto_threshold = 10L)
state <- set_xgeo_selection(state, point_ids = state$indices$point_ids[[1]])

summary(state)
#> <summary.xgeo_state>
#>   structure:      spatial
#>   method:         spatial-field-demo
#>   points:         16
#>   features:       16
#>   explanations:   16
#>   embeddings:     2 (active: pca_points)
#>   diagnostics:    1 (active: diagnostics_pca_points_points)
#>   lod bundles:    1 (active: density_grid_pca_points)
#>   selected points:1
#>   selected feats: 0

Access backend-neutral fields

names(xgeo_geometry(state))
#> [1] "points"
names(xgeo_attributes(state))
#>  [1] "explanations" "point_meta"   "feature_meta" "predictions"  "uncertainty" 
#>  [6] "embeddings"   "diagnostics"  "baseline"     "method"       "structure"
names(xgeo_indices(state))
#> [1] "point_ids"   "feature_ids"
xgeo_selection(state)
#> $point_ids
#> [1] "point_1"
#> 
#> $features
#> character(0)
names(xgeo_metadata(state))
#> [1] "source"    "sample_id"

Build selected backend tables

long_tbl <- xgeo_explanation_table(state)
point_tbl <- xgeo_point_values(state)
grid <- xgeo_regular_grid(point_tbl)

utils::head(long_tbl)
#>   point_id  feature value x y z    label
#> 1  point_1 cell_1_1  0.65 1 1 0 cell_1_1
utils::head(point_tbl)
#>   point_id x y z value
#> 1  point_1 1 1 0  0.65
names(grid)
#> [1] "x" "y" "z"

Downstream use-case packages should consume these public tables rather than internal ingestion objects.

Downstream consumers

shapViz3D can consume explanation and point-value tables for Shapley-oriented workflows. rTDA3D can consume point and grid summaries for topology-oriented workflows. Renderer frontends such as ggWebGL can consume xgeo_state through their own adapter contracts. Those packages own presentation, interaction, and front-end behavior.

Downstream use-case consumers

XGeoRTR stops at backend state and backend tables. It does not ship use-case-specific presentation assets. SHAP semantics belong downstream in a Shapley-oriented package, topology semantics belong downstream in a topology-oriented package, and display orchestration belongs in renderer frontends such as ggWebGL.

The backend-only example below shows the intended downstream-consumption pattern:

source("inst/examples/downstream_shapviz3d_state_tables.R")

When the sibling shapViz3D repository is available, that example reads the three deterministic evidence CSVs from shapViz3D, builds xgeo_state objects, applies selection, computes optional embedding/diagnostic/LOD state, and emits only backend tables. When the downstream repo is unavailable, it falls back to the bundled spatial_demo.csv so the example still runs without renderer or SHAP-package dependencies.

Write and reload state

json_file <- tempfile(fileext = ".json")
write_xgeo_state(state, json_file)
restored <- read_xgeo_state(json_file)

restored$attributes$embeddings$active
#> [1] "pca_points"

Package boundary

XGeoRTR exposes backend state, derived tables, and serialized state exchange. It does not expose scene/camera/viewport APIs or renderer-specific orchestration.

Create an xgeo_state