chaochangmicro / microgeo Goto Github PK

The microgeo R package warps ggplot2 and ggspatial, and other R packages involved in geographic information system (GIS) and machine learning such as gstat, raster, terra, sf, sp and caret. It permits the microbial biogeographical trait calculation, spatial data collection, and spatial interpolation, machine learning modeling/prediction and visualization for microbial biogeographical traits. Specifically, the microgeo provides the flexible visualization methods for microbial traits onto maps, e.g., gridded-based visualization, spatial interpolation and machine learning, and it is not limited to those traits calculated by microgeo package itself. Users can rapidly visualize any microbial traits calculated by other tools onto maps, and also can analyze microbiome dataset in conjunction with the data calculated by microgeo R package. The microgeo is currently undergoing continuous developments and updates. We welcome any ideas and suggestions. If you find any errors during use, please submit them to GitHub Issues or Gitee Issues.

The microgeo R package requires R >= 4.1.0 and several dependent R packages, and it is now available on both GitHub and Gitee. The installation may take a few minutes because the dependencies, especially the installation on an Ubuntu OS. Please be patient and wait for the installation process to complete. If the installation is interrupted, you may need to install several libraries. Please pay attention to the prompts during the installation process for guidance.

The microgeo R package has been tested in the following environments:

Before installing the microgeo R package, there are a few additional steps to take. Here, we present the installation procedures on the three major operating systems.

Before installing the microgeo R package on a Windows OS, the Git and RTools need to be installed. Notably, the version of RTools must be compatible with the version of R base, and please pay attention to distinguish. For example, if your R version is 4.1.0, you should install the RTools 4.0; if your R version is 4.3.2, you should install RTools 4.3.

The installation of microgeo R package on a macOS requires Xcode Command Line Tools and several system libraries. We need to install the Xcode Command Line Tools if it is not avaliable on your Mac. Just run the following codes in your terminal, and install Xcode Command Line Tools according to the prompt in the pop-up window

xcode-select --install

Usually, we can use the Homebrew to install the dependencies of microgeo R package on a macOS. Firstly, we need to install the Homebrew if it is not avaliable on your Mac. Just run the following codes in your terminal. This step may take a few minutes, especially for the old versions of Mac.

# Install the `Homebrew`
# You may need to add `185.199.110.133 raw.githubusercontent.com` to `/etc/hosts` if the network can not connect to GitHub
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 

# Configure `Homebrew` if the `brew` command is not avaliable in your therminal
# The path of `brew` may be not the `/opt/homebrew/bin` in your Mac! 
# Run `dirname $(which brew)` to find a correct path on your macOS
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc # The default terminal is `zsh` rather than `bash` in the new version of Mac; Run `echo $SHELL` to check it
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.bash_profile # The default terminal is `bash` in the old version of Mac; Run `echo $SHELL` to check it
source ~/.zshrc && source ~/.bash_profile

# Check the version of `Homebrew`
brew --version

Switching the Homebrew package manager to a mirror or source within the country is often done to improve download speeds and reduce latency for users. Homebrew relies on external servers to fetch and install software packages, and using a local mirror can significantly enhance the installation process by utilizing servers located within the country. This helps to mitigate slow download speeds that may occur when fetching packages from international servers, resulting in a more efficient and faster software installation experience for users. Here's a specific example tailored for users in Mainland China.

# Check the default mirror or source of `Homebrew` 
# The default may be `https://github.com/Homebrew/brew.git`
cd "$(brew --repo)" && git remote -v 

# Switch the default mirror to the Aliyun mirror
git -C "$(brew --repo)" remote set-url origin https://mirrors.aliyun.com/homebrew/brew.git
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.aliyun.com/homebrew/homebrew-bottles' >> ~/.zshrc
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.aliyun.com/homebrew/homebrew-bottles' >> ~/.bash_profile
source ~/.zshrc && source ~/.bash_profile

# Update 
brew update

# Sometimes, you may need to exit and re-enter the terminal for changes to take effect.
# Run `cd "$(brew --repo)" && git remote -v` to check the changes before installing the system libraries using `brew`

Now, we can use Homebrew to install the system libraries required by microgeo R packages. Just run the following codes.

brew install gdal

We also can use the MacPorts to install the system libraries required by microgeo R packages on a macOS. Please note that you must install a correct MacPorts version according to the version of your macOS. For example, I have a MacBook Pro with a macOS Sonoma v14.0, thus I need to install the MacPorts-2.8.1-14-Sonoma.pkg. Once the installation package is successfully downloaded, you only need to follow the installation wizard to complete the installation. Please note: Remember to disconnect the network before installing, otherwise the installation process will be very, very slow！

After successfully installing MacPorts, we need to add it to the system's environment variables. Otherwise, the port command can not be found in the terminal. Just run the following codes in your termal.

