SPATA2

https://themilolab.github.io/SPATA2/
Admin
SPATA2 is a software package for inferring histology-associated gene expression gradients in spatial...
Tokens:342,082
Snippets:2,959
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Load SPATA2 and Example Data

Source: https://themilolab.github.io/SPATA2/articles/dimensional-reduction.html

Loads necessary R packages and the inbuilt example dataset for SPATA2. Ensure packages are installed before running.

```r
library(SPATA2)
library(SPATAData)
library(tidyverse)

data("example_data")
object_t269 <- loadExampleObject(sample_name = "UKF269T", process = TRUE, meta = TRUE)

# left plot
plotImage(object_t269)

# right plot
plotSurface(object_t269, color_by = "histology")
```

--------------------------------

### Load Example Object and Get Annotation IDs

Source: https://themilolab.github.io/SPATA2/reference/getSpatAnnBarcodes.html

Loads an example SPATA2 object and retrieves all spatial annotation IDs. This is a common setup step before extracting barcodes.

```r
library(SPATA2)
library(tidyverse)

object <- loadExampleObject("UKF313T", process = T, meta = T)

# show all IDs
getSpatAnnIds(object)
```

--------------------------------

### Load Example Object and Get Assay Names

Source: https://themilolab.github.io/SPATA2/reference/getSignatureNames.html

Loads an example SPATA2 object and displays its assay names. This is useful for understanding the available molecular data modalities within the object.

```R
library(SPATA2)

object <- loadExampleObject("UKF269T", process = TRUE)

# only one assay exists...
getAssayNames(object)

# ... which is the default assay
activeAssay(object)
```

--------------------------------

### Load SPATA2 Example Object

Source: https://themilolab.github.io/SPATA2/articles/individual-visiumHD-resolution.html

Loads the necessary libraries and an example VisiumHD object for demonstration purposes.

```R
library(SPATA2)
library(SPATAData)
library(tidyverse)
library(patchwork)

# Load the SPATA2 example object
object <- downloadSpataObject("HumanPancreasHD", update = FALSE)

# show object
object
```

--------------------------------

### Load example data and object

Source: https://themilolab.github.io/SPATA2/reference/ggpLayerAxesSI.html

Loads the example data and a SPATA2 object for demonstration purposes.

```R
library(SPATA2)

data("example_data")

object <- loadExampleObject("UKF275T")
```

--------------------------------

### Install SPATAData and confuns Packages

Source: https://themilolab.github.io/SPATA2/articles/spata-data.html

Install the SPATAData package from GitHub. Also install the confuns package if it is not already present.

```r
devtools::install_github(repo = "theMILOlab/SPATAData")

# and if you have not already:  
devtools::install_github("kueckelj/confuns")
```

--------------------------------

### Load Example Data in SPATA2

Source: https://themilolab.github.io/SPATA2/articles/adding-data.html

Loads the inbuilt example data for SPATA2. Ensure SPATA2 and tidyverse are loaded.

```r
library(SPATA2)
library(tidyverse)

# load SPATA2 inbuilt example data
object_t269 <- loadExampleObject("UKF269T")
```

--------------------------------

### Example: Adding a Spatial Trajectory with Start and End Coordinates

Source: https://themilolab.github.io/SPATA2/reference/addSpatialTrajectory.html

This example demonstrates how to add a spatial trajectory to a SPATA2 object using the 'start' and 'end' arguments. It also shows how to plot the added trajectory.

```r
library(SPATA2)
library(tidyverse)

data("example_data")

object <- example_data$object_UKF275T_diet

object <-   addSpatialTrajectory(
     object = object,
     id = "cross_sample",
     width = "1.5mm",
     start = c(x = "1.35mm", y = "4mm"),
     end = c(x = "6.25mm", y = "4mm"),
     overwrite = TRUE
   )

 plotSpatialTrajectories(object, ids = "cross_sample")
```

--------------------------------

### Load and Display Example SPATA2 Object

Source: https://themilolab.github.io/SPATA2/articles/molecular-variables.html

Loads the inbuilt UKF269T example object and displays its summary. Ensure SPATA2 and tidyverse are loaded.

```r
# load required packages
library(SPATA2)
library(tidyverse)

# load SPATA2 inbuilt example data
object_t269 <- loadExampleObject("UKF269T", process = TRUE)

show(object_t269)

```

--------------------------------

### Example: Get Active Assay Name

Source: https://themilolab.github.io/SPATA2/reference/activateAssay.html

