Welcome to MetaGate!

Install MetaGate

The installation has two steps. First, you need to install R. Then, MetaGate can be installed through R.

Install or upgrade R

MetaGate is an R package, so before you start, make sure that you have R installed on your computer. If you have an old version, installing the most recent version might prevent some problems during installation. You can download R for free from the CRAN website:

• If you are using Mac, go to the R for Mac OS X page and download the file that ends with ".pkg" under "Latest release". When the download is completed, open the file and follow the installation instructions.
• If you are using Windows, go to the R for Windows page and click on the large "Download R x.x.x for Windows" link. When the download is completed, open the file and follow the installation instructions.

After completing the installation, you can open the R application to check if the installation was successful.

If you are using Mac, you might get error messages like "Setting LC_CTYPE failed, using "C"" or "You're using a non-UTF8 locale". If this is the case, run the following command in the R console and restart R: (Read more here)

system("defaults write org.R-project.R force.LANG en_US.UTF-8")

Install MetaGate

Now that you have R installed, MetaGate can be installed. Open an R console and enter the following commands to install MetaGate from the GitHub repository, along with required packages.

if (!require("remotes")) install.packages("remotes")
remotes::install_github("malmberglab/metagate")

During installation, R might ask you questions, like which mirror you want to use (selecting a mirror geographically close to you makes sense) or whether you want to create a personal library (which is usually a good idea if R asks). If you do not know how to respond or if any errors appear, help is very often to be found by googling. If installation seems to be done, you can now start MetaGate.

Launch MetaGate

To load the MetaGate package, enter the following code in R:

library(metagate)

If MetaGate was loaded successfully, it will output "Welcome to MetaGate!". You can now enter the following in R to start MetaGate:

run_metagate()

MetaGate will now launch in your web browser. If your web browser does not open automatically, open it manually and go to the address that was outputted by R.

You can now create your own project or get started using our sample project data.

To exit MetaGate, close the web browser, and hit the ESC key inside the R application. You can then quit R.

Sample data

If you want to try out the features of MetaGate without creating your own project, you can download the MetaGate file used to create all statistics and figures in the article Interactive Analysis of High-Dimensional Cytometry Data with Meta Data Integration (article in submission)

When you have downloaded the DLBCL.metagate file, launch MetaGate and select the DLBCL.metagate file in the Load project box.

FCS files can be downloaded from FlowRepository using accession code FR-FCM-Z6DF.

Create a project

Please follow the instructions provided inside the MetaGate application to create a new project and import your data in MetaGate. Once your project is created, you will have a stand-alone MetaGate file that can be used for visualization and statistical analysis. This file will be considerably smaller than the original FCS files, and while the project creation process can be computationally demanding and potentially time-consuming, the subsequent analysis and visualization will be much simpler and faster.

Some tips and tricks for data import

• If you are using Cytobank for gating, MetaGate will only use your gates, not your populations. Populations are defined inside MetaGate.
• If you are using FlowJo for gating, try to keep your gating hierarchy as simple as possible. See example here. You can then define populations based on these gates later inside MetaGate. It is not strictly necessary to do it this way (you can also import your very complex FlowJo gating hierarchy), but it may simplify the procedure.

  Example: If you have a gating hierarchy with subsets for CD4+ and CD8+ T cells, gates set in one the subsets cannot be used in the other. However, gates set higher up in the gating hierarchy can be used in both subsets.

• After importing your FlowJo workspace file or Cytobank GatingML file, copy or move this to a safe place and avoid editing it. That way, you can go back and look at your gates at later stages in the analysis.
• In MetaGate, when you have defined your populations, export these as an Excel file by clicking on the "Export" button. If you want to import the same or similar data later, you can then import your population definitions.
• In MetaGate, make population names as simple as possible, as these will appear in plots. You can always access the definition for each population inside MetaGate.
• In the last step of the data import procedure, you can change the marker names. Make sure that these names are as simple as possible, as these will appear in your plots.

  Note: If some marker names are spelled differently in your samples, these will be listed as multiple markers in the marker list. To solve this, change the names of these markers so that they become identical.

