### Install FlowSOM R Package from GitHub

Source: https://github.com/sofievg/flowsom/blob/master/README.md

Installs the FlowSOM R package directly from its GitHub repository using the devtools library. This method ensures you get the latest development version and can optionally build package vignettes for more detailed documentation.

```R
devtools::install_github("saeyslab/FlowSOM", build_vignettes = TRUE)
```

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

### Build Minimal Spanning Tree (MST) with FlowSOM

Source: https://context7.com/sofievg/flowsom/llms.txt

Constructs a minimal spanning tree connecting SOM nodes to visualize cluster relationships. Requires a FlowSOM object and outputs an updated object with MST information. Dependencies include the FlowSOM package.

```r
library(FlowSOM)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
fsom <- ReadInput(fileName, compensate = TRUE, transform = TRUE, scale = TRUE)
fsom <- BuildSOM(fsom, colsToUse = c(9, 12, 14:18))

# Build the minimal spanning tree
fsom <- BuildMST(fsom, silent = FALSE)

# Access MST results
str(fsom$MST, max.level = 1)
# $ graph: igraph object
# $ l    : num [1:49, 1:2] ...  # Node coordinates for plotting

# The MST enables tree-based visualizations
PlotStars(fsom)
```

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

### PlotPies: Create Pie Chart Visualizations (R)

Source: https://context7.com/sofievg/flowsom/llms.txt

Displays nodes as pie charts illustrating the distribution of cell labels within each cluster. Requires cell type labels and optionally accepts a custom color palette.

```r
library(FlowSOM)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
gatingFile <- system.file("extdata", "gatingResult.csv", package = "FlowSOM")

flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Load manual labels
gatingResult <- as.factor(read.csv(gatingFile, header = FALSE)[, 1])

# Plot pies showing manual gating distribution per cluster
PlotPies(flowSOM.res,
         cellTypes = gatingResult,
         backgroundValues = flowSOM.res$metaclustering)

# Custom color palette
PlotPies(flowSOM.res,
         cellTypes = gatingResult,
         colorPalette = FlowSOM_colors)
```

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

### GetChannels and GetMarkers

Source: https://context7.com/sofievg/flowsom/llms.txt

Utility functions for marker and channel name mapping.

```APIDOC
## GetChannels / GetMarkers

### Description
Utility functions to convert between channel names and marker descriptions.

### Method
Function Call

### Parameters
- **object** (flowFrame/FlowSOM) - Required - The input data object.
- **names** (character) - Required - Vector of names to convert.

### Response
Returns a named vector of converted names.
```

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

### PlotStars: Create Star Chart Visualizations (R)

Source: https://context7.com/sofievg/flowsom/llms.txt

Generates star chart visualizations where each node represents median marker expression as radial bars. Supports background coloring for metaclusters, grid views, and custom marker selection. Can return a list for further customization.

```r
library(FlowSOM)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Basic star plot with metacluster backgrounds
PlotStars(flowSOM.res,
          backgroundValues = flowSOM.res$metaclustering)

# Grid view
PlotStars(flowSOM.res,
          view = "grid",
          backgroundValues = flowSOM.res$metaclustering)

# Custom markers and equal node sizes
PlotStars(flowSOM.res,
          markers = c("CD3", "CD4", "CD8", "CD19"),
          equalNodeSize = TRUE,
          backgroundValues = flowSOM.res$metaclustering)

# Return list for further customization
plot_list <- PlotStars(flowSOM.res,
                       backgroundValues = flowSOM.res$metaclustering,
                       list_insteadof_ggarrange = TRUE)
# plot_list$tree, plot_list$starLegend, plot_list$backgroundLegend
```

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

### Read FlowJo Gating Results with GetFlowJoLabels

Source: https://context7.com/sofievg/flowsom/llms.txt

Reads manual gating results from FlowJo workspace files (.wsp) for comparison with FlowSOM clustering. It takes FCS files, a FlowJo workspace file, a group name, and cell types of interest as input, returning a list containing gating matrices and manual labels.

```r
library(FlowSOM)

fcsFile <- system.file("extdata", "68983.fcs", package = "FlowSOM")
wspFile <- system.file("extdata", "gating.wsp", package = "FlowSOM")

# Define cell types of interest
cellTypes <- c("B cells", "gd T cells", "CD4 T cells",
               "CD8 T cells", "NK cells", "NK T cells")

# Parse FlowJo workspace
gatingResult <- GetFlowJoLabels(
  files = fcsFile,
  wspFile = wspFile,
  group = "All Samples",
  cellTypes = cellTypes,
  getData = TRUE
)

# Results
colSums(gatingResult$matrix)  # Cells per gate
table(gatingResult$manual)    # Manual labels

# Use in FlowSOM visualization
flowSOM.res <- FlowSOM(gatingResult$flowFrame,
                       colsToUse = c(9, 12, 14:18), nClus = 10)

PlotPies(flowSOM.res,
         gatingResult$manual,
         backgroundValues = flowSOM.res$metaclustering)
```

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

### BuildSOM() - SOM Construction

Source: https://context7.com/sofievg/flowsom/llms.txt

Constructs the self-organizing map on preprocessed data to cluster cells into nodes.

```APIDOC
## BuildSOM()

### Description
Trains a self-organizing map on the provided FlowSOM object using selected marker columns.

### Method
Function Call

### Parameters
#### Request Body
- **fsom** (FlowSOM object) - Required - The object returned by ReadInput.
- **colsToUse** (vector) - Required - Markers for clustering.
- **xdim/ydim** (integer) - Optional - Grid dimensions.
- **rlen** (integer) - Optional - Training iterations.

### Response
#### Success Response (200)
- **FlowSOM object** (object) - Updated object with map information (codes, grid dimensions).
```

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

### Generate Comprehensive Reports with FlowSOMmary

Source: https://context7.com/sofievg/flowsom/llms.txt

Automates the generation of a PDF report containing various visualizations such as trees, grids, marker plots, and heatmaps. It can also return a list of ggplot objects if no file path is provided.

```R
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
FlowSOMmary(fsom = flowSOM.res, plotFile = "FlowSOMmary.pdf")
plot_list <- FlowSOMmary(fsom = flowSOM.res, plotFile = NULL)
```

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

### FlowSOM() - Main Workflow

Source: https://context7.com/sofievg/flowsom/llms.txt

The primary wrapper function that executes the complete FlowSOM pipeline including data loading, preprocessing, SOM training, and metaclustering in a single call.

```APIDOC
## FlowSOM()

### Description
Executes the full FlowSOM workflow: reading, compensating, transforming, scaling, SOM building, and metaclustering.

### Method
Function Call

### Parameters
#### Request Body
- **input** (string/flowFrame) - Required - Path to FCS file or flowFrame object.
- **compensate** (boolean) - Optional - Apply spillover compensation.
- **transform** (boolean) - Optional - Apply logicle transformation.
- **scale** (boolean) - Optional - Scale data to mean=0, sd=1.
- **colsToUse** (vector) - Required - Column indices for clustering.
- **xdim/ydim** (integer) - Optional - Dimensions of the SOM grid.
- **nClus** (integer) - Optional - Number of metaclusters to identify.

### Request Example
FlowSOM(input = "data.fcs", compensate = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

### Response
#### Success Response (200)
- **FlowSOM object** (object) - Returns a trained FlowSOM object containing map, data, and metadata.
```

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

### Load and Preprocess Cytometry Data

Source: https://context7.com/sofievg/flowsom/llms.txt

The ReadInput() function prepares cytometry data for FlowSOM analysis. It supports input from FCS files, flowFrames, or matrices, and applies necessary compensation, transformation, and scaling steps.

```r
library(FlowSOM)
library(flowCore)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
fsom <- ReadInput(
  input = fileName,
  compensate = TRUE,
  transform = TRUE,
  toTransform = c(8:18),
  transformFunction = logicleTransform(),
  scale = TRUE
)
```

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

### Map Channels and Markers with GetChannels and GetMarkers

Source: https://context7.com/sofievg/flowsom/llms.txt

Utility functions to convert between flow cytometry channel names and marker descriptions, ensuring consistent data referencing.

```R
library(FlowSOM)
library(flowCore)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
ff <- read.FCS(fileName)
channels <- GetChannels(ff, c("CD3", "CD4", "CD8"))
markers <- GetMarkers(ff, c("PE-Cy7-A", "APC-A", "Pacific Blue-A"))
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
GetChannels(flowSOM.res, "CD19")
```

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

### PlotMarker: Overlay Marker Expression on SOM (R)

Source: https://context7.com/sofievg/flowsom/llms.txt

Colors nodes based on the median expression values of specified markers. Supports plotting single or multiple markers (faceted view), custom color palettes, and value limits. Can be combined with background highlighting.

```r
library(FlowSOM)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = FALSE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Plot single marker
PlotMarker(flowSOM.res, marker = "CD19")

# Plot multiple markers in faceted view
PlotMarker(flowSOM.res, marker = c(9, 12, 14:18))

# Custom color palette and limits
PlotMarker(flowSOM.res,
           marker = "FSC-A",
           lim = c(55000, 130000),
           colorPalette = c("blue", "white", "red"))

# With background highlighting
PlotMarker(flowSOM.res,
           marker = "CD19",
           view = "grid",
           equalNodeSize = TRUE,
           backgroundValues = flowSOM.res$metaclustering)
```

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

