Chapter 2 Setting up IsoriX
2.1 Installation
Before installing a new package it is good practice to have the latest version of R installed. The current documentation has been created with R version 4.3.2 (2023-10-31). So make sure you have at least an R version as recent as that one.
Please also make sure that all your R packages are up to date. You can update them all by simply typing in the R console update.packages(); and if you don’t want to be bothered by confirmation messages asking you to type Y or yes, just add the option ask = FALSE.
Once your R and all installed R packages are up to date, you are ready to install IsoriX.
When it comes to installing IsoriX, you have to choose between installing either the stable version or the development version. We recommend you to use the stable version unless advised otherwise by us (e.g. following discussions on our mailing list).
The stable version does not change very often, but it should be stable (i.e. not broken or buggy). The development version changes more often and corresponds to work in progress. Once the development version is mature enough, a new stable version is created and a new round of development starts from scratch.
2.1.1 Installing the stable version
You can install the latest stable release of IsoriX – the version hosted by the Comprehensive R Archive Network (CRAN) – as follows:
This command will install IsoriX, as well as all packages IsoriX depends on. If you don’t specify dependencies = TRUE, the suggested packages – that is those we use in some examples but that are not essential to IsoriX – will not be installed.
Any package should only be installed once for a given R installation. Then, just keep updating regularly your packages if you want less bugs and more functionalities. You will have to install IsoriX from scratch again only after reinstalling R.
2.1.2 Installing the development version
In-between two consecutive releases of IsoriX on CRAN, we keep updating a development version of the package. The development version corresponds to a work in progress and should thus be considered as such. It may contain new features and fixes to bugs identified in the current official version but the new code may not be very mature and the documentation may be lagging behind. It must thus been used at your own risk and/or under the guidance of the IsoriX developers.
If you want to install such development version, the easiest is to install the package remotes (if it is not already present on your system) and to use that package it to install the copy of IsoriX stored on GitHub:
## install remotes if missing
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}
## install IsoriX devel
remotes::install_github("courtiol/IsoriX/IsoriX", dependencies = TRUE)Geeky note: Note that the double mention of IsoriX in "courtiol/IsoriX/IsoriX" is not a typo: the name is present twice because on our IsoriX repository in GitHub the content of the R package is located inside a sub-folder also called IsoriX.
2.2 Dependencies to other R packages
In the unlikely event you encounter a difficulty installing IsoriX, that may come from another package on which IsoriX depends, or from another package on which these other packages depends on, and so on.
Indeed, much of the work performed by a given package in R is actually outsourced to other packages. As mentioned in chapter 1 IsoriX uses, for example, spaMM to fit the models and rasterVis to make the plots. Thus, if a single package that is needed by IsoriX (or by the packages used by IsoriX) cannot install, IsoriX will not install (or worse, it may install but not work).
To avoid problems caused by dependencies, the only thing we can do on our side is to minimise dependencies and try not to use packages people have often problems with. That is why we have already stopped relying on packages (e.g. Cairo) which are not so easy to install on some systems.
Despite these effort, for IsoriX to work we do rely on 15 packages. Here is the current list:
pkg_IsoriX_Imports <- tools::package_dependencies("IsoriX",
which = "Imports",
recursive = FALSE)$IsoriX
pkg_IsoriX_Suggests <- tools::package_dependencies("IsoriX",
which = "Suggests",
recursive = FALSE)$IsoriX
pkg_base <- names(which(installed.packages()[, "Priority"] == "base"))
## Packages required for key functionalities in IsoriX:
data.frame(Imported_packages = sort(setdiff(pkg_IsoriX_Imports, pkg_base)))## Packages adding extra functionalities to IsoriX:
data.frame(Suggested_packages = sort(setdiff(pkg_IsoriX_Suggests, pkg_base)))We can use a modified version of miniCRAN to visualise dependencies among the core packages required by IsoriX:
## install remotes if missing
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}
## install special fork from miniCRAN
if (!requireNamespace("miniCRAN", quietly = TRUE)) {
remotes::install_github("courtiol/miniCRAN@Recursion_optional")
}
## setting the RNG seed controls the rotation in the plot
set.seed(1)
## plotting dependencies
plot(miniCRAN::makeDepGraph("IsoriX", recursive = FALSE, suggests = FALSE))
Geeky note: We are not using the original version of the package miniCRAN because it would display the own dependencies of each dependency of IsoriX.
While the number of dependencies is reasonable, since each package depends on other packages, the current stable release of IsoriX indirectly uses 69 packages (on top of some R base packages) and 59 more packages can optionally be used to increase functionalities.
All in all, this represents quite a lot of dependencies, and problems can thus happen.
In case of problem(s), you should thus read carefully the error message and make sure that the problem is not caused by some other packages. If that is the case, try to install the problematic packages on their own (check the documentation of that other packages, it may help). A work around is to simply not rely on the problematic packages. That is possible as long as the problematic packages are among those that IsoriX “suggests” (or among those that are required by such suggested packages) and not packages that IsoriX depends on. The list of such packages that are not crucial for IsoriX (but that offer additional functionalities) is this: AsioHeaders, askpass, base64enc, bslib, cachem, chromote, class, classInt, codetools, colorspace, commonmark, cpp11, curl, DBI, e1071, elevatr, ellipsis, fastmap, fontawesome, furrr, future, globals, highr, htmltools, htmlwidgets, httr, hunspell, jquerylib, KernSmooth, knitr, later, listenv, magick, memoise, mime, openssl, parallelly, progressr, promises, purrr, rappdirs, rgl, rmarkdown, s2, sass, sf, slippymath, spelling, stringi, stringr, sys, tinytex, units, webshot2, websocket, wk, xfun, xml2, yaml.
Since IsoriX could live without them and still perform all essential tasks, to circumvent installation issues on your system you may try to install IsoriX again without them using:
That way the argument dependencies of the function install.packages() will be set to its default setting NA, which does not lead to install “suggested” packages.
Note: if you are used to install the packages using the RStudio menu, there is a small box that you can tick or untick to do the same thing.
2.3 Loading IsoriX
Once you have installed IsoriX, before using it you must load it. And this must be done every single time you restart your R session. To load IsoriX simply do:
If you have just updated IsoriX, don’t forget to check the news by typing news(package = "IsoriX"). This will show you what we have changed since the last version!
2.4 Working directory
Don’t forget to set up your working directory, that is to tell R in which folder you want to work. This matters because you will have to read and write files in this directory while using IsoriX. The best is to let RStudio handle that automatically by using an RStudio project.
Otherwise, you can set the working directory by hand using the R command setwd().
You can also use the RStudio menu for that or the shortcut that seems to be (as default) CTRL-SHIFT-H.
In any case, double check that the folder you selected in the correct one by looking at the content of the working directory with dir().
2.5 Global options
There are a few general options you can set up for IsoriX (see ?options_IsoriX for details).
Like the loading of the package, changing the general options must be done again each time you start an R session.
Two of these general options are particularly useful: example_maxtime and Ncpu.
The former allows you to control whether examples in the IsoriX help files should be run or not
depending on the time they take. We have to restrict long examples to run since CRAN, the platform
hosting R packages, checks all examples but do not allow for them to last more than a few seconds.
None of our examples takes a terribly long time to run so we recommend you to activate them all by typing:
The option Ncpu allows you to set up how many Central Processing Units (CPUs) you allow IsoriX to use.
Most computer nowadays have 2, 4 or 8. If a function can use several CPUs and performed
so-called parallel computing, the computation will be much faster if you allows it to use more CPUs.
For now, only a few functions in IsoriX can make good use of that.
We will try to make more functions able to perform such parallel computing in the future.
We considered 2 as the default number of CPUs, but you may want to increase this. For example if you have 4 CPUs you can do: