### Install and Launch ProTIGY App

Source: https://github.com/broadinstitute/protigy-v2/blob/main/README.md

Install the ProTIGY package and launch the Shiny application. Ensure devtools is installed first. After initial installation, only `library()` calls are needed.

```R
# Change to the repo folder
setwd("protigy-v2")

# Install and load devtools. NOTE: After installing once, you don't need to install every time. Just use library()
install.packages('devtools')
library(devtools)

# Install the package. NOTE: After installing once, you don't need to install every time. Just use library()
devtools::install('.')

# Load the package and start the app
library(Protigy)
Protigy::launchApp()
```

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

### Launch ProTIGY Shiny Application

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Use `launchApp()` to start the ProTIGY Shiny application. The app window is initialized at 3000 x 900 px and the maximum upload size is set to 500 MB. Optionally, set the Shiny port and host before launching.

```r
library(Protigy)

# Launch the app in the default browser
Protigy::launchApp()

# Optionally set port/host before launching (standard Shiny options)
options(shiny.port = 8080, shiny.host = "0.0.0.0")
Protigy::launchApp()
```

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

### launchApp()

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Starts the ProTIGY Shiny application, providing an interactive interface for multi-omics data analysis. The application window is initialized at 3000 × 900 px and the maximum upload size is set to 500 MB.

```APIDOC
## launchApp()

### Description
Starts the ProTIGY Shiny application, providing an interactive interface for multi-omics data analysis. The application window is initialized at 3000 × 900 px and the maximum upload size is set to 500 MB.

### Method
`library(Protigy)`
`Protigy::launchApp()`

### Parameters
None

### Request Example
```r
library(Protigy)

# Launch the app in the default browser
Protigy::launchApp()

# Optionally set port/host before launching (standard Shiny options)
options(shiny.port = 8080, shiny.host = "0.0.0.0")
Protigy::launchApp()
```

### Response
Launches the Shiny application in the user's default web browser.
```

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

### Accessing GCTs and Parameters

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/module_requirements.md

Retrieve processed GCT objects or setup parameters for each ome. Use the $GCTs accessor for a list of individual omes or $GCTs_merged for a combined GCT. The $parameters accessor provides ome-specific configuration details.

```R
> GCTs_and_params()$GCTs
$Prot 
Formal class 'GCT' [package "cmapR"] with 7 slots ...

$Prot
Formal class 'GCT' [package "cmapR"] with 7 slots ...

$RNA
Formal class 'GCT' [package "cmapR"] with 7 slots ...

```

```R
> GCTs_and_params()$parameters # named list of parameters
$Prot: List of 9
$Phos: List of 9
$RNA: List of 9

> GCTs_and_params()$parameters$Prot # parameters for a single ome
$gct_file_path
[1] "/var/folders/52/lnhkwk791mb8x2xqdnkv837w0000gq/T//RtmpOUAtjA/a1b10dd3206e7ca97d4c209c/1.gct"

$gct_file_name
[1] "proteome-aggregate.gct"

$log_transformation
[1] "None"

$data_normalization
[1] "None"

$data_filter
[1] "None"

$max_missing
[1] 100

$intensity_data
[1] "No"

$group_normalization
[1] FALSE

$annotation_column
[1] "PAM50"

```

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

### Get plot export dimensions with get_plot_export_dimensions

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Retrieves plot export dimensions from a configuration file, returning a list compatible with ggsave or pdf. Standard plots default to 8x6 inches, while specific plots like the multi-omics heatmap use 12x8 inches. Use this to ensure consistent plot sizing for exports.

```r
# Standard plot dimensions
dims <- get_plot_export_dimensions("default")
dims
#> $width   [1] 8
#> $height  [1] 6
#> $units   [1] "in"
```

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

### Get Plot Export Dimensions

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Retrieves dimensions for plot exports. Use directly with ggsave.

```r
hm_dims <- get_plot_export_dimensions("multiome_heatmap")
hm_dims$width   #> 12
```

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

### Clone ProTIGY Repository

Source: https://github.com/broadinstitute/protigy-v2/blob/main/README.md

Clone the ProTIGY repository from GitHub using Git. This is the first step to setting up the project locally.

```bash
# Clone the repository
git clone https://github.com/broadinstitute/protigy-v2.git
```

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

### Run all tests with devtools

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/shinytest2_testing_guide.md

Load package code and run all tests using devtools::test(). This is typically done before merging a PR or for full test suite verification.

```r
devtools::load_all(".")
devtools::test()
```

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

### Load Test Datasets in R

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/README.md

Run these lines to load the test datasets included in the package for testing convenience.

```r
data(brca_retrospective_v5.0_rnaseq_gct)
data(brca_retrospective_v5.0_phosphoproteome_gct)
data(brca_retrospective_v5.0_proteome_gct)
```

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

### Run specific test file

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/shinytest2_testing_guide.md

Execute a single test file directly using testthat::test_file(). This is useful for quickly testing changes in a specific workflow.

```r
testthat::test_file("tests/testthat/test-smoke-shinytest2.R")
```

```r
testthat::test_file("tests/testthat/test-file-upload-shinytest2.R")
```

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

### Accessing Global Colors and Default Ome

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/module_requirements.md

Inspect the color palettes and the default ome setting managed by the global application state. The $colors accessor provides named lists of color schemes per ome, while $default_ome indicates the initial ome tab.

```R
> names(globals$colors)
[1] "multi_ome" "Phos"      "Prot"      "RNA" 

> names(globals$colors$Prot)
 [1] "Sample.ID"      "Experiment"      "Channel"      ... 

> globals$colors$Prot$PAM50
$is_discrete
[1] TRUE

$vals
[1] "Basal" "Her2"  "LumA"  "LumB" 

$colors
[1] "#117733" "#88CCEE" "#CC6677" "#999933"

```

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

### Run targeted shinytest2 tests with devtools

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/shinytest2_testing_guide.md

Load package code and run specific shinytest2 tests using devtools::test() with a filter. This provides faster feedback during development.

```r
devtools::load_all(".")
devtools::test(filter = "smoke-shinytest2")
devtools::test(filter = "file-upload-shinytest2")
```

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

### Data Normalization Methods

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Applies different normalization techniques to a data matrix. Ensure data is positive for VSN normalization.

```R
mat_median <- normalize.data(mat, method = "Median")
```

```R
mat_quant <- normalize.data(mat, method = "Quantile")
```

```R
grp <- setNames(rep(c("BatchA", "BatchB"), each = 5), colnames(mat))
mat_grp <- normalize.data(mat, method = "Median", grp.vec = grp)
```

```R
mat_vsn <- normalize.data(mat + 10, method = "VSN")  # needs positive values
```

```R
colMeans(mat_median, na.rm = TRUE)  # should be ~0 after median normalization
```

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

### Load and Inspect BRCA Retrospective Datasets

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Loads three bundled GCT objects for BRCA retrospective study data. Inspect dimensions, column, and row metadata.

```r
# Load all three test datasets
data(brca_retrospective_v5.0_proteome_gct)
data(brca_retrospective_v5.0_phosphoproteome_gct)
data(brca_retrospective_v5.0_rnaseq_gct)

# Inspect dimensions
dim(brca_retrospective_v5.0_proteome_gct@mat)
#> features  samples  (e.g. ~12000  77)

# Column (sample) metadata
head(brca_retrospective_v5.0_proteome_gct@cdesc)

# Row (feature) metadata — includes geneSymbol column
head(brca_retrospective_v5.0_proteome_gct@rdesc[, c("id", "geneSymbol")])

# Pass directly to processGCTs for a fully scripted analysis
GCTs <-
  list(
    prot = brca_retrospective_v5.0_proteome_gct,
    phos = brca_retrospective_v5.0_phosphoproteome_gct,
    rna  = brca_retrospective_v5.0_rnaseq_gct
  )
```

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

### Exporting Plots from a Module Server Function

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/module_requirements.md

This R code demonstrates how to define a reactive plot, create an export function for it, and structure module exports. Ensure the reactive object is called correctly when exporting.

