### Execute SignatureSearch Workflow

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/runWF.Rd

Example demonstrating the setup of query signatures and the execution of the runWF function.

```R
#library(signatureSearch)
#library(ExperimentHub); library(rhdf5)
#eh <- ExperimentHub()
#cmap <- eh[["EH3223"]]; cmap_expr <- eh[["EH3224"]]
#lincs <- eh[["EH3226"]]; lincs_expr <- eh[["EH3227"]]
#lincs2 <- eh[["EH7297"]]
#h5ls(lincs2)
#db_path <- system.file("extdata", "sample_db.h5", package = "signatureSearch")
#library(SummarizedExperiment);
#library(HDF5Array)
#load(system.file("data", "cell_info2.rda", package = "signatureSearch"))
#sample_db <- SummarizedExperiment(HDF5Array(db_path, name="assay"))
#rownames(sample_db) <- HDF5Array(db_path, name="rownames")
#colnames(sample_db) <- HDF5Array(db_path, name="colnames")
#query_mat <- as.matrix(assay(sample_db[,"vorinostat__SKB__trt_cp"]))
#query <- as.numeric(query_mat); names(query) <- rownames(query_mat)
#upset <- head(names(query[order(-query)]), 150)
#head(upset)
#downset <- tail(names(query[order(-query)]), 150)
#head(downset)
#runWF(Signature = list(upset=upset, downset=downset),
#       cellInfo = cell_info2,
```

--------------------------------

### Setup Package Environment

Source: https://github.com/yduan004/signaturesearch/blob/devel/inst/extdata/GESS_report.Rmd

Initializes the required libraries for the analysis workflow.

```r
suppressPackageStartupMessages({
    library(signatureSearch); 
    library(readr); library(dplyr); library(DT)
})
```

--------------------------------

### Install signatureSearch from GitHub

Source: https://github.com/yduan004/signaturesearch/blob/devel/README.md

Install the latest development version directly from the GitHub repository.

```r
devtools::install_github("yduan004/signatureSearch", build_vignettes=TRUE)
```

--------------------------------

### Initialize qSig Object

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/qSig.Rd

Examples demonstrating the construction of qSig objects using different GESS methods and input types.

```R
db_path <- system.file("extdata", "sample_db.h5", 
                       package = "signatureSearch")
qsig_lincs <- qSig(query=list(
                     upset=c("230", "5357", "2015", "2542", "1759"), 
                     downset=c("22864", "9338", "54793", "10384", "27000")), 
                   gess_method="LINCS", refdb=db_path)
qmat <- matrix(runif(5), nrow=5)
rownames(qmat) <- c("230", "5357", "2015", "2542", "1759")
colnames(qmat) <- "treatment"
qsig_gcmap <- qSig(query=qmat, gess_method="gCMAP", refdb=db_path)
```

--------------------------------

### Install signatureSearch from Bioconductor

Source: https://github.com/yduan004/signaturesearch/blob/devel/README.md

Use BiocManager to install the package from the Bioconductor repository.

```r
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("signatureSearch")
```

--------------------------------

### Load signatureSearch

Source: https://github.com/yduan004/signaturesearch/blob/devel/README.md

Load the installed package into the current R session.

```r
library(signatureSearch)
```

--------------------------------

### Append matrix to HDF5 file example

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/append2H5.Rd

Demonstrates creating a temporary HDF5 file and appending a matrix to it.

```R
mat <- matrix(1:12, nrow=3)
rownames(mat) <- paste0("r", 1:3); colnames(mat) <- paste0("c", 1:4)
tmp_file <- tempfile(fileext=".h5")
create_empty_h5(tmp_file)
append2H5(mat, tmp_file)
rhdf5::h5ls(tmp_file)
```

--------------------------------

### runWF function configuration

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/runWF.Rd

Example configuration for the runWF function parameters.

```R
#     PertColName = "pert_iname",
#     drug = "vorinostat",
#     refdb = lincs2,
#     gess_method="LINCS",
#     fea_method="dup_hyperG",
#     N_gess_drugs=150,
#     env_dir="./GESSWFResults",
#     tau=FALSE,
#     Nup=150,
#     Ndown=150,
#     higher=1,
#     lower=-1,
#     method="spearman",
#     pvalueCutoff=1,
#     qvalueCutoff=1,
#     minGSSize=5,
#     maxGSSize=500,
#     runFEA=TRUE,
#     GenerateReport= TRUE)
}
```

--------------------------------

### Initialize DSEA GSEA example data

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/fea.Rd

Sets up a ranked list of drug scores for use in DSEA GSEA analysis.

```R
data(drugs10)

############ DSEA GSEA method ############
dl <- c(rev(seq(0.1, 0.5, by=0.05)), 0)
names(dl)=drugs10
```

--------------------------------

### Run gseGO2 Analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gseGO2.Rd

Example usage of the gseGO2 function with a target gene list.

```R
data(targetList)
# gsego <- gseGO2(geneList=targetList, ont="MF", OrgDb="org.Hs.eg.db",
#                 pvalueCutoff=1)
# head(gsego)
```

--------------------------------

### Perform Reactome Enrichment Analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/mabsReactome.Rd

Example usage of mabsReactome showing how to prepare a gene list and execute the analysis.

