CyCombine allows for batch normalization and is available as a task in OMIQ. Batch effects are considered to be non-biological variation between groups of samples.
Pedersen, C.B., Dam, S.H., Barnkob, M.B.et al. cyCombine allows for robust integration of single-cell cytometry datasets within and across technologies. Nat Commun 13, 1698 (2022). https://doi.org/10.1038/s41467-022-29383-5
1. Prepare your Data
1.1. Add Metadata to your Dataset
Batch metadata is required to run CyCombine. Optionally, you can also include metadata on Condition and Anchor (covered in more detail below), though the task can run without this information.
You can find out how to add metadata to your datasets here.
1.2. Perform any Compensation/Unmixing and Scaling Tasks
Prepare your data as you usually would for flow cytometry analysis. Find links to useful resources below:
1.3. Optionally Perform any Gating or Clustering Tasks
In Step (3) below, you have the option of using Filters or Clusters to group similar cells to guide the CyCombine algorithm. In this example we use FlowSOM for clustering, but you can use any clustering task or a gating task, or none at all. Find information on how to perform manual gating here and on how to perform a clustering task here.
2. Add CyCombine task to your Workflow
Click Add new child task and select CyCombine from the task selector. In this example we are using Files generated from a mass cytometer, therefore, no compensation or unmixing is needed. We have chosen to perform FlowSOM clustering because we want to use the clustering data as input in the following step.
Your exact workflow branch may look different than the example above, depending on Steps (1.2) and (1.3). The important thing is that your workflow follows a logical ordering of tasks.
3. Setup and Run CyCombine
3.1. Select Files and Features
Select the Files you want to correct batch effects for. Select the Features you want to include. Note that I have not included physical parameters. Do not include any clustering features that will show in this list, if you performed previous clustering steps.
3.2. Enter CyCombine Settings
Batch Metadata: Add the metadata you entered in Step (1.1) here. This does not need to be called Batch.
Condition (optional): If you have known comparison groups, enter the column containing that metadata here. In this example, we could have included the Condition metadata that you can see in Step (1.1) here.
Anchor (optional): A metadata column that specifies which samples are replicates and which are not.
Select Filter or Cluster to group similar cells (optional): This informs the algorithm where expected groups of similarity exist. This is typically a cluster Feature but can be a Filter, or can be left as None. In this example we have included the cluster feature from the FlowSOM task.
You can include a cluster Feature from any Clustering task, or a Filter from a Gating task in step (1.3).
Generate before/after report (optional): If you want CyCombine to automatically generate histogram plots comparing before and after feature normalization, select this option.
If selected, a PDF file of the before and after histogram plots will be created. This will add to the computational load and computational time. You can also create your own before and after histogram plots using the Figure task.
Enable large dataset processing: Select this option when you have a large dataset. CyCombine will automatically process the features in chunks which helps the algorithm run more effectively.
Enable large dataset processing allows the algorithm to process large datasets more efficiently.
3.3. Run 🏃➡️
Click Run CyCombine. This will take you to the Status tab and you can watch the progress. However, you are free to go back to your workflow or do whatever you please while this runs in the cloud. The status can also be seen in the Workflow itself, or you can have an email sent to you when it is completed.
4. Review your Results
Go to the Results tab to review your Results. Here I have chosen to download the batchcor_plot.pdf to compare the before and after distributions across seven batches. You can see a couple of example plots from the pdf file above.
5. Continue to Build you Workflow
If you are satisfied with the batch normalization results then you can simply continue to build this workflow branch and the normalized Features will be available in downstream tasks.
Useful Tip: Change Channels to Reflect Normalized Values
You can change the feature channels to reflect the normalized values.
Go to the Results Tab. In the Result Columns, open the Rename Result Columns.
Click Configure Names.
Select all Result Columns. Click Submit.
Delete the Secondary Feature Name in the New Name Column, retaining only the Primary Feature Name. For example, in the above image, the feature Dy161Di | LAG3-norm becomes Dy161Di and so on. Click Submit.
Select the Files you want the name change to be applied to. Click Submit.
The features downstream of the CyCombine task will now contain the normalized features.