```r
ome <- "Prot" # making plots for the proteome

# making my reactive plot
example_plot_reactive <- reactive({
  ggplot() + ggtitle(paste("Example for:", ome))
})

# Export function
example_plot_export_function <- function(dir_name) {
  ggsave(
    filename = paste0("example_plot_", ome, ".pdf"), 
    plot = example_plot_reactive(), # call the reactive object
    device = 'pdf',
    path = dir_name # save in the desired output directory
  )
}

# create the nested list of exports
module_exports <- list()
module_exports[[ome]] <- list(
  example_plot <- example_plot_export_function
  # add other functions for plots/exports here
)

return(module_exports)
```

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

### Enable shinytest2 tests

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/shinytest2_testing_guide.md

Unset the PROTIGY_SKIP_SHINYTEST2 environment variable to re-enable shinytest2 tests. Ensure this is done in the same terminal session where tests are run.

```bash
unset PROTIGY_SKIP_SHINYTEST2
```

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

### Reload R Package with devtools::load_all

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/README.md

Use this command to reload your R package after making code changes. A keyboard shortcut is available for convenience. Enabling shiny.autoreload can provide live updates in the browser.

```r
devtools::load_all(".")
```

```r
options(shiny.autoreload = TRUE)
```

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

### Updating a reactiveVal Object in app_server

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/module_requirements.md

This R code demonstrates how to update a reactiveVal object, like GCTs_and_params, which requires updating the entire object. Grab the current value, modify the desired field, and then reassign the whole object.

```r
# I want to update the `GCTs` part
new_GCTs_reactive <- ...

observeEvent(new_GCTs_reactive(), {
  # grab the current GCTs_and_params
  new_GCTs_and_params <- GCTs_and_params()
  
  # edit with your new GCTs
  new_GCTs_and_params$GCTs <- new_GCTs_reactive()
  
  # update the GCTs_and_params reactive val
  GCTs_and_params(new_GCTs_and_params)
})
```

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

### Handle Shiny errors and warnings with my_shinyalert_tryCatch

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Wraps expressions in a tryCatch block to display warnings as Shiny notifications and catch errors, preventing app crashes. Use this for any reactive expression that might produce warnings or errors, providing user feedback without interrupting the application flow.

```r
# Inside a Shiny server context:
result <- my_shinyalert_tryCatch(
  expr = {
    # Code that might warn or error
    log(-1)          # produces NaN with a warning
    42               # returned if no error
  },
  text.warning  = "<b>Warning:</b> unexpected value",
  show.warning  = TRUE,
  append.warning = TRUE,   # appends R's warning message to text.warning
  text.error    = "<b>Error processing data.</b>",
  show.error    = TRUE,
  return.error  = NULL     # returned when an error is caught
)
# result is 42 (warnings are non-fatal); a notification banner appears in the UI
```

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

### Updating Global ReactiveValues in app_server

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/module_requirements.md

This R code shows how to update a global reactiveValues object from a module's output. Assign the module's server output and use observeEvent to update the global object.

```r
## Inside of app_server ...

# assign the output of your module's server
my_reactive_output <- myModuleServer()

# observeEvent to update globals each time the module's output changes
observeEvent(my_reactive_output(), {
  globals$myField <- my_reactive_output()
})
```

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

### normalize.data(data, method, grp.vec)

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Applies one of eight normalization methods to a numeric data matrix. Supports group-wise normalization when a `grp.vec` is provided. The '2-component' method is automatically disabled for datasets with more than 20 samples.

```APIDOC
## normalize.data(data, method, grp.vec)

### Description
Applies one of eight normalization methods to a numeric data matrix. Supports group-wise normalization when a `grp.vec` is provided. The '2-component' method is automatically disabled for datasets with more than 20 samples.

### Method
`normalize.data(data, method, grp.vec)`

### Parameters
- **data** (matrix) - A numeric data matrix (features x samples).
- **method** (string) - The normalization method to apply (e.g., "Median", "2-component").
- **grp.vec** (vector, optional) - A vector assigning samples to groups for group-wise normalization.

### Request Example
```r
# Simulate a log-ratio proteomics matrix (features x samples)
set.seed(42)
mat <- matrix(rnorm(1000, mean = 0.2, sd = 1.5),
              nrow = 100, ncol = 10,
              dimnames = list(paste0("prot_", 1:100),
                              paste0("S", 1:10)))