• Disabling the progress indicator in the last step of the import procedure can speed up the parsing. If you have a small number of FCS files (< 5-10), setting the number of cores to 1 can also potentially speed things up.
• The .metagates file contain all the information that MetaGate needs from the FCS files to make plots and statistical analyses. However, you cannot retrieve raw data from .metagate files or convert them to FCS files. Therefore, never delete your FCS files.

Analyze data in MetaGate

If no project is loaded, start by creating a project following the instructions above, or opening a saved project file by selecting this under Open saved project after launching MetaGate.

Remember to save your project if you want to keep your added meta data or groups. Click on the Save project button on the Project page. Please note that every time you save your project, a new project file will be downloaded, so no project files will be overwritten.

During analysis, yellow boxes with text might appear. These can provide valuable hints for getting further with your analysis. For some labels (e.g. Plot type or Mean bar), a pop-up with additional information will appear when you hold the cursor over it.

Add meta data to your project

In MetaGate, meta data is defined as information about samples. To be able to create groups and analyze your samples, you need to assign some meta data to each sample. This could for example be clinical data (e.g. diagnosis or treatment outcome) or experimental conditions (e.g. timepoint or stimulation type).

1. Select the Meta data page in the main menu.
2. Click on the Download Excel file template. An Excel (.xlsx) file will now be downloaded.
3. Open the Excel file with Microsoft Excel, LibreOffice Calc or any other spreadsheet software.
4. In this file, each row represents one sample, while each column represent a meta data variable (e.g. sex, diagnosis or timepoint). To create a new variable (e.g. sex), find an empty column, write "sex" in the top row, and fill in "male" or "female" for each of the samples. Samples can be identified by the FCS file name in the file column. Do not make the any changes to the file column.

   Note: If you already have an Excel file (or similar) with a list of all your samples and related meta data, you can also use this as a starting point. To do this, create a new column called "file", and fill it with the FCS file names for each sample.

5. Save the file (as .xlsx).
6. Go back to MetaGate, click on the Upload Excel meta file and select the file you just saved.
7. If your upload was successful, you will now see a list of all the meta data variables in the Summary tab of the Meta data page. The Samples tab shows you the meta data for each sample.

   Note: By clicking on the Settings button on the Meta data page, you will be able to choose which meta data variables should be used for different purposes. By default, all variables are used for all purposes, and it is not essential to do any changes here. However, if you have a high number of samples or variables, making appropriate changes here could increase speed and usability of the software.

8. You can now continue to creating groups. If you at any point during analysis want to change the meta data, just download a new template, make adjustments and upload.

   Note: Remember to save your project after adding new meta data. You can do this by selecting the Project page in the main menu and clicking on the Save project button. Be aware that this will download a new project file, so your old file will not be updated.

Create groups based on your meta data

Now that you have assigned some meta data to each sample, you can create groups based on this meta data. Groups let you combine all your meta data variables to enable comparison of very specific selections of samples.

1. Select the Groups page in the main menu.
2. Find an empty row in the table, and start by giving your group a name by typing in the first column.
3. Next, go to the second column to give your group a definition. Do this by selecting options for any of your variables.

   Example: Say that your meta data variables are "sex" (with the options "female" and "male"), and "diagnosis" (with the options "AML", "ALL" and "CML"). Leaving the definition blank will include all samples in this group. Selecting only "sex: male" will include all samples from male patients in the group (regardless of diagnosis). If you select both "sex: male" and "diagnosis: AML", only samples from male AML patients will be included. Selecting "sex: male", "diagnosis: AML" and "diagnosis: ALL" will include samples from male patients with either AML or ALL.

4. When some groups are defined, you can go ahead and create plots. You can go back and add, remove or change groups at any point during analysis.

   Note: If you have spent some time creating groups, it might be worthwhile to save your project. You can do this by selecting the Project page in the main menu and clicking on the Save project button. Be aware that this will download a new project file, so your old file will not be updated.

