Tutorial: Exporting Data as CSV

Exporting Data

Exporting structured data to commonly used text formats is an important workflow. This process is simplified by SpatialMap’s built-in CSV export functions. Below, we demonstrate the functions and some of their key arguments. Let’s load some data first:

sm <- load_sm_data()

The main functions used in SpatialMap are:

Function	Slot	Export (CSV)
`exportMetadata()`	`@projectMetadata`	Region/sample metadata
`exportData()`	`<region>@Data`	Expression table
`exportAnnotations()`	`<region>@cellMetadata`	Cell annotations
`exportCoords()`	`<region>@coords`	Cell centroids
`exportCellData()`	`@coords`, `@Data`, `@cellMetadata`	All cell-level data in a unified table

There are some important things to note about these functions right off the bat!

They respect the activeAnalysis of the SpatialMap object.
- That means that, if your activeAnalysis is "regions", each Region will get its own CSV file.
- If you are working with a combined analysis, the data from each Region will be combined.
- Feel free to provide the analyze parameter to guarantee that your data gets written in the same way each time!
- By default, CSV file names correspond to region IDs (for analyze = "regions"), or to the ID of the analysis (e.g. "combined"). You can specify different filenames using the file_names parameter.
The rows represent cells, and the cell names are rownames in the CSV
The first row of each CSV will be a header row. (Useful to know for loading the data elsewhere!)
Features (for @Data export) and annotation names (for @cellMetadata export) can be specified, to output only the elements you want

Let’s dive into more detail on each of the functions.

`exportData()`

Here’s an example of exporting expression data either by Region or by combined Analysis.


# creating a combined analysis
sm <- createAnalysis(sm, id = "combined")
#> New analysis created.
#>  2 Regions
#>  16504 cells
#>  16 common features
#> 
#> Added Analysis `combined` to SpatialMap project 'SpatialMap Project'.
#> Setting as active Analysis
#> 

# export per-region
regions_paths <- exportData(sm,
                            data_layer = "Data",
                            analyze = "regions")
#> Creating base export directory:  '~/SpatialMap_Project'
#> Data successfully written to '/root/SpatialMap_Project/expression/regions/Data'!

# export combined
combined_paths <- exportData(sm,
                             data_layer = "Data",
                             analyze = "combined")
#>   By analysis: 'combined'
#> 
#> Data successfully written to '/root/SpatialMap_Project/expression/combined/Data'!

print(regions_paths)
#>                                                        TonsilA 
#> "/root/SpatialMap_Project/expression/regions/Data/TonsilA.csv" 
#>                                                        TonsilB 
#> "/root/SpatialMap_Project/expression/regions/Data/TonsilB.csv"
print(combined_paths)
#>                                                         combined 
#> "/root/SpatialMap_Project/expression/combined/Data/combined.csv"

We can also subset the expression matrix by any features() of the SpatialMap object.

feature_path <- exportData(
  sm,
  data_layer = "Data",
  analyze = "combined",
  features = c("CD3e", "CD21", "Actin", "CD4", "PanCK", "Ki67")
)
#>   By analysis: 'combined'
#> 
#> Exporting specific annotations:
#>   'CD3e'
#>   'CD21'
#>   'Actin'
#>   'CD4'
#>   'PanCK'
#>   'Ki67'
#> Data successfully written to '/root/SpatialMap_Project/expression/combined/Data'!

# reading back in to check
colnames(read.csv(feature_path, header = TRUE))
#> [1] "X"     "CD3e"  "CD21"  "Actin" "CD4"   "PanCK" "Ki67"
colnames(read.csv(feature_path, header = TRUE, row.names = 1))
#> [1] "CD3e"  "CD21"  "Actin" "CD4"   "PanCK" "Ki67"

# Note - this code also demonstrates a way to reliably re-import the exported data into R. 
# The user can choose whether to use row.names or not. 

# SpatialMap expects row.names to exist.

We may want to specify a different destination for saved CSV files. We can do so using the following parameters:

base_dir: A base directory into which CSV files (and any corresponding sub-directories) will be saved. The default value can be viewed by running exportPathDefault() on the SpatialMap object.
file_names: A character vector of custom file names, with length matching the number of CSV files to be saved (based on activeAnalysis/analyze). The character vector may be named to provide a mapping to region IDs, otherwise the file names are assumed to follow the same order as Regions.

# print the default export path
print(exportPathDefault(sm))
#> [1] "~/SpatialMap_Project"