Demonstrates how to retrieve the name of the currently active assay from a SPATA2 object. Ensure the `example_data` is loaded and the object is initialized.

```R
data("example_data")

object <- example_data$object_UKF275T_diet

activeAssay(object)
```

--------------------------------

### Install SPATA2 and Related Packages from GitHub

Source: https://themilolab.github.io/SPATA2/articles/installation.html

Installs SPATA2 and its associated data package from GitHub using devtools. Ensures devtools is installed first if not already present.

```R
if(!requireNamespace("devtools", quietly = TRUE)){
  
  install.packages("devtools")
  
}

devtools::install_github(repo = "kueckelj/confuns")
devtools::install_github(repo = "theMILOlab/SPATAData")
devtools::install_github(repo = "theMILOlab/SPATA2")
```

--------------------------------

### Load SPATA2 and Example Data

Source: https://themilolab.github.io/SPATA2/articles/using-spatial-annotations.html

Loads the necessary SPATA2 and tidyverse packages, and then loads an example SPATA2 object for demonstration.

```R
library(SPATA2)
library(tidyverse)

# load SPATA2 inbuilt data
object_t313 <- loadExampleObject("UKF313T", process = TRUE, meta = TRUE)
```

--------------------------------

### Example: Downloading and Writing SPATA2 Object Image

Source: https://themilolab.github.io/SPATA2/reference/writeImage.html

Demonstrates how to download a SPATA2 object and then write its associated image to disk. This example illustrates a common workflow for managing image data with SPATA2.

```R
library(SPATA2)
library(SPATAData)

object <- downloadSpataObject("UKF313T")

```

--------------------------------

### Load Example Data and Set Default Display

Source: https://themilolab.github.io/SPATA2/articles/image-handling.html

Loads an example SPATA2 object and sets default display options for images and point size.

```r
library(SPATA2)
library(SPATAData)
library(tidyverse)

# load SPATA2 inbuilt example data
object_t275 <- loadExampleObject("UKF275T")
object_t275 <- setDefault(object_t275, display_image = TRUE, pt_size = 1.5)
```

--------------------------------

### Load Example Data

Source: https://themilolab.github.io/SPATA2/reference/example_data.html

Loads the example_data object, which is a list containing various components for SPATA2 tutorials. This data is essential for running and reproducing examples.

```R
data(example_data)
```

--------------------------------

### Load a Simple Example SPATA2 Object

Source: https://themilolab.github.io/SPATA2/reference/loadExampleObject.html

Loads a basic example SPATA2 object using the 'UKF269T' sample. This is useful for initial exploration without processing.

```r
library(SPATA2)

# simply load
object <- loadExampleObject(sample_name = "UKF269T")
```

--------------------------------

### Load Example Object and Create Segmentation

Source: https://themilolab.github.io/SPATA2/articles/spatial-segmentation.html

Load an example dataset and then create a spatial segmentation variable. This is a common workflow for testing and demonstrating segmentation features.

```r
object_t313 <- loadExampleObject("UKFT313", process = TRUE)

object_t313 <- createSpatialSegmentation(object_t313)
```

--------------------------------

### Load Example Object and Plot Spatial Annotations

Source: https://themilolab.github.io/SPATA2/articles/spatial-annotation-screening.html

Loads an example SPATA2 object and visualizes specified spatial annotations. Ensure SPATA2 and tidyverse are loaded.

```r
library(SPATA2)
library(tidyverse)

# load SPATA2 inbuilt data and process
object_t313 <- loadExampleObject("UKF313T", process = TRUE, meta = TRUE)

necrotic_ids <- c("necrotic_area", "necrotic_edge", "necrotic_edge2")

plotSpatialAnnotations(object_t313, ids = necrotic_ids, nrow = 1)
```

--------------------------------

### Example Usage of ggpLayerExprEstimatesSAS

Source: https://themilolab.github.io/SPATA2/reference/ggpLayerExprEstimatesSAS.html

This example demonstrates how to use `ggpLayerExprEstimatesSAS` to visualize expression estimates. It involves loading example data, creating numeric annotations, and then plotting the surface with expression estimates and a scale bar.

