HOME  ›   visualization
If your question is not answered here, please email us at:  ${email.software}

Space Ranger


Loupe

10x Genomics
Visium Spatial Gene Expression

Space Ranger6.4 (latest), printed on 12/22/2024

Navigating the Loupe Browser Interface

Table of Contents

Loupe Browser 4.0 and later provides functionality to analyze and visualize spatial datasets. Loupe Browser 5.1 onwards is required to access the spatial enrichment table. To learn how to navigate the Loupe Browser interface, a pre-loaded mouse brain dataset is used to demonstrate the interactive functionality. Follow these steps to access this dataset. To return to the home screen and the Recent Files list, click in the top left corner.

Components of the interface

The following image provides an overview of the key components of the Loupe Browser interface. Each of these components are described in more detail below.

Mouse Selector

The Mouse Selector has three options from left to right:

Tool Description
Pan - Move the image up and down, or left and right.
Polygonal Selection - Select and label an image area within a region of your choosing. Hovering over the button will allow you to choose either a freehand or rectangular selection.
Draw Selection - Select and label individual spots using a brush tool.

Toolbox

The Toolbox is on the left side of the window and contains tools that perform the functions listed in the table below.

Tool Description
Zoom In and Zoom Out - Click on + to Zoom In, click on − to Zoom Out, or use the slide bar to zoom in and out. In Spatial mode, the current magnification level is shown.
Autoscale - Reverts to default zoom and position that fits the screen after zooming in or out or moving the image/plot around.
Save - Save changes to the .cloupe file.
Export Plot - Export the spatial image or the scatter plot (UMAP, t-SNE, Feature Plot) in SVG or PNG format.
Marker Settings - This option can be used with t-SNE, UMAP and Feature Plot views to scale marker size. Uncheck the Auto-scale box and use the slider to move to desired size.

Data Panel Selector

The Data Panel Selector tools are on the bottom left of the window. They are used to change the information located in the Data Panel at the bottom of the window. The tools perform the functions listed in the table below.

Tool Description
Heat Map - Two dimensional representation of the significant features for each cluster. The colors represent the feature log2 fold change.
Feature Table - Lists the top differentially expressed genes across the clusters in a tabular format.
Spatial Enrichment - Represents the Moran's I values, UMI counts and Spots in tabular format.
Violin Plots - Hybrid of box plot and kernel density plot across all clusters shown for one or more selected active features.
Hide Bottom Panel - Choose this to minimize the tool options in the Data Panel Selector.

Data Panel

The data panel on the bottom of the workspace displays information about the features driving differences between clusters. It enumerates the genes that drive differences between the current precomputed clustering selected in the Categories sidebar. It also displays the results of a Significant Features analysis.

The tools in the data panel selector allows for different views. Clicking on a feature name in the table view allows you to add that feature to a list for future reference, or to show counts of that feature across the dataset in the active projection. To expand the viewable area of the data panel, use your cursor to drag the top border of the panel up. Drag it down to reduce the size.

View Selector and View-Dependent Controls

The View Selector controls what is displayed in the View Panel. There are three different types of views that can be selected:

Multiple concurrent views of the same data can be viewed via linked windows on the desktop. For example, a Spatial projection can also be opened alongside a t-SNE, UMAP, or Feature Plot view. Changes made in any of the linked windows are seen in all open linked windows.


Linked windows can be opened through the View Selector. Icons shown in the following table explain how to use linked windows.

Tool Description
Click on the icon to see a list of linked windows for the current projection.
This icon is seen in the View Selector to indicate what projections can be opened from the current view. It is also seen in new projection windows.
Linked windows open in a small size. Use this icon to open the window to full size or toggle back to the smaller size.

A few navigational elements are now view-dependent. The following sections underline the differences between views.

Spatial view

When a Spatial Gene Expression .cloupe file is opened, the initial workspace is centered around the Spatial view, which shows the tissue image overlayed by the tissue covered spots on the slide. The spots have already been aligned to the correct positions in the image. Each spot is color-coded based on the active legend in the Mode Panel.