### Construct Self-Organizing Map

Source: https://context7.com/sofievg/flowsom/llms.txt

The BuildSOM() function performs the clustering of cells into nodes on a two-dimensional grid. It requires a preprocessed FlowSOM object and allows customization of grid dimensions, learning rates, and distance metrics.

```r
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
fsom <- ReadInput(fileName, compensate = TRUE, transform = TRUE, scale = TRUE)
fsom <- BuildSOM(
  fsom,
  colsToUse = c(9, 12, 14:18),
  xdim = 7,
  ydim = 7,
  rlen = 10,
  distf = 2
)
```

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

### PlotStars - Star Chart Visualization

Source: https://context7.com/sofievg/flowsom/llms.txt

Creates star chart visualizations where each node displays median marker expression as radial bars. Supports background coloring for metaclusters and custom marker selection.

```APIDOC
## PlotStars - Star Chart Visualization

### Description
Creates star chart visualizations where each node displays median marker expression as radial bars, with optional background coloring for metaclusters.

### Method
`PlotStars(object, ...)`

### Parameters
- **object** (FlowSOM object) - The result of a FlowSOM analysis.
- **markers** (character vector, optional) - Specific markers to display in the star plots. Defaults to all markers used in the FlowSOM analysis.
- **backgroundValues** (numeric vector, optional) - Values to use for background coloring of metaclusters.
- **view** (character, optional) - Layout for the plots. Options include 'default' or 'grid'.
- **equalNodeSize** (logical, optional) - If TRUE, all nodes will have the same size.
- **list_insteadof_ggarrange** (logical, optional) - If TRUE, returns a list of ggplot objects instead of arranging them with ggarrange.

### Request Example
```r
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Basic star plot with metacluster backgrounds
PlotStars(flowSOM.res,
          backgroundValues = flowSOM.res$metaclustering)

# Grid view
PlotStars(flowSOM.res,
          view = "grid",
          backgroundValues = flowSOM.res$metaclustering)

# Custom markers and equal node sizes
PlotStars(flowSOM.res,
          markers = c("CD3", "CD4", "CD8", "CD19"),
          equalNodeSize = TRUE,
          backgroundValues = flowSOM.res$metaclustering)

# Return list for further customization
plot_list <- PlotStars(flowSOM.res,
                       backgroundValues = flowSOM.res$metaclustering,
                       list_insteadof_ggarrange = TRUE)
```

### Response
Returns a ggplot object or a list of ggplot objects representing the star chart visualization.
```

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

### ReadInput() - Data Loading

Source: https://context7.com/sofievg/flowsom/llms.txt

Reads cytometry data from files, flowFrames, or matrices and applies necessary preprocessing steps.

```APIDOC
## ReadInput()

### Description
Loads cytometry data and performs optional compensation, transformation, and scaling.

### Method
Function Call

### Parameters
#### Request Body
- **input** (string/flowFrame/matrix) - Required - Data source.
- **compensate** (boolean) - Optional - Apply compensation.
- **transform** (boolean) - Optional - Apply transformation.
- **scale** (boolean) - Optional - Scale data.

### Response
#### Success Response (200)
- **FlowSOM object** (object) - Initialized object ready for BuildSOM.
```

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

### PlotPies - Pie Chart Visualization

Source: https://context7.com/sofievg/flowsom/llms.txt

Displays nodes as pie charts showing the distribution of cell labels (e.g., manual gating results) within each cluster. Allows for custom color palettes.

```APIDOC
## PlotPies - Pie Chart Visualization

### Description
Displays nodes as pie charts showing the distribution of cell labels (e.g., manual gating results) within each cluster.

### Method
`PlotPies(object, ...)`

### Parameters
- **object** (FlowSOM object) - The result of a FlowSOM analysis.
- **cellTypes** (factor) - A factor indicating the cell type or label for each cell.
- **backgroundValues** (numeric vector, optional) - Values to use for background coloring of metaclusters.
- **colorPalette** (character vector, optional) - Custom color palette for the pie charts.

### Request Example
```r
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
gatingFile <- system.file("extdata", "gatingResult.csv", package = "FlowSOM")

flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Load manual labels
gatingResult <- as.factor(read.csv(gatingFile, header = FALSE)[, 1])

# Plot pies showing manual gating distribution per cluster
PlotPies(flowSOM.res,
         cellTypes = gatingResult,
         backgroundValues = flowSOM.res$metaclustering)

# Custom color palette
PlotPies(flowSOM.res,
         cellTypes = gatingResult,
         colorPalette = FlowSOM_colors)
```

### Response
Returns a ggplot object representing the pie chart visualization.
```

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

### PlotMarker - Marker Expression Overlay

