### Quick Start GeneNMF Analysis

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/package-overview.md

A minimal example to quickly run GeneNMF and visualize meta-programs. Requires Seurat and GeneNMF libraries.

```r
library(Seurat)
library(GeneNMF)
data(sampleObj)
mp <- getMetaPrograms(multiNMF(list(sampleObj), k=5), nMP=3)
plotMetaPrograms(mp)
```

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

### Test GeneNMF Installation

Source: https://github.com/carmonalab/genenmf/blob/master/README.md

Load the GeneNMF library and run a basic NMF decomposition on a sample object to test the installation.

```r
library(GeneNMF)
data(sampleObj)
sampleObj <- runNMF(sampleObj, k=5)
```

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

### Install GeneNMF from GitHub

Source: https://github.com/carmonalab/genenmf/blob/master/README.md

Install the latest development version of the GeneNMF package from GitHub using the remotes package.

```r
library(remotes)
remotes::install_github("carmonalab/GeneNMF")
```

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

### Get Meta Programs for Broad Patterns (R)

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/README.md

Use permissive settings to discover broad patterns in meta-programs. Adjust `nMP`, `specificity.weight`, `weight.explained`, and `min.confidence` for looser discovery.

```r
# Permissive settings to discover broad patterns
mp <- getMetaPrograms(nmf.res, nMP = 5, specificity.weight = 0,
                      weight.explained = 0.3, min.confidence = 0.3)
```

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

### Install GeneNMF Package

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/INDEX.md

Install the GeneNMF package from CRAN or directly from GitHub using remotes.

```r
# Installation
install.packages("GeneNMF")
remotes::install_github("carmonalab/GeneNMF")
```

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

### Install GeneNMF from CRAN

Source: https://github.com/carmonalab/genenmf/blob/master/README.md

Install the release version of the GeneNMF package from CRAN.

```r
install.packages("GeneNMF")
```

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

### Basic plotMetaPrograms Usage

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/plotMetaPrograms.md

This is a basic example demonstrating the default usage of the plotMetaPrograms function after loading sample data, running NMF, and extracting meta-programs.

```r
library(Seurat)
library(GeneNMF)

# Load sample data
data(sampleObj)

# Run NMF and extract meta-programs
geneNMF_programs <- multiNMF(list(sampleObj), k = 5)
mp <- getMetaPrograms(geneNMF_programs, nMP = 3)

# Basic visualization
plotMetaPrograms(mp)
```

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

### Run multiNMF with k=5 and k=6

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/multiNMF.md

This example demonstrates how to load sample data, split it into a list of Seurat objects, and then run the multiNMF function for a specified range of NMF components (k=5 and k=6). It also shows how to access the resulting factorization models.

```r
library(Seurat)
library(GeneNMF)

# Load sample data
data(sampleObj)

# Split into samples and run NMF for k=5 and k=6
obj.list <- list(sample1 = sampleObj, sample2 = sampleObj)
geneNMF_programs <- multiNMF(obj.list, k = 5:6)

# Access individual factorizations
nmf.k5 <- geneNMF_programs$sample1.k5
head(nmf.k5$w[, 1:3])  # First 3 gene loadings
```

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

### Check GeneNMF Package Version

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Demonstrates how to check the installed version of the GeneNMF package.

```r
packageVersion("GeneNMF")  # 0.9.5
```

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

### Less Stringent Specificity with getMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/getMetaPrograms.md

This example illustrates how to achieve less stringent specificity in gene selection by adjusting 'specificity.weight' and 'weight.explained'. This can lead to more genes being included in meta-programs, albeit with less specific weighting.

```r
# Less stringent specificity (more genes, less specific)
mp_loose <- getMetaPrograms(geneNMF_programs, nMP = 5, 
                            specificity.weight = 2, weight.explained = 0.3)
```

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

### Run GSEA with Test Data and C8 Signatures

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/runGSEA.md

An example of running GSEA with a small set of test genes against MSigDB C8 cell type signatures. Requires 'fgsea' and 'msigdbr' packages.