# Example of normalization (method and grp.vec would be specified based on context)
# normalized_mat <- normalize.data(data = mat, method = "Median")
```

### Response
A normalized numeric data matrix.
```

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

### Check R Package Validity with devtools::check

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/README.md

Run this command to ensure your R package is valid and free of code errors. This check is also performed automatically on GitHub pushes.

```r
devtools::check()
```

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

### smart_trim

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Intelligently trims a character vector of sample labels to a fixed length, preserving maximum uniqueness by choosing to trim from the beginning or end of each string.

```APIDOC
## `smart_trim(labels, trim_length, default_trim)` — Intelligent label truncation

Trims a character vector of (potentially long) sample labels to a fixed `trim_length` while preserving maximum uniqueness. The function checks whether the beginning or the end of each string contains the most discriminating characters and trims accordingly.

### Parameters
- **labels** (character vector) - The labels to trim.
- **trim_length** (numeric) - The desired maximum length of the trimmed labels.
- **default_trim** (character, optional) - Specifies the default trimming direction ('start' or 'end') when uniqueness is equal at both ends.

### Request Example
```r
labels <- c("TCGA-BR-A4J4-01A-21-A30V-20",
            "TCGA-BR-A4J9-01A-11-A30V-20",
            "TCGA-BR-A4JL-01A-22-A30V-20")

# Default: trim to 10 characters
trimmed <- smart_trim(labels, trim_length = 10)
print(trimmed)

# Increase trim length for longer distinguishing prefixes
trimmed_long <- smart_trim(labels, trim_length = 15)
print(trimmed_long)

# Explicit fallback direction when start == end uniqueness
trimmed_fallback <- smart_trim(c("AAA_X", "AAA_Y"), trim_length = 5, default_trim = "end")
print(trimmed_fallback)
```

### Response Example
```r
# For trim_length = 10:
# [1] "TCGA-BR-A4" "TCGA-BR-A4" "TCGA-BR-A4"

# For trim_length = 15:
# [1] "TCGA-BR-A4J4-01A-21-A3" "TCGA-BR-A4J9-01A-11-A3" "TCGA-BR-A4JL-01A-22-A3"

# For default_trim = "end":
# [1] "AAA_X" "AAA_Y"
```
```

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

### my_shinyalert_tryCatch

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

A Shiny-aware error and warning handler that wraps expressions, displaying warnings as notifications and catching errors to prevent reactive chain crashes.

```APIDOC
## `my_shinyalert_tryCatch(expr, ...)` — Shiny-aware error/warning handler

Wraps any expression in a `tryCatch` + `withCallingHandlers` block. Warnings are caught and displayed as `shiny::showNotification` banners (type `"warning"`); errors are caught, displayed as error banners, and return a configurable `return.error` value instead of crashing the reactive chain. Used throughout the processing pipeline to give users in-app feedback.

### Parameters
- **expr** (expression) - The R expression to evaluate.
- **...** - Additional arguments passed to `tryCatch` and `withCallingHandlers`, including:
  - **text.warning** (character) - Text to display for warnings.
  - **show.warning** (logical) - Whether to display warning notifications.
  - **append.warning** (logical) - Whether to append R's warning message to `text.warning`.
  - **text.error** (character) - Text to display for errors.
  - **show.error** (logical) - Whether to display error notifications.
  - **return.error** (any) - The value to return when an error is caught.

### Request Example
```r
# Inside a Shiny server context:
result <- my_shinyalert_tryCatch(
  expr = {
    # Code that might warn or error
    log(-1)          # produces NaN with a warning
    42               # returned if no error
  },
  text.warning  = "<b>Warning:</b> unexpected value",
  show.warning  = TRUE,
  append.warning = TRUE,   # appends R's warning message to text.warning
  text.error    = "<b>Error processing data.</b>",
  show.error    = TRUE,
  return.error  = NULL     # returned when an error is caught
)
print(result)
```

### Response Example
```r
# result is 42 (warnings are non-fatal); a notification banner appears in the UI
```
```

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