Source: https://context7.com/sofievg/flowsom/llms.txt

Colors nodes by the median expression values of one or more markers, enabling visual inspection of marker distributions across the SOM. Supports faceted views and custom color palettes.

```APIDOC
## PlotMarker - Marker Expression Overlay

### Description
Colors nodes by median expression values of one or more markers, enabling visual inspection of marker distributions across the SOM.

### Method
`PlotMarker(object, ...)`

### Parameters
- **object** (FlowSOM object) - The result of a FlowSOM analysis.
- **marker** (character vector or numeric vector) - The marker(s) to visualize. Can be marker names or column indices.
- **lim** (numeric vector, optional) - Limits for the color scale.
- **colorPalette** (character vector, optional) - Custom color palette.
- **view** (character, optional) - Layout for the plots. Options include 'default' or 'grid'.
- **equalNodeSize** (logical, optional) - If TRUE, all nodes will have the same size.
- **backgroundValues** (numeric vector, optional) - Values to use for background coloring of metaclusters.

### Request Example
```r
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = FALSE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Plot single marker
PlotMarker(flowSOM.res, marker = "CD19")

# Plot multiple markers in faceted view
PlotMarker(flowSOM.res, marker = c(9, 12, 14:18))

# Custom color palette and limits
PlotMarker(flowSOM.res,
           marker = "FSC-A",
           lim = c(55000, 130000),
           colorPalette = c("blue", "white", "red"))

# With background highlighting
PlotMarker(flowSOM.res,
           marker = "CD19",
           view = "grid",
           equalNodeSize = TRUE,
           backgroundValues = flowSOM.res$metaclustering)
```

### Response
Returns a ggplot object representing the marker expression overlay.
```

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

### Execute Complete FlowSOM Workflow

Source: https://context7.com/sofievg/flowsom/llms.txt

The FlowSOM() function serves as the primary wrapper to perform the entire analysis pipeline in one call. It handles data loading, preprocessing, SOM training, and metaclustering, returning a model object ready for downstream analysis.

```r
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(
  input = fileName,
  compensate = TRUE,
  transform = TRUE,
  scale = TRUE,
  colsToUse = c(9, 12, 14:18),
  xdim = 10,
  ydim = 10,
  rlen = 10,
  nClus = 10,
  seed = 42
)
cluster_labels <- GetClusters(flowSOM.res)
metacluster_labels <- GetMetaclusters(flowSOM.res)
```

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

### GetClusterMFIs and GetMetaclusterMFIs

Source: https://context7.com/sofievg/flowsom/llms.txt

Retrieve Median Fluorescence Intensities.

```APIDOC
## GetClusterMFIs / GetMetaclusterMFIs

### Description
Returns the median fluorescence intensity values for each marker across clusters or metaclusters.

### Method
Function Call

### Parameters
- **fsom** (FlowSOM object) - Required - The trained FlowSOM model.
- **colsUsed** (logical) - Optional - If TRUE, only returns clustering markers.

### Response
Returns a matrix of MFI values.
```

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

### GetFeatures - Extract Features from Multiple Files

Source: https://context7.com/sofievg/flowsom/llms.txt

Maps multiple FCS files to a FlowSOM model to extract counts, percentages, and MFI values.

```APIDOC
## GetFeatures

### Description
Maps multiple FCS files to an existing FlowSOM model and extracts counts, percentages, and MFI values per cluster or metacluster.

### Method
Function Call

### Parameters
- **fsom** (FlowSOM object) - Required - The trained FlowSOM model.
- **files** (list) - Required - List of FCS files or flowFrame objects.
- **level** (character) - Optional - 'clusters' or 'metaclusters'.
- **type** (character) - Optional - 'counts', 'percentages', or 'MFIs'.

### Response
Returns a list containing cluster_counts, metacluster_percentages, and cluster_MFIs.
```

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

### Batch Quality Control with PlotFileScatters

Source: https://context7.com/sofievg/flowsom/llms.txt

Generates marker distribution plots for multiple FCS files to identify batch effects prior to FlowSOM analysis. This function can plot specified channels, include quantile markers, group samples, and assign custom colors, with options to save the plot to a file or display it directly.

```r
library(FlowSOM)

# With aggregated data
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")

PlotFileScatters(
  input = c(fileName, fileName),  # Multiple files
  channels = c("Pacific Blue-A", "PE-Cy7-A", "APC-A"),
  maxPoints = 5000,
  quantiles = c(0.1, 0.5, 0.9),   # Show quantile markers
  plotFile = "FileScatters.png"
)

# With groups and custom colors
PlotFileScatters(
  input = c(fileName, fileName),
  channels = c("Pacific Blue-A", "PE-Cy7-A"),
  groups = c("Control", "Treatment"),
  color = c("blue", "red"),
  legend = TRUE,
  plotFile = NULL
)
```

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