```r
# Example with test data

# Load sample data (assuming sampleObj is available from previous steps)
data(sampleObj)

test_genes <- c("BANK1", "CD22", "CD79A", "CD19", "IGHD", "IGHG3", "IGHM")
if (requireNamespace("fgsea", quietly = TRUE) &&
    requireNamespace("msigdbr", quietly = TRUE)) {
  results <- runGSEA(test_genes, universe = rownames(sampleObj), 
                    category = "C8")
}
```

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

### Run multiNMF with Poisson loss function

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/multiNMF.md

This example shows how to use a different loss function, specifically the 'gp' (Poisson) loss, with the multiNMF function. Note that this requires RcppML version 1.0.0 or higher.

```r
# Use Poisson loss function (requires RcppML >= 1.0.0)
geneNMF_programs <- multiNMF(obj.list, k = 5, loss = "gp")
```

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

### Get Meta Programs for High-Confidence Markers (R)

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/README.md

Use stringent settings to identify specific marker genes. Increase `nMP`, `specificity.weight`, `weight.explained`, and `min.confidence` for stricter marker identification.

```r
# Stringent settings for specific marker genes
mp <- getMetaPrograms(nmf.res, nMP = 15, specificity.weight = 10,
                      weight.explained = 0.8, min.confidence = 0.8)
```

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

### Inspect Gene Content of Remaining Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/dropMetaPrograms.md

Provides an example of how to inspect the gene content of the remaining meta-programs after filtering. This helps in understanding the biological relevance of the retained programs.

```r
# Check gene content of remaining programs
head(mp_filtered$metaprograms.genes$MP1)
head(mp_filtered$metaprograms.genes$MP2)
```

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

### Using Jaccard Similarity with getMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/getMetaPrograms.md

This example shows how to use the 'jaccard' metric instead of the default cosine similarity for meta-program extraction. This metric is useful for analyzing binary presence/absence of genes.

```r
# Use Jaccard similarity instead of cosine
mp_jaccard <- getMetaPrograms(geneNMF_programs, nMP = 5, metric = "jaccard")
```

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

### Run GSEA with Hallmark Gene Sets

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/runGSEA.md

Performs GSEA against MSigDB Hallmark gene sets. Ensure 'fgsea' and 'msigdbr' are installed. The universe parameter should be set to all genes in your dataset.

```r
library(Seurat)
library(GeneNMF)

# Load sample data
data(sampleObj)

# Run NMF and extract gene programs
geneNMF_programs <- multiNMF(list(sampleObj), k = 5)
nmf_genes <- getNMFgenes(geneNMF_programs)

# Get genes from first program
program1_genes <- names(nmf_genes$sampleObj.k5.1)

# Perform overrepresentation analysis (requires fgsea, msigdbr)
if (requireNamespace("fgsea", quietly = TRUE) &&
    requireNamespace("msigdbr", quietly = TRUE)) {
  
  # Against Hallmark gene sets
  gsea_hallmark <- runGSEA(program1_genes, universe = rownames(sampleObj))
  head(gsea_hallmark)
}
```

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

### Multi-Sample NMF Analysis (R)

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/README.md

Process multiple samples efficiently using `multiNMF`. This example demonstrates selective Highly Variable Gene (HVG) filtering by providing a blocklist for genes to exclude, such as mitochondrial and ribosomal genes.

```r
# Process many samples; use selective HVG filtering
nmf_programs <- multiNMF(samples, k = 5:9, nfeatures = 3000,
                        hvg.blocklist = list(
                          mito = grep("^MT-", rownames(samples[[1]]), value=T),
                          ribo = grep("^RP", rownames(samples[[1]]), value=T)
                        ))
```

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

### Run multiNMF with pre-specified HVGs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/multiNMF.md

This example shows how to use pre-calculated highly variable genes (HVGs) with the multiNMF function. It first extracts HVGs from a Seurat object and then passes a subset of these genes to the `hvg` parameter.