```R
library(SPATA2)
library(tidyverse)

data("example_data")

object <- loadExampleObject("UKF275T")

object <- createNumericAnnotations(
  object = object,
  variable = "HM_HYPOXIA",
  threshold = "kmeans_high",
  id = "hypoxia_ann",
  force1 = TRUE
  )

plotSurface(object, color_by = "HM_HYPOXIA", outline = T, pt_clrsp = "Reds 3") +
 ggpLayerExprEstimatesSAS(object, ids = "hypoxia_ann", distance = "3mm") +
 ggpLayerScaleBarSI(object, sb_pos = c("3mm", "2mm"))
```

--------------------------------

### Load and Process Example SPATA2 Object with Meta Data

Source: https://themilolab.github.io/SPATA2/reference/loadExampleObject.html

Loads an example SPATA2 object, applies default processing steps, and includes additional meta data. This is suitable for analyses requiring pre-processed data.

```r
# load, process and add some meta data
object_proc <- loadExampleObject(sample_name = "UKF269T", process = TRUE, meta = TRUE)
```

--------------------------------

### Example: Plotting Trajectories by Histology

Source: https://themilolab.github.io/SPATA2/reference/plotSpatialTrajectories.html

Demonstrates plotting spatial trajectories, coloring points by 'histology' and using the 'npg' color palette. Requires loading SPATA2 and example data.

```r
library(SPATA2)

data("example_data")

object <- example_data$object_UKF269T_diet

plotSpatialTrajectories(object, color_by = "histology", pt_clrp = "npg", ids = "horizontal_mid")
```

--------------------------------

### Example Usage of createSpatialSegmentation

Source: https://themilolab.github.io/SPATA2/reference/createSpatialSegmentation.html

Demonstrates how to use the createSpatialSegmentation function with an example SPATA2 object. This code is typically run within an interactive session.

```r
library(SPATA2)
library(tidyverse)

data("example_data")

object <- example_data$object_UKF275T_diet

if(FALSE){

 object <- createSpatialSegmentation(object)

 }
```

--------------------------------

### Load SPATA2 Example Data and Plot Surface

Source: https://themilolab.github.io/SPATA2/articles/creating-spatial-trajectories.html

Loads example data using SPATA2 and visualizes the sample surface, optionally colored by histological classification. Ensure SPATA2 and SPATAData packages are loaded.

```R
library(SPATA2)
library(SPATAData)
library(tidyverse)

# load SPATA2 inbuilt example data
object_t269 <- loadExampleObject(sample_name = "UKF269T", process = TRUE, meta = TRUE)

# histology only
plotSurface(object_t269, pt_alpha = 0)

# colored by histological classification
plotSurface(object_t269, color_by = "histology")
```

--------------------------------

### Example Usage of computeMetaFeatures

Source: https://themilolab.github.io/SPATA2/reference/computeMetaFeatures.html

Demonstrates loading an example object, checking assay names, computing meta features for the 'gene' assay, and visualizing the results using plotSurface.

```r
library(SPATA2)

object <- loadExampleObject("UKF269T")

getAssayNames(object)

getMetaDf(object)

object <- computeMetaFeatures(object, asay_name = "gene")

getMetaDf(object)

plotSurface(object, color_by = "n_counts_gene")
```

--------------------------------

### Example Usage of computeCaptureArea

Source: https://themilolab.github.io/SPATA2/reference/computeCaptureArea.html

Demonstrates how to use the computeCaptureArea function with an existing SPATA2 object. This example is typically run within a development environment and is marked as dontrun.

```R
if (FALSE) { # \dontrun{
# Example usage:
object <- computeCaptureArea(object)
} # }
```

--------------------------------

### Load and Process Example Object

Source: https://themilolab.github.io/SPATA2/articles/plotting-surface.html

Loads an example object and processes it for spatial annotation and grouping. This is a prerequisite for most plotting functions.

```R
library(SPATA2)
library(tidyverse)

# load object and process for this tutorial
object_t313 <- 
  loadExampleObject("UKF313T", process = TRUE, meta = TRUE) %>%
  spatialAnnotationToGrouping(
    object = .,
    ids = c("necrotic_area", "necrotic_edge", "necrotic_edge2"),
    grouping_name = "histology", 
    inside = "necrotic",
    outside = "vivid"
    )

object_t313 <- setDefault(object_t313, display_image = FALSE)

plotImage(object_t313)
```

--------------------------------

### Basic Scatterplot Example

Source: https://themilolab.github.io/SPATA2/reference/plotScatterplot.html

Demonstrates how to create a basic scatterplot using the plotScatterplot function with specified variables. Ensure the SPATA2 library is loaded and example data is available.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF275T_diet

