Skip to contents

Installing and setting up rPHG and rJava

Source: vignettes/rphg_installation.Rmd
rphg_installation.Rmd

In contrast to other R packages, installing rPHG involves additional steps that require linking the package to Java. This document will show you how to set up rJava and properly load rPHG.

Installation

Prerequisite - installing rJava

Since the PHG API is written primarily in Java, a Java JDK will need to be installed on your machine. Additionally, for R to communicate with Java, the R package rJava will need to be installed. More info on the rJava package can be found here. In order to load rJava properly, ensure that you have:

  • A JDK (Java Development Kit \(\geq\) 8) installed on your system.
  • Your system environment variable JAVA_HOME is configured appropriately and points to your JDK of choice. This will usually be included in your PATH environment variable as well. Options and system environmental variables that are available from R can be seen with Sys.getenv() and more specifically Sys.getenv("JAVA_HOME").

NOTE: If you are using a UNIX system (e.g. Ubuntu) and are experiencing issues, you may need to reconfigure R with Java. To perform this, open a terminal and enter the command:

R CMD javareconf

You may need to have root privileges when performing this so you may need to add sudo to the prior command.

If you need additional steps on how to perform these actions, detailed information can be found using the following links, depending on your OS:

Install from GitHub

After you have rJava up and running on your machine, install the latest version from GitHub:

# install.packages("pak")
pak::pak("maize-genetics/rPHG")

After the package has been installed, load rPHG using:

Or, if you want to use a function without violating your environment you can use rPHG::<function>, where <function> is an rPHG function.

Set-up

Setting memory

Since certain analyses can possibly use up a lot of computational resources, memory allocation to rPHG can be modified. To change the amount of memory, use the base options() function and modify the following parameter:

options(java.parameters = c("-Xmx<memory>", "-Xms<memory>"))
⚠ This will need to be set before loading the rPHG package!

Replace <memory> with a specified unit of memory. For example, if I want to allocate a maximum of 6 GB of memory for my operations, I would use the input "-Xmx6g", where g stands for gigabyte (GB). More information about memory allocation can be found here.

Starting a logging file

Since the rPHG package is an interface to the PHG API, we can track internal API progress via a logging file. This file is beneficial for debugging, tracking, and reproducing the progress of your workflow.

⚠ It is highly recommended to set up a logging file!

To start a logging file, use the following command:

startLogger(fullPath = NULL, fileName = NULL)

If the startLogger() parameters are set to NULL, the logging file will be created in your current working directory. If you are unsure of what your working directory is in R, use the base getwd() command.

Commonly encountered issues with rJava

Problems installing rJava M1/M2/M\(n\) CPU architecture (macOS)

If you are running into issues with installing rJava using the newer Mac chip architecture, Oracle JDK currently (as of writing this) does not work. Consider an alternative JDK source such as OpenJDK or Azul JDK.

More detailed information about a possible workaround can be found in this Stack Overflow post.

Problems with rJava if you have upgraded Java (macOS)

When using macOS, if you previously had rJava working through RStudio, then you upgraded your Java and it now longer works, try the following:

At the command line type:

R CMD javareconf

Then check for a left over symbolic link via:

ls -ltr /usr/local/lib/libjvm.dylib

If the link exists, remove it, then create it fresh via these commands:

rm /usr/local/lib/libjvm.dylib
sudo ln -s $(/usr/libexec/java_home)/lib/server/libjvm.dylib /usr/local/lib

You should now be able to enter RStudio and setup rJava.

Problems loading the rJava package (Linux)

If you are using a UNIX system (e.g. Ubuntu) and are experiencing issues, you may need to reconfigure R with Java. To perform this, open a terminal and enter the command:

R CMD javareconf

You may need to have root privileges when performing this so you may need to add sudo to the prior command:

sudo R CMD javareconf