---
title: "Installation Guide"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Installation Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

## Overview

Welcome to **leo.sc**! This guide outlines the recommended steps to install the package and its dependencies. Since `leo.sc` relies on various CRAN, Bioconductor, and GitHub-hosted packages, a structured installation approach ensures a smooth setup.

## Prerequisites

Ensure you have a recent version of **R (>= 4.1.0)** installed. We highly recommend using [RStudio](https://posit.co/download/rstudio-desktop/) or [radian](https://github.com/randy3k/radian) running inside [VS Code](https://code.visualstudio.com/) as your integrated development environment (IDE).

You will need the `pak` package for a fast and reliable installation experience:

```{r install-pak, eval=FALSE}
if (!requireNamespace("pak", quietly = TRUE)) {
  install.packages("pak", dependencies = TRUE)
}
```

The most straightforward method to install `leo.sc` is directly from GitHub using `pak`. It will automatically resolve and install all CRAN, Bioconductor, and GitHub dependencies in parallel.

```{r install-leosc, eval=FALSE}
pak::pkg_install("laleoarrow/leo.sc")
```

## Troubleshooting Dependencies

Bioinformatics packages often have complex dependency trees. If the standard installation fails due to missing packages, follow these targeted troubleshooting steps:

### 1. Bioconductor Dependencies

Several core functions in `leo.sc` depend on Bioconductor infrastructure. You can install any missing ones like this:

```{r install-bioc, eval=FALSE}
bioc_deps <- c("clusterProfiler", "org.Hs.eg.db", "enrichplot")
missing_bioc <- bioc_deps[!vapply(bioc_deps, requireNamespace, quietly = TRUE, FUN.VALUE = logical(1))]

if (length(missing_bioc) > 0) {
  pak::pkg_install(missing_bioc)
}
```

### 2. GitHub-Hosted Dependencies

`leo.sc` relies on other custom packages, notably `leo.basic` and `DoubletFinder`. If needed, install them directly:

```{r install-remotes, eval=FALSE}
github_deps <- c("chris-mcginnis-ucsf/DoubletFinder", "laleoarrow/leo.sc")
# pak handles GitHub repositories automatically
pak::pkg_install(github_deps)
```

## Verification

Once the installation completes, verify that the package loads successfully into your R session:

```{r verify_install}
library(leo.sc)
cli::cli_alert_success("leo.sc loaded successfully!")
```

If you encounter persistent issues during installation, please open an issue on the [leo.sc GitHub repository](https://github.com/laleoarrow/leo.sc/issues).