# How to create supercells

## Introduction

This vignette describes the steps to generate supercells for cytometry data using SuperCellCyto R package.

Briefly, supercells are “mini” clusters of cells that are similar in their marker expressions. The motivation behind supercells is that instead of analysing millions of individual cells, you can analyse thousands of supercells, making downstream analysis much faster while maintaining biological interpretability.

See other vignettes for how to:

- Prepare your data for SuperCellCyto
- Use SuperCellCyto for downsampling
- Integrate SuperCellCyto output with SingleCellExperiment objects
- Integrate SuperCellCyto output with Seurat objects

## Installation

You can install stable version of SuperCellCyto from Bioconductor using:

    if (!requireNamespace("BiocManager", quietly = TRUE))
        install.packages("BiocManager")
    BiocManager::install("SuperCellCyto")

For the latest development version, you can install it from GitHub using `pak`:

    if (!requireNamespace("pak", quietly = TRUE))
        install.packages("pak")
    pak::install_github("phipsonlab/SuperCellCyto")

## Preparing your dataset

The function which creates supercells is called `runSuperCellCyto`, and it operates on a `data.table` object, an enhanced version of R native `data.frame`.

In addition to needing the data stored in a `data.table` object it also requires:

1. The markers you will be using to create supercells to have been appropriately transformed, typically using either arcsinh transformation or linear binning (using FlowJo). `runSuperCellCyto` does not perform any data transformation or scaling.
2. The object to have a column denoting the unique ID of each cell. You most likely have to create this column yourself, and it can simply just be a numerical value ranging from 1 to however many cells you have in your data.
3. The object to have a column denoting the biological sample each cell comes from. This column is critical to ensure that cells from different samples will not be mixed in a supercell.

If you are not sure how to import CSV or FCS files into `data.table` object, and/or how to subsequently prepare the object ready for SuperCellCyto, please consult this vignette. In that vignette, we also provide an explanation behind why we need to have the cell ID and sample column.

For this vignette, we will simulate some toy data using the `simCytoData` function. Specifically, we will simulate 15 markers and 3 samples, with each sample containing 10,000 cells. Hence in total, we will have a toy dataset containing 15 markers and 30,000 cells.

    n_markers <- 15
    n_samples <- 3
    dat <- simCytoData(nmarkers = n_markers, ncells = rep(10000, n_samples))
    head(dat)
    #>    Marker_1 Marker_2 Marker_3 Marker_4 Marker_5 Marker_6 Marker_7 Marker_8
    #>       <num>    <num>    <num>    <num>    <num>    <num>    <num>    <num>
    #> 1: 16.90525 6.824898 11.18817 7.375742 8.330038 20.26430 13.89144 14.11245
    #> 2: 18.69420 7.322856 12.14254 7.004208 7.390566 20.63310 13.53098 12.73084
    #> 3: 17.79865 6.369678 11.28838 5.834467 8.862278 19.76450 13.09814 13.00262
    #> 4: 17.67244 7.305475 12.22762 7.063949 8.157630 19.98139 14.58052 13.51146
    #> 5: 19.43247 7.401481 10.99491 7.372419 6.402098 18.35134 14.18057 14.24904
    #> 6: 16.24345 6.390859 11.83615 7.006253 9.348214 18.51348 15.32304 13.57877
    #>    Marker_9 Marker_10 Marker_11 Marker_12 Marker_13 Marker_14 Marker_15
    #>       <num>     <num>     <num>     <num>     <num>     <num>     <num>
    #> 1: 5.253095  16.00471  16.07186  8.655540  9.610312  15.83451  7.591509
    #> 2: 5.454277  16.04286  13.73902  6.153510 10.287315  16.31029  7.913685
    #> 3: 7.102600  17.79722  13.92657  8.606785  7.630800  16.90352  7.858680
    #> 4: 6.055998  17.11559  14.84128  8.462307 10.865492  17.38207  7.702059
    #> 5: 7.534724  19.36332  16.50106 10.809977  9.139645  15.17072  6.481928
    #> 6: 5.325053  15.94636  13.59154  8.278568  9.869531  16.86992  7.502719
    #>      Sample Cell_Id
    #>      <char>  <char>
    #> 1: Sample_1  Cell_1
    #> 2: Sample_1  Cell_2
    #> 3: Sample_1  Cell_3
    #> 4: Sample_1  Cell_4
    #> 5: Sample_1  Cell_5
    #> 6: Sample_1  Cell_6