### processGCTs(GCTs, parameters)

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Applies a comprehensive preprocessing pipeline to a list of GCT objects, including filtering, gene-symbol resolution, log transformation, and normalization. It returns the processed GCTs, updated parameters, and a merged GCT object.

```APIDOC
## processGCTs(GCTs, parameters)

### Description
Applies a comprehensive preprocessing pipeline to a list of GCT objects, including filtering, gene-symbol resolution, log transformation, and normalization. It returns the processed GCTs, updated parameters, and a merged GCT object.

### Method
`processGCTs(GCTs, parameters)`

### Parameters
- **GCTs** (list) - A named list of `cmapR::GCT` objects, where each object represents an omics dataset.
- **parameters** (list) - A list of preprocessing parameters, with keys corresponding to the omics dataset names in `GCTs`.

### Request Example
```r
library(Protigy)
library(cmapR)

# Load the bundled BRCA test datasets
data(brca_retrospective_v5.0_proteome_gct)
data(brca_retrospective_v5.0_phosphoproteome_gct)

GCTs <- list(
  prot  = brca_retrospective_v5.0_proteome_gct,
  phos  = brca_retrospective_v5.0_phosphoproteome_gct
)

# Build a parameters list matching setupDefaults.yaml
params_prot <- list(
  log_transformation      = "None",
  data_normalization      = "Median",
  data_filter             = "None",
  max_missing             = 50,          # keep rows with <= 50 % missing
  intensity_data          = "No",
  group_normalization     = FALSE,
  gene_symbol_column      = "geneSymbol",
  convert_ids_to_gene_symbol = FALSE,
  annotation_column       = "Type",      # cdesc column used for grouping
  sample_filter_enabled   = FALSE,
  row_filter_enabled      = FALSE,
  data_filter_sd_pct      = 10
)
parameters <- list(prot = params_prot, phos = params_prot)

# Run the pipeline (normally called inside a Shiny session with withProgress)
result <- processGCTs(GCTs = GCTs, parameters = parameters)

# Inspect outputs
names(result)
#> [1] "GCTs"        "parameters"  "GCTs_merged"

dim(result$GCTs$prot@mat)       # processed proteome matrix
dim(result$GCTs_merged@mat)     # all features row-stacked
result$parameters$prot$data_normalization  # may differ if auto-fallback triggered
```

### Response
A list containing:
- **GCTs**: Processed `cmapR::GCT` objects.
- **parameters**: Updated preprocessing parameters.
- **GCTs_merged**: A single `cmapR::GCT` object with all omics features row-merged.
```

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

### Use ns() for Shiny Module Input/Output IDs

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/README.md

The ns() function is crucial for scoping input and output IDs within Shiny modules. It prevents naming conflicts and ensures UI elements function correctly. Remember to define ns <- session$ns in your module server function if using ns() within renderUI.

```r
textInput(inputId = ns('myText'))
```

```r
plotOutput(outputId = ns("myPlot"))
```

```r
renderUI({
  textInput(inputId = ns('myText'))
})
```

```r
conditionalPanel
```

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

### Disable shinytest2 tests

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/shinytest2_testing_guide.md

Set the PROTIGY_SKIP_SHINYTEST2 environment variable to true to disable shinytest2 tests. This is useful for faster local iteration.

```bash
export PROTIGY_SKIP_SHINYTEST2=true
```

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

### stat.testing

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

A core statistical testing engine that performs various tests (t-tests, F-tests) using limma. It returns a list of results data frames for specified omics, including fold-change, p-values, and significance flags.