plotScatterplot(object, variables = c("HM_HYPOXIA", "METRN"))
```

--------------------------------

### Example Usage of runSeuratClustering

Source: https://themilolab.github.io/SPATA2/reference/runSeuratClustering.html

Demonstrates how to use the `runSeuratClustering` function with an example SPATA2 object and visualize the resulting clusters using `plotSurface`.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF269T_diet

object <- runSeuratClustering(object, name = "new_seurat_clst")

plotSurface(object, color_by = "new_seurat_clst")
```

--------------------------------

### Interactive Spatial Trajectory Creation Example

Source: https://themilolab.github.io/SPATA2/reference/createSpatialTrajectories.html

Demonstrates how to load example data and use the createSpatialTrajectories function to interactively draw trajectories. Requires the SPATA2 and tidyverse packages.

```r
library(SPATA2)
library(tidyverse)

data("example_data")

object <- example_data$object_UKF275T_diet

object <- createSpatialTrajectories(object)
```

--------------------------------

### Example Usage of plotSasHeatmap

Source: https://themilolab.github.io/SPATA2/reference/plotSasHeatmap.html

Demonstrates how to use plotSasHeatmap to visualize gene expression patterns. Requires loading SPATA2, ggplot2, and example data.

```r
library(SPATA2)
library(ggplot2)

data("example_data")

object <- example_data$object_UKF313T_diet

ids <- getSpatAnnIds(object, tags = c("necrotic", "compr"), test = "identical")

object <- normalizeCounts(object, activate = T)

# visualize with lines
plotSasLineplot(object, ids = ids, variables = c("VEGFA", "HM_HYPOXIA", "RCTM_TCR_SIGNALING", "CD74")) + 
  labs(x = "Distance to Necrosis")

# visualize with ridgeplots
plotSasRidgeplot(object, ids = ids, variables = c("VEGFA", "HM_HYPOXIA", "RCTM_TCR_SIGNALING", "CD74")) + 
  labs(x = "Distance to Necrosis")

# visualize with a heatmap
plotSasHeatmap(object, ids = ids, variables = c("VEGFA", "HM_HYPOXIA", "RCTM_TCR_SIGNALING", "CD74")) + 
  labs(x = "Distance to Necrosis")
```

--------------------------------

### Load SPATA2 Example Object

Source: https://themilolab.github.io/SPATA2/articles/spatial-segmentation.html

Loads the SPATA2 library and an example spatial transcriptomic object with metadata and processing enabled. Use this to begin working with SPATA2's built-in datasets.

```R
library(tidyverse)
library(SPATA2)

# load SPATA2 inbuilt data 
object_t269 <- loadExampleObject("UKF269T", meta = TRUE, process = TRUE)
```

--------------------------------

### Run Spatial Annotation Screening Example

Source: https://themilolab.github.io/SPATA2/reference/spatialAnnotationScreening.html

This example demonstrates how to run the `spatialAnnotationScreening` function. It includes steps for data loading, identifying tissue outlines, selecting spatial annotations and genes, and finally performing the screening.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF313T_diet

object <- identifyTissueOutline(object)

ids <- getSpatAnnIds(object, tags = c("necrotic", "compr"), test = "all")

# opt 1 prefiltering by SPARKX is recommended, but not required
object <- runSPARKX(object)
genes <- getSparkxGenes(object, threshold_pval = 0.05)

# opt 2
genes <- getGenes(object)

sas_out <-
 spatialAnnotationScreening(
   object = object,
   ids = ids,
   variables = genes,
   core = FALSE
   )

```

--------------------------------

### Example Usage of expandSpatialAnnotation

Source: https://themilolab.github.io/SPATA2/reference/expandSpatialAnnotation.html

Demonstrates how to use the `expandSpatialAnnotation` function to expand a spatial annotation and visualize the result. Ensure the SPATA2 and tidyverse libraries are loaded and example data is available.

```r
library(SPATA2)
library(tidyverse)

data("example_data")

object <- loadExampleObject("UKF275T")

plotImage(object) + ggpLayerSpatAnnOutline(object, ids = "vessel1", line_color = "red")
plotSpatialAnnotations(object, "vessel1")

object <- expandSpatialAnnotation(object, id = "vessel1", expand = "50um", new_id = "vessel1_exp")

