Create a multimodal object in a shared spot coordinate framework

This function takes two sets of spatial coordinates (the reference and the one that should be mapped to the reference coordinate system), with matching pixel coordinates, along with a feature count matrix, and generates a new count matrix containing the aggregated feature values for each reference coordinate based on the mapping relationship between the two coordinate systems.

Usage

CreateMultiModalObject(object_ref, ...)

# S3 method for default
CreateMultiModalObject(
  object_ref,
  object_map,
  map_counts,
  agg_func = "mean",
  n_neighbors = 100,
  distance_max = NULL,
  nCores = (parallel::detectCores() - 1),
  verbose = TRUE,
  ...
)

# S3 method for Seurat
CreateMultiModalObject(
  object_ref,
  object_map,
  new_assay_name = NULL,
  agg_func = "mean",
  n_neighbors = 100,
  distance_max = NULL,
  assay = NULL,
  slot = "counts",
  layer = "counts",
  nCores = (parallel::detectCores() - 1),
  verbose = TRUE,
  ...
)

Arguments

object_ref: Seurat/semla object containing reference coordinates.
...: Arguments passed to other methods
object_map: Seurat/semla object containing mapped coordinates.
map_counts: Feature count matrix where rows represent features and columns represent mapped coordinates identified by their "barcode" values.
agg_func: Character vector specifying either "mean" or "sum", corresponding to the aggregation function to use for summarizing feature values mapped to each reference coordinate. Default set to "mean".
n_neighbors: Integer specifying the number of nearest neighbors to consider for mapping each point in the mapped dataset to the reference dataset. Defaults to 100.
distance_max: Numeric value specifying the maximum allowed distance between a mapped coordinate and its nearest reference neighbor(s). Points exceeding this distance will be excluded from the mapping. Defaults to NULL (maximum distance set to half the center-to-center distance between reference spots).
nCores: Integer specifying the number of cores to use for parallel processing during data aggregation. Defaults to (detectCores() - 1), which uses all available cores minus one. Set to NULL to disable multi-threading.
verbose: Logical indicating whether to print informative messages during execution. Defaults to TRUE.
new_assay_name: Name to be assigned to the new Assay. If left empty, the same name as the `object_map` Active Assay will be used (default).
assay: Seurat object assay in `object_map` to fetch data from
slot: Seurat object slot in `object_map` to fetch data from (Seurat < v.5)
layer: Seurat object layer in `object_map` to fetch data from (Seurat ≥ v.5)

Value

An object with each modality in a shared coordinate framework

A list containing two elements: - `data`: A matrix representing the aggregated feature values for each reference coordinate. Rows represent features, and columns represent reference coordinates. - `map`: A data frame containing detailed information about the mapping between reference and mapped coordinates, including the reference ID(s) for each mapped point and the chosen aggregation function value(s) for each feature and reference coordinate combination.

A Seurat/semla multi-modal object with the added modality data in a new Assay, all in a shared coordinate system.

Details

This function assumes the reference coordinates represent fixed locations (e.g., Visium spots) and the mapped coordinates represent measurements from another modality (e.g., Mass Spec Imaging) that have already been aligned to the same pixel coordinate system. Unless something else is specified, the coordinates from the second modality is mapped to the reference spots by including all coordinates falling within half of the center-to-center distance between reference spots. Count values are then aggregated for each feature using the chosen aggregation function ("mean" or "sum") into the reference coordinate system. The function can optionally utilize multi-threading for faster processing with large datasets.

Author

Lovisa Franzén

Examples


se_mod1 <- readRDS(system.file("extdata/mousebrain", "se_mbrain", package = "semla"))
se_mod2 <- readRDS(system.file("extdata/mousebrain", "se_mbrain", package = "semla"))

# By default, the mean values of the mapping modality will be calculated per 
# reference coordinates
se_mmo <- CreateMultiModalObject(object_ref = se_mod1, object_map = se_mod2, 
                                 new_assay_name = "Modality2", 
                                 agg_func = "mean")
#> 
#> ── Joining second modality data to reference object ──
#> 
#> ℹ Excluding 0 coordinates from the mapping dataset due to being outside of reference coordinate scope
#> ℹ Aggregating assay data in mapping coordinates per reference coordinate (this step may take long if the data is large)
#> ℹ Using 7 threads
#> ✔ Data aggregation finished in 0.03 minutes
#> ℹ Storing aggregated data summarized by mean values
#> ℹ Adding second modality data to a new 'Assay' named 'Modality2', containing 188 features
#> ✔ Returning a `Seurat` object with 188 features and 2560 spots

# To change this and instead compute the sum, the `agg_func` argument can modified:
se_mmo <- CreateMultiModalObject(object_ref = se_mod1, object_map = se_mod2, 
                                 new_assay_name = "Modality2", 
                                 agg_func = "sum")
#> 
#> ── Joining second modality data to reference object ──
#> 
#> ℹ Excluding 0 coordinates from the mapping dataset due to being outside of reference coordinate scope
#> ℹ Aggregating assay data in mapping coordinates per reference coordinate (this step may take long if the data is large)
#> ℹ Using 7 threads
#> ✔ Data aggregation finished in 0.03 minutes
#> ℹ Storing aggregated data summarized by sum values
#> ℹ Adding second modality data to a new 'Assay' named 'Modality2', containing 188 features
#> ✔ Returning a `Seurat` object with 188 features and 2560 spots