```APIDOC
## stat.testing(test, annotation_col, chosen_omes, gct, chosen_groups, selected_contrasts, ...)

### Description
Core function backing the Statistics tab. Dispatches to moderated one-sample t-test, two-sample t-test, or F-test (all via `limma::eBayes`) depending on the `test` argument. Returns a named list of results data frames (one per selected ome) with columns including fold-change, p-value, adjusted p-value, and significance flag.

### Parameters
* **test** (string) - The type of statistical test to perform (e.g., "Moderated F test", "Two-sample Moderated T-test").
* **annotation_col** (string) - The column in the annotation data containing group labels.
* **chosen_omes** (string or vector) - The omics layer(s) to perform testing on.
* **gct** (list) - Processed GCT data, typically from `processGCTs`.
* **chosen_groups** (vector) - The specific groups to include in the analysis.
* **selected_contrasts** (string or NULL) - Specifies the contrast for t-tests. NULL tests all groups against each other.
* **p.value.alpha** (numeric) - The significance level for p-value adjustment.
* **use.adj.pvalue** (boolean) - Whether to use adjusted p-values for significance.
* **apply.log** (boolean) - Whether the input data is log-transformed.
* **intensity** (boolean) - Whether to use intensity values.
* **...** - Additional arguments passed to `limma` functions.

### Request Example
```r
# Minimal example using processed GCTs (result from processGCTs above)
stat_result <- stat.testing(
  test             = "Moderated F test",
  annotation_col   = "Type",           # cdesc column for group labels
  chosen_omes      = "prot",
  gct              = result$GCTs,
  chosen_groups    = c("Luminal", "Basal"),  # groups to include
  selected_contrasts = NULL,           # NULL = test all groups vs each other
  p.value.alpha    = 0.05,
  use.adj.pvalue   = TRUE,
  apply.log        = FALSE,
  intensity        = FALSE
)

head(stat_result$prot)
#   id  geneSymbol   F   P.Value adj.P.Val  sig
# ...

# Two-sample moderated t-test with explicit contrast
stat_t <- stat.testing(
  test               = "Two-sample Moderated T-test",
  annotation_col     = "Type",
  chosen_omes        = "prot",
  gct                = result$GCTs,
  chosen_groups      = c("Luminal", "Basal"),
  selected_contrasts = "Luminal-Basal",
  p.value.alpha      = 0.05,
  use.adj.pvalue     = TRUE,
  apply.log          = FALSE,
  intensity          = FALSE
)
```
```

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

### Intelligently trim labels with smart_trim

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Trims character vectors of labels to a fixed length, prioritizing uniqueness by checking the beginning or end of strings. Use when sample labels are long and need to be shortened while maintaining distinguishability.

```r
labels <- c("TCGA-BR-A4J4-01A-21-A30V-20",
            "TCGA-BR-A4J9-01A-11-A30V-20",
            "TCGA-BR-A4JL-01A-22-A30V-20")

# Default: trim to 10 characters
trimmed <- smart_trim(labels, trim_length = 10)
trimmed
#> [1] "TCGA-BR-A4" "TCGA-BR-A4" ...  (beginning chosen if tie; end if more unique)
```

```r
# Increase trim length for longer distinguishing prefixes
smart_trim(labels, trim_length = 15)
```

```r
# Explicit fallback direction when start == end uniqueness
smart_trim(c("AAA_X", "AAA_Y"), trim_length = 5, default_trim = "end")
#> [1] "AAA_X" "AAA_Y"
```

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

### Map IDs to gene symbols with protigy_legacy_map_ids_to_symbols

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Maps protein or transcript identifiers to HGNC/MGI gene symbols using AnnotationDbi. It automatically detects common ID types (UniProt, RefSeq, Ensembl, Entrez) and queries the correct human or mouse database. Use this to translate identifiers into human-readable gene symbols.

```r
# Map human UniProt accessions to gene symbols
result <- protigy_legacy_map_ids_to_symbols(
  ids     = c("P04637", "P38398", "P00533-2", "Q9Y2T1"),
  species = "Homo sapiens"
)

result$symbols       #> "TP53"  "BRCA1" "EGFR"  NA
result$keytype       #> "UNIPROT"
result$n_total       #> 4
result$n_unmapped    #> 1  (Q9Y2T1 not found)

# Mouse Ensembl gene IDs
result_mm <- protigy_legacy_map_ids_to_symbols(
  ids     = c("ENSMUSG00000059552", "ENSMUSG00000032359"),
  species = "Mus musculus"
)
result_mm$keytype    #> "ENSEMBL"
```

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

### Column-wise Data Normalization

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

The `normalize.data` function applies one of eight normalization methods to a numeric data matrix. Group-wise normalization can be performed when `grp.vec` is provided. The '2-component' method is automatically disabled for datasets with more than 20 samples.