For our toy dataset, we will transform our data using arcsinh transformation. We will use the base R `asinh` function to do this:

    # Specify which columns are the markers to transform
    marker_cols <- paste0("Marker_", seq_len(n_markers))
    # The co-factor for arc-sinh
    cofactor <- 5

    # Do the transformation
    dat_asinh <- asinh(dat[, marker_cols, with = FALSE] / cofactor)

    # Rename the new columns
    marker_cols_asinh <- paste0(marker_cols, "_asinh")
    names(dat_asinh) <- marker_cols_asinh

    # Add them our previously loaded data
    dat <- cbind(dat, dat_asinh)

    head(dat[, marker_cols_asinh, with = FALSE])
    #>    Marker_1_asinh Marker_2_asinh Marker_3_asinh Marker_4_asinh Marker_5_asinh
    #>             <num>          <num>          <num>          <num>          <num>
    #> 1:       1.932518       1.117457       1.545124      1.1808985       1.283457
    #> 2:       2.029345       1.174949       1.620347      1.1384712       1.182561
    #> 3:       1.982001       1.062459       1.553271      0.9946051       1.336985
    #> 4:       1.975152       1.172987       1.626807      1.1453935       1.265575
    #> 5:       2.066809       1.183784       1.529239      1.1805255       1.066456
    #> 6:       1.894287       1.065072       1.596760      1.1387088       1.383771
    #>    Marker_6_asinh Marker_7_asinh Marker_8_asinh Marker_9_asinh Marker_10_asinh
    #>             <num>          <num>          <num>          <num>           <num>
    #> 1:       2.107454       1.745901       1.760766      0.9167175        1.880145
    #> 2:       2.124973       1.721202       1.664243      0.9441815        1.882418
    #> 3:       2.083225       1.690766       1.683931      1.1498514        1.981924
    #> 4:       2.093810       1.791577       1.719848      1.0231233        1.944382
    #> 5:       2.011474       1.765306       1.769851      1.1986093        2.063357
    #> 6:       2.019964       1.838682       1.724509      0.9266042        1.876659
    #>    Marker_11_asinh Marker_12_asinh Marker_13_asinh Marker_14_asinh
    #>              <num>           <num>           <num>           <num>
    #> 1:        1.884142        1.316486        1.408227        1.869945
    #> 2:        1.735527        1.035481        1.469042        1.898212
    #> 3:        1.748278        1.311599        1.209187        1.932420
    #> 4:        1.808360        1.296992        1.518472        1.959221
    #> 5:        1.909335        1.513821        1.363924        1.829189
    #> 6:        1.725392        1.278147        1.431905        1.930512
    #>    Marker_15_asinh
    #>              <num>
    #> 1:        1.204873
    #> 2:        1.239798
    #> 3:        1.233908
    #> 4:        1.216973
    #> 5:        1.076245
    #> 6:        1.195065

We will also create a column Cell_id_dummy which uniquely identify each cell. It will have values such as `Cell_1, Cell_2,` all the way until `Cell_x` where x is the number of cells in the dataset.

    dat$Cell_id_dummy <- paste0("Cell_", seq_len(nrow(dat)))
    head(dat$Cell_id_dummy, n = 10)
    #>  [1] "Cell_1"  "Cell_2"  "Cell_3"  "Cell_4"  "Cell_5"  "Cell_6"  "Cell_7"
    #>  [8] "Cell_8"  "Cell_9"  "Cell_10"

By default, the `simCytoData` function will generate cells for multiple samples, and that the resulting `data.table` object will already have a column called Sample that denotes the sample the cells come from.

    unique(dat$Sample)
    #> [1] "Sample_1" "Sample_2" "Sample_3"

