### Run diffcyt Analysis Pipeline

Source: https://context7.com/lmweber/diffcyt/llms.txt

Demonstrates the complete diffcyt workflow, including data simulation, experiment design setup, and execution of both differential abundance (DA) and differential state (DS) analyses.

```r
library(diffcyt)
d_random <- function(n = 20000, mean = 0, sd = 1, ncol = 20, cofactor = 5) {
  d <- sinh(matrix(rnorm(n, mean, sd), ncol = ncol)) * cofactor
  colnames(d) <- paste0("marker", sprintf("%02d", 1:ncol))
  d
}
set.seed(123)
d_input <- list(sample1 = d_random(), sample2 = d_random(), sample3 = d_random(), sample4 = d_random())
experiment_info <- data.frame(sample_id = factor(paste0("sample", 1:4)), group_id = factor(c("group1", "group1", "group2", "group2")), stringsAsFactors = FALSE)
marker_info <- data.frame(channel_name = paste0("channel", sprintf("%03d", 1:20)), marker_name = paste0("marker", sprintf("%02d", 1:20)), marker_class = factor(c(rep("type", 10), rep("state", 10)), levels = c("type", "state", "none")), stringsAsFactors = FALSE)
design <- createDesignMatrix(experiment_info, cols_design = "group_id")
contrast <- createContrast(c(0, 1))
out_DA <- diffcyt(d_input, experiment_info, marker_info, design = design, contrast = contrast, analysis_type = "DA", method_DA = "diffcyt-DA-edgeR", seed_clustering = 123, verbose = FALSE)
out_DS <- diffcyt(d_input, experiment_info, marker_info, design = design, contrast = contrast, analysis_type = "DS", method_DS = "diffcyt-DS-limma", seed_clustering = 123, verbose = FALSE)
topTable(out_DA, format_vals = TRUE)
topTable(out_DS, format_vals = TRUE)
```

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

### Install diffcyt R Package

Source: https://github.com/lmweber/diffcyt/blob/devel/README.md

Installs the diffcyt R package and its dependencies from Bioconductor. Requires the BiocManager package to be installed first.

```R
install.packages("BiocManager")
BiocManager::install("diffcyt")
```

```R
BiocManager::install(c("HDCytoData", "CATALYST"))
```

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

### Prepare Cytometry Data with prepareData

Source: https://context7.com/lmweber/diffcyt/llms.txt

Shows how to convert raw cytometry input into a SummarizedExperiment object. Includes options for subsampling cells and selecting specific markers for the analysis pipeline.

```r
d_se <- prepareData(d_input, experiment_info, marker_info)
d_se_subsampled <- prepareData(d_input, experiment_info, marker_info, subsampling = TRUE, n_sub = 10000, seed_sub = 123)
cols_to_include <- c(rep(TRUE, 18), FALSE, FALSE)
d_se_subset <- prepareData(d_input, experiment_info, marker_info, cols_to_include = cols_to_include)
library(SummarizedExperiment)
head(assays(d_se)[["exprs"]])
head(rowData(d_se))
colData(d_se)
metadata(d_se)$n_cells
```

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

### Running Differential State (DS) Tests with diffcyt

Source: https://context7.com/lmweber/diffcyt/llms.txt

Demonstrates how to run differential state (DS) tests using the testDS_limma function. This includes options for excluding precision weights, testing specific markers, and enabling diagnostic plots.

```r
results <- rowData(res_DS)
head(results[order(results$p_adj), ])

# Without precision weights
res_DS_noweights <- testDS_limma(
  d_counts, d_medians, design, contrast,
  weights = FALSE
)

# Test specific markers only
markers_to_test <- c(rep(FALSE, 10), rep(TRUE, 5), rep(FALSE, 5))  # markers 11-15 only
res_DS_subset <- testDS_limma(
  d_counts, d_medians, design, contrast,
  markers_to_test = markers_to_test
)

# With diagnostic plot
res_DS <- testDS_limma(
  d_counts, d_medians, design, contrast,
  plot = TRUE,
  path = "."
)
```

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

### Create Contrast Matrix

Source: https://context7.com/lmweber/diffcyt/llms.txt

The createContrast function defines a numeric vector representing a linear combination of parameters for hypothesis testing. It allows users to specify which coefficients in the design matrix should be compared.

```r
contrast <- createContrast(c(0, 1))
print(contrast)

contrast_complex <- createContrast(c(0, 1, 0, 0, 0, 0))
print(contrast_complex)
```

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

### createDesignMatrix - Create Design Matrix

Source: https://context7.com/lmweber/diffcyt/llms.txt

Creates a design matrix for model fitting supporting complex experimental designs.

```APIDOC
## createDesignMatrix

### Description
Creates a design matrix for model fitting, supporting factors, blocking, and continuous covariates.

### Method
Function Call

### Parameters
#### Arguments
- **experiment_info** (data.frame) - Required - Metadata containing sample information.
- **cols_design** (character) - Required - Column names to include in the design matrix.

### Request Example
design <- createDesignMatrix(experiment_info, cols_design = c("group_id", "age"))

### Response
- **design** (matrix) - The generated design matrix.
```

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

### Displaying Top Results with topTable

Source: https://context7.com/lmweber/diffcyt/llms.txt

Illustrates how to use the topTable function to display summarized results from differential abundance (DA) or differential states (DS) tests. Options include controlling the number of results, ordering, and including additional statistical information.

```r
# Display top 20 results (default)
topTable(out_DA, format_vals = TRUE)
topTable(out_DS, format_vals = TRUE)

# Show all results
topTable(out_DA, all = TRUE)

# Custom number of top results
topTable(out_DA, top_n = 50)

# Order by different column
topTable(out_DA, order_by = "p_val")
topTable(out_DS, order_by = "cluster_id")

# Include additional information
topTable(out_DA,
         show_counts = TRUE,    # cell counts per sample
         show_props = TRUE,     # proportions per sample
         format_vals = TRUE,
         digits = 3)

# For DS tests, include median expression
topTable(out_DS,
         show_meds = TRUE,      # median expression by sample
         show_logFC = TRUE,     # log fold change
         format_vals = TRUE)

# Show all columns from statistical test
topTable(out_DA, show_all_cols = TRUE)
```

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

### Visualizing Results with plotHeatmap

Source: https://context7.com/lmweber/diffcyt/llms.txt

Shows how to generate heatmaps for visualizing differential testing results using plotHeatmap. This function can be used for both DA and DS tests, with options for customization such as the number of top features, significance thresholds, and sample ordering.

```r
# Plot heatmap for DA test results
plotHeatmap(out_DA, analysis_type = "DA")

# Plot heatmap for DS test results
plotHeatmap(out_DS, analysis_type = "DS")

# Customize number of top clusters/combinations shown
plotHeatmap(out_DA, analysis_type = "DA", top_n = 30)

# Adjust significance threshold for highlighting
plotHeatmap(out_DA, analysis_type = "DA", threshold = 0.05)

# Custom sample ordering
sample_order <- c("sample1", "sample3", "sample2", "sample4")
plotHeatmap(out_DA, analysis_type = "DA", sample_order = sample_order)

# Provide individual objects instead of wrapper output
plotHeatmap(
  res = out_DA$res,
  d_se = out_DA$d_se,
  d_counts = out_DA$d_counts,
  analysis_type = "DA"
)
```

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

### calcCounts - Calculate Cluster Cell Counts

Source: https://context7.com/lmweber/diffcyt/llms.txt

Calculates the number of cells per cluster-sample combination.

```APIDOC
## calcCounts

### Description
Calculates the number of cells per cluster-sample combination for differential abundance testing.

### Method
Function Call

### Parameters
#### Arguments
- **d_se** (SummarizedExperiment) - Required - The clustered data object.

### Request Example
d_counts <- calcCounts(d_se)

### Response
- **d_counts** (SummarizedExperiment) - Object containing the count matrix in assays.
```

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

### generateClusters - FlowSOM Clustering

Source: https://context7.com/lmweber/diffcyt/llms.txt

Performs high-resolution clustering using the FlowSOM algorithm.

```APIDOC
## generateClusters

### Description
Performs high-resolution clustering using the FlowSOM algorithm to identify cell populations.

### Method
Function Call

### Parameters
#### Arguments
- **d_se** (SummarizedExperiment) - Required - The input data object.
- **xdim** (numeric) - Optional - Grid width (default 10).
- **ydim** (numeric) - Optional - Grid height (default 10).
- **meta_clustering** (logical) - Optional - Whether to perform meta-clustering.
- **meta_k** (numeric) - Optional - Number of meta-clusters.
- **seed_clustering** (numeric) - Optional - Random seed for reproducibility.

### Request Example
d_se <- generateClusters(d_se, xdim = 10, ydim = 10, meta_clustering = TRUE, meta_k = 40, seed_clustering = 123)

### Response
- **d_se** (SummarizedExperiment) - The data object updated with cluster IDs.
```

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

### Create Experimental Design Matrix with createDesignMatrix

Source: https://context7.com/lmweber/diffcyt/llms.txt