```r
# Simulate a log-ratio proteomics matrix (features x samples)
set.seed(42)
mat <- matrix(rnorm(1000, mean = 0.2, sd = 1.5),
              nrow = 100, ncol = 10,
              dimnames = list(paste0("prot_", 1:100),
                              paste0("S", 1:10)))

```

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

### Module Export Function Structure

Source: https://github.com/broadinstitute/protigy-v2/blob/main/dev/module_requirements.md

Define custom export functions within a module's server to save plots, tables, or objects. These functions accept a directory name and should handle reactive data, throwing errors if exports fail.

```R
function(dir_name) {
  # Export logic here
  # Assume dir_name exists
  # Save file inside dir_name
  # Use reactive variables
  # Throw error if export cannot be generated
}

```

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

### protigy_legacy_map_ids_to_symbols

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Maps protein or transcript identifiers to HGNC/MGI gene symbols using AnnotationDbi, automatically detecting identifier types and organism databases.

```APIDOC
## `protigy_legacy_map_ids_to_symbols(ids, species)` — ID-to-gene-symbol mapping

Maps a character vector of protein/transcript identifiers to HGNC/MGI gene symbols using `AnnotationDbi::mapIds`. Automatically detects the identifier type (UniProt, RefSeq, Ensembl protein/gene, Entrez) and queries the appropriate organism annotation database (`org.Hs.eg.db` for human, `org.Mm.eg.db` for mouse).

### Parameters
- **ids** (character vector) - A vector of protein or transcript identifiers.
- **species** (character) - The species for mapping (e.g., "Homo sapiens", "Mus musculus").

### Request Example
```r
# Map human UniProt accessions to gene symbols
result <- protigy_legacy_map_ids_to_symbols(
  ids     = c("P04637", "P38398", "P00533-2", "Q9Y2T1"),
  species = "Homo sapiens"
)

print(result$symbols)
print(result$keytype)
print(result$n_total)
print(result$n_unmapped)

# Mouse Ensembl gene IDs
result_mm <- protigy_legacy_map_ids_to_symbols(
  ids     = c("ENSMUSG00000059552", "ENSMUSG00000032359"),
  species = "Mus musculus"
)
print(result_mm$keytype)
```

### Response Example
```r
# For human UniProt:
# [1] "TP53"  "BRCA1" "EGFR"  NA
# [1] "UNIPROT"
# [1] 4
# [1] 1

# For mouse Ensembl:
# [1] "ENSEMBL"
```
```

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

### Statistical Testing Engine

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Performs statistical tests (t-test, F-test) using limma. Returns results data frames for specified omics.

```R
# Minimal example using processed GCTs (result from processGCTs above)
stat_result <- stat.testing(
  test             = "Moderated F test",
  annotation_col   = "Type",           # cdesc column for group labels
  chosen_omes      = "prot",
  gct              = result$GCTs,
  chosen_groups    = c("Luminal", "Basal"),  # groups to include
  selected_contrasts = NULL,           # NULL = test all groups vs each other
  p.value.alpha    = 0.05,
  use.adj.pvalue   = TRUE,
  apply.log        = FALSE,
  intensity        = FALSE
)

head(stat_result$prot)
#   id  geneSymbol   F   P.Value adj.P.Val  sig
# ...

# Two-sample moderated t-test with explicit contrast
stat_t <- stat.testing(
  test               = "Two-sample Moderated T-test",
  annotation_col     = "Type",
  chosen_omes        = "prot",
  gct                = result$GCTs,
  chosen_groups      = c("Luminal", "Basal"),
  selected_contrasts = "Luminal-Basal",
  p.value.alpha      = 0.05,
  use.adj.pvalue     = TRUE,
  apply.log          = FALSE,
  intensity          = FALSE
)
```

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

### Create a deep copy of a GCT object with deep_clone_gct

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Generates a completely independent copy of a cmapR::GCT object, including its matrix and descriptor data frames. This is crucial for preventing unintended modifications to original data when performing operations like normalization or filtering.

