In brunobrr/bdc: Biodiversity Data Cleaning

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  echo = TRUE,
  warning = FALSE,
  eval = F
)

This tutorial will guide you through the installation of gnparser, a required binary file for using our R package. The installation process varies depending on your operating system (Windows, macOS, or Linux).

We provide two installation options: using reproducible code or following a manual step-by-step installation. The first option is a quick and easy way to install the software. In case of errors, you can try the manual step-by-step approach.

Option 1: Run the following code

Installing and loading bdc package

install.packages("bdc")
library(bdc)

⚠ Important: Get the latest version of gnparser. The execution of this step is required independently of our operation system.

  get_latest_gnparser_version <- function() {
    url <- "https://github.com/gnames/gnparser/releases"

    # Reads the content of the releases page
    page <- xml2::read_html(url)

    # Extracts the first tag containing the version, using a CSS selector
    version <- page %>%
      rvest::html_element(".Link--primary") %>%
      rvest::html_text2()

    version <- gsub("v", "", version)
    return(version)
  }

  latest_version <- get_latest_gnparser_version()
  message("Latest version of gnparser: ", latest_version)

Windows

Download the lastest version of gnparser

link <- "https://github.com/gnames/gnparser/releases/download/"
url_latest_version = paste0(link, "v", latest_version, "/gnparser-v", latest_version, "-win-arm.zip")
file_name = here::here(paste0(latest_version, ".zip"))

download.file(url_latest_version, file_name)

Move file to the recommended directory

# Extracts the file in a temporary directory
unzip(file_name, exdir = here::here())

# Sets the destination filename
AppData_path <- Sys.getenv("AppData")

# Moves the executable to the target directory
file.copy("gnparser.exe", AppData_path, recursive = TRUE)

Linux

Download the lastest version of gnparser

link <- "https://github.com/gnames/gnparser/releases/download/"
url_latest_version = paste0(link, "v", latest_version, "/gnparser-v", latest_version, "-linux-arm.tar.gz")
file_name = here::here(paste0(latest_version, ".tar.gz"))

download.file(url_latest_version, file_name)

Move file to the recommended directory

# Extracts the file in a temporary directory
untar(file_name, exdir = here::here())

# Moves the executable to the target directory
file.copy(here::here("gnparser"), "~/bin")

macOS

⚠️IMPORTANT: Before installing gnparser, it is highly recommend to install Homebrew, which is a package manager for macOS and Linux that simplifies the installation of software and libraries directly from the terminal. You can use the steps below to install Homebrew. Moreover, a detailed explanation on how to install homebrew can be found in this video.

1. Open Terminal

   • Press Command + Space to open Spotlight Search
   • Type "Terminal" and press Enter
   • A new window will appear - this is your Terminal

2. Using Homebrew (Recommended)

   • In the Terminal window, paste and run these commands:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. Install gnparser using brew

brew tap gnames/gn 
brew install gnparser

After that, close the terminal and refresh the R section.

Option 2: Manual Installation

Windows

1. Download the installer

   • Go to gnparser releases
   • Download the Windows version (file ending in -win-64.zip)
   • Save it to a known location on your computer

2. Open Command Prompt

   • Press Windows + R on your keyboard
   • Type cmd and press Enter
   • A black window will appear - this is your Command Prompt

3. Create installation directory

   • In the Command Prompt window, type:

   cmd mkdir C:\bin

4. Extract and move the file

   • Extract the downloaded zip file

   • Copy the gnparser.exe file to C:\bin using either:

     • Windows Explorer (drag and drop)
     • Or Command Prompt:

     cmd copy path\to\downloaded\gnparser.exe C:\bin

5. Add to System Path

   • Press Windows + X and select "System"
   • Click "Advanced system settings"
   • Click "Environment Variables"
   • Under "System variables", find and select "Path"
   • Click "Edit"
   • Click "New"
   • Add C:\bin
   • Click "OK" on all windows

6. Verify installation

   • Open a new Command Prompt window
   • Type:

   cmd gnparser --version

   • If you see a version number, the installation was successful

Linux

1. Open Terminal

   • Press Ctrl + Alt + T (on most Linux distributions)
   • Or find Terminal in your applications menu
   • A new window will appear - this is your Terminal

2. Download the binary

   • In the Terminal window, run these commands:

   ``` bash

   Create a temporary directory

   mkdir -p ~/tmp cd ~/tmp

   Download the latest Linux version

   wget https://github.com/gnames/gnparser/releases/download/v1.10.1/gnparser-v1.10.1-linux.tar.gz

   Extract the file

   tar xvf gnparser-*.tar.gz

   Move to system directory

   sudo mv gnparser /usr/local/bin ```

3. Verify installation

   bash gnparser --version

macOS

1. Open Terminal

   • Press Command + Space to open Spotlight Search
   • Type "Terminal" and press Enter
   • A new window will appear - this is your Terminal

2. Using Homebrew (Recommended)

   • In the Terminal window, paste and run these commands:

   ``` bash

   Install Homebrew if you haven't already

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   Install gnparser

   brew tap gnames/gn brew install gnparser ```

3. Manual Installation

   • Download the macOS version (file ending in -mac.tar.gz) from gnparser releases
   • Open Terminal (Applications > Utilities > Terminal)
   • Navigate to the download directory:

   bash cd ~/Downloads

   • Extract the file:

   bash tar xvf gnparser-v*.tar.gz

   • Move to system directory:

   bash sudo mv gnparser /usr/local/bin

   • You may need to allow the application in System Preferences:
     • Go to System Preferences > Security & Privacy
     • Click the lock to make changes
     • Allow gnparser to run ```

Troubleshooting

If you encounter any issues:

1. Command not found

   • Make sure you've added the correct directory to your system PATH
   • Try closing and reopening your terminal/command prompt

2. Permission denied

   • On macOS/Linux, you may need to make the file executable:

   bash chmod +x /usr/local/bin/gnparser

3. Security warnings

   • On macOS: Go to System Preferences > Security & Privacy and allow the application
   • On Windows: You might need to run as administrator

Testing the Installation

After installation, test if gnparser is working correctly:

# In R, try parsing a scientific name
test <-
  bdc::bdc_clean_names(c("OCOTEA odorifera", "ocotea odorifera", "ocotea cf. odorifera"))

brunobrr/bdc documentation built on Nov. 21, 2024, 4:18 a.m.