```R
# Gene Entrez id should be used for Reactome enrichment
#geneList[100:length(geneList)]=0
#rc <- mabsReactome(geneList=geneList, pvalueCutoff = 1)
```

--------------------------------

### Convert GCTX to HDF5 Example

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gctx2h5.Rd

Demonstrates how to convert a GCTX file to an HDF5 file by specifying column indices and new column names.

```R
gctx <- system.file("extdata", "test_sample_n2x12328.gctx", 
        package="signatureSearch")
h5file <- tempfile(fileext=".h5")
gctx2h5(gctx, cid=1:2, 
        new_cid=c('sirolimus__MCF7__trt_cp', 'vorinostat__SKB__trt_cp'), 
        h5file=h5file, overwrite=TRUE)
```

--------------------------------

### Retrieve Drug Targets

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/get_targets.Rd

Example usage of get_targets to fetch target information for a sample set of drugs.

```R
data(drugs10)
dt <- get_targets(drugs10)
```

--------------------------------

### Perform GO Term Enrichment

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/enrichGO2.Rd

Example demonstrating the input format for gene symbols and the function call structure for GO term enrichment analysis.

```R
# The method supports duplicated elements in 'gene', 
# which should be gene SYMBOL ids for GO term enrichment.
gene <- c(rep("HDAC1",4), rep("HDAC3",2), "SOX8", "KLK14")
# data(targetList)
# ego <- enrichGO2(gene = gene, OrgDb="org.Hs.eg.db", ont="MF",
#                  universe=names(targetList))
```

--------------------------------

### Perform MeanAbs GO Enrichment Analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/mabsGO.Rd

Example usage of mabsGO with a target gene list and specified ontology.

```R
data(targetList)
#mg <- mabsGO(geneList=targetList, ont="MF", OrgDb="org.Hs.eg.db",
#             pvalueCutoff=1)
#head(mg)
```

--------------------------------

### Perform Reactome GSEA analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gseReactome.Rd

Example usage of gseReactome using a sample gene list from the DOSE package.

```R
# Gene Entrez id should be used for Reactome enrichment
data(geneList, package="DOSE")
#geneList[100:length(geneList)]=0
#rc <- gseReactome(geneList=geneList, pvalueCutoff=1)
```

--------------------------------

### Compare FEA results with comp_fea_res

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/comp_fea_res.Rd

Example usage of comp_fea_res to visualize and compare enrichment statistics from two different methods.

```R
method1 <- data.frame("ID"=paste0("GO:", 1:5), 
                      "Description"=paste0("desc", 1:5),
                      "pvalue"=c(0.0001, 0.002, 0.004, 0.01, 0.05))
method2 <- data.frame("ID"=paste0("GO:", c(1,3,5,4,6)), 
                      "Description"=paste0("desc", c(1,3,5,4,6)),
                      "pvalue"=c(0.0003, 0.0007, 0.003, 0.006, 0.04))
table_list <- list("method1" = method1, "method2"=method2) 
comp_fea_res(table_list, rank_stat="pvalue", Nshow=20)
```

--------------------------------

### Add PCID to drug data frame example

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/add_pcid.Rd

Demonstrates loading the required perturbation information and the syntax for calling the add_pcid function.

```R
data("lincs_pert_info")
# gess_tb2 <- add_pcid(gess_tb)
```

--------------------------------

### Initialize Database Path

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gess.Rd

Locate the sample database file provided within the signatureSearch package.

```R
db_path <- system.file("extdata", "sample_db.h5", 
                       package = "signatureSearch")
```

--------------------------------

### Initialize Environment and Data Structures

Source: https://github.com/yduan004/signaturesearch/blob/devel/data-raw/target_chembl2uniprotID.ipynb

Imports necessary libraries and initializes the dictionary for mapping.

```python
import csv
```

```python
from chembl_webresource_client.new_client import new_client
```

```python
# This will be resulting structure mapping target ChEMBL IDs into 
# uniprot IDs
chem2uni = dict()
```

--------------------------------

### Initialize Analysis Environment

Source: https://github.com/yduan004/signaturesearch/blob/devel/inst/extdata/GESS_FEA_report.Rmd

Loads required packages and sets the working directory for the analysis.

```R
suppressPackageStartupMessages({ library(signatureSearch); library(readr); library(dplyr); library(DT); library(data.table) })
setwd("<env_name>")
```

--------------------------------

### Prepare Signature Database

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gess.Rd

Load a signature database from an HDF5 file into a SummarizedExperiment object.

```R
library(SummarizedExperiment); library(HDF5Array)
sample_db <- SummarizedExperiment(HDF5Array(db_path, name="assay"))
rownames(sample_db) <- HDF5Array(db_path, name="rownames")
colnames(sample_db) <- HDF5Array(db_path, name="colnames")
query_mat <- as.matrix(assay(sample_db[,"vorinostat__SKB__trt_cp"]))
```

--------------------------------

### Perform MOA Enrichment Analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/enrichMOA.Rd

Example usage of the enrichMOA function to analyze a subset of gene identifiers.

```R
data(geneList, package="DOSE")
emoa <- enrichMOA(gene = names(geneList)[seq(3)])
head(emoa)
```

--------------------------------

### Exporting a matrix to an HDF5 file

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/matrix2h5.Rd

Demonstrates creating a sample matrix and writing it to a temporary HDF5 file.

