bio-flow-cytometry-compensation-transformation

## Version Compatibility

Reference examples tested with: flowCore 2.14+, scanpy 1.10+

Before using code patterns, verify installed versions match. If versions differ:
- R: `packageVersion('<pkg>')` then `?function_name` to verify parameters

If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.

# Compensation and Transformation

**"Compensate and transform my flow cytometry data"** → Correct spectral overlap between fluorophores using a compensation matrix and apply biexponential/arcsinh transforms for visualization and analysis.
- R: `flowCore::compensate()` then `flowCore::transform()` with `estimateLogicle()`

## Load Compensation Matrix

```r
library(flowCore)

# From FCS file keywords
fcs <- read.FCS('sample.fcs', transformation = FALSE)
comp_matrix <- keyword(fcs)$`$SPILLOVER`

# Or from CSV file
comp_matrix <- as.matrix(read.csv('compensation.csv', row.names = 1))
```

## Apply Compensation

```r
# Create compensation object
comp <- compensation(comp_matrix)

# Apply to flowFrame
fcs_comp <- compensate(fcs, comp)

# Apply to flowSet
fs_comp <- compensate(fs, comp)
```

## Calculate Compensation from Controls

```r
library(flowStats)

# Single-stained controls
controls <- read.flowSet(list.files('controls', pattern = '\\.fcs$', full.names = TRUE))

# Calculate spillover matrix
spillover <- spillover(controls,
                        unstained = 'Unstained.fcs',
                        fsc = 'FSC-A', ssc = 'SSC-A',
                        patt = '-A$',  # Channel pattern
                        stain_match = 'regexpr')

# The result is a list; extract matrix
comp_matrix <- spillover$comp
```

## Transformation: Biexponential (Logicle)

```r
# Logicle transformation (standard for flow)
library(flowWorkspace)

# Auto-estimate parameters
lgcl <- estimateLogicle(fcs, colnames(fcs)[3:10])

# Apply
fcs_trans <- transform(fcs, lgcl)

# Manual logicle parameters
lgcl_manual <- logicleTransform(
    w = 0.5,      # Linearization width
    t = 262144,   # Top of scale
    m = 4.5,      # Decades of data
    a = 0         # Additional negative range
)
```

## Transformation: Arcsinh (CyTOF)

```r
# Arcsinh transformation for CyTOF
arcsinh_transform <- function(x, cofactor = 5) {
    asinh(x / cofactor)
}

# Apply to expression matrix
expr <- exprs(fcs)
expr_trans <- apply(expr[, marker_channels], 2, arcsinh_transform, cofactor = 5)

# Or using transformList
asinhTrans <- arcsinhTransform(transformationId = 'arcsinh', a = 0, b = 1/5)
trans_list <- transformList(marker_channels, asinhTrans)
fcs_trans <- transform(fcs, trans_list)
```

## Transformation: Log

```r
# Simple log transformation
logTrans <- logTransform(transformationId = 'log10', logbase = 10, r = 1, d = 1)
trans_list <- transformList(marker_channels, logTrans)
fcs_trans <- transform(fcs, trans_list)
```

## View Before/After Compensation

```r
library(ggcyto)

# Before compensation
p1 <- autoplot(fcs, 'FITC-A', 'PE-A') + ggtitle('Before Compensation')

# After compensation
p2 <- autoplot(fcs_comp, 'FITC-A', 'PE-A') + ggtitle('After Compensation')

library(patchwork)
p1 + p2
```

## Complete Preprocessing Pipeline

**Goal:** Apply a standard compensation-then-transformation workflow to all samples in a flowSet.

**Approach:** Define a reusable preprocessing function that first applies the spillover compensation matrix, then auto-estimates and applies logicle transformation on marker channels, and map it across all samples with fsApply.

```r
preprocess_flow <- function(fcs, comp_matrix, marker_channels) {
    # 1. Compensation
    comp <- compensation(comp_matrix)
    fcs <- compensate(fcs, comp)

    # 2. Transformation (logicle for flow, arcsinh for CyTOF)
    lgcl <- estimateLogicle(fcs, marker_channels)
    fcs <- transform(fcs, lgcl)

    return(fcs)
}

# Apply to flowSet
fs_processed <- fsApply(fs, function(f) {
    preprocess_flow(f, comp_matrix, marker_channels)
})
```

## CATALYST Preprocessing (CyTOF)

```r
library(CATALYST)
library(SingleCellExperiment)

# Create SingleCellExperiment from flowSet
sce <- prepData(fs,
                panel = panel,      # data.frame with columns: fcs_colname, antigen, marker_class
                md = sample_info,   # sample metadata
                transform = TRUE,   # Apply arcsinh
                cofactor = 5,
                FACS = FALSE)       # TRUE for flow, FALSE for CyTOF
```

## Panel File Format (CATALYST)

```r
# panel.csv
panel <- data.frame(
    fcs_colname = c('Yb176Di', 'Er168Di', 'Nd142Di'),
    antigen = c('CD45', 'CD3', 'CD4'),
    marker_class = c('type', 'type', 'type')  # 'type' for phenotyping, 'state' for functional
)
```

## Save Preprocessed Data

```r
# Write transformed FCS
write.FCS(fcs_trans, 'sample_preprocessed.fcs')

# Save transformation for reproducibility
saveRDS(list(comp = comp_matrix, transform = lgcl), 'preprocessing_params.rds')
```

## Related Skills

- fcs-handling - Load FCS files first
- gating-analysis - Gate after preprocessing
- clustering-phenotyping - Cluster transformed data