plotSpatialAnnotations(object, ids = c("vessel1", "vessel1_exp"))
```

--------------------------------

### Example Usage of SPATA2 Plotting Functions

Source: https://themilolab.github.io/SPATA2/reference/plotStsLineplot.html

Demonstrates loading data, normalizing counts, and plotting trajectory data using `plotStsHeatmap`, `plotStsLineplot`, and `plotStsRidgeplot`. Requires the SPATA2 library and example data.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF269T_diet

object <- normalizeCounts(object, activate = TRUE)

genes <- c("EGFR", "MBP", "MAG", "SNAP25")

plotStsHeatmap(object, id = "horizontal_mid", variables = genes)

plotStsLineplot(object, id = "horizontal_mid", variables = genes)

plotStsRidgeplot(object, id = "horizontal_mid", variables = genes)

```

--------------------------------

### Get Image Dimensions

Source: https://themilolab.github.io/SPATA2/articles/initiation-and-preprocessing-customized.html

Retrieves the dimensions of a normalized resolution image from example data.

```R
# get an image from the example data (or read in your own)
img_normres <- example_data$img_normres

dim(img_normres)
```

--------------------------------

### Attempt to Get Protein Sets (Fails)

Source: https://themilolab.github.io/SPATA2/reference/getSignatureList.html

Illustrates an attempt to retrieve protein sets using `getProteinSetList`. This example is expected to fail if the object does not contain a 'protein' assay.

```R
# opt 4 - fails cause no 'protein' assay
protein_sets <- getProteinSetList(object)
```

--------------------------------

### Run BayesSpace Clustering with Automatic q Selection

Source: https://themilolab.github.io/SPATA2/reference/runBayesSpaceClustering.html

This example demonstrates how to run BayesSpace clustering and automatically select the optimal number of clusters (q) by testing values from 3 to 15. It then visualizes the log-likelihood values to help in understanding the clustering results.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF313T_diet

# tests options for q from 3 to 15 and picks the best
object <- runBayesSpaceClustering(object, name = "new_bspace", qs = 3:15)

plotLoglik(object)
```

--------------------------------

### Save SPATA2 Object Example

Source: https://themilolab.github.io/SPATA2/reference/saveSpataObject.html

Demonstrates how to set a directory and save a SPATA2 object. Use this when you need to persist your SPATA2 object to disk.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF269T_diet

getSpataDir(object) # fails, no directory set

# opt 1
object <- setSpataDir(object, directory_spata = "my_folder/object_UKF269T.RDS")

saveSpataObject(object)

# opt 2
object <- saveSpataObject(object, directory_spata = "my_folder/object_UKF269T.RDS")

getSpataDir(object)
```

--------------------------------

### Get center of a spatial annotation

Source: https://themilolab.github.io/SPATA2/reference/getSpatAnnCenter.html

Computes the x- and y-coordinates of the center of the outer border of a specified spatial annotation. Requires loading an example object and optionally plotting annotations.

```R
library(SPATA2)

object <- loadExampleObject("LMU_MCI")

plotSpatialAnnotations(object, unit = "px")

getSpatAnnCenter(object, id = "inj1")
```

--------------------------------

### Example Usage of getImageTransformations

Source: https://themilolab.github.io/SPATA2/reference/getImageTransformations.html

Demonstrates how to use `getImageTransformations` after aligning and resetting image transformations. It shows how to inspect the transformation instructions applied to an image.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF313T_diet

plotImage(object)

object <- alignImage(object, img_name = "lowres", angle = 90)

# note that $angle contains instructions to rotate the image to 90°
getImageTransformations(object, img_name = "lowres")

plotImage(object)

object <- resetImageTransformations(object, img_name = "lowres")

getImageTransformations(object, img_name = "lowres")

plotImage(object)
```

--------------------------------

### Get DEA Results for Tumor Histology

Source: https://themilolab.github.io/SPATA2/articles/dea.html

Retrieves differential gene expression results for the 'tumor' histology. This example shows default usage without specific filtering parameters.

```r
getDeaResultsDf(
  object = object_t269,
  across = "histology",
  across_subset = "tumor" # the group name(s) of interest
)
```

--------------------------------

### Get Spatial Annotation Tags Examples

Source: https://themilolab.github.io/SPATA2/reference/getSpatAnnTags.html

Demonstrates how to use `getSpatAnnTags` to retrieve unique spatial annotation tags. Use `simplify = FALSE` for a detailed list or `simplify = TRUE` (default) for a character vector.

```R
library(SPATA2)

data("example_data")

object <- loadExampleObject("LMU_MCI")