```r
data(brca_retrospective_v5.0_proteome_gct)
original <- brca_retrospective_v5.0_proteome_gct

clone <- deep_clone_gct(original)

# Mutate clone — original is unaffected
clone@mat[1, 1] <- 999
original@mat[1, 1]  #> unchanged original value
```

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

### Save Plot with Custom Parameters

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Saves a ggplot object using specified parameters. Requires ggplot2 and the get_ggsave_params function.

```r
params <- get_ggsave_params("default")
p <- ggplot2::ggplot(mtcars, ggplot2::aes(mpg, wt)) + ggplot2::geom_point()
do.call(ggplot2::ggsave, c(list(filename = "my_plot.pdf", plot = p), params))
```

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

### transformGCTs(GCTs, parameters)

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Performs only log transformation and gene-symbol resolution on GCT objects, skipping normalization and filtering. This is useful for generating original GCTs for export and comparison.

```APIDOC
## transformGCTs(GCTs, parameters)

### Description
Performs only log transformation and gene-symbol resolution on GCT objects, skipping normalization and filtering. This is useful for generating original GCTs for export and comparison.

### Method
`transformGCTs(GCTs, parameters)`

### Parameters
- **GCTs** (list) - A named list of `cmapR::GCT` objects.
- **parameters** (list) - A list of parameters, including `gene_symbol_column` and `log_transformation` settings.

### Request Example
```r
# Continuing from the processGCTs example above
GCTs_original <- transformGCTs(GCTs = GCTs, parameters = parameters)

# The returned list is keyed by ome name
dim(GCTs_original$prot@mat)   # same dimensions as input (no rows removed)
```

### Response
A list of `cmapR::GCT` objects, keyed by ome name, with log transformation and gene-symbol resolution applied.
```

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

### Annotation Type Detection

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Helper functions to determine if an annotation column is discrete or continuous. A column is continuous if it contains only numbers and has more than `nfactor_cutoff` unique non-NA values.

```R
# Discrete example: treatment group labels
is.discrete(c("Control", "TreatA", "TreatA", "Control"))   #> TRUE
is.continuous(c("Control", "TreatA", "TreatA", "Control"))  #> FALSE

# Continuous example: 25 distinct numeric measurements
is.discrete(as.character(seq(0.1, 2.5, by = 0.1)))   #> FALSE
is.continuous(as.character(seq(0.1, 2.5, by = 0.1)))  #> TRUE

# Borderline: 15 numeric values → treated as discrete (< nfactor_cutoff = 20)
is.discrete(as.character(1:15))    #> TRUE
is.discrete(as.character(1:15), nfactor_cutoff = 10)  #> FALSE
```

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

### is.discrete / is.continuous

Source: https://context7.com/broadinstitute/protigy-v2/llms.txt

Helper functions to determine if an annotation column represents discrete (categorical) or continuous (numeric) data based on the number of unique values.

```APIDOC
## is.discrete(annot_col, nfactor_cutoff) / is.continuous(annot_col, nfactor_cutoff)

### Description
Helper functions used throughout the app to decide whether a sample-annotation column should be treated as categorical (discrete) or numeric (continuous) for color assignment and plot styling. A column is considered continuous if it contains only numbers AND has more than `nfactor_cutoff` unique non-NA values (default 20).

### Parameters
* **annot_col** (vector) - The annotation column to check.
* **nfactor_cutoff** (numeric) - The threshold for unique values to consider a column continuous. Defaults to 20.

### Request Example
```r
# Discrete example: treatment group labels
is.discrete(c("Control", "TreatA", "TreatA", "Control"))   #> TRUE
is.continuous(c("Control", "TreatA", "TreatA", "Control"))  #> FALSE

# Continuous example: 25 distinct numeric measurements
is.discrete(as.character(seq(0.1, 2.5, by = 0.1)))   #> FALSE
is.continuous(as.character(seq(0.1, 2.5, by = 0.1)))  #> TRUE

# Borderline: 15 numeric values → treated as discrete (< nfactor_cutoff = 20)
is.discrete(as.character(1:15))    #> TRUE
is.discrete(as.character(1:15), nfactor_cutoff = 10)  #> FALSE
```
```