```r
# Use pre-specified HVGs
hvg <- VariableFeatures(sampleObj)[1:1000]
geneNMF_programs <- multiNMF(obj.list, k = 5, hvg = hvg)
```

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

### Quick Preview of Metaprograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/configuration.md

Use this for a rapid overview of metaprograms with minimal parameters. It defaults to standard behavior.

```r
# Minimal parameters, default behavior
mp <- getMetaPrograms(geneNMF_programs, nMP = 3)
```

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

### Standard Discovery Preset for Meta-Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/configuration.md

Use this preset for a balanced meta-program discovery, with moderate specificity and confidence.

```r
getMetaPrograms(nmf.res, nMP=10, specificity.weight=5,
                weight.explained=0.5, min.confidence=0.5)
```

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

### Quick Discovery Preset for Meta-Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/configuration.md

Use this preset for a permissive meta-program discovery, including many genes with low confidence.

```r
getMetaPrograms(nmf.res, nMP=5, specificity.weight=0, 
                weight.explained=0.3, min.confidence=0.3)
```

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

### Run GSEA for a Different Species

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/runGSEA.md

Performs GSEA for a different species by specifying the 'species' parameter (e.g., 'Mus musculus'). Ensure the 'fgsea' and 'msigdbr' packages are installed.

```r
  # Different species
  gsea_mouse <- runGSEA(program1_genes, species = "Mus musculus")
```

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

### Visualize Filtered Meta-Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/dropMetaPrograms.md

Illustrates how to visualize the meta-programs after they have been filtered using dropMetaPrograms. This step helps in assessing the impact of the filtering on the overall meta-program structure.

```r
# Visualize filtered meta-programs
plotMetaPrograms(mp_filtered)
```

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

### Basic Meta-Program Heatmap

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Generates a basic heatmap visualization of meta-programs. Ensure 'meta_programs' object is available.

```r
plotMetaPrograms(meta_programs)
```

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

### Remove Multiple Meta-Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/dropMetaPrograms.md

Demonstrates how to remove multiple specified meta-programs (e.g., 'MP4', 'MP5') from a meta-program object and verify the removal by checking the updated metrics.

```r
library(Seurat)
library(GeneNMF)

# Load sample data
data(sampleObj)

# Run NMF and extract meta-programs
geneNMF_programs <- multiNMF(list(sampleObj), k = 5)
mp <- getMetaPrograms(geneNMF_programs, nMP = 5)

# Check meta-program metrics before filtering
mp$metaprograms.metrics

# Remove low-confidence or redundant meta-programs
mp_filtered <- dropMetaPrograms(mp, dropMP = c("MP4", "MP5"))

# Verify removal
mp_filtered$metaprograms.metrics
```

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

### Run NMF with Different Loss Function

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/runNMF.md

Computes NMF embeddings using a specified loss function, such as 'gp' (Gaussian Poisson), which is suitable for count data. Ensure the RcppML package is installed and updated for custom loss functions.

```r
# Use different loss function (Gaussian Poisson, for count data)
sampleObj <- runNMF(sampleObj, k = 8, loss = "gp")
```

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

### Meta-Program Heatmap for Large Datasets

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Visualizes meta-programs for large datasets by downsampling and optionally hiding the dendrogram. Requires 'meta_programs' object.

```r
plotMetaPrograms(meta_programs,
                downsample = 500,
                showtree = FALSE)
```

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

### Multi-Sample NMF Workflow

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/README.md

Performs NMF across multiple samples and k values, extracts genes, identifies consensus meta-programs, visualizes results, and optionally filters meta-programs. Requires Seurat objects as input.