Let’s take note of the sample and cell id column for later.

    sample_col <- "Sample"
    cell_id_col <- "Cell_id_dummy"

## Creating supercells

Now that we have our data, let’s create some supercells. To do this, we will use `runSuperCellCyto` function and pass the markers, sample and cell ID columns as parameters.

The reason why we need to specify the markers is because the function will create supercells based on only the expression of those markers. We highly recommend creating supercells using all markers in your data, let that be cell type or cell state markers. However, if for any reason you only want to only use a subset of the markers in your data, then make sure you specify them in a vector that you later pass to `runSuperCellCyto` function.

For this tutorial, we will use all the arcsinh transformed markers in the toy data.

    supercells <- runSuperCellCyto(
        dt = dat,
        markers = marker_cols_asinh,
        sample_colname = sample_col,
        cell_id_colname = cell_id_col
    )

Let’s dig deeper into the object it created:

    class(supercells)
    #> [1] "list"

It is a list containing 3 elements:

    names(supercells)
    #> [1] "supercell_expression_matrix" "supercell_cell_map"
    #> [3] "supercell_object"

### Supercell object

The `supercell_object` contains the metadata used to create the supercells. It is a list, and each element contains the metadata used to create the supercells for a sample. This will come in handy if we need to either regenerate the supercells using different gamma values (so we get more or less supercells) or do some debugging later down the line. More on regenerating supercells on Controlling supercells granularity section below.

### Supercell expression matrix

The `supercell_expression_matrix` contains the marker expression of each supercell. These are calculated by taking the average of the marker expression of all the cells contained within a supercell.

    head(supercells$supercell_expression_matrix)
    #>    Marker_1_asinh Marker_2_asinh Marker_3_asinh Marker_4_asinh Marker_5_asinh
    #>             <num>          <num>          <num>          <num>          <num>
    #> 1:       2.004001       1.061921       1.625547      1.1661126       1.103394
    #> 2:       1.974603       1.179399       1.495408      1.0968913       1.215529
    #> 3:       1.984227       1.127030       1.607508      1.0749492       1.310239
    #> 4:       1.979252       1.133363       1.552394      1.1598747       1.196451
    #> 5:       1.967005       1.280150       1.590272      1.0657448       1.314479
    #> 6:       1.983026       1.194416       1.551679      0.9816926       1.374196
    #>    Marker_6_asinh Marker_7_asinh Marker_8_asinh Marker_9_asinh Marker_10_asinh
    #>             <num>          <num>          <num>          <num>           <num>
    #> 1:       2.073475       1.764573       1.800982      0.9410555        1.913922
    #> 2:       2.069474       1.779232       1.750564      1.0584992        1.894182
    #> 3:       2.075349       1.730649       1.811780      1.1279418        1.918734
    #> 4:       2.064659       1.716860       1.781669      1.1410970        1.912997
    #> 5:       2.069527       1.702626       1.767818      1.2260852        1.930066
    #> 6:       2.063796       1.707441       1.799527      0.9185037        1.917469
    #>    Marker_11_asinh Marker_12_asinh Marker_13_asinh Marker_14_asinh
    #>              <num>           <num>           <num>           <num>
    #> 1:        1.813559        1.396472        1.520352        1.950524
    #> 2:        1.814877        1.473589        1.468446        1.941043
    #> 3:        1.823048        1.441000        1.365689        1.946828
    #> 4:        1.811495        1.420028        1.367226        1.941966
    #> 5:        1.821774        1.313258        1.394832        1.939288
    #> 6:        1.839457        1.423040        1.409289        1.923986
    #>    Marker_15_asinh   Sample                 SuperCellId
    #>              <num>   <char>                      <char>
    #> 1:        1.215271 Sample_1 SuperCell_1_Sample_Sample_1
    #> 2:        1.185508 Sample_1 SuperCell_2_Sample_Sample_1
    #> 3:        1.382230 Sample_1 SuperCell_3_Sample_Sample_1
    #> 4:        1.309981 Sample_1 SuperCell_4_Sample_Sample_1
    #> 5:        1.242197 Sample_1 SuperCell_5_Sample_Sample_1
    #> 6:        1.315484 Sample_1 SuperCell_6_Sample_Sample_1