### GetCounts and GetPercentages

Source: https://context7.com/sofievg/flowsom/llms.txt

Retrieve cell distribution metrics.

```APIDOC
## GetCounts / GetPercentages

### Description
Returns the number or proportion of cells in each cluster or metacluster.

### Method
Function Call

### Parameters
- **fsom** (FlowSOM object) - Required - The trained FlowSOM model.
- **level** (character) - Required - 'clusters' or 'metaclusters'.

### Response
Returns a numeric vector of counts or percentages.
```

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

### Perform Meta-Clustering with FlowSOM

Source: https://context7.com/sofievg/flowsom/llms.txt

Performs hierarchical clustering on SOM nodes to identify cell populations at a higher level. It can use a specified number of clusters (k) or automatically determine the number of clusters up to a maximum. Dependencies include the FlowSOM package and the input SOM codes.

```r
library(FlowSOM)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
fsom <- ReadInput(fileName, compensate = TRUE, transform = TRUE, scale = TRUE)
fsom <- BuildSOM(fsom, colsToUse = c(9, 12, 14:18))
fsom <- BuildMST(fsom)

# Option 1: Consensus clustering with specified number of clusters
metacl <- metaClustering_consensus(fsom$map$codes, k = 10, seed = 42)

# Option 2: Automatic number determination (up to max)
metacl_auto <- MetaClustering(
  data = fsom$map$codes,
  method = "metaClustering_consensus",
  max = 20,       # Maximum clusters to try
  seed = 42
)

# Get metacluster assignment per cell
metacluster_per_cell <- metacl[fsom$map$mapping[, 1]]
table(metacluster_per_cell)

# For FlowSOM objects from the wrapper function
fsom_full <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                     scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
GetMetaclusters(fsom_full)
```

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

### Map New Data to Existing FlowSOM Model

Source: https://context7.com/sofievg/flowsom/llms.txt

Maps new FCS files or data to a pre-existing FlowSOM model, ensuring consistent analysis across samples. It requires the trained FlowSOM object and the new input data. Outlier detection is possible via the madAllowed parameter.

```r
library(FlowSOM)
library(flowCore)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
ff <- read.FCS(fileName)
ff <- compensate(ff, keyword(ff)[["SPILL"]])
ff <- transform(ff, transformList(
  colnames(keyword(ff)[["SPILL"]]),
  logicleTransform()
))

# Build model on subset of data
flowSOM.res <- FlowSOM(ff[1:5000, ], scale = TRUE,
                       colsToUse = c(9, 12, 14:18), nClus = 10)

# Map new data to existing model
fsom_new <- NewData(
  fsom = flowSOM.res,
  input = ff[5001:10000, ],
  madAllowed = 4,    # Outlier threshold
  silent = FALSE
)

# Compare cluster distributions
table(GetMetaclusters(flowSOM.res))
table(GetMetaclusters(fsom_new))
```

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

### Aggregate Multiple FCS Files with FlowSOM

Source: https://context7.com/sofievg/flowsom/llms.txt

Combines cells from multiple FCS files into a single flowFrame, including tracking of file origin. This is useful for building models across multiple samples. It requires a list of file names and allows sampling control.

```r
library(FlowSOM)
library(flowCore)

# Example: Aggregate multiple files
fileNames <- c(
  system.file("extdata", "68983.fcs", package = "FlowSOM"),
  system.file("extdata", "68983.fcs", package = "FlowSOM")
)

ff_aggregated <- AggregateFlowFrames(
  fileNames = fileNames,
  cTotal = 10000,              # Total cells to sample
  channels = NULL,             # Use all channels (or specify)
  writeOutput = FALSE,         # Write to file?
  keepOrder = FALSE,           # Maintain original cell order?
  sampleWithReplacement = FALSE
)

# The aggregated flowFrame includes File and Original_ID columns
colnames(ff_aggregated)
# Includes: "File", "File_scattered", "Original_ID"

# Use for FlowSOM analysis
flowSOM.res <- FlowSOM(ff_aggregated, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
```

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

### GetFlowJoLabels

Source: https://context7.com/sofievg/flowsom/llms.txt

Reads manual gating results from FlowJo workspace files to compare with FlowSOM clustering results.

