Introduction to immunarch
Author: ImmunoMind

# Introduction to `immunarch`

#### ImmunoMind

#### support@immunomind.io

# Introduction

`immunarch` is an R package designed to analyse T-cell receptor (TCR) and B-cell receptor (BCR) repertoires, aimed at medical scientists and bioinformaticians. The mission of `immunarch` is to make immune sequencing data analysis as effortless as possible and help you focus on research instead of coding. Follow us on Twitter for news and updates.

## Installation

### Latest release on CRAN

In order to install `immunarch` execute the following command:

    install.packages("immunarch")

That’s it, you can start using `immunarch` now! See the Quick Start section below to dive into immune repertoire data analysis. If you run in any trouble with installation, take a look at the Installation Troubleshooting section.

Note: there are quite a lot of dependencies to install with the package because it installs all the widely-used packages for data analysis and visualisation. You got both the AIRR data analysis framework and the full Data Science package ecosystem with only one command, making `immunarch` the entry-point for single-cell & immune repertoire Data Science.

### Latest release on GitHub

If the above command doesn’t work for any reason, try installing `immunarch` directly from its repository:

    install.packages("devtools") # skip this if you already installed devtools
    devtools::install_github("immunomind/immunarch")

### Latest pre-release on GitHub

Since releasing on CRAN is limited to one release per one-two months, you can install the latest pre-release version with bleeding edge features and optimisations directly from the code repository. In order to install the latest pre-release version, you need to execute only two commands:

    install.packages("devtools") # skip this if you already installed devtools
    devtools::install_github("immunomind/immunarch", ref="dev")

You can find the list of releases of `immunarch` here: http://github.com/immunomind/immunarch/releases

## Quick start

The gist of the typical TCR or BCR data analysis workflow can be reduced to the next few lines of code.

### Use `immunarch` data

1) Load the package and the data

    library(immunarch)  # Load the package into R
    data(immdata)  # Load the test dataset

2) Calculate and visualise basic statistics

    repExplore(immdata$data, "lens") %>% vis()  # Visualise the length distribution of CDR3
    repClonality(immdata$data, "homeo") %>% vis()  # Visualise the relative abundance of clonotypes

3) Explore and compare T-cell and B-cell repertoires

    repOverlap(immdata$data) %>% vis()  # Build the heatmap of public clonotypes shared between repertoires
    geneUsage(immdata$data[[1]]) %>% vis()  # Visualise the V-gene distribution for the first repertoire
    repDiversity(immdata$data) %>% vis(.by = "Status", .meta = immdata$meta)  # Visualise the Chao1 diversity of repertoires, grouped by the patient status

### Use your own data

    library(immunarch)  # Load the package into R
    immdata <- repLoad("path/to/your/data")  # Replace it with the path to your data. Immunarch automatically detects the file format.

### Advanced methods

For advanced methods such as clonotype annotation, clonotype tracking, kmer analysis and public repertoire analysis see “Tutorials”.

## Installation troubleshooting

If you can not install `devtools`, check sections 1 and 2 below.

If you run in any other trouble, try the following steps:

1. Check your R version. Run `version` command in the console to get your R versions. If the R version is below 3.5.0 (for example, `R version 3.1.0`), try updating your R version to the latest one. Check this this link if you are on Ubuntu. Note: if you try to install a package after the update and it still fails with the following message:

       ERROR: dependencies ‘httr’, ‘usethis’ are not available for package ‘devtools’
       * removing ‘/home/ga/R/x86_64-pc-linux-gnu-library/3.5/devtools’
       Warning in install.packages :
         installation of package ‘devtools’ had non-zero exit status

   it means that you need to re-install packages that were built under the previous R version. In the above example it would be packages `httr` and `usethis`. In order to re-install a package you need to execute the command `install.packages("package_name")`, where `package_name` is the name of the package to update. To find packages that need to be re-installed after updating R, you need to look for installation messages like this in the installation process:

       ERROR: package ‘usethis’ was installed by an R version with different internals; it needs to be reinstalled for use with this R version

2. Check if your packages are outdated and update them. In RStudio you can run the “Update” button on top of the package list in the “Package” window. In R console you can run the `old.packages()` command to view a list of outdated packages. The following messages indicate that an update is required:

       Error: package ‘dtplyr’ 0.0.3 was found, but >= 1.0.0 is required by ‘immunarch’
       Execution halted
       ERROR: lazy loading failed for package ‘immunarch’

       byte-compile and prepare package for lazy loading
       Error in loadNamespace(j <- i[[1L]], c(lib.loc, .libPaths()), versionCheck = vI[[j]]) :
         namespace 'ggalluvial' 0.9.1 is being loaded, but >= 0.10.0 is required
       Calls: <Anonymous> ... namespaceImportFrom -> asNamespace -> loadNamespace
       Execution halted

3. For Mac users. Make sure to install XCode from App Store first and command line developers tools second by executing the following command in Terminal: `xcode-select –install`