# let's specify a different directory
# export per-region (with mapped custom file_names)
regions_paths_specified <- exportData(sm,
                                      data_layer = "Data",
                                      analyze = "regions",
                                      base_dir = "~/Tonsil",
                                      file_names = c("TonsilA" = "first_tonsil", 
                                                     "TonsilB" = "second_tonsil"))
#> Creating base export directory:  '~/Tonsil'
#> Data successfully written to '/root/Tonsil/expression/regions/Data'!

# export combined
combined_paths_specified <- exportData(sm,
                                       data_layer = "Data",
                                       analyze = "combined",
                                       file_names = "all_regions")
#>   By analysis: 'combined'
#> 
#> Data successfully written to '/root/SpatialMap_Project/expression/combined/Data'!

print(regions_paths_specified)
#>                                                  TonsilA 
#>  "/root/Tonsil/expression/regions/Data/first_tonsil.csv" 
#>                                                  TonsilB 
#> "/root/Tonsil/expression/regions/Data/second_tonsil.csv"
print(combined_paths_specified)
#>                                                            combined 
#> "/root/SpatialMap_Project/expression/combined/Data/all_regions.csv"

`exportCoords()` and `exportAnnotations()`

Exporting coordinates and annotations works in much the same way.

exportCoords() expects a coords argument to specify which embeddings to export - spatial coords, PCA coords, etc. Note that you’ll likely get an error trying to export "spatial" coordinates from a multi-Region Analysis!
exportAnnotations() can accept specific annotations of interest for export, just like exportData() can accept specific features. Of course, you’ll get an error if you try to specify annotations that don’t exist!

# creating a PCA in the 'combined' analysis
sm <- runPCA(sm, data.slot = "Data", dims = 10)
#>   By analysis: 'combined'
#> 

# export

coord_path <-
  exportCoords(sm, coords = "spatial", analyze = "regions")
#> Coords successfully written to '/root/SpatialMap_Project/coords/regions/spatial'!

coord_path <-
  exportCoords(sm, coords = "pca", analyze = "combined")
#>   By analysis: 'combined'
#> 
#> Coords successfully written to '/root/SpatialMap_Project/coords/combined/pca'!

anno_path <-
  exportAnnotations(
    sm,
    annotations = c("anno253_Hierarchy.1", "anno247_test_letters_324"),
    analyze = "regions"
  )
#> Exporting specific annotations:
#>   'anno253_Hierarchy.1'
#>   'anno247_test_letters_324'
#> Annotations successfully written to '/root/SpatialMap_Project/annotations/regions'!

`exportMetadata()`

This one is straigtforward - just an export of the SpatialMap @projectMetadata slot.

meta_path <- exportMetadata(sm)
#> Metadata successfully written to '/root/SpatialMap_Project/meta'!

`exportCellData()`

This function is like a combination of exportData(), exportCoords(), and exportAnnotations(). The output will be one CSV file containing all of this cell data. You can still filter on features or annotations of interest with this function.

sm <- Normalize(sm, method = "asinh")
#> Normalizing data using method `asinh`
#> 
#>   By analysis: 'combined'
#> 

cd_path <- exportCellData(
  sm,
  data_layer = "NormalizedData",
  features = c("CD3e", "CD21", "Actin", "CD4", "PanCK", "Ki67"),
  annotations = c("anno253_Hierarchy.1", "anno247_test_letters_324"),
  coords = "pca",
  analyze = "combined"
)
#>   By analysis: 'combined'
#> 
#> Exporting specific annotations:
#>   'anno253_Hierarchy.1'
#>   'anno247_test_letters_324'
#> Exporting specific features:
#>   'CD3e'
#>   'CD21'
#>   'Actin'
#>   'CD4'
#>   'PanCK'
#>   'Ki67'
#> Cell data successfully written to '/root/SpatialMap_Project/combined_cell_data/combined/NormalizedData_pca'!

colnames(read.csv(cd_path, header = TRUE))
#>  [1] "X"                        "CD3e"                    
#>  [3] "CD21"                     "Actin"                   
#>  [5] "CD4"                      "PanCK"                   
#>  [7] "Ki67"                     "PC1"                     
#>  [9] "PC2"                      "PC3"                     
#> [11] "PC4"                      "PC5"                     
#> [13] "PC6"                      "PC7"                     
#> [15] "PC8"                      "PC9"                     
#> [17] "PC10"                     "anno253_Hierarchy.1"     
#> [19] "anno247_test_letters_324"

Exporting Data

exportData()

exportCoords() and exportAnnotations()

exportMetadata()

exportCellData()

`exportData()`

`exportCoords()` and `exportAnnotations()`

`exportMetadata()`

`exportCellData()`