```APIDOC
## GetFlowJoLabels

### Description
Parses FlowJo workspace files (.wsp) to extract manual gating labels for validation against FlowSOM clustering.

### Method
Function Call (R)

### Parameters
#### Arguments
- **files** (character) - Required - Path to the FCS file(s).
- **wspFile** (character) - Required - Path to the FlowJo workspace file.
- **group** (character) - Optional - The group name within the workspace to extract.
- **cellTypes** (vector) - Optional - List of cell types/gates to extract.
- **getData** (logical) - Optional - Whether to return the flowFrame data.

### Request Example
GetFlowJoLabels(files = "data.fcs", wspFile = "gating.wsp", cellTypes = c("B cells", "T cells"))

### Response
#### Success Response (List)
- **matrix** (matrix) - Counts per gate.
- **manual** (factor) - Manual labels for each cell.
- **flowFrame** (flowFrame) - The associated flow data.
```

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

### GroupStats - Statistical Comparison

Source: https://context7.com/sofievg/flowsom/llms.txt

Performs statistical comparisons between groups of samples.

```APIDOC
## GroupStats

### Description
Performs statistical comparisons between two groups of samples based on feature matrices, calculating fold changes and p-values.

### Method
Function Call

### Parameters
- **data** (matrix) - Required - Feature matrix (e.g., percentages).
- **groups** (list) - Required - List defining groups and their associated file names.

### Response
Returns a list containing medians, p-values, adjusted p-values, and fold changes.
```

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

### PlotFileScatters

Source: https://context7.com/sofievg/flowsom/llms.txt

Generates marker distribution plots for quality control and batch effect identification.

```APIDOC
## PlotFileScatters

### Description
Visualizes marker distributions across multiple files to identify batch effects or quality issues.

### Method
Function Call (R)

### Parameters
#### Arguments
- **input** (vector) - Required - Vector of file paths.
- **channels** (vector) - Required - Markers to plot.
- **maxPoints** (numeric) - Optional - Maximum points to sample.
- **quantiles** (vector) - Optional - Quantiles to display.
- **groups** (vector) - Optional - Group labels for coloring.

### Request Example
PlotFileScatters(input = c("s1.fcs", "s2.fcs"), channels = c("CD3", "CD4"))

### Response
#### Success Response (Plot)
- **Output** (Graphic) - A scatter plot or PNG file showing marker distributions.
```

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

### Calculate Median Fluorescence Intensities with GetClusterMFIs

Source: https://context7.com/sofievg/flowsom/llms.txt

These functions retrieve the median fluorescence intensity (MFI) for markers across clusters or metaclusters, supporting human-readable column names.

```R
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
cluster_mfis <- GetClusterMFIs(flowSOM.res, colsUsed = TRUE, prettyColnames = TRUE)
metacluster_mfis <- GetMetaclusterMFIs(flowSOM.res, colsUsed = TRUE, prettyColnames = TRUE)
cvs <- GetMetaclusterCVs(flowSOM.res)
```

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

### PlotVariable - Custom Variable Visualization

Source: https://context7.com/sofievg/flowsom/llms.txt

Colors nodes by any custom variable (one value per cluster), enabling flexible visualization of analysis results. Can be combined with AddLabels.

```APIDOC
## PlotVariable - Custom Variable Visualization

### Description
Colors nodes by any custom variable (one value per cluster), enabling flexible visualization of analysis results.

### Method
`PlotVariable(object, ...)`

### Parameters
- **object** (FlowSOM object) - The result of a FlowSOM analysis.
- **variable** (numeric vector) - A vector of values, one for each cluster or metacluster.
- **variableName** (character, optional) - Name of the variable to display in the legend.

### Request Example
```r
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Plot random values
random_values <- runif(NClusters(flowSOM.res))
PlotVariable(flowSOM.res,
             variable = random_values,
             variableName = "Random Score")

# Plot metaclustering as variable with labels
PlotVariable(flowSOM.res,
             variable = flowSOM.res$metaclustering,
             variableName = "Metacluster") %>%
  AddLabels(labels = flowSOM.res$metaclustering)

# Visualize p-values or fold changes
# PlotVariable(flowSOM.res,
#              variable = stats["p values", ],
#              variableName = "p-value")
```

### Response
Returns a ggplot object representing the custom variable visualization.
```

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

### Perform Statistical Comparison with GroupStats

Source: https://context7.com/sofievg/flowsom/llms.txt

GroupStats performs statistical comparisons between two groups of samples. It calculates fold changes and p-values based on provided feature matrices.

```R
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
groups <- list("Control" = c("file1.fcs", "file2.fcs", "file3.fcs"), "Treatment" = c("file4.fcs", "file5.fcs", "file6.fcs"))
```

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

### Export FlowSOM Clusters to FCS with SaveClustersToFCS

Source: https://context7.com/sofievg/flowsom/llms.txt

Appends FlowSOM cluster assignments and MST coordinates to original FCS files, enabling downstream analysis in other software. It requires a FlowSOM object, the original FCS file paths, an output directory, and an optional suffix for the new file names.