4. For Mac users. If you have issues like old packages can’t be updated, or error messages such as `ld: warning: directory not found for option` or `ld: library not found for -lgfortran`, this link will help you to fix the issue.

5. For Mac Mojave (1.14) users. If you run into the following error:

       /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/v1/math.h:301:15: fatal error: 'math.h' file not found
       #include_next <math.h>
                  ^~~~~~~~

   Open Terminal, execute the following command and try again to install `immunarch`:

       sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /

6. For Linux users. If you have issues with the `igraph` library or have Fortran errors such as:

       ** testing if installed package can be loaded from temporary location
       Error: package or namespace load failed for 'igraph' in dyn.load(file, DLLpath = DLLpath, ...):
        unable to load shared object '/usr/local/lib/R/site-library/00LOCK-igraph/00new/igraph/libs/igraph.so':
         libgfortran.so.4: cannot open shared object file: No such file or directory

   See this link for help.

7. For Linux users. If you have issues with the `rgl` package:

       configure: error: missing required header GL/gl.h
       ERROR: configuration failed for package ‘rgl’

   Install “mesa-common-dev” via OS terminal by executing the following command:

       apt-get install mesa-common-dev

   Check this link for more information and other possible workarounds.

8. If you have error messages with `rlang` in them such as:

       Error: .onLoad failed in loadNamespace() for 'vctrs', details:
       call: env_bind_impl(.env, list3(...), "env_bind()", bind = TRUE)
       error: object 'rlang_env_bind_list' not found

   Remove the `rlang` package and install it again. This error is often happens after updating R to a newer version, while `rlang` not being properly updated.

9. If you have error messages like the following (note the `(converted from warning)` part):

       ** byte-compile and prepare package for lazy loading
       Error: (converted from warning) package 'ggplot2' was built under R version 3.6.1
       Execution halted
       ERROR: lazy loading failed for package 'immunarch'

   Execute the following command in R and try again to install the package:

       Sys.setenv(R_REMOTES_NO_ERRORS_FROM_WARNINGS="true")

10. For Windows users. If you have issues with the package installation, or if you want to change the folder for R packages, feel free to check this forum post.

11. For Windows users. Make sure to install Rtools. Before installation close RStudio, install Rtools and re-open it afterwards. To check if Rtools installed correctly, run the `devtools::find_rtools()` command (after installing the devtools package). If you have an error, check this link for help.

12. If you can not install dependencies for `immunarch`, please try manual installation of all dependencies by executing the following command in R console:

        install.packages(c("rematch", "prettyunits", "forcats", "cellranger", "progress", "zip", "backports", "ellipsis", "zeallot", "SparseM", "MatrixModels", "sp", "haven", "curl", "readxl", "openxlsx", "minqa", "nloptr", "RcppEigen", "utf8", "vctrs", "carData", "pbkrtest", "quantreg", "maptools", "rio", "lme4", "labeling", "munsell", "cli", "fansi", "pillar", "viridis", "car", "ellipse", "flashClust", "leaps", "scatterplot3d", "modeltools", "DEoptimR", "digest", "gtable", "lazyeval", "rlang", "scales", "tibble", "viridisLite", "withr", "assertthat", "glue", "magrittr", "pkgconfig", "R6", "tidyselect", "BH", "plogr", "purrr", "ggsci", "cowplot", "ggsignif", "polynom", "fastcluster", "plyr", "abind", "dendextend", "FactoMineR", "mclust", "flexmix", "prabclus", "diptest", "robustbase", "kernlab", "GlobalOptions", "shape", "colorspace", "stringi", "hms", "clipr", "crayon", "httpuv", "mime", "jsonlite", "xtable", "htmltools", "sourcetools", "later", "promises", "gridBase", "RColorBrewer", "yaml", "ggplot2", "dplyr", "dtplyr", "dbplyr", "data.table", "gridExtra", "ggpubr", "pheatma3", "ggrepel", "reshape2", "DBI", "factoextra", "fpc", "circlize", "tidyr", "Rtsne", "readr", "readxl", "shiny", "shinythemes", "treemap", "igraph", "airr", "ggseqlogo", "UpSetR", "stringr", "ggalluvial", "Rcpp"))

13. If you encounter the following error while running the `devtools::install_local` function:

        In normalizePath(path.expand(path), winslash, mustWork) :
          path[1]="path/to/your/folder/with/immunarch.tar.gz":

        In file.copy(x$path, bundle, recursive = TRUE) :
          problem copying No such file or directory

    Check your path to the downloaded package archive file. It should not be “path/to/your/folder/with/immunarch.tar.gz”, but a path on your PC to the downloaded file, e.g., “C:/Users/UserName/Downloads/immunarch.tar.gz” or “/Users/UserName/Downloads/immunarch.tar.gz”.

14. If troubles still persist, let us know via GitHub (preferably) or support@immunomind.io (in case of private data).