---
title: "Quick Start Guide"
author: "Zaoqu Liu, Robert K. Suter, Nagi G. Ayad"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{Quick Start Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  message = FALSE,
  warning = FALSE,
  fig.width = 8,
  fig.height = 6,
  eval = FALSE
)
```

## Introduction

**scFOCAL** (Single-Cell Framework for Omics-Connectivity and Analysis via L1000) is a computational framework designed to bridge single-cell transcriptomics with pharmacological knowledge. By integrating drug-response transcriptional consensus signatures (TCS) from the LINCS L1000 database with single-cell RNA sequencing data, scFOCAL enables:

- **Identification of drug-sensitive and drug-resistant cell populations**
- **Discovery of combination therapy candidates**
- **Analysis of tumor heterogeneity in drug response**

This vignette provides a quick introduction to get you started with scFOCAL.

## Installation

### From R-Universe (Recommended)

```{r install-universe}
install.packages("scFOCAL", repos = "https://zaoqu-liu.r-universe.dev")
```

### From GitHub

```{r install-github}
# Install devtools if needed
if (!requireNamespace("devtools", quietly = TRUE))
    install.packages("devtools")

devtools::install_github("Zaoqu-Liu/scFOCAL")
```

### Dependencies

scFOCAL requires several Bioconductor packages:

```{r install-bioc}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install(c("MAST", "edgeR", "ComplexHeatmap", "EnhancedVolcano"))
```

**Note**: Seurat is required but listed as a suggested package:

```{r install-seurat}
# For Seurat v4 (recommended)
remotes::install_version("Seurat", version = "4.4.0")

# Or for Seurat v5
install.packages("Seurat")
```

## Launching scFOCAL

Once installed, launching the interactive Shiny application is straightforward:

```{r launch}
library(scFOCAL)

# Launch the GUI
runscFOCAL()
```

This will open the scFOCAL interface in your default web browser.

## Workflow Overview

```{r workflow-diagram, echo=FALSE, eval=TRUE, out.width="100%"}
knitr::include_graphics("images/scFOCAL_graphicalAbstract.png")
```

The scFOCAL workflow consists of five main steps:

### Step 1: Data Upload

Upload your preprocessed Seurat object (`.rds` format) containing:

- Normalized expression data
- Cell type annotations in metadata
- Dimensional reduction (UMAP/tSNE)

```{r data-upload, echo=FALSE, eval=TRUE, out.width="80%"}
knitr::include_graphics("images/01_dataUpload.png")
```

### Step 2: Pre-processing

Define your analysis groups:

- **Control populations**: Non-malignant cells (e.g., immune cells, stromal cells)
- **Test populations**: Tumor cells of interest

```{r preprocessing, echo=FALSE, eval=TRUE, out.width="80%"}
knitr::include_graphics("images/02_preProcessing.png")
```

### Step 3: Disease Signature Generation

Compute cell-type-specific differential expression signatures using the MAST statistical framework:

```{r disease-sig, echo=FALSE, eval=TRUE, out.width="80%"}
knitr::include_graphics("images/03_DiseaseSignatures.png")
```

### Step 4: Drug-Cell Connectivity Analysis

Calculate Spearman correlations between single-cell expression profiles and L1000 drug signatures:

```{r connectivity, echo=FALSE, eval=TRUE, out.width="80%"}
knitr::include_graphics("images/04_inSilicoPerturbation.png")
```

### Step 5: Results Analysis

Explore differential connectivity and identify combination therapy candidates:

```{r results, echo=FALSE, eval=TRUE, out.width="80%"}
knitr::include_graphics("images/05_resultsTab.png")
```

## Built-in Data

scFOCAL includes pre-processed LINCS L1000 data:

```{r data-overview}
library(scFOCAL)

# View available compounds
head(L1000_compounds)

# View L1000 gene list
head(L1000_genes)

# LINCS Response Signatures (1679 compounds × 978 genes)
dim(LINCS.ResponseSigs)
```

## Example Dataset

Download our example dataset to test scFOCAL:

- [Subsampled Seurat Object](https://drive.google.com/u/0/uc?id=1Q-OqX27l9SRFX4iaJ1eFlXacUHk1vSPe&export=download) (500 cells)
- [Pre-calculated Connectivity Matrix](https://drive.google.com/u/0/uc?id=1JFJjxCUKsPvO_LMr7AB1MWgsT9uewL9c&export=download)

## Next Steps

For more detailed information, see:

- [Algorithm Principles](algorithm-principles.html) - Mathematical foundations
- [Statistical Framework](statistical-framework.html) - Statistical methods
- [Case Study: GBM Analysis](case-study-gbm.html) - Complete analysis example
- [Visualization Gallery](visualization-gallery.html) - Output visualizations

## Citation

If you use scFOCAL in your research, please cite:

> Suter RK, Jermakowicz AM, Veeramachaneni R, *et al*. Drug and single-cell gene expression integration identifies sensitive and resistant glioblastoma cell populations. **Nature Communications** 17, 99 (2026). https://doi.org/10.1038/s41467-025-67783-5

## Session Info

```{r session-info, eval=TRUE}
sessionInfo()
```