Therein, we will have the following columns:

1. All the markers we previously specified in the `markers_col` variable. In this example, they are the arcsinh transformed markers in our toy data.
2. A column (`Sample` in this case) denoting which sample a supercell belongs to, (note the column name is the same as what is stored in `sample_col` variable).
3. The `SuperCellId` column denoting the unique ID of the supercell.

#### SuperCellId

Let’s have a look at `SuperCellId`:

    head(unique(supercells$supercell_expression_matrix$SuperCellId))
    #> [1] "SuperCell_1_Sample_Sample_1" "SuperCell_2_Sample_Sample_1"
    #> [3] "SuperCell_3_Sample_Sample_1" "SuperCell_4_Sample_Sample_1"
    #> [5] "SuperCell_5_Sample_Sample_1" "SuperCell_6_Sample_Sample_1"

Let’s break down one of them, `SuperCell_1_Sample_Sample_1`. `SuperCell_1` is a numbering (1 to however many supercells there are in a sample) used to uniquely identify each supercell in a sample. Notably, you may encounter this (`SuperCell_1`, `SuperCell_2`) being repeated across different samples, e.g.,

    supercell_ids <- unique(supercells$supercell_expression_matrix$SuperCellId)
    supercell_ids[grep("SuperCell_1_", supercell_ids)]
    #> [1] "SuperCell_1_Sample_Sample_1" "SuperCell_1_Sample_Sample_2"
    #> [3] "SuperCell_1_Sample_Sample_3"

While these 3 supercells’ id are pre-fixed with `SuperCell_1`, it does not make them equal to one another! `SuperCell_1_Sample_Sample_1` will only contain cells from `Sample_1` while `SuperCell_1_Sample_Sample_2` will only contain cells from `Sample_2`.

By now, you may have noticed that we appended the sample name into each supercell id. This aids in differentiating the supercells in different samples.

### Supercell cell map

`supercell_cell_map` maps each cell in our dataset to the supercell it belongs to.

    head(supercells$supercell_cell_map)
    #>                      SuperCellID CellId   Sample
    #>                           <char> <char>   <char>
    #> 1:  SuperCell_96_Sample_Sample_1 Cell_1 Sample_1
    #> 2: SuperCell_422_Sample_Sample_1 Cell_2 Sample_1
    #> 3:  SuperCell_19_Sample_Sample_1 Cell_3 Sample_1
    #> 4: SuperCell_139_Sample_Sample_1 Cell_4 Sample_1
    #> 5: SuperCell_391_Sample_Sample_1 Cell_5 Sample_1
    #> 6:  SuperCell_92_Sample_Sample_1 Cell_6 Sample_1

This map is very useful if we later need to expand the supercells out. Additionally, this is also the reason why we need to have a column in the dataset which uniquely identify each cell.

## Running `runSuperCellCyto` in parallel

By default, `runSuperCellCyto` will process each sample one after the other. As each sample is processed independent of one another, strictly speaking, we can process all of them in parallel.

To do this, we need to:

1. Create a `BiocParallelParam` object from the BiocParallel package. This object can either be of type `MulticoreParam`or `SnowParam`. We highly recommend consulting their vignette for more information.
2. Set the number of tasks for the `BiocParallelParam` object to the number of samples we have in the dataset.
3. Set the `load_balancing` parameter for `runSuperCellCyto` function to TRUE. This is to ensure even distribution of the supercell creation jobs. As each sample will be processed by a parallel job, we don’t want a job that processs large sample to also be assigned other smaller samples if possible. If you want to know more how this feature works, please refer to our manuscript.

    supercell_par <- runSuperCellCyto(
        dt = dat,
        markers = marker_cols_asinh,
        sample_colname = sample_col,
        cell_id_colname = cell_id_col,
        BPPARAM = MulticoreParam(tasks = n_samples),
        load_balancing = TRUE
    )