```R
mat <- matrix(rnorm(12), nrow=3, dimnames=list(
              paste0("r",1:3), paste0("c",1:4)))
h5file <- tempfile(fileext=".h5")
matrix2h5(matrix=mat, h5file=h5file, overwrite=TRUE)
```

--------------------------------

### Build a custom signature database

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/build_custom_db.Rd

Creates a sample data frame, saves it to an HDF5 file, and verifies the content using SummarizedExperiment.

```R
# Generate a data.frame 
df <- data.frame(sirolimus__MCF7__trt_cp=rnorm(1000),
                 vorinostat__SKB__trt_cp=rnorm(1000))
data(targetList)
rownames(df) = names(targetList)
h5file = tempfile(fileext=".h5")
build_custom_db(df, h5file)
library(SummarizedExperiment)
tmp <- SummarizedExperiment(HDF5Array::HDF5Array(h5file, name="assay"))
rownames(tmp) <- HDF5Array::HDF5Array(h5file, name="rownames")
colnames(tmp) <- HDF5Array::HDF5Array(h5file, name="colnames")
```

--------------------------------

### Initialize an empty HDF5 file

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/create_empty_h5.Rd

Creates a temporary HDF5 file with a specified compression level.

```R
tmp_file <- tempfile(fileext=".h5")
create_empty_h5(tmp_file, level=6)
```

--------------------------------

### Displaying signaturesearch result objects

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/show-methods.Rd

Demonstrates how to instantiate and display feaResult and gessResult objects using the show method.

```R
fr <- feaResult(result=dplyr::tibble(id=letters[seq_len(10)], 
                                     val=seq_len(10)),
                organism="human", ontology="MF", drugs=c("d1", "d2"), 
                targets=c("t1","t2"))
fr 
gr <- gessResult(result=dplyr::tibble(pert=letters[seq_len(10)], 
                               val=seq_len(10)), 
                 query=list(up=c("g1","g2"), down=c("g3","g4")),
                 gess_method="LINCS", refdb="path/to/lincs/db")
gr
```

--------------------------------

### read_gmt(file, start = 1, end = -1)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/read_gmt.Rd

Reads and parses a .gmt file into a list of gene sets.

```APIDOC
## read_gmt(file, start = 1, end = -1)

### Description
Reads in and parses information from the MSigDB's .gmt files. Pathway information is returned as a list of gene sets.

### Parameters
- **file** (string) - Required - The .gmt file to be read.
- **start** (integer) - Optional - Read the gmt file from this start line. Default is 1.
- **end** (integer) - Optional - Read the gmt file to this end line. Default is -1 (read to the end).

### Returns
- **list** - A list where each index represents a separate gene set.

### Example
```r
gmt_path <- system.file("extdata/test_gene_sets_n4.gmt", package="signatureSearch")
geneSets <- read_gmt(gmt_path)
```
```

--------------------------------

### Perform LINCS Connectivity Mapping

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gess.Rd

Example usage of the gess_lincs function to perform connectivity mapping with specified sorting and tau parameters.

```R
gess_method="LINCS", refdb=db_path)
lincs <- gess_lincs(qsig_lincs, sortby="NCS", tau=FALSE)
result(lincs)
```

--------------------------------

### Load and Inspect targetList

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/targetList.Rd

Load the dataset into the environment and display the first and last few entries.

```R
# Load object
data(targetList)
head(targetList)
tail(targetList)
```

--------------------------------

### show(object)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/show-methods.Rd

Displays the contents of a qSig, gessResult, or feaResult object.

```APIDOC
## show(object)

### Description
Displays a summary or representation of the provided object.

### Parameters
- **object** (qSig | gessResult | feaResult) - Required - The object to be displayed.

### Returns
- **message** (string) - A message or printed representation of the object.
```

--------------------------------

### Load and inspect cell_info2 dataset

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/cell_info2.Rd

Load the dataset into the environment and display the first few rows.

```R
# Load object
data(cell_info2)
head(cell_info2)
```

--------------------------------

### Load and inspect cell_info dataset

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/cell_info.Rd

Load the dataset into the environment and display the first few rows to verify the structure.

```R
# Load object
data(cell_info)
head(cell_info)
```

--------------------------------

### create_empty_h5(h5file, delete_existing = FALSE, level = 6)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/create_empty_h5.Rd

Creates an empty HDF5 file at the specified path with defined compression settings and internal data structure.

```APIDOC
## create_empty_h5

### Description
Creates an empty HDF5 file with root groups 'assay', 'colnames', and 'rownames' for storing numeric matrices and associated metadata.

### Signature
`create_empty_h5(h5file, delete_existing = FALSE, level = 6)`

### Parameters
- **h5file** (character) - Required - Path to the HDF5 file to be created.
- **delete_existing** (logical) - Optional - Whether to delete an existing HDF5 file with the same path. Defaults to FALSE.
- **level** (integer) - Optional - Compression level between 0 (no compression) and 9 (highest compression). Defaults to 6.

### Returns
- An empty HDF5 file structure.

### Example
```r
tmp_file <- tempfile(fileext=".h5")
create_empty_h5(tmp_file, level=6)
```
```

--------------------------------

### Access signatureSearch Vignettes

Source: https://github.com/yduan004/signaturesearch/blob/devel/README.md

Open the package documentation and vignettes within R.