getSpatAnnTags(object, simplify = FALSE)
getSpatAnnTags(object)
```

--------------------------------

### Get Chromosome Regions Data Frame

Source: https://themilolab.github.io/SPATA2/reference/getChrRegionsDf.html

Use this function to extract a data frame containing start, end, and length information for chromosomal arms. Specify the desired format ('long' or 'wide') for the output.

```r
getChrRegionsDf(object, format = "long")
```

--------------------------------

### Running Spatial Trajectory Screening

Source: https://themilolab.github.io/SPATA2/reference/spatialTrajectoryScreening.html

This example demonstrates how to run the spatialTrajectoryScreening function. It first prepares the data by identifying tissue outlines and running SPARK-X to get significant genes, then plots the trajectories and finally performs the screening.

```R
library(SPATA2)

object <- example_data$object_UKF269T_diet

object <- identifyTissueOutline(object)

object <- runSPARKX(object)
genes <- getSparkxGenes(object, threshold_pval = 0.05)

id <- "horizontal_mid"

plotImage(object) +
  ggpLayerSpatialTrajectories(object, ids = id)

plotSpatialTrajectories(object, ids = id)

sts_out <-
  spatialTrajectoryScreening(
    object = object,
    id = id,
    variables = genes
    )

```

--------------------------------

### Example: Removing Genes with Zero Counts and Stress Genes

Source: https://themilolab.github.io/SPATA2/reference/removeMolecules.html

Demonstrates how to remove genes with zero counts and stress-related genes from a SPATA2 object. It shows the process of getting initial gene lists, applying the removal functions, and then checking the updated gene list.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF313T_diet

genes <- getGenes(object)
head(genes)
length(genes)

object <- removeGenesZeroCounts(object)
object <- removeGenesStress(object)

genes_new <- getGenes(object)
length(genes_new)
```

--------------------------------

### Install SPATA2 Dependencies from BiocManager

Source: https://themilolab.github.io/SPATA2/articles/installation.html

Installs essential R packages for SPATA2 from BiocManager. Ensures BiocManager is installed first if not already present.

```R
if(!requireNamespace("BiocManager", quietly = TRUE)){
  
  install.packages("BiocManager")
      
}

BiocManager::install(c('BiocGenerics', 'DelayedArray', 'DelayedMatrixStats',
                       'limma', 'S4Vectors', 'SingleCellExperiment',
                       'SummarizedExperiment', 'batchelor', 'Matrix.utils', 'EBImage'))
```

--------------------------------

### Get Valid Color Spectra

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid color spectra names. Set flatten to FALSE to get a named list.

```R
validColorSpectra(flatten = FALSE)
```

--------------------------------

### Example Usage of read_matrix_from_folder

Source: https://themilolab.github.io/SPATA2/reference/read_matrix_from_folder.html

Demonstrates how to use the read_matrix_from_folder function. Ensure the specified directory contains the required matrix, barcodes, and features files.

```R
if (FALSE) { # \dontrun{
  matrix_dir <- "path/to/matrix/folder"
  matrix <- read_matrix_from_folder(matrix_dir)
  print(matrix)
} # }
```

--------------------------------

### Get Valid Color Palettes

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid color palette names. Set flatten to FALSE to get a named list.

```R
validColorPalettes(flatten = FALSE)
```

--------------------------------

### Generate Mosaic Plot with Seurat Clusters and Bayes Space

Source: https://themilolab.github.io/SPATA2/reference/plotMosaicplot.html

Example of using plotMosaicplot to visualize the relationship between 'seurat_clusters' and 'bayes_space' from an example SPATA2 object. Requires the SPATA2 library and example data.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF275T_diet

plotMosaicPlot(object, grouping = "seurat_clusters", fill_by = "bayes_space")
```

--------------------------------

### Example Usage of ggpLayerHorizonSAS with plotSurface

Source: https://themilolab.github.io/SPATA2/reference/ggpLayerHorizonSAS.html

This example demonstrates how to use ggpLayerHorizonSAS in conjunction with plotSurface to visualize spatial data with a screening horizon. It requires loading an example object and creating numeric annotations.

```r
library(SPATA2)
library(tidyverse)

object <- loadExampleObject("UKF275T")

object <- createNumericAnnotations(
  object = object,
  variable = "HM_HYPOXIA",
  threshold = "kmeans_high",
  id = "hypoxia_ann",
  force1 = TRUE
  )