```r
library(Seurat)
library(GeneNMF)

# 1. Prepare multiple Seurat objects
samples <- list(sample1, sample2, sample3)

# 2. Run NMF across multiple k values
nmf_programs <- multiNMF(samples, k = 5:9)

# 3. Extract genes from individual programs
genes <- getNMFgenes(nmf_programs)

# 4. Find consensus meta-programs
meta_programs <- getMetaPrograms(nmf_programs, nMP = 10)

# 5. Visualize
plotMetaPrograms(meta_programs)

# 6. Filter and validate
meta_programs <- dropMetaPrograms(meta_programs, dropMP = c("MP9", "MP10"))

# 7. Enrichment analysis (optional)
mp1_genes <- names(meta_programs$metaprograms.genes$MP1)
enrichment <- runGSEA(mp1_genes, universe = rownames(samples[[1]])))
```

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

### Run multiNMF excluding mitochondrial genes from HVG selection

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/multiNMF.md

This example demonstrates how to exclude specific genes, such as mitochondrial genes, from the highly variable gene (HVG) selection process when running multiNMF. It identifies mitochondrial genes and passes them to the `hvg.blocklist` parameter.

```r
# Exclude mitochondrial genes from HVG selection
mito.genes <- grep("^MT-", rownames(sampleObj), value = TRUE)
geneNMF_programs <- multiNMF(obj.list, k = 5, hvg.blocklist = mito.genes)
```

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

### Stringent Gene Selection with getMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/getMetaPrograms.md

This snippet demonstrates how to apply more stringent criteria for gene selection using the 'weight.explained' and 'min.confidence' parameters. This results in a more focused set of genes per meta-program.

```r
# More stringent gene selection (90% of weight, minimum 80% confidence)
mp_strict <- getMetaPrograms(geneNMF_programs, nMP = 5, 
                             weight.explained = 0.9, min.confidence = 0.8)
```

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

### Discover Meta Programs with Default Parameters

Source: https://github.com/carmonalab/genenmf/blob/master/README.md

Perform NMF on a list of Seurat objects for multiple k values and then cluster the resulting gene programs into meta-programs.

```r
sampleObj.list <- Seurat::SplitObject(sampleObj, split.by = "donor")
geneNMF.programs <- multiNMF(sampleObj.list, k=4:9)
```

```r
geneNMF.metaprograms <- getMetaPrograms(geneNMF.programs, nMP=5)
```

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

### Default Parameters for getMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Displays the default settings for the getMetaPrograms function. Useful for understanding default meta-program extraction and filtering.

```r
getMetaPrograms(
  nMP = 10,
  specificity.weight = 5,
  weight.explained = 0.5,
  max.genes = 200,
  metric = "cosine",
  hclust.method = "ward.D2",
  min.confidence = 0.5,
  remove.empty = TRUE
)
```

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

### Genenmf Project File Structure

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/INDEX.md

This tree displays the directory structure of the Genenmf project, highlighting the location of the main documentation files and the API reference subdirectory.

```bash
output/
├── INDEX.md                           ← You are here
├── README.md                          ← Start here
├── quick-reference.md                 ← Fast lookup
├── package-overview.md                ← Overview
├── types.md                           ← Data structures
├── configuration.md                   ← Parameters
├── errors-and-edge-cases.md           ← Troubleshooting
├── internal-utilities.md              ← Implementation
├── DOCUMENTATION-MANIFEST.md          ← Generation info
└── api-reference/
    ├── multiNMF.md                    ← Functions A-Z
    ├── getNMFgenes.md
    ├── getMetaPrograms.md
    ├── plotMetaPrograms.md
    ├── runNMF.md
    ├── getDataMatrix.md
    ├── findVariableFeatures_wfilters.md
    ├── runGSEA.md
    └── dropMetaPrograms.md
```

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

### Customizing Meta-Program Colors in plotMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/plotMetaPrograms.md

Demonstrates how to assign specific colors to meta-program annotations using the annotation_colors parameter.

```r
mp_colors <- c("red", "blue", "green", "orange", "purple")
plotMetaPrograms(mp, annotation_colors = mp_colors)
```

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

### getMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/package-overview.md

Finds consensus programs from NMF models. It takes NMF models as input and returns a meta-program object.

```APIDOC
## getMetaPrograms

### Description
Find consensus programs.

### Input
NMF models

### Output
meta-program object
```

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