## Controlling supercells granularity

This is described in the `runSuperCellCyto` function’s documentation, but let’s briefly go through it here.

The `runSuperCellCyto` function is equipped with various parameters which can be customised to alter the composition of the supercells. The one that is very likely to be used the most is the gamma parameter, denoted as `gam` in the function. By default, the value for `gam` is set to 20, which we found work well for most cases.

The gamma parameter controls how many supercells to generate, and indirectly, how many cells are captured within each supercell. This parameter is resolved into the following formula `gamma=n_cells/n_supercells` where `n_cell` denotes the number of cells and `n_supercells` denotes the number of supercells.

In general, the larger gamma parameter is set to, the less supercells we will get. Say for instance we have 10,000 cells. If gamma is set to 10, we will end up with about 1,000 supercells, whereas if gamma is set to 50, we will end up with about 200 supercells.

You may have noticed, after reading the sections above, `runSuperCellCyto` is ran on each sample independent of each other, and that we can only set 1 value as the gamma parameter. Indeed, for now, the same gamma value will be used across all samples, and that depending on how many cells we have in each sample, we will end up with different number of supercells for each sample. For instance, say we have 10,000 cells for sample 1, and 100,000 cells for sample 2. If gamma is set to 10, for sample 1, we will get 1,000 supercells (10,000/10) while for sample 2, we will get 10,000 supercells (100,000/10).

Do note: whatever gamma value you chose, you should not expect each supercell to contain exactly the same number of cells. This behaviour is intentional to ensure rare cell types are not intermixed with non-rare cell types in a supercell.

### Adjusting gamma value after one run of runSuperCellCyto

If you have run `runSuperCellCyto` once and have not discarded the SuperCell object it generated (no serious, please don’t!), you can use the object to quickly regenerate supercells using different gamma values.

As an example, using the SuperCell object we have generated for our toy dataset, we will regenerate the supercells using gamma of 10 and 50. The function to do this is `recomputeSupercells`. We will store the output in a list, one element per gamma value.

    addt_gamma_vals <- c(10, 50)
    supercells_addt_gamma <- lapply(addt_gamma_vals, function(gam) {
        recomputeSupercells(
            dt = dat,
            sc_objects = supercells$supercell_object,
            markers = marker_cols_asinh,
            sample_colname = sample_col,
            cell_id_colname = cell_id_col,
            gam = gam
        )
    })