plotSurface(object, color_by = "HM_HYPOXIA", outline = T, pt_clrsp = "Reds 3") +
 ggpLayerHorizonSAS(object, id = "hypoxia_ann", distance = "3mm") +
 ggpLayerScaleBarSI(object, sb_pos = c("3mm", "2mm"))
```

--------------------------------

### Example: Activating and Plotting with Different Matrices

Source: https://themilolab.github.io/SPATA2/reference/activateMatrix.html

Demonstrates how to normalize counts, activate a specific matrix, and then plot surface data colored by a feature, updating the plot subtitle to show the active matrix name. This helps visualize how different matrices affect downstream analysis.

```R
library(SPATA2)
library(ggplot2)

data("example_data")

object <- example_data$object_UKF275T_diet

object <- normalizeCounts(object, mtr_name = "LogNormalize")

p1 <- plotSurface(object, color_by = "METRN") + labs(subtitle = activeMatrix(object))

object <- activateMatrix(object, mtr_name = "LogNormalize")

p2 <- plotSurface(object, color_by = "METRN") + labs(subtitle = activeMatrix(object))

plot(p1)
plot(p2)
```

--------------------------------

### Get Valid Units

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid general unit names.

```R
validUnits()
```

--------------------------------

### Get Valid Model Names

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid model names.

```R
validModelNames()
```

--------------------------------

### Example: Tagging Spatial Annotations

Source: https://themilolab.github.io/SPATA2/reference/tagSpatialAnnotations.html

Demonstrates how to use tagSpatialAnnotations to add tags to spatial annotations. It shows the state before and after tagging.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF313T_diet

plotSpatialAnnotations(object)
getSpatAnnTags(object, simplify = FALSE)

object <- tagSpatialAnnotations(object, ids = c("necrotic_edge", "necrotic_edge2"), tags = "edge")

getSpatAnnTags(object, simplify = FALSE)
```

--------------------------------

### Running Kmeans Clustering Example

Source: https://themilolab.github.io/SPATA2/reference/runKmeansClustering.html

This example demonstrates how to use the runKmeansClustering function. It first runs PCA and then applies K-means clustering to the SPATA2 object with specified cluster counts and principal components. Finally, it retrieves the names of the features to show the newly added clustering results.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF269T_diet

object <- runPCA(object, n_pcs = 20)

object <- runKmeansClustering(object, ks = 3:10, n_pcs = 20)

getFeatureNames(object)
```

--------------------------------

### Get Valid Distance Methods

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid distance method names.

```R
validDistanceMethods()
```

--------------------------------

### Get Valid DEA Methods

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid DEA method names.

```R
validDeaMethods()
```

--------------------------------

### SPATA2 Activate Image Example Usage

Source: https://themilolab.github.io/SPATA2/reference/activateImage.html

Demonstrates how to activate a specific image for a SPATA2 object and retrieve its name. It also shows how coordinate systems are affected by image activation.

```R
library(SPATA2)

data("example_data")

object <- example_data$object_UKF275T_diet

getImageNames(object)

activeImage(object)
plotImage(object)

getCoordsDf(object) # with image1

object <- activateImage(object, img_name = "very_low_res")
activeImage(object)
plotImage(object)

# note how x_orig, y_orig remain the same, but x and y differ
getCoordsDf(object) # with very_low_res
```

--------------------------------

### Create Image Annotations

Source: https://themilolab.github.io/SPATA2/reference/createImageAnnotations.html

Demonstrates how to use the createImageAnnotations function with a SPATA2 object. Ensure the SPATA2 library is loaded and example data is available.

```r
library(SPATA2)

data("example_data")

object <- example_data$object_UKF275T_diet

object <- createImageAnnotations(object)
```

--------------------------------

### Get Valid Alluvial Types

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid alluvial type names.

```R
validAlluvialTypes()
```

--------------------------------

### Get Valid Agglomeration Methods

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid agglomeration method names.

```R
validAgglomerationMethods()
```

--------------------------------

### Align Image with 'add' Option (Multiple Steps)

Source: https://themilolab.github.io/SPATA2/reference/alignImage.html

Demonstrates sequential image alignment using the 'add' option. The image is registered and activated, then aligned in two steps, showing cumulative adjustments.

```R
object <- registerImage(object, img = img_bad, img_name = "bad", overwrite = T)
object <- activateImage(object, img_name = "bad")

plotSurface(object, pt_clr = "red", display_image = T)

object <- alignImage(object, img_name = "bad", opt = "add", transl_h = -15, transl_v = -10)