The createDesignMatrix function builds a design matrix for statistical modeling. It handles simple group comparisons, paired designs, batch effects, and continuous covariates.

```r
# Simple two-group comparison
experiment_info <- data.frame(
  sample_id = factor(paste0("sample", 1:4)),
  group_id = factor(c("group1", "group1", "group2", "group2")),
  stringsAsFactors = FALSE
)
design <- createDesignMatrix(experiment_info, cols_design = "group_id")
print(design)

# Paired design with patient IDs and batch effects
experiment_info_complex <- data.frame(
  sample_id = factor(paste0("sample", 1:8)),
  group_id = factor(rep(paste0("group", 1:2), each = 4)),
  patient_id = factor(rep(paste0("patient", 1:4), 2)),
  batch_id = factor(rep(paste0("batch", 1:2), 4)),
  stringsAsFactors = FALSE
)
design_complex <- createDesignMatrix(
  experiment_info_complex,
  cols_design = c("group_id", "patient_id", "batch_id")
)
print(design_complex)

# Design with continuous covariate
experiment_info_cov <- data.frame(
  sample_id = factor(paste0("sample", 1:4)),
  group_id = factor(c("group1", "group1", "group2", "group2")),
  age = c(52, 35, 71, 60),
  stringsAsFactors = FALSE
)
design_cov <- createDesignMatrix(experiment_info_cov, cols_design = c("group_id", "age"))
print(design_cov)
```

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

### topTable - Display Top Results

Source: https://context7.com/lmweber/diffcyt/llms.txt

The topTable() function displays a summary table of the most significant clusters (DA tests) or cluster-marker combinations (DS tests). It can optionally show counts, proportions, and median expression values.

```APIDOC
## topTable - Display Top Results

### Description
Displays a summary table of the most significant results from differential abundance (DA) or differential state (DS) tests. Can optionally include cell counts, proportions, and median expression values.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Function Arguments
- **object** (DA or DS results object) - Required - The output object from a DA or DS test.
- **format_vals** (logical) - Optional - Whether to format numerical values (e.g., p-values).
- **all** (logical) - Optional - Whether to show all results or only the top ones (default).
- **top_n** (numeric) - Optional - The number of top results to display when `all` is FALSE.
- **order_by** (character) - Optional - The column name to order the results by (e.g., "p_val", "cluster_id").
- **show_counts** (logical) - Optional - Whether to include cell counts per sample.
- **show_props** (logical) - Optional - Whether to include cell proportions per sample.
- **show_meds** (logical) - Optional - Whether to include median expression values per sample (for DS tests).
- **show_logFC** (logical) - Optional - Whether to include log fold change values (for DS tests).
- **show_all_cols** (logical) - Optional - Whether to show all columns from the statistical test results.
- **digits** (numeric) - Optional - The number of digits to use for formatting numerical values.

### Request Example
```r
# Display top 20 results (default)
topTable(out_DA, format_vals = TRUE)
topTable(out_DS, format_vals = TRUE)

# Show all results
topTable(out_DA, all = TRUE)

# Custom number of top results
topTable(out_DA, top_n = 50)

# Order by different column
topTable(out_DA, order_by = "p_val")
topTable(out_DS, order_by = "cluster_id")

# Include additional information
topTable(out_DA,
         show_counts = TRUE,    # cell counts per sample
         show_props = TRUE,     # proportions per sample
         format_vals = TRUE,
         digits = 3)

# For DS tests, include median expression
topTable(out_DS,
         show_meds = TRUE,      # median expression by sample
         show_logFC = TRUE,     # log fold change
         format_vals = TRUE)

# Show all columns from statistical test
topTable(out_DA, show_all_cols = TRUE)
```

### Response
#### Success Response (200)
A data frame containing the top differential testing results, potentially including counts, proportions, and median expression values, formatted as specified.
```

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

### calcMedians - Calculate Cluster Medians

Source: https://context7.com/lmweber/diffcyt/llms.txt

Calculates median marker expression for each cluster-sample combination.

```APIDOC
## calcMedians

### Description
Calculates median marker expression for each cluster-sample combination for differential state testing.

### Method
Function Call

### Parameters
#### Arguments
- **d_se** (SummarizedExperiment) - Required - The clustered data object.

### Request Example
d_medians <- calcMedians(d_se)

### Response
- **d_medians** (SummarizedExperiment) - Object containing median values per marker in assays.
```

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

### transformData - Apply Arcsinh Transformation

Source: https://context7.com/lmweber/diffcyt/llms.txt

Applies an inverse hyperbolic sine (arcsinh) transformation to normalize data distribution.