Note: If you update the meta data, groups and plots will automatically be updated accordingly.

Create plots and statistics

There are five main ways of visualizing data in MetaGate: dot plots, heatmaps, volcano plots, sample clustering and readout correlations. Use the main menu to select between these. Each analysis method is briefly described below.

Dot plots

Dot plots let you analyze single readouts across multiple groups. The readout is selected in the left column. Select one or more groups at the top of the right column. Analysis options and statistical tests varies based on the number of groups you select.

Heatmap

Heatmaps are great for visualizing multiple readouts at the same time. Select readouts in the left column and click on the Add readouts button. Then, select the groups you want to include. If only one group is selected, the heatmap will show the values of each readout with readouts on one axis and populations on the other one. If two groups are selected, the same kind of plot will be showed, but values will instead indicate fold change (or any other comparison method you choose). If more groups are selected, all groups will be showed side by side.

Volcano plots

Volcano plots let you compare multiple readouts between two groups by visualizing both the fold change and the statistical significance. Select readouts in the left column and click on the Add readouts button. Then, select the groups you want to compare in the drop-down menus at the top of the right column. In the volcano plot, each dot represent one readout. The X axis shows fold change (or absolute change), while the Y axis shows the negative base 10 logarithm of the p value.

About statistical testing

MetaGate performs statistical testing based on the number of groups you are comparing. Additionally, when testing mulitple readouts or groups, MetaGate lets you apply various p value adjustment methods. However, it is always the responsibility of the user to make sure that the choice and interpretation of statistical tests is appropriate for the data. You can see the p values and what test MetaGate used by selecting the Data table tab beneath the analysis. Click on the Download data as an Excel file button in the Export tab to look at this table in any spreadsheet software.

Glossary

Some of the technical terms used in MetaGate can be ambiguous. The definitions below are not intended as a suggestions for the correct interpretation of these terms in general, but rather as a guide to how these terms should be understood when using MetaGate.

• Project: A project can be stored in a .metagate file, and a .metagate file can only contain one project. Merging multiple projects will result in one project.
• Gate file: The FlowJo workspace file or the Cytobank GatingML file that was used to define gates when importing data.
• Sample: Equivalent to an FCS file. Analyzing one biological specimen using multiple panels will result in multiple samples.
• Readout: A metric that can be calculated for each sample. A readout is always defined by a marker and a population.
• Marker: A metric that can be calculated in a population. This could be a percentage or a mean, median or geometric mean value of a parameter. Examples: % CD4+ cells, % T cells, mean CD28 expression, median CD28 expression.
• Population: A set of events in sample, defined by one or more gates. Examples: T cells, CD4+, CD57+ CD8+ T cells.
• Bulk: A population created automatically by MetaGate. Includes all events in a sample.
• Parameter: A channel detected by the cytometer.
• Event: A sample contains multiple events, for which one or more parameters is recorded. An event typically represents a cell or a bead.
• Meta data: Categorical or numeric information assigned to each sample. The meta data consists of one categorical og numeric value per variable per sample.
• Variable: A column in the meta data file. Variables can be used to define groups, pair samples or to add annotations to plots. Examples: timepoint, diagnosis, disease stage.
• Group: A set of samples selected based on their meta data.

Questions

Install and launch

Creating projects

run_metagate(populations = 512)

Analyzing data

run_metagate(groups = 20)

Statistics

run_metagate(asterisk_limits = c(0.01, 0.001, 0.0001, 0.00001, 0.000001))

run_metagate(posthoc_limit = 0.05)

Citation and license

How to cite

Please cite the following article:

Ask EH, Tschan-Plessl A, Hoel HJ, Kolstad A, Holte H, Malmberg KJ. MetaGate: Interactive analysis of high-dimensional cytometry data with metadata integration. Patterns. 2024 May;100989. https://doi.org/10.1016/j.patter.2024.100989.

License

MetaGate is licensed under the GNU General Public License v3.0.

Source code

The full source code for MetaGate can be found in the MetaGate GitHub repository.