The gateR package is a suite of R functions to identify significant spatial clustering of mass and flow cytometry data used in immunological investigations. The gateR package can be used for a panel of all surface markers or a mixture of surface markers and functional readouts. The gateR package performs a gating technique that estimates statistically significant marker combination values within which one immunologically distinctive group (i.e., disease case) is more associated than another group (i.e., healthy control), successively, using various combinations (i.e., “gates”) of markers to examine features of cells that may be different between groups. For a two-group comparison, the gateR package uses the spatial relative risk function estimated using the sparr package. The gates are conducted in two-dimensional space comprised of two markers.

Examples of a single condition with two groups:

- Disease case vs. Healthy control
- Time 2 vs. Time 1 (baseline)

For a two-group comparison of two conditions, we estimate two relative risk surfaces for one condition and then a ratio of the relative risks. For example:

- Estimate a relative risk surface for:
- Condition 2B vs. Condition 2A
- Condition 1B vs. Condition 1A

- Estimate the relative risk surface for the ratio:

\[\frac{(\frac{Condition2B}{Condition2A})}{(\frac{Condition1B}{Condition1A})}\]

Within areas where the relative risk exceeds an asymptotic normal assumption, the gateR package has the functionality to examine the features of these cells.

This vignette implements the gateR package using a randomly generated data set. Please see the README.md file within the gateR GitHub repository for an example using publicly available flow cytometry data from the flowWorkspaceData package available via Bioconductor. Here, we generate data with two conditions, four markers, and two additional features.

We start with the necessary packages and seed for the vignette.

```
<- c("gateR", "graphics", "stats", "tibble", "utils")
loadedPackages invisible(lapply(loadedPackages, library, character.only = TRUE))
set.seed(1234) # for reproducibility
```

A unique function randomly generates multivariate normal (MVN) data
around a central point. Parameters include the centroid coordinates
(`centre`

), the number of observations to generate
(`ncell`

), and the standard deviation of the normal
distribution (`scalar`

).

```
<- function(centre, ncell, scalar) {
rand_mvn <- centre[1]
x0 <- centre[2]
y0 <- rep(x0, ncell)
x1 <- rep(y0, ncell)
y1 <- x1 + stats::rnorm(ncell, 0, scalar)
x2 <- y1 + stats::rnorm(ncell, 0, scalar)
y2 <- cbind(x2, y2)
x }
```

At Condition 1, we generate 100,000 cases and 100,000 controls
(`ncell = 100000`

) randomly MVN with a case centroid at
(`0.55, 0.55`

) and a control centroid at
(`0.40, 0.40`

) within a unit square window
`(0, 1)`

, and cases have a more focal cluster
(`scalar = 0.05`

) than controls
(`scalar = 0.15`

).

```
# Initial parameters
<- 100000 # number of observations per group per condition
ncell <- c(0.55, 0.55)
c1_cas_center <- c(0.40, 0.40)
c1_con_center # V1 and V2 at Condition 1
<- rand_mvn(centre = c1_cas_center, ncell = ncell, scalar = 0.05)
c1_cas <- rand_mvn(centre = c1_con_center, ncell = ncell, scalar = 0.15)
c1_con ::par(pty = "s")
graphics::plot(c1_con,
graphicscol = "blue",
xlim = c(0, 1),
ylim = c(0, 1),
main = "Gate 1, Condition 1",
xlab = "V1",
ylab = "V2")
::points(c1_cas, col = "orangered4") graphics
```

At Condition 2, we generate 100,000 cases and 100,000 controls
(`ncell = 100000`

) randomly MVN with a case centroid at
(`0.45, 0.45`

) and a control centroid at
(`0.40, 0.40`

) within a unit square window
`(0, 1)`

, and cases have a more focal cluster
(`scalar = 0.05`

) than controls
(`scalar = 0.10`

).

```
# Initial parameters
<- c(0.45, 0.45)
c2_cas_center <- c(0.40, 0.40)
c2_con_center # V1 and V2 at Condition 2
<- rand_mvn(centre = c2_cas_center, ncell = ncell, scalar = 0.05)
c2_cas <- rand_mvn(centre = c2_con_center, ncell = ncell, scalar = 0.10)
c2_con ::par(pty = "s")
graphics::plot(c2_con,
graphicscol = "cornflowerblue",
xlim = c(0, 1),
ylim = c(0, 1),
main = "Gate 1, Condition 2",
xlab = "V1",
ylab = "V2")
::points(c2_cas, col = "orangered1") graphics
```

```
# compile data
<- tibble::tibble("id" = seq(1, ncell * 2 * 2, 1),
df_full "group" = factor(c(rep("case", ncell * 2),
rep("control", ncell * 2))),
"condition" = factor(c(rep("2", ncell), rep("1", ncell),
rep("2", ncell), rep("1", ncell))),
"V1" = c(c2_cas[ , 1], c1_cas[ , 1], c2_con[ , 1], c1_con[ , 1]),
"V2" = c(c2_cas[ , 2], c1_cas[ , 2], c2_con[ , 2], c1_con[ , 2]))
rm(c2_cas, c1_cas, c2_con, c1_con) # conserve memory
```