### Basic GeneNMF Workflow

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/INDEX.md

Perform a basic GeneNMF workflow by obtaining metaprograms from a multiNMF analysis and plotting them. Ensure the 'multiNMF' function is correctly applied to your sample object.

```r
# Basic workflow (from README)
library(GeneNMF)
mp <- getMetaPrograms(multiNMF(list(sampleObj), k=5), nMP=3)
plotMetaPrograms(mp)
```

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

### Adjust Meta-Program Confidence and Weight Thresholds

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/errors-and-edge-cases.md

Addresses empty meta-programs by relaxing the min.confidence and weight.explained thresholds in getMetaPrograms(). Alternatively, manually filter empty meta-programs before rerunning.

```r
# Relax thresholds
mp <- getMetaPrograms(nmf.res, min.confidence = 0.3, weight.explained = 0.3)
```

```r
# Or manually filter and rerun
mp_filtered <- dropMetaPrograms(mp, dropMP = which_are_empty)
```

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

### Run GSEA with Gene Ontology (GO) - Biological Process

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/runGSEA.md

Performs GSEA against Gene Ontology Biological Process gene sets. Specify category 'C5' and subcategory 'GO:BP'. The universe parameter should be set to all genes in your dataset.

```r
# Against Gene Ontology (Biological Process)
  gsea_go <- runGSEA(program1_genes, universe = rownames(sampleObj),
                     category = "C5", subcategory = "GO:BP")
```

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

### Discover Meta-Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Use getMetaPrograms to discover meta-programs from NMF results. Adjust nMP for the number of meta-programs. Control specificity with specificity.weight, the proportion of explained variance with weight.explained, and the minimum gene presence in meta-program clusters with min.confidence. Permissive settings discover broad patterns, balanced is standard, and stringent settings focus on specific markers.

```r
getMetaPrograms(nmf.res, nMP = 5, specificity.weight = 0, 
                weight.explained = 0.3, min.confidence = 0.3)
```

```r
getMetaPrograms(nmf.res, nMP = 10, specificity.weight = 5,
                weight.explained = 0.5, min.confidence = 0.5)
```

```r
getMetaPrograms(nmf.res, nMP = 15, specificity.weight = 10,
                weight.explained = 0.8, min.confidence = 0.8)
```

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

### Displaying Program Names with plotMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/plotMetaPrograms.md

Shows how to display individual program names as row and column names on the heatmap, which is useful for smaller datasets.

```r
plotMetaPrograms(mp, show_rownames = TRUE, show_colnames = TRUE)
```

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

### plotMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/package-overview.md

Visualizes similarities between meta-programs. It takes a meta-program object as input and generates a heatmap plot.

```APIDOC
## plotMetaPrograms

### Description
Visualize similarities.

### Input
meta-programs

### Output
heatmap plot
```

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

### Discover Consensus Meta-Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/configuration.md

Use getMetaPrograms for consensus gene program discovery. Configure parameters like nMP, specificity.weight, and weight.explained to tailor the discovery process.

```r
getMetaPrograms(nmf.res,
               nMP=10,
               specificity.weight=5,
               weight.explained=0.5,
               max.genes=200,
               metric=c("cosine","jaccard"),
               hclust.method="ward.D2",
               min.confidence=0.5,
               remove.empty=TRUE)
```

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

### Default Parameters for runNMF

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Lists the default configuration for the runNMF function, including NMF parameters and reduction naming.

```r
runNMF(
  k = 10,
  new.reduction = "NMF",
  seed = 123,
  loss = "mse",
  L1 = c(0, 0),
  center = FALSE,
  scale = FALSE
)
```

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

### Using a Custom Color Palette in plotMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/plotMetaPrograms.md

Illustrates how to apply a custom color palette to the heatmap using the palette argument. Requires the 'viridis' package.

```r
library(viridis)
custom_palette <- heat.colors(100)
plotMetaPrograms(mp, palette = custom_palette)
```

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

### Determine Meta-Program Sample Composition

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/internal-utilities.md