```r
browseVignettes("signatureSearch")
```

--------------------------------

### runWF(Signature, cellInfo, ...)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/runWF.Rd

Executes the entire GESS/FEA workflow based on provided query parameters and database configurations.

```APIDOC
## runWF

### Description
Runs the entire GESS/FEA workflow when providing the query drug and cell type, as well as selecting the reference database and defining specific GESS and FEA methods.

### Signature
`runWF(Signature, cellInfo, PertColName = "pert_iname", drug, refdb, gess_method = "LINCS", fea_method = "dup_hyperG", N_gess_drugs = 150, env_dir = ".", tau = FALSE, Nup = 150, Ndown = 150, higher = 1, lower = -1, method = "spearman", pvalueCutoff = 1, qvalueCutoff = 1, minGSSize = 5, maxGSSize = 500, runFEA = TRUE, GenerateReport = TRUE)`

### Parameters
- **Signature** (object) - The signature to perform signatureSearching on.
- **cellInfo** (data.table) - A table containing cell type information; must contain a "cell_id" column.
- **PertColName** (character) - Column name from results used to summarize results.
- **drug** (character) - Query drug name.
- **refdb** (character) - Reference database: "lincs", "lincs_expr", "cmap", "cmap_expr", or path to HDF5 file.
- **gess_method** (character) - GESS method: "LINCS", "CORsub", "CORall", "Fisher", "CMAP", "gCMAP".
- **fea_method** (character) - FEA method: "dup_hyperG", "mGSEA", "mabs", "hyperG", "GSEA".
- **N_gess_drugs** (numeric) - Number of unique drugs in GESS result used as input for FEA.
- **env_dir** (character) - Directory for result environment.
- **tau** (logical) - Whether to compute Tau scores.
- **Nup** (integer) - Number of up-regulated genes for GESS query.
- **Ndown** (integer) - Number of down-regulated genes for GESS query.
- **higher** (numeric) - Upper threshold for gCMAP/Fisher methods.
- **lower** (numeric) - Lower threshold for gCMAP/Fisher methods.
- **method** (character) - Correlation coefficient: "spearman", "kendall", or "pearson".
- **pvalueCutoff** (double) - P-value cutoff for FEA.
- **qvalueCutoff** (double) - Q-value cutoff for FEA.
- **minGSSize** (integer) - Minimum gene set size.
- **maxGSSize** (integer) - Maximum gene set size.
- **runFEA** (logical) - Whether to perform FEA analysis.
- **GenerateReport** (logical) - Whether to generate a report.

### Returns
- **list** - A list object containing GESS/FEA result tables.
```

--------------------------------

### Load and Inspect LINCS Instance Information

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/lincs_expr_inst_info.Rd

Load the dataset into the R environment and display the first few rows to verify the structure.

```R
# Load object
data(lincs_expr_inst_info)
head(lincs_expr_inst_info)
```

--------------------------------

### Access and Modify Drugs in feaResult

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/drugs-methods.Rd

Demonstrates initializing an feaResult object and performing get/set operations on the drugs slot.

```R
fr <- feaResult(result=dplyr::tibble(id=letters[seq_len(10)], 
                                     val=seq_len(10)),
                organism="human", ontology="MF", drugs=c("d1", "d2"), 
                targets=c("t1","t2"))
drugs(fr)
drugs(fr) <- c("d3", "d4")
```

--------------------------------

### Load and inspect clue_moa_list

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/clue_moa_list.Rd

Load the dataset into the R environment and display the first few entries.

```R
# Load object
data(clue_moa_list)
head(clue_moa_list)
```

--------------------------------

### Retrieve the first part of result objects

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/head-methods.Rd

Demonstrates how to use the head method on gessResult and feaResult objects to view the first few rows of the internal result data frame.

```R
gr <- gessResult(result=dplyr::tibble(pert=letters[seq_len(10)], 
                                      val=seq_len(10)), 
                 query=list(up=c("g1","g2"), down=c("g3","g4")), 
                 gess_method="LINCS", refdb="path/to/lincs/db")
head(gr)
fr <- feaResult(result=dplyr::tibble(id=letters[seq_len(10)], 
                                    val=seq_len(10)),
                organism="human", ontology="MF", drugs=c("d1", "d2"), 
                targets=c("t1","t2"))
head(fr)
```

--------------------------------

### runWF(PertColName, drug, refdb, gess_method, fea_method, N_gess_drugs, env_dir, tau, Nup, Ndown, higher, lower, method, pvalueCutoff, qvalueCutoff, minGSSize, maxGSSize, runFEA, GenerateReport)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/runWF.Rd

Executes the signature search workflow with configurable parameters for GESS and FEA methods.