We should end up with a list containing 2 elements. The 1st element contains supercells generated using gamma = 10, and the 2nd contains supercells generated using gamma = 50.

    supercells_addt_gamma[[1]]
    #> $supercell_expression_matrix
    #>       Marker_1_asinh Marker_2_asinh Marker_3_asinh Marker_4_asinh
    #>                <num>          <num>          <num>          <num>
    #>    1:       1.985596      1.0665213      1.6262870      0.9038113
    #>    2:       1.936856      1.1612248      1.4922660      1.0501560
    #>    3:       1.960944      0.9432953      1.5834091      1.1275580
    #>    4:       1.984616      1.0676563      1.5930605      1.0093973
    #>    5:       1.963732      1.0140471      1.5956161      1.0846241
    #>   ---
    #> 2996:       2.053227      1.3306916      0.8897168      1.6052685
    #> 2997:       2.022841      1.2040844      1.0006684      1.7875130
    #> 2998:       2.059455      1.2799995      0.8581879      1.5356397
    #> 2999:       1.992892      1.3597693      0.8156451      1.5077350
    #> 3000:       2.071741      1.4078763      1.1261081      1.6049279
    #>       Marker_5_asinh Marker_6_asinh Marker_7_asinh Marker_8_asinh
    #>                <num>          <num>          <num>          <num>
    #>    1:      0.9434499       2.051396       1.750597       1.724282
    #>    2:      1.1463182       2.019151       1.709845       1.747246
    #>    3:      1.2497478       2.066877       1.696000       1.736776
    #>    4:      1.0341429       2.074896       1.743632       1.801289
    #>    5:      1.2091516       2.054988       1.744709       1.767564
    #>   ---
    #> 2996:      1.7223814       2.075798       1.809607       2.097750
    #> 2997:      1.7755265       1.954178       1.835567       2.041643
    #> 2998:      1.8492764       2.017215       1.895183       2.020852
    #> 2999:      1.7563029       2.045583       1.849813       2.047250
    #> 3000:      1.8832765       2.001782       1.950283       2.077815
    #>       Marker_9_asinh Marker_10_asinh Marker_11_asinh Marker_12_asinh
    #>                <num>           <num>           <num>           <num>
    #>    1:      0.8307463        1.880891        1.759161        1.364952
    #>    2:      1.1008446        1.878202        1.795001        1.295082
    #>    3:      1.0066721        1.878564        1.798771        1.356755
    #>    4:      1.1726975        1.930117        1.835982        1.320126
    #>    5:      1.1141005        1.897684        1.829871        1.379352
    #>   ---
    #> 2996:      0.9086830        2.037189        2.117449        1.987358
    #> 2997:      1.2581821        2.027827        2.013240        1.957460
    #> 2998:      1.2483190        2.004304        2.018441        2.006039
    #> 2999:      1.1826612        2.033918        2.026799        1.962394
    #> 3000:      1.1136483        1.993246        1.994564        1.965599
    #>       Marker_13_asinh Marker_14_asinh Marker_15_asinh   Sample
    #>                 <num>           <num>           <num>   <char>
    #>    1:        1.384083       1.9293180        1.339086 Sample_1
    #>    2:        1.419020       1.9140392        1.157774 Sample_1
    #>    3:        1.409550       1.9104500        1.362545 Sample_1
    #>    4:        1.396372       1.9515331        1.346449 Sample_1
    #>    5:        1.340239       1.9468700        1.281308 Sample_1
    #>   ---
    #> 2996:        2.055513       0.7030505        1.877322 Sample_3
    #> 2997:        2.052978       0.8599115        1.807901 Sample_3
    #> 2998:        2.044912       1.1801959        1.832194 Sample_3
    #> 2999:        2.027799       0.7394585        1.779773 Sample_3
    #> 3000:        2.019601       0.7444161        1.827554 Sample_3
    #>                          SuperCellId
    #>                               <char>
    #>    1:    SuperCell_1_Sample_Sample_1
    #>    2:    SuperCell_2_Sample_Sample_1
    #>    3:    SuperCell_3_Sample_Sample_1
    #>    4:    SuperCell_4_Sample_Sample_1
    #>    5:    SuperCell_5_Sample_Sample_1
    #>   ---
    #> 2996:  SuperCell_996_Sample_Sample_3
    #> 2997:  SuperCell_997_Sample_Sample_3
    #> 2998:  SuperCell_998_Sample_Sample_3
    #> 2999:  SuperCell_999_Sample_Sample_3
    #> 3000: SuperCell_1000_Sample_Sample_3
    #>
    #> $supercell_cell_map
    #>                          SuperCellID     CellId   Sample
    #>                               <char>     <char>   <char>
    #>     1: SuperCell_191_Sample_Sample_1     Cell_1 Sample_1
    #>     2: SuperCell_636_Sample_Sample_1     Cell_2 Sample_1
    #>     3:  SuperCell_39_Sample_Sample_1     Cell_3 Sample_1
    #>     4: SuperCell_196_Sample_Sample_1     Cell_4 Sample_1
    #>     5: SuperCell_433_Sample_Sample_1     Cell_5 Sample_1
    #>    ---
    #> 29996: SuperCell_270_Sample_Sample_3 Cell_29996 Sample_3
    #> 29997:  SuperCell_44_Sample_Sample_3 Cell_29997 Sample_3
    #> 29998: SuperCell_140_Sample_Sample_3 Cell_29998 Sample_3
    #> 29999: SuperCell_312_Sample_Sample_3 Cell_29999 Sample_3
    #> 30000: SuperCell_639_Sample_Sample_3 Cell_30000 Sample_3