In the Spatial view, one can drag the mouse over the image to reposition it, and use the mouse wheel or track pad to smoothly zoom in and out. The cluster label associated with a spot is shown when you hover your mouse over that spot in the image.

Spatial image settings

Spatial image settings, located in the top left corner, provides a number of options to view the image and gene expression data. The visibility of spots can be changed from opaque to fully transparent using the slider. Clicking offers more image settings options including:


There are additional controls for multi-channel fluorescence images:

UMAP and t-SNE views

Space Ranger and Cell Ranger pipelines calculate t-SNE and UMAP projections over expression data. Loupe Browser shows these scatter plots. When a UMAP, t-SNE or custom coordinate projection is shown, a Split View selector is visible in the upper-left hand corner of the interface. Like the Spatial View, each spot is color-coded based on the active legend in the Mode Panel.


In t-SNE and UMAP views, dragging the mouse over the display area repositions the projection, and the mouse wheel or track pad can be used to smoothly zoom in and out. The cluster label associated with a spot is shown when you hover your mouse over that spot in the image.

Feature Plot view

The Feature Plot view allows you to visualize the expression levels of one or two genes for each spot. This view makes it easy to threshold sets of spots based on the level of expression of one or two genes. Features, in this case genes, can be entered in the text box at the top of the Y axis or on the right side of the X axis. Click to change the scale of the axis between linear and log scale.


Import projections

There are many scripts and third-party tools that can be used to generate different projections of the data including but not limited to the following:

If you generate alternate projection coordinates from customer analysis, you can input that projection into Loupe Browser. To do this, click in the View Selector to import a CSV file to use a custom projection for a dataset.


The CSV format for importing projections is as follows:

Here is an example CSV file generated using Harmony batch effect correction algorithm between two datasets:

Barcode,UMAP_1,UMAP_2
AAACAAGTATCTCCCA-1,8.07877147981845,-0.0187730615722626
AAACAGAGCGACTCCT-1,4.9019435722562,5.21225776022797
AAACAGTGTTCCTGGG-1,-4.84007798841275,-1.70023451501007

To import new projections, click on Import Projection, select the CSV file, and click on Import Projection. Once a custom projection is uploaded, click on Import Projection again to edit the name of the projection, or to delete it.

Mode Selector and Mode Panel

Use the mode selector in the top right corner of the workspace to switch between Loupe Browser's different modes. Switching between modes applies mode-specific coloring to the View Panel, and changes mode-specific functionality to the Mode Panel. There are four modes in Loupe Browser:

Categories mode

The view in categories mode defaults to the Space Ranger pipeline generated analysis including graph-based and K-Means clustering for Gene Expression. Additional user defined or imported custom clusters appear under Other Categories in the drop down menu.

In Categories mode, you can control the content in the mode panel by clicking next to the drop-down menu. The options are explained in the table below.