```APIDOC
## runWF

### Description
Executes a gene expression signature search workflow. This function processes drug signatures against a reference database and optionally performs functional enrichment analysis.

### Parameters
- **PertColName** (string) - Column name for perturbation identifiers.
- **drug** (string) - The name of the drug to search.
- **refdb** (object) - The reference database object.
- **gess_method** (string) - Method for GESS (e.g., "LINCS").
- **fea_method** (string) - Method for FEA (e.g., "dup_hyperG").
- **N_gess_drugs** (integer) - Number of drugs to return from GESS.
- **env_dir** (string) - Directory path for saving results.
- **tau** (boolean) - Whether to calculate tau scores.
- **Nup** (integer) - Number of upregulated genes.
- **Ndown** (integer) - Number of downregulated genes.
- **higher** (numeric) - Threshold for higher expression.
- **lower** (numeric) - Threshold for lower expression.
- **method** (string) - Statistical method (e.g., "spearman").
- **pvalueCutoff** (numeric) - P-value cutoff for enrichment.
- **qvalueCutoff** (numeric) - Q-value cutoff for enrichment.
- **minGSSize** (integer) - Minimum gene set size.
- **maxGSSize** (integer) - Maximum gene set size.
- **runFEA** (boolean) - Whether to run functional enrichment analysis.
- **GenerateReport** (boolean) - Whether to generate a summary report.
```

--------------------------------

### Construct a gessResult object

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gessResult.Rd

Initializes a gessResult object with sample data including a tibble result, a query list, and method/database identifiers.

```R
gr <- gessResult(result=dplyr::tibble(pert=letters[seq_len(10)], 
                                      val=seq_len(10)), 
                 query=list(up=c("g1","g2"), down=c("g3","g4")),
                 gess_method="LINCS", refdb="path/to/lincs/db")
```

--------------------------------

### Execute GESS/FEA Workflow

Source: https://github.com/yduan004/signaturesearch/blob/devel/inst/extdata/GESS_report.Rmd

Runs the complete GESS and FEA pipeline using specified drug, reference database, and method parameters.

```r
wf_list <- runWF(drug="<drug>", refdb="<refdb>", 
                 gess_method="<gess_method>", fea_method="<fea_method>", 
                 N_gess_drugs=<N_gess_drugs>)
```

--------------------------------

### Retrieve Gene Expression Signatures and DEGs

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/getSig.Rd

Demonstrates how to initialize a reference database path and extract signatures or DEG sets for a specific compound and cell line.

```R
refdb <- system.file("extdata", "sample_db.h5", package = "signatureSearch")
vor_sig <- getSig("vorinostat", "SKB", refdb=refdb)
vor_degsig <- getDEGSig(cmp="vorinostat", cell="SKB", Nup=150, Ndown=150,
                        refdb=refdb)
all_expr <- as.matrix(runif(1000, 0, 10), ncol=1)
rownames(all_expr) <- paste0('g', sprintf("%04d", 1:1000))
colnames(all_expr) <- "drug__cell__trt_cp"
de_prof <- as.matrix(rnorm(1000, 0, 3), ncol=1)
rownames(de_prof) <- paste0('g', sprintf("%04d", 1:1000))
colnames(de_prof) <- "drug__cell__trt_cp"
## getSPsubSig internally uses deprof2subexpr function
## sub_expr <- deprof2subexpr(all_expr, de_prof, Nup=150, Ndown=150)
```

--------------------------------

### runWF

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/runWF.Rd

Executes the signature search workflow and generates a working environment containing result tables and report templates.

```APIDOC
## runWF

### Description
Executes the GESS/FEA workflow. It creates a working environment in the current or specified directory, storing result tables in a 'results' folder and providing a template Rmd vignette and rendered HTML report.

### Signature
runWF(Signature, cellInfo, ...)

### Parameters
- **Signature** (list) - Required - A list containing 'upset' and 'downset' gene signatures.
- **cellInfo** (object) - Required - Cell information data used for the analysis.

### Usage Example
runWF(Signature = list(upset=upset, downset=downset), cellInfo = cell_info2)
```

--------------------------------

### Load and Inspect chembl_moa_list

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/chembl_moa_list.Rd

Load the dataset into the R environment and display the first few entries.

```R
# Load object
data(chembl_moa_list)
head(chembl_moa_list)
```

--------------------------------

### Retrieve dimensions of gessResult and feaResult objects

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/dim-methods.Rd

Demonstrates how to instantiate result objects and retrieve their dimensions using the dim method.

```R
gr <- gessResult(result=dplyr::tibble(pert=letters[seq_len(10)], 
                                      val=seq_len(10)), 
                 query=list(up=c("g1","g2"), down=c("g3","g4")),
                 gess_method="LINCS", refdb="path/to/lincs/db")
dim(gr)
fr <- feaResult(result=dplyr::tibble(id=letters[seq_len(10)], 
                                     val=seq_len(10)),
                organism="human", ontology="MF", drugs=c("d1", "d2"), 
                targets=c("t1","t2"))
dim(fr)
```

--------------------------------

### Convert GMT file to HDF5 format

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gmt2h5.Rd

Demonstrates how to convert a GMT file to an HDF5 file using the signatureSearch package.

```R
gmt <- system.file("extdata", "test_gene_sets_n4.gmt", 
        package="signatureSearch")
h5file <- tempfile(fileext=".h5")
gmt2h5(gmtfile=gmt, dest_h5=h5file, overwrite=TRUE)
```

--------------------------------

### Perform Reactome Enrichment Analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/enrichReactome.Rd

Demonstrates how to execute the enrichment analysis using a vector of Entrez gene IDs and a background universe.

```R
# This method supports duplicated elements in "gene"
gene <- c(rep("4312",4), rep("8318",2), "991", "10874")
data(geneList, package="DOSE")
rc <- enrichReactome(gene=gene, universe=names(geneList))
result(rc)
```

--------------------------------

