diff --git a/01_session2.Rmd b/01_session2.Rmd index db5ab7c..66cd25e 100644 --- a/01_session2.Rmd +++ b/01_session2.Rmd @@ -37,7 +37,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