1 Installing for the first time
When installing for the first time, it is recommended to first ensure that all pre-requisite software is available, and then install Giotto Suite using pak
1.1 Basic requirements
- R (>= 4.1.0)
- Python (>= 3.6)
- Windows, MacOS or Linux specific installation tools for Posit (previously RStudio)
1.2 terra installation
terra is a major dependency of Giotto Suite. It may have some additional steps when installing depending on which system you are on. Please see the terra repo for specifics. Installations of the CRAN release on Windows and Mac are expected to be simple, only requiring the code below.
For Linux, there are several prerequisite installs:
GDAL (>= 2.2.3), GEOS (>= 3.4.0), PROJ (>= 4.9.3), sqlite3On our AlmaLinux 8 HPC, the following versions have been working well:
gdal/3.6.4
geos/3.11.1
proj/9.2.0
sqlite3/3.37.2
install.packages("terra")1.3 Matrix installation
(Only important for R versions lower than 4.4.0)
Giotto requires Matrix 1.6-2 or greater, but when installing Giotto with pak on an R version lower than 4.4.0, the installation can fail asking for R 4.5 which doesn’t exist yet. We can solve this by installing the 1.6-5 version directly by un-commenting and running the line below.
# devtools::install_version("Matrix", version = "1.6-5")1.4 Install Giotto Suite
To install the currently released version of Giotto in a single step:
if(!"pak" %in% installed.packages()) {
install.packages("pak")
}
pak::pkg_install("drieslab/Giotto")This should automatically install all the Giotto dependencies and other Giotto module packages (main branch).
2 Installing from dev branch
Giotto Suite is a set of modular packages and pak tends to forcibly install the stable version despite dev versions with higher version numbers. This can make it difficult to install the dev branch.
Instead, you can install dev branch versions by using devtools::install_github() alongside one of the following dev branch paths as shown below. Do not update other Giotto modules that should be installed from dev branch if prompted.
Core module dev branchs:
"drieslab/Giotto@suite_dev""drieslab/GiottoVisuals@dev""drieslab/GiottoClass@dev""drieslab/GiottoUtils@dev"
if(!"devtools" %in% installed.packages()) {
install.packages("devtools")
}
devtools::install_github("[dev branch path]")3 Giotto python environment installation
Giotto uses some python packages through reticulate. A default python 3.10.2 environment named ‘giotto_env’ that covers Giotto’s commonly used python packages can be installed using installGiottoEnvironment(). This is just a convenient default installation and users are free to create their own preferred python environment(s) for use with Giotto.
4 Solutions to Installation Errors
4.1 Errors on MacOS
4.1.1 Packages not Found
In the event that packages are inaccessible in the default installation of the Giotto miniconda environment, one troubleshooting method is provided here.
# Restart the R session, while maintaining workspace variables.
# If using RStudio, the following command will do exactly that:
.rs.restartR()
# Creating Giotto Instructions without specifying a Python path will make
# reticulate activate the default Giotto environment.
default_instrs <- createGiottoInstructions()
# Extract python path information
default_python_path <- default_instrs$python_path
# Direct reticulate to use Python within the Giotto Environment
reticulate::use_python(default_python_path)
# Make reticulate iteratively check for the packages
pkg_check <- function(){
py_pkgs = c('pandas','networkx', 'igraph', 'leidenalg','community','sklearn','python.app')
py_pkg_error = character()
test_availability = TRUE
for (i in py_pkgs){
if(i == 'python.app' & Sys.info()[['sysname']] != "Darwin"){
# If the machine OS is not OSX (Mac), break out of the loop
# Otherwise, also check for python.app
break
}
test_availability <- reticulate::py_module_available(i)
if(!test_availability) {py_pkg_error <- c(py_pkg_error,i)}
}
if(test_availability){
cat('All Python packages for Giotto are accessible at environment:\n', default_python_path)
}else{
for (x in py_pkg_error) cat(x,'was not found within environment:\n',default_python_path,'\n\n')
}
return(py_pkg_error)
}
# Check if packages exist again. Ensure function from above code block is defined.
missing_packages <- pkg_check()
retry_install <- length(missing_packages) > 0
if(retry_install){
# Attempt to reinstall all packages.
pkgs_w_versions <- c('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',
'scikit-learn==1.1.3')
python_version = "3.10.2"
py_pkgs = c('pandas','networkx',
'igraph', 'leidenalg',
'python-louvain','scikit-learn','python.app')
if(Sys.info()[['sysname']] != "Darwin"){
pkgs_w_versions = pkgs_w_versions[!grepl(pattern = 'python.app', x = pkgs_w_versions)]
py_pkgs = py_pkgs[!grepl(pattern = 'python.app', x = py_pkgs)]
}
env_location <- reticulate::py_discover_config()$pythonhome
partial_path_to_conda <- paste0(reticulate::miniconda_path(),'/envs/giotto_env')
py_lou = pkgs_w_versions[grepl(pattern = 'python-louvain',x = pkgs_w_versions)]
pip_packages = c("smfishhmrf", py_lou)
pkgs_w_versions = pkgs_w_versions[!grepl(pattern = 'python-louvain',x = pkgs_w_versions)]
if(.Platform[['OS.type']] == 'unix') {
conda_full_path = paste0(partial_conda_path,'/','bin/conda')
# Remove all previous installations
reticulate::conda_remove(envname = env_location,
packages = py_pkgs,
conda = conda_full_path)
# Reinstall
reticulate::conda_install(packages = pkgs_w_versions,
envname = env_location,
method = 'conda',
conda = conda_full_path,
python_version = python_version)
# Reinstall with pip
reticulate::conda_install(packages = pip_packages,
envname = env_location,
method = 'conda',
conda = conda_full_path,
pip = TRUE,
python_version = python_version)
}
else if(.Platform[['OS.type']] == 'windows'){
conda_full_path = paste0(partial_conda_path,'/','condabin/conda.bat')
# Remove all previous installations
reticulate::conda_remove(envname = env_location,
packages = py_pkgs,
conda = conda_full_path)
# Reinstall
reticulate::conda_install(packages = pkgs_w_versions,
envname = env_location,
method = 'conda',
conda = conda_full_path,
python_version = python_version,
channel = c('conda-forge', 'vtraag'))
# Reinstall with pip
reticulate::conda_install(packages = pip_packages,
envname = env_location,
method = 'conda',
conda = conda_full_path,
pip = TRUE,
python_version = python_version)
}
}4.2 Errors on Windows
4.2.1 Windows 11 OpenSSL Error
Please note that this troubleshooting workflow is for a Windows 11 64-bit machine.
Unfortunately, it is known that installing miniconda on Windows 11 can sometimes result in an OpenSSL error.
It should be noted that Conda developers are aware of this, and that this particular issue does not have to do with the configuration of the Giotto package. One workaround for this error is described below and on the conda repository, here.
First, open a terminal and navigate to the folder in which miniconda lives on the machine. To find this, press the Windows Key and search for “Anaconda Prompt”. If anaconda3 is installed on the machine, there may be multiple options for this terminal; choose the Anaconda Prompt with “R-MINI~1” in parenthesis.
Output from the following commands will be provided as a comparative guide. Once the terminal is open, identify the Conda environments on the machine by running the following:
(base) PS > conda info --envs
# conda environments:
#
# base * C:\Users\matto\AppData\Local\R-MINI~1
# giotto_env C:\Users\matto\AppData\Local\R-MINI~1\envs\giotto_env
# C:\Users\matto\AppData\Local\r-miniconda\envs\giotto_env
# C:\Users\matto\anaconda3Change your current directory to the R-MINI~1 subdirectory. Then, navigate to the Library/bin/ subdirectory within. Use the dir command to search bin for two groups of files. These files will be moved to a different directory, and should fix the issue. There may be more than two files per group here, and that is okay. All of the files with these names will be moved, regardless of the extension.
(base) PS > cd C:\Users\matto\AppData\Local\R-MINI~1
(base) PS > cd .\Library\bin
(base) PS > dir libssl-1_1-x64.*
# Directory: C:\Users\matto\AppData\Local\r-miniconda\Library\bin
# Mode LastWriteTime Length Name
# ---- ------------- ------ ----
# -a---- 11/4/2022 11:06 AM 686080 libssl-1_1-x64.dll
# -a---- 11/4/2022 11:06 AM 2338816 libssl-1_1-x64.pdbo
(base) PS > dir libcrypto-1_1-x64.*
# Directory: C:\Users\matto\AppData\Local\r-miniconda\Library\bin
# Mode LastWriteTime Length Name
# ---- ------------- ------ ----
# -a---- 11/4/2022 11:06 AM 3416064 libcrypto-1_1-x64.dll
# -a---- 11/4/2022 11:06 AM 10219520 libcrypto-1_1-x64.pdbOnce these files are located, they may be moved to R-MINI~1/DLLs/, the proper directory for the search path.
(base) PS > pwd
# Path
# ----
# C:\Users\matth\AppData\Local\r-miniconda\Library\bin
(base) PS > mv libssl-1_1-x64.* ..\..\DLLs\
(base) PS > mv libcrypto-1_1-x64.* ..\..\DLLs\Finally, change to the DLLs directory within R-MINI~1 and verify that the files now exist there.
(base) PS > cd C:\Users\matth\AppData\Local\r-miniconda\DLLs\
(base) PS > dir libssl-1_1-x64.*
# Directory: C:\Users\matth\AppData\Local\r-miniconda\DLLs
# Mode LastWriteTime Length Name
# ---- ------------- ------ ----
# -a---- 11/4/2022 11:07 AM 686080 libssl-1_1-x64.dll
# -a---- 11/4/2022 11:07 AM 2338816 libssl-1_1-x64.pdb
(base) PS > dir libcrypto-1_1-x64.*
# Directory: C:\Users\matto\AppData\Local\r-miniconda\DLLs
# Mode LastWriteTime Length Name
# ---- ------------- ------ ----
# -a---- 11/4/2022 11:07 AM 3416064 libcrypto-1_1-x64.dll
# -a---- 11/4/2022 11:07 AM 10219520 libcrypto-1_1-x64.pdbNow that these files have moved, this error should disappear. Activate the Giotto environment, and run python within it to test a package import. The OpenSSL error should no longer occur.
(base) PS > conda info --envs
# conda environments:
#
# base * C:\Users\matto\AppData\Local\R-MINI~1
# giotto_env C:\Users\matto\AppData\Local\R-MINI~1\envs\giotto_env
# C:\Users\matto\AppData\Local\r-miniconda\envs\giotto_env
# C:\Users\matto\anaconda3
(base) PS > conda activate giotto_env
(giotto_env) PS > cd C:\Users\matto\AppData\Local\R-MINI~1\envs\giotto_env
(giotto_env) PS > python
Python 3.10.2 | packaged by conda-forge | (main, Mar 8 2022, 15:47:33) [MSC v.1929 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import pandas, networkx, igraph, leidenalg, community, sklearn
>>>4.3 UnsatisfiableError
This error results from conflicts within the anaconda and miniconda environment. This error presents itself when conflicting versions of conda live on the same machine; conda environments can only be so isolated from each other. To begin the troubleshooting workflow, open a terminal (macOS, Linux) or an Anaconda Prompt (Windows), and identify the environments on the machine. If anaconda3 is installed on the Windows machine, there may be multiple options for this terminal; choose the Anaconda Prompt with “anaconda3” in parenthesis.
NOTE: The following commands will be shown as if within an Anaconda Prompt to emphasize the difference for Windows users; for these purposes, the only difference between terminals is the appearance of the message (i.e., (active_env) PS >) preceding the textual entry. No output will be shown here as differences in OS, environments, and versions will vary.
First, identify the environments on the machine:
(base) PS > conda info --envsTo proceed, any r-miniconda associated environments will be deleted, and the base environment will be updated. If any environment is frequently used for other analyses and a python version update is undesirable, it may be preserved by cloning the environment. The original environment, however, will be removed or updated, so ensure that files and workflows associated with this environment are redirected to the new, cloned environment. Ensure the path of the cloned environment is not associated with r-miniconda.
It is recommended that conda is updated within any cloned environment (see below).
(base) PS > conda create --name my_base_clone --clone baseVerify that the clone exists to the proper specifications before proceeding by comparing packages and python versions:
(base) PS > conda info --envs
(base) PS > conda activate my_base_clone
(my_base_clone) PS > conda update conda
(my_base_clone) PS > python -V
(my_base_clone) PS > conda list
(my_base_clone) PS > conda activate base
(base) PS > python -V
(base) PS > conda list Ensure the base environment is activated. If the r-miniconda environments are still on the machine, remove them. Specify the r-miniconda environments other than giotto_env, as these will be unique to the machine. This may be done at the command line:
(base) PS > conda env remove --name giotto_env
(base) PS > conda env remove /path/to/r-miniconda/Alternatively, in R, reticulate can uninstall miniconda and remove the associated environments:
reticulate::miniconda_uninstall()It is advisable to remove any and all environments which are outdated and/or no longer used.
Recall that by default, Giotto installs a miniconda environment with python v3.10.2 for interfacing with R. Older versions of conda in the base environment cannot handle a python version that high in a different environment. Therefore, the recommended troubleshooting method is to update conda and python within the base environment at a minimum. Updating to python v3.8.5 at a minimum is recommended. It is advisable to update conda and python within each environment on the machine if feasible.
(base) PS > conda update conda
(base) PS > conda update python==3.8.5Finally, close the terminal and open the RStudio, VSCode, or an alternative IDE. Running the following should ensure successful installation:
library(Giotto)
installGiottoEnvironment(force_environment = TRUE, force_miniconda = TRUE)If the issue persists, please post an issue on the GitHub.
4.4 Installation Time out
If you’re installing Giotto using the devtools or remote packages, with the most recent version of Giotto, the following error has been observed:
This error is related to the time required for downloading the package. To solve the error, increase the limit of downloading time by running this code in your R console:
If you are doing the installation through a linux terminal, you can run instead this command to directly modify your R environment variable:
echo "R_DEFAULT_INTERNET_TIMEOUT = 1000" >> .RenvironAlternatively, you can use the package pak to install Giotto
if(!"pak" %in% installed.packages()) {
install.packages("pak")
}
pak::pkg_install("drieslab/Giotto")5 Try Giotto in the cloud
You can also run analyses in Giotto on Terra.bio. Take a look on the Terra tutorial.
Encountering errors? Post to an issue to the Giotto GitHub page here. Please include the version numbers of R, Giotto, and the OS in use at the time of the issue.
6 Session Info
R version 4.3.2 (2023-10-31)
Platform: aarch64-apple-darwin20 (64-bit)
Running under: macOS Sonoma 14.2.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.3-arm64/Resources/lib/libRlapack.dylib; LAPACK version 3.11.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/Mexico_City
tzcode source: internal
attached base packages:
[1] stats graphics grDevices utils datasets methods
[7] base
other attached packages:
[1] Giotto_4.0.2 GiottoClass_0.1.2
loaded via a namespace (and not attached):
[1] colorRamp2_0.1.0 DBI_1.2.0
[3] bitops_1.0-7 biomaRt_2.58.0
[5] rlang_1.1.2 magrittr_2.0.3
[7] GiottoUtils_0.1.2 matrixStats_1.2.0
[9] e1071_1.7-14 compiler_4.3.2
[11] RSQLite_2.3.4 png_0.1-8
[13] vctrs_0.6.5 stringr_1.5.1
[15] pkgconfig_2.0.3 SpatialExperiment_1.12.0
[17] crayon_1.5.2 fastmap_1.1.1
[19] backports_1.4.1 dbplyr_2.4.0
[21] magick_2.8.2 XVector_0.42.0
[23] utf8_1.2.4 rmarkdown_2.25
[25] purrr_1.0.2 bit_4.0.5
[27] xfun_0.41 zlibbioc_1.48.0
[29] cachem_1.0.8 GenomeInfoDb_1.38.5
[31] progress_1.2.3 blob_1.2.4
[33] rhdf5filters_1.14.1 gmp_0.7-3
[35] DelayedArray_0.28.0 Rhdf5lib_1.24.1
[37] terra_1.7-65 parallel_4.3.2
[39] prettyunits_1.2.0 R6_2.5.1
[41] stringi_1.8.3 ClusterR_1.3.2
[43] GenomicRanges_1.54.1 Rcpp_1.0.11
[45] assertthat_0.2.1 SummarizedExperiment_1.32.0
[47] knitr_1.45 IRanges_2.36.0
[49] Matrix_1.6-4 tidyselect_1.2.0
[51] yaml_2.3.8 rstudioapi_0.15.0
[53] abind_1.4-5 codetools_0.2-19
[55] curl_5.2.0 lattice_0.21-9
[57] tibble_3.2.1 Biobase_2.62.0
[59] KEGGREST_1.42.0 evaluate_0.23
[61] sf_1.0-15 units_0.8-5
[63] proxy_0.4-27 BiocFileCache_2.10.1
[65] xml2_1.3.6 Biostrings_2.70.1
[67] pillar_1.9.0 filelock_1.0.3
[69] MatrixGenerics_1.14.0 KernSmooth_2.23-22
[71] checkmate_2.3.1 stats4_4.3.2
[73] generics_0.1.3 RCurl_1.98-1.13
[75] S4Vectors_0.40.2 hms_1.1.3
[77] ggplot2_3.4.4 munsell_0.5.0
[79] scales_1.3.0 class_7.3-22
[81] glue_1.6.2 tools_4.3.2
[83] GiottoVisuals_0.1.1 data.table_1.14.10
[85] XML_3.99-0.16 cowplot_1.1.2
[87] rhdf5_2.46.1 grid_4.3.2
[89] AnnotationDbi_1.64.1 colorspace_2.1-0
[91] SingleCellExperiment_1.24.0 GenomeInfoDbData_1.2.11
[93] cli_3.6.2 rappdirs_0.3.3
[95] fansi_1.0.6 S4Arrays_1.2.0
[97] arrow_14.0.0.2 dplyr_1.1.4
[99] gtable_0.3.4 digest_0.6.33
[101] progressr_0.14.0 BiocGenerics_0.48.1
[103] classInt_0.4-10 SparseArray_1.2.3
[105] rjson_0.2.21 memoise_2.0.1
[107] htmltools_0.5.7 lifecycle_1.0.4
[109] httr_1.4.7 bit64_4.0.5