Determines the sample composition of each meta-program by counting the contribution of programs from each sample. Useful for identifying sample-specific vs. shared programs.

```r
get_metaprogram_composition(J = NULL, markers.consensus = NULL,
                            cl_members = NULL)
```

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

### Increase Specificity Weight for Differentiating Meta-Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/errors-and-edge-cases.md

Helps differentiate identical meta-programs by increasing the specificity.weight parameter in getMetaPrograms(). Also suggests checking data quality for biological diversity.

```r
# Increase specificity to differentiate
mp <- getMetaPrograms(nmf.res, specificity.weight = 10)
```

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

### Basic Usage of getMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/getMetaPrograms.md

This snippet demonstrates the fundamental usage of the getMetaPrograms function to extract meta-programs and access their associated data like genes, metrics, weights, and composition. It requires the Seurat and GeneNMF libraries and sample data.

```r
library(Seurat)
library(GeneNMF)

# Load sample data
data(sampleObj)

# Run NMF and extract meta-programs
geneNMF_programs <- multiNMF(list(sampleObj), k = 5:6)
geneNMF_metaprograms <- getMetaPrograms(geneNMF_programs, nMP = 5)

# Access meta-program genes
head(geneNMF_metaprograms$metaprograms.genes$MP1, 10)

# Get meta-program metrics
geneNMF_metaprograms$metaprograms.metrics

# Access gene weights for MP1
mp1_weights <- geneNMF_metaprograms$metaprograms.genes.weights$MP1
head(mp1_weights, 5)

# Sample composition across meta-programs
geneNMF_metaprograms$metaprograms.composition
```

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

### Calculate Meta-Program Quality Metrics

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/internal-utilities.md

Calculates quality metrics for each meta-program, including sample coverage, silhouette width, mean similarity, number of genes, and number of programs. Requires similarity or distance matrices, consensus gene lists, and cluster assignments.

```r
get_metaprogram_metrics(J = NULL, Jdist = NULL, markers.consensus = NULL,
                        cl_members = NULL)
```

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

### Rigorous Discovery Preset for Meta-Programs

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/configuration.md

Use this preset for a conservative meta-program discovery, focusing on highly specific and confident genes.

```r
getMetaPrograms(nmf.res, nMP=15, specificity.weight=10,
                weight.explained=0.8, min.confidence=0.8)
```

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

### Multi-Sample NMF Analysis

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Run NMF across multiple samples and identify consensus meta-programs. This workflow involves running NMF for a range of k values, extracting genes, and then identifying meta-programs.

```r
# Input: list of Seurat objects
samples <- list(sample1, sample2, sample3)

# Run NMF for multiple k values
nmf_programs <- multiNMF(samples, k = 5:9)

# Extract genes from individual programs
program_genes <- getNMFgenes(nmf_programs)

# Identify meta-programs (consensus)
meta_programs <- getMetaPrograms(nmf_programs, nMP = 10)

# Visualize meta-program relationships
plotMetaPrograms(meta_programs)
```

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

### Default Parameters for multiNMF

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Shows the default values for the multiNMF function. Use this to understand the default behavior or to set custom parameters.

```r
multiNMF(
  k = 5:6,
  nfeatures = 2000,
  L1 = c(0, 0),
  loss = "mse",
  min.exp = 0.01,
  max.exp = 3.0,
  center = FALSE,
  scale = FALSE,
  min.cells.per.sample = 10,
  seed = 123
)
```

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

### Customized Meta-Program Heatmap

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Customizes the meta-program heatmap with a title, color palette, and scaling. Requires 'meta_programs' object and 'viridis' package.

```r
plotMetaPrograms(meta_programs,
                main = "Gene Program Similarities",
                palette = viridis::plasma(100),
                scale = "row")
```

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

### Check RcppML Package Version

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Shows how to check the version of the RcppML package, which is relevant for loss function support.

```r
packageVersion("RcppML")
```

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

### Access and Visualize NMF Reduction

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/runNMF.md