At Condition 1, we generate 100,000 cases and 100,000 controls
(`ncell = 100000`

) randomly MVN with a case centroid at
(`0.55, 0.55`

) and a control centroid at
(`0.50, 0.50`

) within a unit square window
`(0, 05)`

, but both have the same amount of spread
(`scalar = 0.10`

).

```
# Initial parameters
<- c(0.55, 0.55)
c1_cas_center <- c(0.50, 0.50)
c1_con_center # V3 and V4 at Condition 1
<- rand_mvn(centre = c1_cas_center, ncell = ncell, scalar = 0.05)
c1_cas <- rand_mvn(centre = c1_con_center, ncell = ncell, scalar = 0.10)
c1_con ::par(pty = "s")
graphics::plot(c1_con,
graphicscol = "blue",
xlim = c(0, 1),
ylim = c(0, 1),
main = "Gate 2, Condition 1",
xlab = "V3",
ylab = "V4")
::points(c1_cas, col = "orangered4") graphics
```

At Condition 2, we generate 100,000 cases and 100,000 controls
(`ncell = 100000`

) randomly with a case centroid at
(`0.65, 0.65`

) and control a centroid at
(`0.50, 0.50`

) within a unit square window
`(0, 1)`

, and cases have a more focal cluster
(`scalar = 0.05`

) than controls
(`scalar = 0.10`

).

```
# Initial parameters
<- c(0.65, 0.65)
c2_cas_center <- c(0.50, 0.50)
c2_con_center # V3 and V4 at Condition 2
<- rand_mvn(centre = c2_cas_center, ncell = ncell, scalar = 0.05)
c2_cas <- rand_mvn(centre = c2_con_center, ncell = ncell, scalar = 0.10)
c2_con ::par(pty = "s")
graphics::plot(c2_con,
graphicscol = "cornflowerblue",
xlim = c(0, 1),
ylim = c(0, 1),
main = "Gate 2, Condition 2",
xlab = "V3",
ylab = "V4")
::points(c2_cas, col = "orangered1") graphics
```

Compile the toy data into a data frame

```
$V3 <- c(c2_cas[ , 1], c1_cas[ , 1], c2_con[ , 1], c1_con[ , 1])
df_full$V4 <- c(c2_cas[ , 2], c1_cas[ , 2], c2_con[ , 2], c1_con[ , 2])
df_full
rm(c2_cas, c1_cas, c2_con, c1_con) # conserve memory
```

Generate random values for two example cytokines and append to the data frame.

```
# Two Cytokines
<- stats::rchisq(ncell * 4, df = 5) # Random Chi-square distribution
Z1 <- stats::rnorm(ncell * 4, 0, 1) # Random Gaussian distribution
Z2 # Append to data.frame
$Z1 <- Z1
df_full$Z2 <- Z2
df_fullrm(Z1, Z2) # conserve memory
# Visualize histograms by the two group conditions
::par(mfrow = c(2, 2), pty = "s")
graphics::plot(stats::density(df_full$Z1[df_full$group == "case"
graphics& df_full$condition == "1"]),
main = "Cytokine 1 of Cases at Condition 1")
::plot(stats::density(df_full$Z1[df_full$group == "case"
graphics& df_full$condition == "2"]),
main = "Cytokine 1 of Cases at Condition 2")
::plot(stats::density(df_full$Z1[df_full$group == "control"
graphics& df_full$condition == "1"]),
main = "Cytokine 1 of Controls at Condition 1")
::plot(stats::density(df_full$Z1[df_full$group == "control"
graphics& df_full$condition == "2"]),
main = "Cytokine 1 of Controls at Condition 2")
::plot(stats::density(df_full$Z2[df_full$group == "case"
graphics& df_full$condition == "1"]),
main = "Cytokine 2 of Cases at Condition 1")
::plot(stats::density(df_full$Z2[df_full$group == "case"
graphics& df_full$condition == "2"]),
main = "Cytokine 2 of Cases at Condition 2")
::plot(stats::density(df_full$Z2[df_full$group == "control"
graphics& df_full$condition == "1"]),
main = "Cytokine 2 of Controls at Condition 1")
::plot(stats::density(df_full$Z2[df_full$group == "control"
graphics& df_full$condition == "2"]),
main = "Cytokine 2 of Controls at Condition 2")
```

The toy data frame has nine columns (id, groups, markers, and cytokines).

`::head(df_full) utils`

```
## # A tibble: 6 × 9
## id group condition V1 V2 V3 V4 Z1 Z2
## <dbl> <fct> <fct> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
## 1 1 case 2 0.491 0.402 0.677 0.586 4.35 -0.488
## 2 2 case 2 0.407 0.493 0.714 0.698 8.61 0.279
## 3 3 case 2 0.508 0.409 0.547 0.644 6.79 -0.786
## 4 4 case 2 0.423 0.480 0.657 0.656 1.04 -0.552
## 5 5 case 2 0.367 0.420 0.635 0.637 4.10 0.239
## 6 6 case 2 0.499 0.405 0.547 0.656 6.99 0.0472
```

```
# Initial parameters
al
```