```r
library(FlowSOM)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Save clusters to new FCS file
SaveClustersToFCS(
  fsom = flowSOM.res,
  originalFiles = fileName,
  outputDir = ".",
  suffix = "_FlowSOM.fcs"
)

# The output FCS file will contain additional columns:
# - FlowSOM_cluster: cluster assignment
# - FlowSOM_x, FlowSOM_y: MST coordinates
# - FlowSOM_meta: metacluster assignment
```

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

### Visualize Dimensionality Reduction with PlotDimRed

Source: https://context7.com/sofievg/flowsom/llms.txt

Creates t-SNE or other dimensionality reduction plots colored by clusters, metaclusters, or specific marker expressions. It supports subsampling for performance and can return the layout for further customization.

```R
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
PlotDimRed(flowSOM.res, cTotal = 5000, colorBy = "metaclusters", seed = 1, title = "t-SNE by Metacluster")
PlotDimRed(flowSOM.res, cTotal = 5000, colorBy = "CD3", seed = 1)
result <- PlotDimRed(flowSOM.res, cTotal = 5000, colorBy = "metaclusters", returnLayout = TRUE, seed = 1)
```

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

### Extract Features from Multiple FCS Files with GetFeatures

Source: https://context7.com/sofievg/flowsom/llms.txt

The GetFeatures function maps multiple FCS files to a FlowSOM model to extract counts, percentages, and MFI values. It requires a pre-built FlowSOM model and a list of flowFrame objects.

```R
library(FlowSOM)
library(flowCore)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
ff <- read.FCS(fileName)
ff <- compensate(ff, keyword(ff)[["SPILL"]])
ff <- transform(ff, transformList(colnames(keyword(ff)[["SPILL"]]), logicleTransform()))
flowSOM.res <- FlowSOM(ff[1:5000, ], scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
features <- GetFeatures(fsom = flowSOM.res, files = list(ff[5001:7000, ], ff[7001:9000, ]), level = c("clusters", "metaclusters"), type = c("counts", "percentages", "MFIs"), MFI = c("APC-A", "PE-Cy7-A"), filenames = c("sample1", "sample2"), silent = FALSE)
```

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

### Retrieve Cell Distribution with GetCounts and GetPercentages

Source: https://context7.com/sofievg/flowsom/llms.txt

These functions return the number or proportion of cells assigned to each cluster or metacluster within a FlowSOM model.

```R
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
mc_counts <- GetCounts(flowSOM.res, level = "metaclusters")
cl_counts <- GetCounts(flowSOM.res, level = "clusters")
mc_pctgs <- GetPercentages(flowSOM.res, level = "metaclusters")
```

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

### PlotNumbers & PlotLabels: Add Node Identifiers (R)

Source: https://context7.com/sofievg/flowsom/llms.txt

Functions to add cluster or metacluster identifiers directly onto the SOM nodes. Supports grid views, custom sizing, and text styling for labels.

```r
library(FlowSOM)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Show cluster numbers
PlotNumbers(flowSOM.res, level = "clusters")

# Show metacluster numbers
PlotNumbers(flowSOM.res, level = "metaclusters")

# Grid view with equal sizes
PlotNumbers(flowSOM.res,
            level = "clusters",
            view = "grid",
            maxNodeSize = 1,
            equalNodeSize = TRUE)

# Custom labels
PlotLabels(flowSOM.res,
           labels = flowSOM.res$metaclustering,
           textSize = 4,
           textColor = "blue")
```

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

### PlotVariable: Visualize Custom Variables (R)

Source: https://context7.com/sofievg/flowsom/llms.txt

Colors nodes based on any provided custom variable (one value per cluster), allowing flexible visualization of analysis results like p-values or arbitrary scores. Can be combined with AddLabels.

```r
library(FlowSOM)

fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Plot random values
random_values <- runif(NClusters(flowSOM.res))
PlotVariable(flowSOM.res,
             variable = random_values,
             variableName = "Random Score")

# Plot metaclustering as variable with labels
PlotVariable(flowSOM.res,
             variable = flowSOM.res$metaclustering,
             variableName = "Metacluster") %>%
  AddLabels(labels = flowSOM.res$metaclustering)

# Visualize p-values or fold changes
# PlotVariable(flowSOM.res,
#              variable = stats["p values", ],
#              variableName = "p-value")
```

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

### Query Cell Types with QueryStarPlot

Source: https://context7.com/sofievg/flowsom/llms.txt

Identifies nodes matching specific marker expression patterns (high/low) to isolate cell types. It returns node scores and selected IDs, which can be used to annotate the FlowSOM tree.

