From 64411e46fb4613f5f80237c185416f49791a6522 Mon Sep 17 00:00:00 2001 From: "Jonas I. Liechti" Date: Mon, 15 Jul 2024 12:16:31 +0200 Subject: [PATCH] structure by OS --- README.md | 463 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 262 insertions(+), 201 deletions(-) diff --git a/README.md b/README.md index cf66acaa..6d8c7d60 100644 --- a/README.md +++ b/README.md @@ -23,48 +23,112 @@ The package provides routines for structure learning and parameter estimation of `abn` and its installation process relies on various software that might, or might not, be present in your system. -The [Prerequisites](#prerequisites) section contains information about software that is needed but is (very) likely already installed in your system. -In the [Dependencies](#dependencies) section you will find information about required software that is likely not already present. +In order for `abn` to work correctly on your system some dependencies need to be installed first. +The required step to achieve this are specific to the operation system you are using and the following drop-down sections detail these steps for the most common ones: -We recommend to go through both sections and follow the suggested installation process for your operating system before you try to install `abn`. -## R version support +
+Ubuntu -Officially supported is R version >= 4.4 +#### Prerequisites -## Prerequisites +Most likely you have R installed already but if not run: -
- Ubuntu - +```bash +apt-get install r-base +``` - Most likely you have R installed already but if not run: - +To configure and build `abn` correctly we need `cmake` and `pkg-config`, as well as, the R `devtools` package: + +```bash +apt-get install pkg-config +apt-get install cmake +apt-get install r-cran-devtools +``` + +Finally, we will use `wget` to download `JAGS` later, as well as, the development headers of `curl` and `openssl`: + +```bash +apt-get install wget +apt-get install libcurl4-openssl-dev +apt-get install libssl-dev + +``` + +#### Dependencies + +- **GSL** + + [GSL](https://www.gnu.org/software/gsl/), the _GNU Scientific Library_, is a numerical library for C/C++. + It is required to compile `abn`'s C/C++ code. + + `GSL` is available through the Advanced Package Tool, `APT`, simply type: + ```bash - apt-get install r-base + sudo apt-get install libgsl-dev ``` - To configure and build `abn` correctly we need `cmake` and `pkg-config`, as well as, the R `devtools` package: - +- **JAGS & rjags** + + [JAGS](https://mcmc-jags.sourceforge.io/), _Just Another Gibbs Sampler_, is a program for analyzing Bayesian hierarchical models using Markov Chain Monte Carlo (MCMC) simulation. [rjags](https://cran.r-project.org/web/packages/rjags/index.html) is R's interface to the `JAGS` library. + `JAGS` is required in some simulations `abn` can perform. + + `JAGS` is available through the Advanced Package Tool, `APT`, simply type: + ```bash - apt-get install pkg-config - apt-get install cmake - apt-get install r-cran-devtools + sudo apt-get install jags + ``` + And to install `rjags` open an R session and type: + + ```R + install.packages("rjags", configure.args="--enable-rpath", repos=c(CRAN="https://cran.r-project.org")) + library("rjags") ``` - Finally, we will use `wget` to download `JAGS` later, as well as, the development headers of `curl` and `openssl`: +- **INLA** + [INLA](https://www.r-inla.org/) is an R package that is not hosted on CRAN and thus needs to be installed separately. + `anb` uses `INLA` to fit some models. + + `INLA` relies on various other R packages and C/C++ libraries. + It thus needs some additional installation steps: + ```bash - apt-get install wget - apt-get install libcurl4-openssl-dev - apt-get install libssl-dev + apt-get install --no-install-recommends libudunits2-dev + apt-get install libjpeg-dev + apt-get install libgdal-dev + apt-get install libgeos-dev # might not be needed + apt-get install libproj-dev + ``` + Now, to install `INLA` itself, simply start an R session and run: + + ```R + install.packages("INLA", repos = c(getOption("repos"), INLA = "https://inla.r-inla-download.org/R/stable"), dep = TRUE) + ``` + + If you run into trouble, please see also [INLA's installation instructions](https://www.r-inla.org/download-install) for further details. + +- **Dependencies from BiocManager** + + [Rgraphviz](https://www.bioconductor.org/packages/release/bioc/html/Rgraphviz.html) and [graph](https://bioconductor.org/packages/3.19/bioc/html/graph.html) are used to produce plots of network graphs. + Both packages are hosted on [Bioconductor](https://www.bioconductor.org/) and thus need to be installed with `BiocManager`: + + The installation is straight forward on most common platforms, simply start an R session and run: + + ```R + if (!requireNamespace("BiocManager", quietly = TRUE)) + install.packages("BiocManager") + BiocManager::install("Rgraphviz") + BiocManager::install("graph") ```
- Fedora +Fedora + +#### Prerequisites You will need C/C++ and Fortran compilers and various libraries: @@ -98,10 +162,107 @@ Officially supported is R version >= 4.4 dnf install libcurl-devel dnf install openssl-devel ``` + +#### Dependencies + +- **GSL** + + [GSL](https://www.gnu.org/software/gsl/), the _GNU Scientific Library_, is a numerical library for C/C++. + It is required to compile `abn`'s C/C++ code. + + `GSL` is available through Fedoras standard package manager, `DNF`, simply type: + + ```bash + sudo dnf install gsl-devel + ``` + +- **JAGS & rjags** + + [JAGS](https://mcmc-jags.sourceforge.io/), _Just Another Gibbs Sampler_, is a program for analyzing Bayesian hierarchical models using Markov Chain Monte Carlo (MCMC) simulation. [rjags](https://cran.r-project.org/web/packages/rjags/index.html) is R's interface to the `JAGS` library. + `JAGS` is required in some simulations `abn` can perform. + + `JAGS` must be installed from source. + Below are the steps to install `JAGS 4.3.2`. + + ```bash + wget -O /tmp/jags.tar.gz https://sourceforge.net/projects/mcmc-jags/files/JAGS/4.x/Source/JAGS-4.3.2.tar.gz/download + cd /tmp + tar -xf jags.tar.gz + cd /tmp/JAGS-4.3.2 + ./configure --libdir=/usr/local/lib64 + make + sudo make install + ``` + + > [!NOTE] + > If you are on a 64bit system (you likely are) mind the `--libdir=/usr/local/lib64` argument when launching `./configure`. + > Omitting this argument will lead to `rjags` "not seeing" `jags`. + + + On Fedora `rjags` might need some special configuration for it to link properly to the `JAGS` library. + Also, it might be needed to add the path to the `JAGS` library to the linker path (see [rjags INSTALL file](https://github.com/cran/rjags/blob/master/INSTALL) for further details). + + In order to add the `JAGS` library to the linker path, run the following commands: + + ```bash + sudo echo "/usr/local/lib64" > /etc/ld.so.conf.d/jags.conf + sudo /sbin/ldconfig + ``` + + **Note:** + _These commands might not be needed, you might first try to install `rjags` (see below) and only run them if you encounter a `configure: error: Runtime link error`._ + + To install `rjags` open an R session and type: + + ```R + install.packages("rjags", configure.args="--enable-rpath", repos=c(CRAN="https://cran.r-project.org")) + ``` + +- **INLA** + + [INLA](https://www.r-inla.org/) is an R package that is not hosted on CRAN and thus needs to be installed separately. + `anb` uses `INLA` to fit some models. + + `INLA` relies on various other R packages and C/C++ libraries. + It thus needs some additional installation steps: + + ```bash + dnf install udunits2-devel + dnf install libjpeg-devel + dnf install gdal-devel + dnf install geos-devel + dnf install proj-devel + ``` + + Now, to install `INLA` itself, simply start an R session and run: + + ```R + install.packages("INLA", repos = c(getOption("repos"), INLA = "https://inla.r-inla-download.org/R/stable"), dep = TRUE) + ``` + + If you run into trouble, please see also [INLA's installation instructions](https://www.r-inla.org/download-install) for further details. + +- **Dependencies from BiocManager** + + [Rgraphviz](https://www.bioconductor.org/packages/release/bioc/html/Rgraphviz.html) and [graph](https://bioconductor.org/packages/3.19/bioc/html/graph.html) are used to produce plots of network graphs. + Both packages are hosted on [Bioconductor](https://www.bioconductor.org/) and thus need to be installed with `BiocManager`: + + The installation is straight forward on most common platforms, simply start an R session and run: + + ```R + if (!requireNamespace("BiocManager", quietly = TRUE)) + install.packages("BiocManager") + BiocManager::install("Rgraphviz") + BiocManager::install("graph") + ``` +
- MacOS +MacOS + +#### Prerequisites + The installation process on MacOS relies on [Homebrew](https://brew.sh/), head over to their site to see the installation process or simply open a terminal and run: @@ -129,151 +290,101 @@ Officially supported is R version >= 4.4 brew install R ``` -
- -## Dependencies -`abn` has a few **dependencies that need to be installed** before installing the package itself. -Some are C/C++ libraries and some are R packages that are not hosted on CRAN. +#### Dependencies -Below is a list of these dependencies with details on how to install and configure them: +- **GSL** --
- GSL - [GSL](https://www.gnu.org/software/gsl/), the _GNU Scientific Library_, is a numerical library for C/C++. It is required to compile `abn`'s C/C++ code. - - #### Installation - -
- Ubuntu - - `GSL` is available through the Advanced Package Tool, `APT`, simply type: - - ```bash - sudo apt-get install libgsl-dev - ``` - -
-
- Fedora - - `GSL` is available through Fedoras standard package manager, `DNF`, simply type: - - ```bash - sudo dnf -y install gsl-devel - ``` - -
-
- MacOS - + With Homebrew you can install the `GSL` binaries directly: ``` brew install gsl ``` -
-
- Windows - - In Windows `GSL` is available a.o. through [cygwin](https://cygwin.com/index.html), which has a straight forward installation process. - Either head over to the website, download and install the setup-x86_64.exe file, or use PowerShell: - - ``` - Import-Module bitstransfer - New-Item -ItemType Directory -Force -Path "C:\Program Files\cygwin" - start-bitstransfer -source https://cygwin.com/setup-x86_64.exe "C:\Program Files\cygwin\setup-x86_64.exe" - Start-Process -Wait -FilePath "C:\Program Files\cygwin\setup-x86_64.exe" -ArgumentList "/S" -PassThru - ``` -
-
--
JAGS & rjags + +- **JAGS & rjags** [JAGS](https://mcmc-jags.sourceforge.io/), _Just Another Gibbs Sampler_, is a program for analyzing Bayesian hierarchical models using Markov Chain Monte Carlo (MCMC) simulation. [rjags](https://cran.r-project.org/web/packages/rjags/index.html) is R's interface to the `JAGS` library. `JAGS` is required in some simulations `abn` can perform. + + With Homebrew you can install the `JAGS` binaries directly: - #### Installation - - In principle, we could only install `JAGS` and have `rjags` be installed automatically as dependency when installing `abn`, however, there are situations where `rjags` cannot find the `JAGS` libraries or `jags` at runtime, and therefore we recommend installing `rjags` directly after `JAGS` so to make sure that everything works as expected: - -
- Ubuntu - - `JAGS` is available through the Advanced Package Tool, `APT`, simply type: - - ```bash - sudo apt-get install jags ``` - And to install `rjags` open an R session and type: + brew install jags + ``` + + And now to install `rjags`, open an R session and type: ```R - install.packages("rjags", configure.args="--enable-rpath", repos=c(CRAN="https://cran.r-project.org")) + install.packages("rjags", type="source", repos=c(CRAN="https://cran.r-project.org")) library("rjags") ``` + +- **INLA** + + [INLA](https://www.r-inla.org/) is an R package that is not hosted on CRAN and thus needs to be installed separately. + `anb` uses `INLA` to fit some models. -
-
- Fedora - - `JAGS` must be installed from source. - Below are the steps to install `JAGS 4.3.2`. + `INLA` relies on various other R packages and C/C++ libraries. + It thus needs some additional installation steps: ```bash - wget -O /tmp/jags.tar.gz https://sourceforge.net/projects/mcmc-jags/files/JAGS/4.x/Source/JAGS-4.3.2.tar.gz/download - cd /tmp - tar -xf jags.tar.gz - cd /tmp/JAGS-4.3.2 - ./configure --libdir=/usr/local/lib64 - make - sudo make install + brew install udunits + brew install gdal # installs also geos as dependency + brew install proj ``` - - **Note:** - - _If you are on a 64bit system (you likely are) mind the `--libdir=/usr/local/lib64` argument when launching `./configure`._ - _Omitting this argument will lead to `rjags` "not seeing" `jags`._ - - - On Fedora `rjags` might need some special configuration for it to link properly to the `JAGS` library. - Also, it might be needed to add the path to the `JAGS` library to the linker path (see [rjags INSTALL file](https://github.com/cran/rjags/blob/master/INSTALL) for further details). - - In order to add the `JAGS` library to the linker path, run the following commands: - - ```bash - sudo echo "/usr/local/lib64" > /etc/ld.so.conf.d/jags.conf - sudo /sbin/ldconfig - ``` - **Note:** - _These commands might not be needed, you might first try to install `rjags` (see below) and only run them if you encounter a `configure: error: Runtime link error`._ - - To install `rjags` open an R session and type: + + Now, to install `INLA` itself, simply start an R session and run: ```R - install.packages("rjags", configure.args="--enable-rpath", repos=c(CRAN="https://cran.r-project.org")) + install.packages("INLA", repos = c(getOption("repos"), INLA = "https://inla.r-inla-download.org/R/stable"), dep = TRUE) ``` -
-
- MacOS - - With Homebrew you can install the `JAGS` binaries directly: + If you run into trouble, please see also [INLA's installation instructions](https://www.r-inla.org/download-install) for further details. + +- **Dependencies from BiocManager** + + [Rgraphviz](https://www.bioconductor.org/packages/release/bioc/html/Rgraphviz.html) and [graph](https://bioconductor.org/packages/3.19/bioc/html/graph.html) are used to produce plots of network graphs. + Both packages are hosted on [Bioconductor](https://www.bioconductor.org/) and thus need to be installed with `BiocManager`: + + The installation is straight forward on most common platforms, simply start an R session and run: + ```R + if (!requireNamespace("BiocManager", quietly = TRUE)) + install.packages("BiocManager") + BiocManager::install("Rgraphviz") + BiocManager::install("graph") ``` - brew install jags - ``` - - And now to install `rjags`, open an R session and type: + +
+ +
+Windows + +#### Dependencies + +- **GSL** + + [GSL](https://www.gnu.org/software/gsl/), the _GNU Scientific Library_, is a numerical library for C/C++. + It is required to compile `abn`'s C/C++ code. + + In Windows `GSL` is available a.o. through [cygwin](https://cygwin.com/index.html), which has a straight forward installation process. + Either head over to the website, download and install the `setup-x86_64.exe` file or use PowerShell: - ```R - install.packages("rjags", type="source", repos=c(CRAN="https://cran.r-project.org")) - library("rjags") ``` + Import-Module bitstransfer + New-Item -ItemType Directory -Force -Path "C:\Program Files\cygwin" + start-bitstransfer -source https://cygwin.com/setup-x86_64.exe "C:\Program Files\cygwin\setup-x86_64.exe" + Start-Process -Wait -FilePath "C:\Program Files\cygwin\setup-x86_64.exe" -ArgumentList "/S" -PassThru + ``` + +- **JAGS & rjags** -
-
- Windows + [JAGS](https://mcmc-jags.sourceforge.io/), _Just Another Gibbs Sampler_, is a program for analyzing Bayesian hierarchical models using Markov Chain Monte Carlo (MCMC) simulation. [rjags](https://cran.r-project.org/web/packages/rjags/index.html) is R's interface to the `JAGS` library. + `JAGS` is required in some simulations `abn` can perform. + You can either head over to the [JAGS download page](https://sourceforge.net/projects/mcmc-jags/files/JAGS/4.x/Windows/), download and execute the installable, or use PowerShell. The following instructions will download and install `JAGS 4.3.1` in PowerShell: @@ -293,79 +404,25 @@ Below is a list of these dependencies with details on how to install and configu install.packages("rjags", repos=c(CRAN="https://cran.r-project.org")) library("rjags") ``` - -
-
--
- INLA - + +- **INLA** + [INLA](https://www.r-inla.org/) is an R package that is not hosted on CRAN and thus needs to be installed separately. `anb` uses `INLA` to fit some models. - #### Dependencies - - `INLA` relies on various other R packages and C/C++ libraries. - It thus needs some additional installation steps: - -
- Ubuntu - - Install with: - - ```bash - apt-get install --no-install-recommends libudunits2-dev - apt-get install libjpeg-dev - apt-get install libgdal-dev - apt-get install libgeos-dev # might not be needed - apt-get install libproj-dev - ``` -
-
- Fedora - - Install with: - - ```bash - dnf install udunits2-devel - dnf install libjpeg-devel - dnf install gdal-devel - dnf install geos-devel - dnf install proj-devel - ``` - -
-
- MacOS - - Install with: - - ```bash - brew install udunits - brew install gdal # installs also geos as dependency - brew install proj - ``` - -
- - #### Installation - - The installation is straight forward on common platforms, simply start an R session and run: + The installation is straight forward, simply start an R session and run: ```R install.packages("INLA", repos = c(getOption("repos"), INLA = "https://inla.r-inla-download.org/R/stable"), dep = TRUE) ``` If you run into trouble, please see also [INLA's installation instructions](https://www.r-inla.org/download-install) for further details. - -
--
- Dependencies from BiocManager - + +- **Dependencies from BiocManager** + [Rgraphviz](https://www.bioconductor.org/packages/release/bioc/html/Rgraphviz.html) and [graph](https://bioconductor.org/packages/3.19/bioc/html/graph.html) are used to produce plots of network graphs. Both packages are hosted on [Bioconductor](https://www.bioconductor.org/) and thus need to be installed with `BiocManager`: - - #### Installation - + The installation is straight forward on most common platforms, simply start an R session and run: ```R @@ -374,10 +431,14 @@ Below is a list of these dependencies with details on how to install and configu BiocManager::install("Rgraphviz") BiocManager::install("graph") ``` - -
-_Click on each dependency to see the specific installation instructions_ +
+ +_Click on your operation system to see the specific installation instructions_ + +## R version support + +Officially supported is R version >= 4.4 ## Installing from GitHub (recommended)