### Read a GMT file

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/read_gmt.Rd

Demonstrates loading a .gmt file from a package and parsing it into a list of gene sets.

```R
gmt_path <- system.file("extdata/test_gene_sets_n4.gmt", package="signatureSearch")
geneSets <- read_gmt(gmt_path)
```

--------------------------------

### head(feaResult)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/head-methods.Rd

Returns the first part of the result table in an feaResult object.

```APIDOC
## head(feaResult)

### Description
Returns the first part of the result table in an feaResult object.

### Signature
head(x, n = 6L, ...)

### Parameters
- **x** (feaResult) - Required - The feaResult object.
- **n** (integer) - Optional - A single integer. If positive or zero, the number of rows to return. If negative, all but the n last rows are returned.
- **...** (dots) - Optional - Additional arguments passed to other methods.

### Returns
- **data.frame** - The first part of the result table.
```

--------------------------------

### Calculate Mean Expression Values and Save to HDF5

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/meanExpr2h5.Rd

Demonstrates how to compute mean expression values from a GCTX file and save the result to a temporary HDF5 file.

```R
gctx <- system.file("extdata", "test_sample_n2x12328.gctx", package="signatureSearch")
h5file <- tempfile(fileext=".h5")
inst <- data.frame(inst_id=c("ASG001_MCF7_24H:BRD-A79768653-001-01-3:10",
                             "CPC012_SKB_24H:BRD-K81418486:10"), 
    pert_cell_factor=c('sirolimus__MCF7__trt_cp', 'vorinostat__SKB__trt_cp'))
meanExpr2h5(gctx, inst, h5file, overwrite=TRUE)
```

--------------------------------

### Perform Hypergeometric test analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/fea.Rd

Executes a hypergeometric test for drug sets using GO annotations.

```R
hyperG_res <- dsea_hyperG(drugs=drugs10, type="GO", ont="MF")
result(hyperG_res)
hyperG_k_res <- dsea_hyperG(drugs=drugs10, type="GO", 
                            pvalueCutoff=1, qvalueCutoff=1, 
                            minGSSize=10, maxGSSize=500)
result(hyperG_k_res)
```

--------------------------------

### Perform GSEA analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/fea.Rd

Executes a GSEA analysis on a drug list using GO annotations.

```R
gsea_k_res <- dsea_GSEA(drugList=dl, type="GO", exponent=1, nPerm=100, 
                        pvalueCutoff=0.5, minGSSize=2)
result(gsea_k_res)
```

--------------------------------

### qSig(query, gess_method, refdb)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/qSig.Rd

Constructs a qSig object required for performing gene expression signature searches.

```APIDOC
## qSig(query, gess_method, refdb)

### Description
Constructs a `qSig` object to store the query signature, reference database, and the GESS method used for signature searching.

### Parameters
- **query** (list or matrix) - Required - The query data. Format depends on the `gess_method` (e.g., list of up/down gene sets for 'CMAP'/'LINCS', or a matrix of ranks/scores for 'gCMAP'/'Cor').
- **gess_method** (character) - Required - The method to use for the search. Options: 'CMAP', 'LINCS', 'gCMAP', 'Fisher', or 'Cor'.
- **refdb** (character) - Required - The reference database identifier (e.g., 'cmap', 'lincs') or a file path to a custom HDF5 database file.

### Returns
- **qSig object** - An object containing the query, method, and reference database configuration.

### Example
```R
db_path <- system.file("extdata", "sample_db.h5", package = "signatureSearch")
qsig_lincs <- qSig(query=list(
                     upset=c("230", "5357", "2015", "2542", "1759"), 
                     downset=c("22864", "9338", "54793", "10384", "27000")),
                   gess_method="LINCS", refdb=db_path)
```
```

--------------------------------

### Reduce target list display with tarReduce

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/tarReduce.Rd

Demonstrates how to limit the number of targets shown in a character vector to a specified maximum.

```R
vec <- c("t1; t2; t3; t4; t5; t6", "t7; t8")
vec2 <- tarReduce(vec, Ntar=5)
```

--------------------------------

### Perform TSEA MeanAbs analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/fea.Rd

Executes a TSEA MeanAbs analysis using GO annotations.

```R
res1 <- tsea_mabs(drugs=drugs10, type="GO", ont="MF", nPerm=1000, 
                  pvalueCutoff=0.05, minGSSize=5)
```

--------------------------------

### Extract results from feaResult and gessResult objects

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/result-methods.Rd

Demonstrates extracting result tibbles from both feaResult and gessResult instances.

```R
fr <- feaResult(result=dplyr::tibble(id=letters[seq_len(10)], 
                                     val=seq_len(10)),
                organism="human", ontology="MF", drugs=c("d1", "d2"), 
                targets=c("t1","t2"))
result(fr)
gr <- gessResult(result=dplyr::tibble(pert=letters[seq_len(10)], 
                               val=seq_len(10)), 
                 query=list(up=c("g1","g2"), down=c("g3","g4")),
                 gess_method="LINCS", refdb="path/to/lincs/db")
result(gr)
```

--------------------------------

### Load and display drugs10 dataset

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/drugs10.Rd

Load the drugs10 object into the workspace and print its contents.

```R
# Load drugs object
data(drugs10)
drugs10
```

--------------------------------

### Verify mapping dictionary size