plotSurface(object, pt_clr = "red", display_image = T)

object <- alignImage(object, img_name = "bad", opt = "add", transl_h = -10, transl_v = -10)

plotSurface(object, pt_clr = "red", display_image = T)
```

--------------------------------

### Get Valid Activation Functions

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid activation function names.

```R
validActivationFunctions()
```

--------------------------------

### Demonstrate SPATA2 flip functions

Source: https://themilolab.github.io/SPATA2/reference/flipAll.html

This example demonstrates how to use `flipImage()`, `flipCoordinates()`, and `flipAll()` to manipulate spatial data and images within a SPATA2 object. It shows the effect of each function on the displayed surface.

```r
library(SPATA2)
library(tidyverse)

data("example_data")

object <- example_data$object_UKF275T_diet

plotSurface(object, display_image = T)

object <- flipImage(object, axis = "h")

plotSurface(object, display_image = T)

object <- flipCoordinates(object, axis = "h")

plotSurface(object, display_image = T)

object <- flipAll(object, axis = "v")

plotSurface(object, display_image = T)
```

--------------------------------

### Get Valid Padj Methods

Source: https://themilolab.github.io/SPATA2/reference/validActivationFunctions.html

Call this function to get a character vector of valid adjusted p-value method names.

```R
validPadjMethods()
```

--------------------------------

### Load Data and Visualize Trajectories in SPATA2

Source: https://themilolab.github.io/SPATA2/articles/spatial-trajectory-screening.html

Load an example SPATA2 object and visualize the image and spatial trajectories. Ensure the 'SPATA2' and 'tidyverse' packages are loaded.

```R
library(SPATA2)
library(tidyverse)

# load SPATA2 inbuilt data
object_t269 <- object_t269 <- loadExampleObject("UKF269T", process = TRUE, meta = TRUE)

# show image 
plotImage(object_t269)

# created with code 
plotSpatialTrajectories(
  object = object_t269, 
  ids = "horizontal_mid", 
  color_by = "histology"
)
```

--------------------------------

### Initiate SPATA2 Object from Visium Data

Source: https://themilolab.github.io/SPATA2/articles/initiation-and-preprocessing-visium.html

Use `initiateSpataObjectVisium()` to create a SPATA2 object from Visium output. This function supports both VisiumSmall (6.5mm x 6.5mm) and VisiumLarge (11mm x 11mm) capture areas. Ensure the `directory_visium` path points to your downloaded Visium folder.

```r
library(SPATA2)

object <- 
  initiateSpataObjectVisium(
    sample_name = "UKF269T", 
    directory_visium = "initiate_VisiumSmall" # adjust to your liking 
  )

# show overview
object
```

--------------------------------

### loadExampleObject Function

Source: https://themilolab.github.io/SPATA2/reference/loadExampleObject.html

Loads a sample SPATA2 object. This function allows for loading example datasets with options to process them and include meta-data.

```APIDOC
## loadExampleObject

### Description
Loads a diet example `SPATA2` object.

### Signature
`loadExampleObject(sample_name, process = FALSE, meta = FALSE, verbose = TRUE)`

### Parameters
#### Arguments
- **sample_name** (Character value) - Required - One of `c("UKF275T", "UKF313T", "UKF269T", "LMU_MIC")`.
- **process** (Logical value) - Optional - If `TRUE`, the object is processed via `identifyTissueOutline()`, `identifySpatialOutliers()`, `removeSpatialOutliers()`, `normalizeCounts()`, and `computeMetaFeatures()` using their default setup.
- **meta** (Logical value) - Optional - If `TRUE`, adds meta features like clustering, histological segmentation or copy number variation results to the meta data.frame.
- **verbose** (Logical) - Optional - If `TRUE`, informative messages regarding the computational progress will be printed.

### Value
A reduced diet object of class `SPATA2`.

### Details
The example objects only contain a subsetted count matrix. If you want to work with the complete data sets, use `downloadSpataObject()`.

### Examples
```R
library(SPATA2)

# simply load
object <- loadExampleObject(sample_name = "UKF269T")

# load, process and add some meta data
object_proc <- loadExampleObject(sample_name = "UKF269T", process = TRUE, meta = TRUE)

getMatrixNames(object)
getMatrixNames(object_proc)

plotSurface(object, color_by = "histology") # fails
plotSurface(object_proc, color_by = "histology")
```
```
Tokens:
Raw