---
title: "2. Start a Typical Workflow"
author: "Qingzhou Zhang"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{2. Start a Typical Workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Introduction

Protein complexes are the functional machinery of the cell. High-throughput experimental methods can identify hundreds of putative protein complexes in a single experiment. The `ComplexMap` package provides a comprehensive, end-to-end workflow to process, analyze, annotate, and visualize such datasets.

The version 2.0 workflow is built around a **Physical-First** philosophy: we prioritize the physical composition (protein identity) of complexes to define the map's layout, while using functional enrichment to provide a "color landscape" that highlights biological diversity without collapsing distinct sub-complexes into generic blobs.

# Step 1: Loading Data

The `ComplexMap` package includes the `demoComplexes` dataset (622 putative human complexes). We also provide a helper to locate an example BioCarta gene set (GMT) file.

```{r load-data}
# Load example complexes
data("demoComplexes", package = "ComplexMap")

# Access the included example GMT file (BioCarta)
gmtPath <- getExampleGmt()
biocartaGmt <- getGmtFromFile(gmtPath, verbose = FALSE)

# Preview the input
message(sprintf("Loaded %d complexes and %d gene sets.", 
                length(demoComplexes), length(biocartaGmt)))
```

# Step 2: Running the Main Workflow

The core of the package is the `createComplexMap()` function. This high-level wrapper handles:

1.  **Refinement**: (Optional) Merges highly redundant complexes to clean the input.

2.  **Functional Enrichment**: Calculates p-values and **Fold Enrichment** for every complex.

3.  **Network Construction**: Links complexes based on shared proteins (`alpha=0.75` gives 75% weight to physical overlap).

4.  **Semantic Clustering**: Groups functional terms to assign a consistent color palette that maximizes diversity.

5.  **Topology Calculation**: Runs a Fruchterman-Reingold layout and calculates centrality metrics (betweenness and degree).

```{r create-map, message=TRUE}
# Run the entire workflow
# We use a subset of 200 complexes for this vignette demonstration
cmap <- createComplexMap(
  complexList = demoComplexes[1:200],
  gmt = biocartaGmt,
  ifRefineCpx = TRUE,    # Clean up redundancy
  mergeThreshold = 0.90, # Only merge nearly identical complexes
  alpha = 0.75,          # Layout priority: 75% Physical, 25% Functional
  verbose = TRUE
)
```

### The Systems Biology Dashboard

One of the key features of the `ComplexMap` object is its `print` method, which provides immediate feedback on the "health" of your landscape.

```{r print-object}
# Inspect the resulting object
print(cmap)
```

**What to look for:**

- **Diversity**: A high count of distinct functional domains indicates a specific, high-resolution map.

- **Coverage**: Shows what percentage of your experimental data could be biologically annotated.

# Step 3: Exploring and Querying

You can interact with the map data using standard accessors or the targeted `queryMap` tool.

### 3.1 Targeted Querying
Let's find complexes containing **"SMAD4"** (a central mediator of TGF-beta signaling).

```{r query-protein}
# Search for protein members
smad_complexes <- queryMap(cmap, query = "SMAD4", type = "protein")

if (nrow(smad_complexes) > 0) {
  smad_complexes %>%
    select(complexId, primaryFunctionalDomain, proteinCount) %>%
    knitr::kable()
} else {
  message("SMAD4 not found in this subset.")
}
```

### 3.2 Accessing Tables
The node and edge tables are available as tibbles for custom downstream analysis (e.g., in `ggplot2`).

```{r tables}
nodes <- getNodeTable(cmap)
edges <- getEdgeTable(cmap)

# Example: Top 3 most central complexes by betweenness
nodes %>%
  select(complexId, primaryFunctionalDomain, betweenness) %>%
  arrange(desc(betweenness)) %>%
  head(3)
```

# Step 4: Interactive Visualization

In `ComplexMap >= 2.0.0`, static R plots have been replaced by a powerful interactive engine based on **Cytoscape.js**. 

To launch the explorer, simply call `explore()` on your object. This will open a Shiny application where you can:

1.  **Zoom and Pan** through the physical landscape.

2.  **Filter** by functional domain or protein count.

3.  **Inspect** specific nodes to see their full protein list and enrichment scores.

```r
# Launch the interactive viewer
explore(cmap)
```

# Step 5: Exporting to External Tools

If you prefer to perform advanced network analysis in **Cytoscape Desktop** or **Gephi**, use `exportNetwork`. It sanitizes complex R data types into strings and writes standard TSV or GraphML files.

```{r export, eval=FALSE}
# Export for Cytoscape Desktop
exportNetwork(cmap, filePrefix = "my_complex_landscape", format = "cytoscape")
```

# Conclusion

The `ComplexMap` workflow transforms a raw list of protein identifications into a structured, functional landscape. By prioritizing physical composition and enforcing functional diversity, it ensures that your map reflects the true biological complexity of the proteome.