The output generated by `recomputeSupercells` is essentially a list:

1. `supercell_expression_matrix`: A data.table object that contains the marker expression for each supercell.
2. `supercell_cell_map`: A data.table that maps each cell to its corresponding supercell.

As mentioned before, gamma dictates the granularity of supercells. Compared to the previous run where gamma was set to 20, we should get more supercells for gamma = 10, and less for gamma = 50. Let’s see if that’s the case.

    n_supercells_gamma20 <- nrow(supercells$supercell_expression_matrix)
    n_supercells_gamma10 <- nrow(
        supercells_addt_gamma[[1]]$supercell_expression_matrix
    )
    n_supercells_gamma50 <- nrow(
        supercells_addt_gamma[[2]]$supercell_expression_matrix
    )

    n_supercells_gamma10 > n_supercells_gamma20
    #> [1] TRUE

    n_supercells_gamma50 < n_supercells_gamma20
    #> [1] TRUE

### Specifying different gamma value for different samples

In the future, we may add the ability to specify different `gam` value for different samples. For now, if we want to do this, we will need to break down our data into multiple `data.table` objects, each containing data from 1 sample, and run `runSuperCellCyto` function on each of them with different `gam` parameter value. Something like the following:

    n_markers <- 10
    dat <- simCytoData(nmarkers = n_markers)
    markers_col <- paste0("Marker_", seq_len(n_markers))
    sample_col <- "Sample"
    cell_id_col <- "Cell_Id"

    samples <- unique(dat[[sample_col]])
    gam_values <- c(10, 20, 10)

    supercells_diff_gam <- lapply(seq_len(length(samples)), function(i) {
        sample <- samples[i]
        gam <- gam_values[i]
        dat_samp <- dat[dat$Sample == sample, ]
        supercell_samp <- runSuperCellCyto(
            dt = dat_samp,
            markers = markers_col,
            sample_colname = sample_col,
            cell_id_colname = cell_id_col,
            gam = gam
        )
        return(supercell_samp)
    })

Subsequently, to extract and combine the `supercell_expression_matrix` and `supercell_cell_map`, we will need to use `rbind`:

    supercell_expression_matrix <- do.call(
        "rbind", lapply(
            supercells_diff_gam, function(x) x[["supercell_expression_matrix"]]
        )
    )

    supercell_cell_map <- do.call(
        "rbind", lapply(
            supercells_diff_gam, function(x) x[["supercell_cell_map"]]
        )
    )

    rbind(
        head(supercell_expression_matrix, n = 3),
        tail(supercell_expression_matrix, n = 3)
    )
    #>     Marker_1  Marker_2 Marker_3  Marker_4  Marker_5  Marker_6  Marker_7
    #>        <num>     <num>    <num>     <num>     <num>     <num>     <num>
    #> 1:  4.580436 11.627934 9.315564 11.655859 16.335015  7.539119  7.021215
    #> 2:  3.239868 12.323742 9.022821 10.303073 16.266310  9.806767  6.765926
    #> 3:  5.784899 11.674768 8.989137  9.332666 17.303874  8.413620  7.766605
    #> 4:  8.645193  9.227455 5.227140  9.251951  6.851307 17.958263 20.120249
    #> 5: 10.176724  6.460807 4.608580  8.386169  8.494580 17.929808 19.188869
    #> 6: 12.289900  5.656810 5.449735  9.106417  6.573927 17.339239 19.428163
    #>     Marker_8 Marker_9 Marker_10   Sample                   SuperCellId
    #>        <num>    <num>     <num>   <char>                        <char>
    #> 1: 17.937234 5.806962 17.786944 Sample_1   SuperCell_1_Sample_Sample_1
    #> 2: 18.792858 6.150215 20.223025 Sample_1   SuperCell_2_Sample_Sample_1
    #> 3: 17.662014 4.811567 19.646904 Sample_1   SuperCell_3_Sample_Sample_1
    #> 4:  5.351835 6.076154  9.757472 Sample_2 SuperCell_498_Sample_Sample_2
    #> 5:  5.220019 8.018877  9.778254 Sample_2 SuperCell_499_Sample_Sample_2
    #> 6:  6.197180 7.479147  8.597182 Sample_2 SuperCell_500_Sample_Sample_2

    rbind(head(supercell_cell_map, n = 3), tail(supercell_cell_map, n = 3))
    #>                      SuperCellID     CellId   Sample
    #>                           <char>     <char>   <char>
    #> 1: SuperCell_717_Sample_Sample_1     Cell_1 Sample_1
    #> 2:  SuperCell_48_Sample_Sample_1     Cell_2 Sample_1
    #> 3: SuperCell_265_Sample_Sample_1     Cell_3 Sample_1
    #> 4:  SuperCell_77_Sample_Sample_2 Cell_19998 Sample_2
    #> 5: SuperCell_174_Sample_Sample_2 Cell_19999 Sample_2
    #> 6: SuperCell_294_Sample_Sample_2 Cell_20000 Sample_2

