add tutorial

vignettes/instructions.Rmd

@@ -0,0 +1,160 @@
+---
+title: "Create and change Giotto instructions"
+output: 
+  html_document:
+    number_sections: true
+    toc: true
+pkgdown:
+  as_is: true
+vignette: >
+  %\VignetteIndexEntry{Create and change Giotto instructions}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+The Giotto instructions slot contains values that homogenize and facilitate the behavior of the Giotto object, such as whether the plots should be stored locally, shown, or returned, where to save the plots, what python path to use, etc. 
+
+If you don't provide specific instructions, some default values will be automatically added. 
+
+# Create new instructions
+
+Create new instructions and save them in a variable to pass them to the Giotto object later.
+
+```{r, eval=FALSE}
+results_folder <- "path/to/results"
+python_path <- NULL
+
+instructions <- createGiottoInstructions(save_dir = results_folder,
+                                         save_plot = TRUE,
+                                         show_plot = FALSE,
+                                         return_plot = FALSE,
+                                         python_path = python_path)
+
+createGiottoObject(expression = my_expression,
+                   spatial_locs = my_spatial_locs,
+                   instructions = instructions)
+```
+
+# Retrieve instructions
+
+## Setup and load example dataset
+
+```{r, eval=FALSE}
+# Ensure Giotto Suite is installed
+if(!"Giotto" %in% installed.packages()) {
+  pak::pkg_install("drieslab/Giotto")
+}
+
+# Ensure Giotto Data is installed
+if(!"GiottoData" %in% installed.packages()) {
+  pak::pkg_install("drieslab/GiottoData")
+}
+
+library(Giotto)
+
+# Ensure the Python environment for Giotto has been installed
+genv_exists <- checkGiottoEnvironment()
+
+if(!genv_exists){
+  # The following command need only be run once to install the Giotto environment
+  installGiottoEnvironment()
+}
+```
+
+```{r, eval=FALSE}
+# load the object
+g <- GiottoData::loadGiottoMini("visium")
+```
+
+## Show current instructions
+
+```{r, eval=FALSE}
+instructions(g)
+```
+
+# Update the instructions 
+
+## Update one instruction value
+
+```{r, eval=FALSE}
+instructions(g, "return_plot") <- TRUE
+```
+
+## Update multiple values
+
+```{r, eval=FALSE}
+instructions(g, c("return_plot", "save_plot")) <- c(TRUE, TRUE)
+```
+
+# Session Info
+
+```{r, eval=FALSE}
+sessionInfo()
+```
+
+```{r, eval=FALSE}
+R version 4.4.2 (2024-10-31)
+Platform: x86_64-apple-darwin20
+Running under: macOS Sequoia 15.0.1
+
+Matrix products: default
+BLAS:   /System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libBLAS.dylib 
+LAPACK: /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0
+
+locale:
+[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
+
+time zone: America/New_York
+tzcode source: internal
+
+attached base packages:
+[1] stats     graphics  grDevices utils     datasets  methods   base     
+
+other attached packages:
+[1] Giotto_4.1.4      GiottoClass_0.4.3
+
+loaded via a namespace (and not attached):
+ [1] tidyselect_1.2.1            viridisLite_0.4.2          
+ [3] dplyr_1.1.4                 GiottoVisuals_0.2.7        
+ [5] fastmap_1.2.0               SingleCellExperiment_1.26.0
+ [7] lazyeval_0.2.2              digest_0.6.37              
+ [9] lifecycle_1.0.4             terra_1.7-78               
+[11] magrittr_2.0.3              compiler_4.4.2             
+[13] rlang_1.1.4                 tools_4.4.2                
+[15] igraph_2.0.3                utf8_1.2.4                 
+[17] yaml_2.3.10                 data.table_1.16.0          
+[19] knitr_1.48                  S4Arrays_1.4.1             
+[21] htmlwidgets_1.6.4           reticulate_1.39.0          
+[23] DelayedArray_0.30.1         abind_1.4-8                
+[25] withr_3.0.1                 purrr_1.0.2                
+[27] BiocGenerics_0.50.0         grid_4.4.2                 
+[29] stats4_4.4.2                fansi_1.0.6                
+[31] colorspace_2.1-1            ggplot2_3.5.1              
+[33] scales_1.3.0                gtools_3.9.5               
+[35] SummarizedExperiment_1.34.0 cli_3.6.3                  
+[37] rmarkdown_2.28              crayon_1.5.3               
+[39] generics_0.1.3              rstudioapi_0.16.0          
+[41] httr_1.4.7                  rjson_0.2.23               
+[43] zlibbioc_1.50.0             parallel_4.4.2             
+[45] XVector_0.44.0              matrixStats_1.4.1          
+[47] vctrs_0.6.5                 Matrix_1.7-1               
+[49] jsonlite_1.8.9              GiottoData_0.2.15          
+[51] IRanges_2.38.1              S4Vectors_0.42.1           
+[53] ggrepel_0.9.6               scattermore_1.2            
+[55] magick_2.8.5                GiottoUtils_0.2.0          
+[57] plotly_4.10.4               tidyr_1.3.1                
+[59] pak_0.8.0                   glue_1.8.0                 
+[61] codetools_0.2-20            cowplot_1.1.3              
+[63] gtable_0.3.5                GenomeInfoDb_1.40.1        
+[65] GenomicRanges_1.56.1        UCSC.utils_1.0.0           
+[67] munsell_0.5.1               tibble_3.2.1               
+[69] pillar_1.9.0                htmltools_0.5.8.1          
+[71] GenomeInfoDbData_1.2.12     R6_2.5.1                   
+[73] evaluate_1.0.0              lattice_0.22-6             
+[75] Biobase_2.64.0              png_0.1-8                  
+[77] backports_1.5.0             SpatialExperiment_1.14.0   
+[79] Rcpp_1.0.13                 SparseArray_1.4.8          
+[81] checkmate_2.3.2             colorRamp2_0.1.0           
+[83] xfun_0.47                   MatrixGenerics_1.16.0      
+[85] pkgconfig_2.0.3 
+```