From 4be6011b5e23c84a6591e735755a3f6030bab36c Mon Sep 17 00:00:00 2001
From: George Chen <72078254+jiajic@users.noreply.github.com>
Date: Sun, 4 Aug 2024 12:07:14 -0400
Subject: [PATCH] add python instructions

---
 01_session2.Rmd | 102 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)

diff --git a/01_session2.Rmd b/01_session2.Rmd
index f46f80a..396ae70 100644
--- a/01_session2.Rmd
+++ b/01_session2.Rmd
@@ -34,7 +34,109 @@ More information is available at https://drieslab.github.io/Giotto_website/artic
 
 ## Installation + python environment
 
+### Giotto installation
 
+Giotto Suite is currently available installable only from GitHub, but we are actively working on getting it into a major repository. 
+Much of this already covered in Section 2.2, but the highlights are:
+
+1. Ensure your system 
+
+To install the currently released version of Giotto on R 4.4 in a single step, we recommend using _pak_.
+
+```{r, eval=FALSE}
+pak::pak("drieslab/Giotto")
+```
+
+
+### Python environment
+
+#### Default installation
+
+In order to make use of python packages, the first thing to do after installing Giotto for the first time is to create a giotto python environment. Giotto provides the following as a convenience wrapper around _reticulate_ functions to setup a default environment.
+
+```{r, eval=FALSE}
+library(Giotto)
+installGiottoEnvironment()
+```
+
+Two things are needed for python to work:
+
+1. A conda (e.g. miniconda or anaconda) installation which is the package and environment management system. 
+2. Independent environment(s) with specific versions of the python language and associated python packages.
+
+`installGiottoEnvironment()` checks both and will install miniconda using _reticulate_ if necessary. If a specific conda binary already exists that you want to use, the `conda` param can be set, or you can set the _reticulate_ option `options("reticulate.conda_binary" = "[conda path]")` or `Sys.setenv("RETICULATE_CONDA" = "[conda path]")`.
+
+After ensuring the conda binary exists, the default Giotto environment is installed which is a python 3.10.2 environment named 'giotto_env'. 
+It will contain several default packages that Giotto installs:
+
+- "pandas==1.5.1"
+- "networkx==2.8.8"
+- "python-igraph==0.10.2"
+- "leidenalg==0.9.0"
+- "python-louvain==0.16"
+- "python.app==1.4" (if needed)
+- "scikit-learn==1.1.3"
+
+#### Custom installs
+
+Custom python environments can be made by first setting up a new environment and establishing the name and python version to use.
+
+```{r, eval=FALSE}
+reticulate::conda_create(envname = "[name of env]", python_version = ???)
+```
+
+Following that, one or more python packages to install can be added to the environment. 
+
+```{r, eval=FALSE}
+reticulate::py_install(
+  pip = TRUE,
+  envname = '[name of env]',
+  packages = c(
+      "package1",
+      "package2",
+      "..."
+  )
+)
+```
+
+
+Once an environment has been set up, _Giotto_ can hook into it.
+
+
+#### Using a specific environment
+
+When using python through _reticulate_, R only allows one environment to be activated per session. Once a session has loaded a python environment, it can no longer switch to another one. Giotto activates a python environment when any of the following happens:
+
+- a `giotto` object is created
+- `giottoInstructions` are created (`createGiottoInstructions()`)
+- `GiottoClass::set_giotto_python_path()` is called (most straightforward)
+
+Which environment is activated is based on a set of 5 defaults in decreasing priority.
+
+1. User provided (when `python_path` param is given. Either a full filepath or an env name are accepted.)
+2. Any provided path or envname set in options  `options("giotto.py_path" = "[path to env or envname]")`
+3. Default expected giotto environment location based on `reticulate::miniconda_path()`
+4. Envname `"giotto_env"`
+5. System default python environment
+
+Method 2 is most recommended when there is a non-standard python environment to regularly use with Giotto. 
+
+You would run `file.edit("~/.Rprofile")` and then add `options("giotto.py_path" = "[path to env or envname]")` as a line so that it is automatically set at the start of each session.
+
+If a specific environment should only be used a couple times then method 1 is easiest:
+```{r, eval=FALSE}
+GiottoClass::set_giotto_python_path(python_path = "[path to env or envname]")
+```
+
+To check which conda environments exist on your machine:
+```{r, eval=FALSE}
+reticulate::conda_list()
+```
+
+Once an environment is activated, you can check more details and ensure that it is the one you are expecting by running:
+```{r, eval=FALSE}
+reticulate::py_config()
+```
 
 ## Giotto instructions