Installing gnparser

bdc_clean_names() uses gnparser, a small program that splits scientific names into their parts. gnparser is not an R package, so it must be installed separately, once per computer.

There are two ways to install it:

Option 1 (recommended): copy one block of R code into the R console and run it. It works on Windows, macOS and Linux, and needs no administrator password.
Option 2: download and copy the file by hand. Use it if Option 1 fails.

Option 1: Install from R

Step 1. Install bdc, if you have not done so yet:

install.packages("bdc")

Step 2. Copy the whole block below, paste it into the R console and press Enter. It finds out your operating system and processor, downloads the latest version of gnparser, and copies it to the folder where bdc looks for it.

# Operating system ("win", "mac" or "linux") and processor ("x86" or "arm")
os <- switch(Sys.info()[["sysname"]],
  Windows = "win",
  Darwin = "mac",
  "linux"
)
arch <- if (R.version$arch %in% c("aarch64", "arm64")) "arm" else "x86"

# Latest version of gnparser, e.g. "v1.15.1"
version <- jsonlite::fromJSON(
  "https://api.github.com/repos/gnames/gnparser/releases/latest"
)$tag_name

# Downloads and extracts gnparser into a temporary folder
extension <- if (os == "win") ".zip" else ".tar.gz"
url <- paste0(
  "https://github.com/gnames/gnparser/releases/download/", version,
  "/gnparser-", version, "-", os, "-", arch, extension
)
archive <- file.path(tempdir(), basename(url))
download.file(url, archive, mode = "wb")
if (os == "win") {
  unzip(archive, exdir = tempdir())
} else {
  untar(archive, exdir = tempdir())
}

# Copies gnparser to the folder where bdc looks for it
folder <- switch(os,
  win = file.path(Sys.getenv("APPDATA"), "gnparser"),
  mac = "~/Library/Application Support/gnparser",
  linux = "~/bin"
)
program <- if (os == "win") "gnparser.exe" else "gnparser"
dir.create(folder, recursive = TRUE, showWarnings = FALSE)
file.copy(file.path(tempdir(), program), folder, overwrite = TRUE)
Sys.chmod(file.path(folder, program), mode = "755")

# Shows the installed version: if you see a version number, it worked
rgnparser::gn_version()

Step 3. Restart R (in RStudio: Session > Restart R) and go to Testing the installation.

Option 2: Manual installation

First, download the file for your computer from the gnparser releases page, under Assets:

Computer	File ending in
Windows (most computers)	`-win-x86.zip`
Windows on ARM processors	`-win-arm.zip`
Mac with Apple processor (M1, M2, …)	`-mac-arm.tar.gz`
Mac with Intel processor	`-mac-x86.tar.gz`
Linux (most computers)	`-linux-x86.tar.gz`
Linux on ARM processors	`-linux-arm.tar.gz`

To find your processor, run R.version$arch in R: aarch64 or arm64 means ARM (Apple processor on a Mac); anything else means x86.

Windows

Open the Downloads folder, right-click the .zip file and choose Extract All. You get a file named gnparser.exe.
Click the address bar of the File Explorer window, type %APPDATA% and press Enter.
In that folder, create a new folder named gnparser and move gnparser.exe into it. The file must end up in %APPDATA%\gnparser\gnparser.exe.

macOS

Open the Downloads folder and double-click the .tar.gz file. You get a file named gnparser.
In Finder, choose Go > Go to Folder…, type ~/Library/Application Support and press Enter.
In that folder, create a new folder named gnparser and move the gnparser file into it.
macOS blocks programs downloaded with a web browser. To unblock gnparser, open Terminal (press Command + Space, type “Terminal” and press Enter), paste this line and press Enter:
```
xattr -d com.apple.quarantine ~/Library/Application\ Support/gnparser/gnparser
```

If you use Homebrew, you can instead run brew tap gnames/gn and then brew install gnparser in Terminal.

Linux

Open a terminal (Ctrl + Alt + T on most distributions) and run the lines below. Replace x86 with arm on ARM processors, and v1.15.1 with the latest version shown on the releases page.

cd ~/Downloads
curl -LO https://github.com/gnames/gnparser/releases/download/v1.15.1/gnparser-v1.15.1-linux-x86.tar.gz
tar xvf gnparser-v1.15.1-linux-x86.tar.gz
mkdir -p ~/bin
mv gnparser ~/bin/

Testing the installation

Restart R and run:

# Shows the installed version of gnparser
rgnparser::gn_version()

# Cleans three spellings of the same name
bdc::bdc_clean_names(
  c("OCOTEA odorifera", "ocotea odorifera", "ocotea cf. odorifera")
)

If you see a version number and a table with the cleaned names, gnparser is installed.

Troubleshooting

“gnparser not found” or “GNparser is not installed in your machine”: restart R and try again. If the message persists, check that the file is in the right folder: %APPDATA%\gnparser\gnparser.exe on Windows, ~/Library/Application Support/gnparser/gnparser on macOS, or ~/bin/gnparser on Linux.
Option 1 stops at jsonlite::fromJSON() with “HTTP error 403”: GitHub limits how often a computer can ask for the latest version. Wait an hour and try again, or use Option 2.
Option 1 stops at download.file(): check your internet connection. Networks with a proxy or firewall (e.g. at universities) may block the download; in that case, use Option 2.
macOS says gnparser “cannot be opened because the developer cannot be verified”: run the xattr line from step 4 of the macOS manual installation.
Windows: the antivirus removes gnparser.exe: allow the file in the antivirus settings and copy it again.
Linux: “Permission denied”: make the file executable with chmod +x ~/bin/gnparser.