Source: https://github.com/yduan004/signaturesearch/blob/devel/data-raw/target_chembl2uniprotID.ipynb

Check the number of entries in the chem2uni dictionary.

```python
len(chem2uni)
```

--------------------------------

### Inspect Mapping Dictionary

Source: https://github.com/yduan004/signaturesearch/blob/devel/data-raw/target_chembl2uniprotID.ipynb

Displays the current state of the mapping dictionary.

```python
chem2uni
```

--------------------------------

### Calculate Grouped Similarity Scores

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/sim_score_grp.Rd

Demonstrates how to initialize a gessResult object and apply the sim_score_grp function to summarize scores by cell type groups.

```R
gr <- gessResult(result=dplyr::tibble(pert=c("p1", "p1", "p2", "p3"),
                                      cell=c("MCF7", "SKB", "MCF7", "SKB"),
                                      type=rep("trt_cp", 4),
                                      NCS=c(1.2, 1, 0.9, 0.6)),
                 query=list(up="a", down="b"), 
                 gess_method="LINCS", refdb="path/to/refdb")
df <- sim_score_grp(result(gr), grp1="SKB", grp2="MCF7", "NCS")
```

--------------------------------

### gessResult(result, query, gess_method, refdb)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/gessResult.Rd

Constructs a new gessResult object from the provided result data, query signature, method name, and reference database path.

```APIDOC
## gessResult(result, query, gess_method, refdb)

### Description
Constructs a gessResult object to store the results of a GESS analysis.

### Parameters
- **result** (tibble) - Required - A tibble object containing the GESS results.
- **query** (list or matrix) - Required - The query signature used for the analysis.
- **gess_method** (character) - Required - The name of the GESS method applied.
- **refdb** (character) - Required - The path to the reference database.

### Returns
- **gessResult** (object) - A new instance of the gessResult class.

### Example
```r
gr <- gessResult(result=dplyr::tibble(pert=letters[seq_len(10)], val=seq_len(10)), query=list(up=c("g1","g2"), down=c("g3","g4")), gess_method="LINCS", refdb="path/to/lincs/db")
```
```

--------------------------------

### head(gessResult)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/head-methods.Rd

Returns the first part of the result table in a gessResult object.

```APIDOC
## head(gessResult)

### Description
Returns the first part of the result table in a gessResult object.

### Signature
head(x, n = 6L, ...)

### Parameters
- **x** (gessResult) - Required - The gessResult object.
- **n** (integer) - Optional - A single integer. If positive or zero, the number of rows to return. If negative, all but the n last rows are returned.
- **...** (dots) - Optional - Additional arguments passed to other methods.

### Returns
- **data.frame** - The first part of the result table.
```

--------------------------------

### Retrieve tail of gessResult and feaResult objects

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/tail-methods.Rd

Demonstrates how to extract the last rows from gessResult and feaResult objects using the tail method.

```R
gr <- gessResult(result=dplyr::tibble(pert=letters[seq_len(10)], 
                                      val=seq_len(10)), 
                 query=list(up=c("g1","g2"), down=c("g3","g4")),
                 gess_method="LINCS", refdb="path/to/lincs/db")
tail(gr)
fr <- feaResult(result=dplyr::tibble(id=letters[seq_len(10)], 
                                     val=seq_len(10)),
                organism="human", ontology="MF", drugs=c("d1", "d2"), 
                targets=c("t1","t2"))
tail(fr)
```

--------------------------------

### getDb(organism)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/getDb.Rd

Maps a supported organism name to its corresponding annotationDb package name.

```APIDOC
## getDb

### Description
Maps an organism name to the appropriate annotationDb package name.

### Signature
`getDb(organism)`

### Parameters
- **organism** (string) - Required - One of the supported organism names.

### Returns
- **annotationDb** (string) - The name of the annotationDb package.
```

--------------------------------

### Load and Inspect LINCS Signature Information

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/lincs_sig_info.Rd

Load the dataset into the R environment and display the first few rows for verification.

```R
# Load object
data(lincs_sig_info)
head(lincs_sig_info)
```

--------------------------------

### append2H5(x, h5file, name = "assay", printstatus = TRUE)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/append2H5.Rd

Appends a matrix object to an existing HDF5 file. If the file is not empty, the input matrix must have the same number of rows as the existing data, and it will be appended column-wise.

```APIDOC
## append2H5

### Description
Function to write matrix data to an existing HDF5 file. If the file contains already matrix data then both need to have the same number of rows. The append will be column-wise.

### Signature
`append2H5(x, h5file, name = "assay", printstatus = TRUE)`

### Parameters
- **x** (matrix) - Required - Matrix object to write to an HDF5 file.
- **h5file** (character) - Required - Path to existing HDF5 file that can be empty or contain matrix data.
- **name** (character) - Optional - The name of the dataset in the HDF5 file. Defaults to "assay".
- **printstatus** (logical) - Optional - Whether to print status. Defaults to TRUE.

### Returns
- **HDF5 file** (file) - The HDF5 file storing the exported matrix.
```

--------------------------------

### Constructing a feaResult object

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/feaResult.Rd

Creates a new feaResult object using a tibble for results and metadata for the enrichment context.