## Mixing cells from different samples in a supercell

If for whatever reason you don’t mind (or perhaps more to the point want) each supercell to contain cells from different biological samples, you still need to have the sample column in your `data.table`. However, what you need to do is essentially set the value in the column to exactly one unique value. That way, SuperCellCyto will treat all cells as coming from one sample.

Just note, the parallel processing feature in SuperCellCyto won’t work for this as you will essentially only have 1 sample and nothing for SuperCellCyto to parallelise.

## I have more cells than RAM in my computer

Is your dataset so huge that you are constantly running out of RAM when generating supercells? This thing happens and we have a solution for it.

Since supercells are generated for each sample independent of others you can easily break up the process. For example:

1. Load up a subset of the samples (say 1-10).
2. Generate supercells for those samples.
3. Save the output using the qs package.
4. Extract the `supercell_expression_matrix` and `supercell_cell_map`, and export them out as a csv file using `data.table`’s `fwrite` function.
5. Load another sets of samples (say 11-20), rinse and repeat step 2-4.

Once you have processed all the samples, you can then load all `supercell_expression_matrix` and `supercell_cell_map` csv files and analyse them.

If you want to regenerate the supercells using different gamma values, load the relevant output saved using the qs package and the relevant data (remember to note which output belongs to which sets of samples!), and run `recomputeSupercells` function.

## Session information

    sessionInfo()
    #> R version 4.5.1 (2025-06-13)
    #> Platform: x86_64-pc-linux-gnu
    #> Running under: Ubuntu 24.04.3 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    #> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    #>
    #> locale:
    #>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    #>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C
    #>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    #>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    #>  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    #> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    #>
    #> time zone: Etc/UTC
    #> tzcode source: system (glibc)
    #>
    #> attached base packages:
    #> [1] parallel  stats     graphics  grDevices utils     datasets  methods
    #> [8] base
    #>
    #> other attached packages:
    #> [1] BiocParallel_1.43.4 SuperCellCyto_1.1.0 BiocStyle_2.37.1
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] cli_3.6.5           knitr_1.50          rlang_1.1.6
    #>  [4] xfun_0.53           data.table_1.17.8   jsonlite_2.0.0
    #>  [7] buildtools_1.0.0    plyr_1.8.9          htmltools_0.5.8.1
    #> [10] maketools_1.3.2     sys_3.4.3           sass_0.4.10
    #> [13] rmarkdown_2.30      grid_4.5.1          evaluate_1.0.5
    #> [16] jquerylib_0.1.4     fastmap_1.2.0       yaml_2.3.10
    #> [19] lifecycle_1.0.4     BiocManager_1.30.26 compiler_4.5.1
    #> [22] igraph_2.2.1        codetools_0.2-20    Rcpp_1.1.0
    #> [25] pkgconfig_2.0.3     lattice_0.22-7      digest_0.6.37
    #> [28] SuperCell_1.0.1     R6_2.6.1            RANN_2.6.2
    #> [31] magrittr_2.0.4      bslib_0.9.0         Matrix_1.7-4
    #> [34] tools_4.5.1         cachem_1.1.0