```R
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10, xdim = 7, ydim = 7)
query <- c("CD3" = "high", "CD4" = "low", "CD8" = "high")
query_res <- QueryStarPlot(flowSOM.res, query = query, equalNodeSize = TRUE)
cellTypes <- factor(rep("Other", NClusters(flowSOM.res)), levels = c("Other", "CD8 T cells"))
cellTypes[query_res$selected] <- "CD8 T cells"
PlotStars(flowSOM.res, backgroundValues = cellTypes, backgroundColors = c("#FFFFFF00", "#0000FF88"))
```

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

### Generate 2D Scatter Plots with Plot2DScatters

Source: https://context7.com/sofievg/flowsom/llms.txt

Produces biaxial scatter plots to highlight specific clusters or metaclusters against background cells. It can save plots directly to a file or return ggplot objects for programmatic use.

```R
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
Plot2DScatters(fsom = flowSOM.res, channelpairs = list(c("PE-Cy7-A", "PE-Cy5-A"), c("PE-Texas Red-A", "Pacific Blue-A")), clusters = c(1, 48, 49), metaclusters = list(c(1, 4), 9), maxPoints = 1000, plotFile = "scatter_plots.png")
plots <- Plot2DScatters(fsom = flowSOM.res, channelpairs = list(c("PE-Texas Red-A", "Pacific Blue-A")), metaclusters = list(1), plotFile = NULL)
```

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

### PlotNumbers and PlotLabels - Node Labeling

Source: https://context7.com/sofievg/flowsom/llms.txt

Functions to add cluster or metacluster identifiers to nodes for reference. Supports grid views and custom text styling.

```APIDOC
## PlotNumbers and PlotLabels - Node Labeling

### Description
These functions add cluster or metacluster identifiers to nodes for reference.

### Method
`PlotNumbers(object, ...)`
`PlotLabels(object, ...)`

### Parameters for PlotNumbers
- **object** (FlowSOM object) - The result of a FlowSOM analysis.
- **level** (character) - The level of identifiers to plot. Options: 'clusters' or 'metaclusters'.
- **view** (character, optional) - Layout for the plots. Options include 'default' or 'grid'.
- **maxNodeSize** (numeric, optional) - Maximum size of the node.
- **equalNodeSize** (logical, optional) - If TRUE, all nodes will have the same size.

### Parameters for PlotLabels
- **object** (FlowSOM object) - The result of a FlowSOM analysis.
- **labels** (character vector) - Custom labels to display on the nodes.
- **textSize** (numeric, optional) - Size of the text.
- **textColor** (character, optional) - Color of the text.

### Request Example
```r
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE,
                       scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)

# Show cluster numbers
PlotNumbers(flowSOM.res, level = "clusters")

# Show metacluster numbers
PlotNumbers(flowSOM.res, level = "metaclusters")

# Grid view with equal sizes
PlotNumbers(flowSOM.res,
            level = "clusters",
            view = "grid",
            maxNodeSize = 1,
            equalNodeSize = TRUE)

# Custom labels
PlotLabels(flowSOM.res,
           labels = flowSOM.res$metaclustering,
           textSize = 4,
           textColor = "blue")
```

### Response
Returns a ggplot object with node labels.
```

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

### Detect Outliers with TestOutliers

Source: https://context7.com/sofievg/flowsom/llms.txt

Identifies cells that deviate significantly from their assigned cluster centers based on Median Absolute Deviation (MAD). It provides a report and visualization tools to inspect potential novel populations.

```R
library(FlowSOM)
fileName <- system.file("extdata", "68983.fcs", package = "FlowSOM")
flowSOM.res <- FlowSOM(fileName, compensate = TRUE, transform = TRUE, scale = TRUE, colsToUse = c(9, 12, 14:18), nClus = 10)
outlier_report <- TestOutliers(flowSOM.res, madAllowed = 4, channels = flowSOM.res$map$colsUsed, plotFile = "outliers.pdf")
PlotOutliers(flowSOM.res, outlier_report$report)
```

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

### SaveClustersToFCS

Source: https://context7.com/sofievg/flowsom/llms.txt

Appends FlowSOM cluster assignments to original FCS files for downstream analysis.

```APIDOC
## SaveClustersToFCS

### Description
Exports FlowSOM clustering results by appending cluster and metacluster IDs to the original FCS file.

### Method
Function Call (R)

### Parameters
#### Arguments
- **fsom** (FlowSOM) - Required - The trained FlowSOM object.
- **originalFiles** (character) - Required - Path to the original FCS file.
- **outputDir** (character) - Required - Directory to save the new file.
- **suffix** (character) - Optional - Suffix for the output filename.

### Request Example
SaveClustersToFCS(fsom = flowSOM.res, originalFiles = "sample.fcs", outputDir = ".")

### Response
#### Success Response (File)
- **File** (FCS) - A new FCS file containing columns: FlowSOM_cluster, FlowSOM_x, FlowSOM_y, FlowSOM_meta.
```