```APIDOC
## transformData

### Description
Applies an inverse hyperbolic sine (arcsinh) transformation to normalize the data distribution. The cofactor parameter controls the linear region width.

### Method
Function Call

### Parameters
#### Arguments
- **d_se** (SummarizedExperiment) - Required - The input data object.
- **cofactor** (numeric) - Optional - The cofactor for transformation (default 5 for CyTOF, 150 for fluorescence flow cytometry).

### Request Example
# Transform with default cofactor
d_se <- transformData(d_se, cofactor = 5)

### Response
- **d_se** (SummarizedExperiment) - The transformed data object.
```

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

### plotHeatmap - Visualize Results

Source: https://context7.com/lmweber/diffcyt/llms.txt

The plotHeatmap() function creates heatmaps to visualize differential testing results. For DA tests, it shows cell type marker expression and cluster abundances. For DS tests, it shows expression of significant cluster-marker combinations.

```APIDOC
## plotHeatmap - Visualize Results

### Description
Generates heatmaps to visualize differential testing results. For DA tests, it displays cell type marker expression and cluster abundances. For DS tests, it visualizes the expression of significant cluster-marker combinations.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Function Arguments
- **object** (DA or DS results object or list of components) - Required - The output object from a DA or DS test, or a list containing `res`, `d_se`, and `d_counts`.
- **analysis_type** (character) - Required - The type of analysis, either "DA" or "DS".
- **top_n** (numeric) - Optional - The number of top clusters (for DA) or cluster-marker combinations (for DS) to display in the heatmap.
- **threshold** (numeric) - Optional - The significance threshold for highlighting results in the heatmap.
- **sample_order** (character vector) - Optional - A custom order for the samples in the heatmap.
- **res** (data frame) - Optional - The results data frame (used when providing individual components instead of the wrapper object).
- **d_se** (SummarizedExperiment) - Optional - The SummarizedExperiment object (used when providing individual components).
- **d_counts** (matrix or data frame) - Optional - The count data (used when providing individual components).

### Request Example
```r
# Plot heatmap for DA test results
plotHeatmap(out_DA, analysis_type = "DA")

# Plot heatmap for DS test results
plotHeatmap(out_DS, analysis_type = "DS")

# Customize number of top clusters/combinations shown
plotHeatmap(out_DA, analysis_type = "DA", top_n = 30)

# Adjust significance threshold for highlighting
plotHeatmap(out_DA, analysis_type = "DA", threshold = 0.05)

# Custom sample ordering
sample_order <- c("sample1", "sample3", "sample2", "sample4")
plotHeatmap(out_DA, analysis_type = "DA", sample_order = sample_order)

# Provide individual objects instead of wrapper output
plotHeatmap(
  res = out_DA$res,
  d_se = out_DA$d_se,
  d_counts = out_DA$d_counts,
  analysis_type = "DA"
)
```

### Response
#### Success Response (200)
A heatmap visualization of the differential testing results.
```

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

### Differential Abundance Testing with limma-voom

Source: https://context7.com/lmweber/diffcyt/llms.txt

The testDA_voom function applies the voom transformation to stabilize mean-variance relationships for differential abundance testing. It supports random effects for paired designs via the block_id parameter.

```r
res_DA_voom <- testDA_voom(d_counts, design, contrast)

res_DA_paired <- testDA_voom(
  d_counts, design_paired, contrast,
  block_id = experiment_info_paired$patient_id
)
```

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

### Perform FlowSOM Clustering with generateClusters

Source: https://context7.com/lmweber/diffcyt/llms.txt

The generateClusters function executes high-resolution clustering using the FlowSOM algorithm. It supports custom grid dimensions, meta-clustering, and specific marker selection to isolate rare cell populations.

```r
# Prepare and transform data
d_se <- prepareData(d_input, experiment_info, marker_info)
d_se <- transformData(d_se)

# Generate clusters with default settings (100 clusters)
d_se <- generateClusters(d_se, seed_clustering = 123)

# Custom grid size (400 clusters)
d_se <- generateClusters(d_se, xdim = 20, ydim = 20, seed_clustering = 123)

# With meta-clustering to reduce cluster number
d_se <- generateClusters(
  d_se,
  xdim = 10, ydim = 10,
  meta_clustering = TRUE,
  meta_k = 40,           # number of meta-clusters
  seed_clustering = 123
)

# Specify custom columns for clustering
cols_clustering <- c(TRUE, TRUE, TRUE, TRUE, TRUE,
                     FALSE, FALSE, FALSE, FALSE, FALSE,
                     rep(FALSE, 10))  # only first 5 markers
d_se <- generateClusters(d_se, cols_clustering = cols_clustering, seed_clustering = 123)

# Access cluster labels
table(rowData(d_se)$cluster_id)

# Access MST object for visualization
mst <- metadata(d_se)$MST
```

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

