Interoperability: AnnData#



1 Converting to and from AnnData (squidpy-flavor)#

This tutorial details how to use the conversion functions anndataToGiotto() and giottoToAnnData(). A mini Giotto object will be used for minimal computational requirements. Please note that these functions are inherently in active development, since changes to either squidpy or anndata are possible.

2 Start Giotto#

# Ensure Giotto Suite is installed
if(!"Giotto" %in% installed.packages()) {

# Ensure Giotto Data is installed
if(!"GiottoData" %in% installed.packages()) {

# Ensure the Python environment for Giotto has been installed
genv_exists = checkGiottoEnvironment()
  # The following command need only be run once to install the Giotto environment

3 Create a Giotto object#

# Specify path to which results may be saved
results_directory = paste0(getwd(),'/giotto_anndata_conversion/')

# Optional: Specify a path to a Python executable within a conda or miniconda
# environment. If set to NULL (default), the Python executable within the previously
# installed Giotto environment will be used.
my_python_path = NULL # alternatively, "/local/python/path/python" if desired.

mini_gobject = loadGiottoMini(dataset = 'vizgen',
                              python_path = my_python_path)

instrs = showGiottoInstructions(mini_gobject)
instrs$save_dir = results_directory

mini_gobject = replaceGiottoInstructions(gobject = mini_gobject,
                                         instructions = instrs)

4 Convert Giotto to AnnData#

Since Giotto is structured hierarchally, converting Giotto to AnnData will result in multiple .h5ad files. Each file will correspond to a Giotto spat_unit feat_type pair. Furthermore, each expression slot will be treated as a layer in the resulting AnnData slot.

Squidpy anndata objects take different defaults for various operations compared to Giotto. For instance, the default nearest neighbor network is a kNN for squidpy, while the default for Giotto is a sNN. We’ll create a kNN in addition to the sNN within this object already to show how it they are handled.

mini_gobject = createNearestNetwork(gobject = mini_gobject,
                                    spat_unit = "aggregate",
                                    feat_type = "rna",
                                    type = "kNN",
                                    dim_reduction_to_use = "umap",
                                    dim_reduction_name = "umap",
                                    k = 15,
                                    name = "kNN.umap")

The above cell creates a nearest network with almost all default parameters. We’ll change some and make a new network to show how the converter handles this.

mini_gobject = createNearestNetwork(gobject = mini_gobject,
                                    spat_unit = "aggregate",
                                    feat_type = "rna",
                                    type = "kNN",
                                    dim_reduction_to_use = "umap",
                                    dim_reduction_name = "umap",
                                    k = 6,
                                    name = "new_network")

Since we have multiple spat_unit feat_type pairs, there will be multiple files created by this function. The names of the .h5ad files will be returned. In the case of a non-anndata-default nearest network or spatial network name, the key_added terms will be recorded and saved in .txt files named accordingly. Please see the documentation for further details.

anndata_conversions = giottoToAnnData(gobject = mini_gobject,
                                      save_directory = results_directory,
                                      python_path = my_python_path)

5 AnnData to Giotto#

To convert an AnnData Object back into a Giotto object, it must first be saved as a .h5ad file. The name of said file may then be provided to anndataToGiotto() for conversion.

If a nearest neighbor network or spatial netowkr was created using the key_added argument, they may be provided to arguments n_key_added and/or spatial_n_key_added, respectively. If converting an anndata object that was originally a giotto object, the .txt files generated by giottoToAnnData() may be provided to these arguments as well.

z0_rna_gobject <- anndataToGiotto(anndata_path = "./giotto_anndata_conversion/z0_rna_converted_gobject.h5ad",
                                  python_path = my_python_path)

z1_rna_gobject <- anndataToGiotto(anndata_path = "./giotto_anndata_conversion/z1_rna_converted_gobject.h5ad",
                                  python_path = my_python_path)

aggregate_rna_gobject <- anndataToGiotto(anndata_path = "./giotto_anndata_conversion/aggregate_rna_converted_gobject.h5ad",
                                         python_path = my_python_path,
                                         n_key_added = list("sNN.pca","new_network"),
                                         spatial_n_key_added = "aggregate_rna_spatial_network_keys_added.txt")

6 Session Info#

R version 4.2.2 (2022-10-31 ucrt)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 10 x64 (build 22621)

Matrix products: default

[1] LC_COLLATE=English_United States.utf8
[2] LC_CTYPE=English_United States.utf8
[3] LC_MONETARY=English_United States.utf8
[5] LC_TIME=English_United States.utf8

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base

other attached packages:
[1] GiottoData_0.2.1 Giotto_3.2.1

loaded via a namespace (and not attached):
 [1] Rcpp_1.0.10       pillar_1.9.0      compiler_4.2.2    tools_4.2.2
 [5] digest_0.6.30     jsonlite_1.8.3    evaluate_0.20     lifecycle_1.0.3
 [9] tibble_3.2.1      gtable_0.3.3      lattice_0.20-45   png_0.1-7
[13] pkgconfig_2.0.3   rlang_1.1.0       igraph_1.4.1      Matrix_1.5-1
[17] cli_3.4.1         rstudioapi_0.14   parallel_4.2.2    yaml_2.3.7
[21] xfun_0.38         fastmap_1.1.0     terra_1.7-18      dplyr_1.1.1
[25] knitr_1.42        rappdirs_0.3.3    generics_0.1.3    vctrs_0.6.1
[29] rprojroot_2.0.3   grid_4.2.2        tidyselect_1.2.0  here_1.0.1
[33] reticulate_1.26   glue_1.6.2        data.table_1.14.6 R6_2.5.1
[37] fansi_1.0.4       rmarkdown_2.21    ggplot2_3.4.1     magrittr_2.0.3
[41] scales_1.2.1      codetools_0.2-18  htmltools_0.5.4   colorspace_2.1-0
[45] utf8_1.2.3        munsell_0.5.0     dbscan_1.1-11