```R
fr <- feaResult(result=dplyr::tibble(id=letters[seq_len(10)], 
                                     val=seq_len(10)),
                organism="human", ontology="MF", drugs=c("d1", "d2"), 
                targets=c("t1","t2"))
```

--------------------------------

### Summarize perturbagen ranks using drug_cell_ranks

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/drug_cell_ranks.Rd

Demonstrates creating a gessResult object and calculating summary ranking statistics across cell types.

```R
gr <- gessResult(result=dplyr::tibble(pert=c("p1", "p1", "p2", "p3"),
                                      cell=c("MCF7", "SKB", "MCF7", "SKB"),
                                      type=rep("trt_cp", 4),
                                      NCS=c(1.2, 1, 0.9, 0.6)),
                 query=list(up="a", down="b"), 
                 gess_method="LINCS", refdb="path/to/refdb")
df <- drug_cell_ranks(gr)
```

--------------------------------

### build_custom_db(df, h5file)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/build_custom_db.Rd

Builds a custom reference signature database from a data.frame or matrix of gene expression signatures.

```APIDOC
## build_custom_db(df, h5file)

### Description
Builds a custom reference signature database for GESS methods. The function takes perturbation-based gene expression data and stores it in an HDF5 file.

### Parameters
- **df** (data.frame or matrix) - Required - Contains genome-wide or close to genome-wide GESs of perturbation experiments. Row names must be gene or transcript IDs. Column names must follow the structure: `(drug)__(cell)__(factor)`.
- **h5file** (character) - Required - The path to the destination HDF5 file.

### Returns
- **HDF5 file** - The generated HDF5 file stored at the specified path.

### Example
```r
df <- data.frame(sirolimus__MCF7__trt_cp=rnorm(1000), vorinostat__SKB__trt_cp=rnorm(1000))
rownames(df) = names(targetList)
h5file = tempfile(fileext=".h5")
build_custom_db(df, h5file)
```
```

--------------------------------

### Retrieve Treatment Information

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/getTreats.Rd

Extracts treatment details from a reference database file and returns them as a tibble.

```R
refdb <- system.file("extdata", "sample_db.h5", package="signatureSearch")
treat_info <- getTreats(refdb, sep=TRUE)
```

--------------------------------

### Perform TSEA mGSEA analysis

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/fea.Rd

Executes a TSEA mGSEA analysis using GO or Reactome annotations.

```R
res1 <- tsea_mGSEA(drugs=drugs10, type="GO", ont="MF", exponent=1, 
                   nPerm=1000, pvalueCutoff=1, minGSSize=5)
result(res1)
res3 <- tsea_mGSEA(drugs=drugs10, type="Reactome", pvalueCutoff=1)
result(res3)
```

--------------------------------

### mabsGO(geneList, ont, OrgDb, keyType, nPerm, minGSSize, maxGSSize, pvalueCutoff, pAdjustMethod)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/mabsGO.Rd

Performs MeanAbs enrichment analysis with GO terms based on a provided ranked gene list.

```APIDOC
## mabsGO

### Description
Performs MeanAbs enrichment analysis with GO terms.

### Signature
`mabsGO(geneList, ont = "BP", OrgDb, keyType = "SYMBOL", nPerm = 1000, minGSSize = 5, maxGSSize = 500, pvalueCutoff = 0.05, pAdjustMethod = "BH")`

### Parameters
- **geneList** (named numeric vector) - Required - Named numeric vector with gene SYMBOLs in the name slot, decreasingly ranked by scores in the data slot.
- **ont** (string) - Optional - One of "BP", "MF", "CC" or "ALL". Default is "BP".
- **OrgDb** (OrgDb) - Required - OrgDb object.
- **keyType** (string) - Optional - Keytype of gene. Default is "SYMBOL".
- **nPerm** (integer) - Optional - Permutation numbers. Default is 1000.
- **minGSSize** (integer) - Optional - Minimum size of each gene set in annotation system. Default is 5.
- **maxGSSize** (integer) - Optional - Maximum size of each gene set in annotation system. Default is 500.
- **pvalueCutoff** (numeric) - Optional - P-value cutoff. Default is 0.05.
- **pAdjustMethod** (string) - Optional - P-value adjustment method. Default is "BH".

### Returns
- **feaResult** (object) - Returns a feaResult object containing the enrichment analysis results.
```

--------------------------------

### getTreats(refdb, sep = TRUE)

Source: https://github.com/yduan004/signaturesearch/blob/devel/man/getTreats.Rd

Retrieves treatment information from a reference database. The output can be returned as a character vector or a tibble depending on the sep argument.

```APIDOC
## getTreats

### Description
Get treatment information including perturbation name, cell type and perturbation type from the reference database.

### Signature
`getTreats(refdb, sep = TRUE)`

### Parameters
- **refdb** (character) - Required - One of "lincs", "lincs_expr", "cmap", "cmap_expr", or a path to a custom HDF5 file generated by build_custom_db.
- **sep** (logical) - Optional - Whether to separate the treatments or column names of the reference database into 'pert', 'cell' and 'pert_type'. Defaults to TRUE.

### Returns
- **character vector** (if sep=FALSE)
- **Tibble object** (if sep=TRUE) with 'pert', 'cell', and 'pert_type' columns.

### Example
```r
refdb <- system.file("extdata", "sample_db.h5", package="signatureSearch")
treat_info <- getTreats(refdb, sep=TRUE)
```
```