### Create Model Formula with Random Effects

Source: https://context7.com/lmweber/diffcyt/llms.txt

The createFormula function generates a model formula incorporating fixed and random effects. It is primarily used for mixed-model methods like testDA_GLMM and testDS_LMM to account for paired designs or overdispersion.

```r
experiment_info <- data.frame(
  sample_id = factor(paste0("sample", 1:8)),
  group_id = factor(rep(paste0("group", 1:2), each = 4)),
  patient_id = factor(rep(paste0("patient", 1:4), 2)),
  stringsAsFactors = FALSE
)

formula_obj <- createFormula(
  experiment_info,
  cols_fixed = "group_id",
  cols_random = c("sample_id", "patient_id")
)

print(formula_obj$formula)
print(formula_obj$data)
print(formula_obj$random_terms)
```

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

### Differential Abundance Testing with edgeR

Source: https://context7.com/lmweber/diffcyt/llms.txt

The testDA_edgeR function performs differential abundance analysis using moderated tests from edgeR. It supports automatic library size normalization and optional TMM normalization for composition effects.

```r
d_se <- prepareData(d_input, experiment_info, marker_info)
d_se <- transformData(d_se)
d_se <- generateClusters(d_se, seed_clustering = 123)
d_counts <- calcCounts(d_se)

design <- createDesignMatrix(experiment_info, cols_design = "group_id")
contrast <- createContrast(c(0, 1))

res_DA <- testDA_edgeR(d_counts, design, contrast)

res_DA_norm <- testDA_edgeR(
  d_counts, design, contrast,
  normalize = TRUE,
  norm_factors = "TMM"
)
```

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

### Calculate Cluster Cell Counts with calcCounts

Source: https://context7.com/lmweber/diffcyt/llms.txt

The calcCounts function computes cell counts per cluster-sample combination. These counts are essential for downstream differential abundance and differential state testing.

```r
# Full pipeline to calculate counts
d_se <- prepareData(d_input, experiment_info, marker_info)
d_se <- transformData(d_se)
d_se <- generateClusters(d_se, seed_clustering = 123)
d_counts <- calcCounts(d_se)

# Access the count matrix (clusters x samples)
counts_matrix <- assays(d_counts)[["counts"]]
head(counts_matrix)

# Row metadata contains cluster IDs and total cell counts
rowData(d_counts)

# Column metadata contains experiment info
colData(d_counts)
```

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

### Differential State Testing with limma

Source: https://context7.com/lmweber/diffcyt/llms.txt

The testDS_limma function tests for differential marker expression within cell populations. It utilizes cluster-marker medians and cell counts as precision weights to perform limma-trend testing.

```r
d_medians <- calcMedians(d_se)
res_DS <- testDS_limma(d_counts, d_medians, design, contrast)
```

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

### Apply Arcsinh Transformation with transformData

Source: https://context7.com/lmweber/diffcyt/llms.txt

The transformData function normalizes data distribution using an inverse hyperbolic sine transformation. It accepts a cofactor parameter to adjust for different cytometry types, such as CyTOF or fluorescence flow cytometry.

```r
# Prepare and transform data
d_se <- prepareData(d_input, experiment_info, marker_info)

# Transform with default cofactor (5, for CyTOF)
d_se <- transformData(d_se, cofactor = 5)

# For fluorescence flow cytometry data, use cofactor = 150
# d_se <- transformData(d_se, cofactor = 150)

# The transformation is: arcsinh(x / cofactor)
# Applied only to marker columns (not columns with marker_class = "none")
```

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

### Calculate Cluster Medians with calcMedians

Source: https://context7.com/lmweber/diffcyt/llms.txt

The calcMedians function calculates median marker expression for each cluster-sample combination. This is used for differential state testing within specific cell populations.

```r
# Full pipeline to calculate medians
d_se <- prepareData(d_input, experiment_info, marker_info)
d_se <- transformData(d_se)
d_se <- generateClusters(d_se, seed_clustering = 123)
d_medians <- calcMedians(d_se)

# Access medians for a specific marker (clusters x samples)
marker01_medians <- assays(d_medians)[["marker01"]]
head(marker01_medians)

# Identify cell type and cell state markers
metadata(d_medians)$id_type_markers   # logical vector for type markers
metadata(d_medians)$id_state_markers  # logical vector for state markers

# Get names of all markers
names(assays(d_medians))
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.