Option Description
New Category - Use this option to create a custom category and associated custom clusters.
Edit Category Name - This option is only applicable to custom categories.
Delete Category - This option is only applicable to custom categories.
Import Categories - Use this option to upload a CSV file that contains customer cluster definitions on a per-barcode basis. The format of the CSV file is as follows:
  • The first row must be a header, such as Barcode, Cell Type, etc.
  • The first column must be barcode and the column’s contents must match at least a subset of the barcodes in the .cloupe file
  • After the barcode column there may be an arbitrary number of columns corresponding to different types of categories.
  • Each additional column must have a unique category name and the column’s contents are cluster labels.
    		•
    Export [Name of Category] - Use this option to export a CSV file with complete list of barcodes for the current Category and the associated cluster names in that Category. For this option, the [Name of Category] reflects the name of the current Category in view. Example file for graph-based clustering:

    Barcode Graph-based
    AAACAAGTATCTCCCA-1Cluster 3
    AAACAATCTACTAGCA-1Cluster 2
    AAACACCAATAACTGC-1Cluster 1
    Show All Clusters - This option automatically selects all clusters in the Mode Panel.
    Hide All Clusters - This option automatically deselects all clusters in the Mode Panel.

    Significant Feature Comparison

    The Significant Feature Comparison functionality determines what features in the dataset distinguish one or more clusters, and allows differential expression analysis between clusters. There are two types of controls for this functionality: (a) analysis method (b) feature type. For Spatial Gene Expression datasets, option for feature type is Gene for single library analysis. Select options for these two controls using the drop-down menus in the bottom right-hand corner. Once options are selected, click on to execute the comparative analysis. Refer to Explore Spatial Clusters tutorial to learn more. To learn more about the statistical methods used for calculating these results refer to the Secondary Analysis section of the algorithms page.

    Gene/Feature Expression mode

    The Gene/Feature Expression mode provides a graphical representation of gene or feature expression across a dataset. The Active Feature List contains a list of the features that have been either searched for, or uploaded. One or more features can be viewed at a time. To learn more about the feature, hover over the feature name and click to load the Ensembl reference page in the browser.

    The expression patterns of the features are displayed in the View Panel. If more than one feature is in the Active Feature List, then the expression pattern corresponds to a combination of all the features. If only one feature is present or selected in the Active Feature List, then the expression pattern corresponds to that feature. Refer to Evaluate Gene Markers tutorial to explore utility of this feature.

    The content of the Active Feature List can be changed by clicking next to the drop-down menu. This gives a number of options, as described below.

    Option Description
    New List - Use this option to create a custom list of features to visualize.
    Edit Name - Edit the name of a list.
    Delete List - Delete a list.
    Import Lists - Use this option to upload a CSV file that contains a custom set of markers that results in one or more new lists. The format of the CSV file is as follows
  • The first row must be a header such as List Name, Gene Name, etc.
  • The first column can contain the name of more than one Feature Lists that will be created. For example importing a CSV of this format will create two lists CA1 and DG.

    List Name
    CA1Spink8
    CA1Lefty1
    DGC1ql2
    DGNr3c2
  • The second column is a list of the feature names, such as gene names associated with each list.
  • You can optionally include the Ensembl IDs in a third column.
  • The feature names and Ensembl IDs, if applicable, must match those that were in the reference file that was passed into Space Ranger.
    		•
    Export Lists - If you have manually added features to a list, use this option to export the list of features as a CSV file. This is useful if you want to reuse a list for other samples visualized in Loupe. Example file from feature search:

    Barcode Graph-based ID FeatureType
    Active Feature ListMap2ENSMUSG00000015222Gene Expression
    Active Feature ListMbpENSMUSG00000041607Gene Expression
    Active Feature ListGfapENSMUSG00000020932Gene Expression

    Controlling the Gene/Feature Expression mode

    At the bottom of the Active Feature List there are a number of options that control how the data is visualized in the View Panel. Click to learn more about these controls.

    The Scale & Attribute parameters control how the expression patterns are rendered in the View Panel. The top left menu sets which scale value to display. The top right menu sets how to combine values when there are multiple features in the Active Feature List. The Select by Count controls how to filter the expression values displayed.


    The color palette in the bottom right controls the color scale and range of values. You can change the color scale using the drop down menu. You can also choose to manually set the min and max of the color scale by unchecking the Auto-scale checkbox, typing in a value, and clicking the .

    When setting manual min and max values, barcodes with values outside the range, less than the minimum or greater than the maximum, are colored gray. This is particularly useful if there is a lot of noise or ambient expression of a gene. Increasing the minimum value of the scale filters that noise. It is also useful to configure the scale to optimally highlight the expression of genes of interest.


    Filters mode

    In Filter mode, you can compose complex boolean filters to find barcodes which fulfill your criteria. You can create rules based on feature counts or cluster membership and combine these rules using boolean operators. You can then save and load filters and use them across multiple datasets. For more details on using the Filter Mode, refer to the Characterize Substructure tutorial.


    Click next to the drop-down menu to change the filter content with options described below:

    Option Description
    New Filter - Use this option to create a custom filter.
    Edit Filter Name - Edit the name of an existing filter.
    Delete List - Delete a filter.
    Import Filters - Import a previously created filter in Loupe Browser in JSON format. Manual creation of filters is not recommended as the JSON specification is Loupe Browser dependent and is subject to change.
    Export Filters - Export the filter in JSON format. This provides a useful way to apply a generalized filter across multiple datasets.