Demonstrates how to access the computed NMF cell embeddings and use them for downstream analyses like clustering and visualization with UMAP. Requires the NMF reduction to be computed first.

```r
# Access the NMF reduction
head(sampleObj@reductions$NMF@cell.embeddings)

# Use for downstream analysis (e.g., clustering)
sampleObj <- FindNeighbors(sampleObj, reduction = "NMF", dims = 1:8)
sampleObj <- FindClusters(sampleObj, resolution = 0.5)

# Visualize NMF components with custom parameters
sampleObj <- RunUMAP(sampleObj, reduction = "NMF", dims = 1:8)
DimPlot(sampleObj, reduction = "umap")
```

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

### dropMetaPrograms

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/package-overview.md

Filters meta-programs. It takes meta-programs as input and returns filtered meta-programs.

```APIDOC
## dropMetaPrograms

### Description
Filter meta-programs.

### Input
meta-programs

### Output
meta-programs
```

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

### GenNMF Project File Organization

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/README.md

This snippet outlines the directory structure of the GenNMF project, showing the location of markdown documentation files and API reference files.

```text
output/
├── README.md (this file)
├── quick-reference.md
├── package-overview.md
├── types.md
├── configuration.md
├── errors-and-edge-cases.md
├── internal-utilities.md
└── api-reference/
    ├── multiNMF.md
    ├── getNMFgenes.md
    ├── getMetaPrograms.md
    ├── plotMetaPrograms.md
    ├── runNMF.md
    ├── getDataMatrix.md
    ├── findVariableFeatures_wfilters.md
    ├── runGSEA.md
    └── dropMetaPrograms.md
```

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

### Remove Single Meta-Program

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/dropMetaPrograms.md

Shows how to remove a single meta-program (e.g., 'MP3') from a meta-program object. This is useful for cleaning up results by removing individual programs with poor scores.

```r
# Remove single meta-program with poor silhouette score
mp_cleaned <- dropMetaPrograms(mp, dropMP = "MP3")
```

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

### Load Data and Run NMF

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/getNMFgenes.md

Loads sample data and performs Non-negative Matrix Factorization (NMF) to generate gene programs. This is a prerequisite for using getNMFgenes.

```r
library(Seurat)
library(GeneNMF)

# Load sample data and run NMF
data(sampleObj)
geneNMF_programs <- multiNMF(list(sampleObj), k = 5)
```

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

### Inspect Matrix Properties

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/api-reference/getDataMatrix.md

Demonstrates how to inspect the dimensions and sparsity of the extracted gene expression matrix. Useful for verifying the output of getDataMatrix.

```r
# Inspect matrix properties
nrow(expr_hvg)     # Number of genes
col(expr_hvg)     # Number of cells
sum(expr_hvg == 0) # Number of zero entries
```

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

### Standard GeneNMF Analysis Workflow

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/package-overview.md

A comprehensive workflow for GeneNMF analysis, including sample preparation, NMF runs for multiple k values, gene extraction, meta-program identification, visualization, and filtering.

```r
# 1. Prepare samples
samples <- list(sample1, sample2, sample3)

# 2. Run NMF for multiple k values
programs <- multiNMF(samples, k = 5:9, nfeatures = 2000)

# 3. Extract genes from programs
genes <- getNMFgenes(programs, weight.explained = 0.5)

# 4. Identify meta-programs
mp <- getMetaPrograms(programs, nMP = 10)

# 5. Visualize
plotMetaPrograms(mp)

# 6. Filter and validate
mp_filtered <- dropMetaPrograms(mp, dropMP = c("MP8", "MP9"))
```

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

### Default Parameters for findVariableFeatures_wfilters

Source: https://github.com/carmonalab/genenmf/blob/master/_autodocs/quick-reference.md

Shows the default settings for findVariableFeatures_wfilters, used for identifying variable features with specific expression thresholds.

```r
findVariableFeatures_wfilters(
  nfeatures = 2000,
  min.exp = 0.01,
  max.exp = 3
)
```