dirname $(which port) # Find the location of `port` command in your macOS. It may be `/opt/local/bin`
echo 'export PATH="/opt/local/bin:/opt/local/sbin:$PATH"' >> ~/.zshrc # The default terminal is `zsh` rather than `bash` in the new version of Mac; Run `echo $SHELL` to check it
echo 'export PATH="/opt/local/bin:/opt/local/sbin:$PATH"' >> ~/.bash_profile # The default terminal is `bash` in the old version of Mac; Run `echo $SHELL` to check it
source ~/.zshrc && source ~/.bash_profile
port version # check the version of `MacPorts`

Now we can use the MacPorts to install system libraries required by microgeo R packages on a macOS. Just run the following codes in your termal.

sudo port selfupdate
sudo port install gdal +hdf4 +hdf5 +netcdf

Please note that in macOS, due to different system versions, additional system libraries may be required (such as subversion, proj, geos and pkg-config, etc.). Pay attention to the prompts during the installation process. If you encounter dependency installation failures due to missing library files, please use the brew or port (recommend) command to install the required libraries before installing the dependencies of microgeo R packages.

The installation of microgeo R package on an Ubuntu OS may require several libraries including libgeos-dev, libgdal-dev, libudunits2-dev, uuid-dev, libharfbuzz-dev, libfribidi-dev, libv8-dev, cmake, libgit2-dev and gdal-bin. Just run the following codes in your terminal to install them.

sudo apt update
sudo apt install -y libgeos-dev libgdal-dev libudunits2-dev uuid-dev libharfbuzz-dev libfribidi-dev libv8-dev cmake libgit2-dev gdal-bin

For Linux (tested only on Ubuntu 18.04，20.04 and 22.04) and macOS operating systems, using the microgeo R packages also requires the GDAL version 3.4.1 or above. You can check the current GDAL version on your system by using the command gdalinfo --version. More importantly, the GDAL installed on your system needs to support both HDF4 and HDF5. You can check if the current version of GDAL meets this requirement by using the command gdalinfo --formats | grep HDF.

After our testing, the GDAL installed using brew on macOS does not by default support HDF4, resulting in errors when processing remote sensing images. This is why we recommend users to install the system dependencies required for the microgeo R packages using MacPorts.

Now, the microgeo R package can be installed. It is important to be aware that the installation of microgeo on the Ubuntu OS may take a considerable amount of time, given the need to build numerous dependencies. Your patience is appreciated while waiting for the installation process to conclude.

# Install the `remotes` R package as the microgeo R package is now available on both GitHub and Gitee
if (!suppressMessages(require('remotes', character.only = TRUE))) 
    install.packages('remotes', dependencies = TRUE, repos = "http://cran.rstudio.com/")

# Install the `mcirogeo` R package from GitHub
if (!suppressMessages(require('microgeo', character.only = TRUE)))
     remotes::install_github('ChaonanLi/microgeo') 

For users in mainland China, installing the microgeo R package from GitHub can be challenging due to network issues. To address this problem, there is a copy of the microgeo R package source code available on Gitee as well. Users in mainland China can directly install microgeo R package from Gitee. Just run the following codes in your R console.

# Install the `mcirogeo` R package from Gitee
if (!suppressMessages(require('microgeo', character.only = TRUE)))
    remotes::install_git("https://gitee.com/bioape/microgeo")

Since several dependent R packages are not avaliable on CRAN, there are a few additional steps to use the microgeo R package. Just run the following codes in your R console. Sometimes, when installing packages in RStudio, you may encounter situations where certain library files cannot be found. In such cases, you can simply switch to your terminal to perform the installation.

# Install additional R packages required by `microgeo`
source(system.file("scripts", "install-extra-pkgs.R", package = "microgeo")) 

Having successfully installed the microgeo R package, we can now delve into using it to create geographic maps. However, it is important to note that several functions may require significant computational resources. Personal computers might not meet the computational demands, so we recommend users to utilize these functions from the microgeo R package on a workstation or server.

If you use the microgeo R package for data processing and publication, please cite it as follows:

Chaonan Li, Chi Liu, Hankang Li, Haijun Liao, Lin Xu, Minjie Yao, Xiangzhen Li. The microgeo: an R package rapidly displays the biogeography of soil microbial community traits on maps. FEMS Microbiology Ecology, 2024, 97, fiae087 (https://doi.org/10.1093/femsec/fiae087).

To make it more convenient to use the microgeo R package, we not only provide detailed examples in the help document section of each function (it can be viewed by running ?function_name() in R console), but also provide detailed usage tutorials. If the microgeo R package and its dependencies have been successfully installed, you can copy and paste these demo codes into R console to run the example codes.

Besides, we also provide the JupyterLab Notebook version of tutorials. If the JupyterLab is avaliable on your PC or server, you can directly run the examples in these Notebooks.

It is recommended to use the JupyterLab or RStudio as your IDE (Integrated Development Environment). However, if you prefer the black screen with white text, using R's command interface directly is also fine.