Color Mapping

Core Feature

This feature is available in all Portrai Explorer deployments.

Color mapping assigns colors to data points based on feature values, allowing you to visualize patterns and distributions in your spatial transcriptomics data.

Selecting a Color Basis

From the Feature List

1. Open the Explorer extension
2. In the Sidebar, browse the Features list
3. Click on a feature name to apply it as the color mapping
4. The map updates immediately with the new coloring

Feature Tabs

Switch between tabs to find the coloring you need:

Tab	Use For
Metadata	Cell types, clusters, quality metrics
Genes	Gene expression
User	Columns added with Import Metadata
Signatures	Combined scores of several variables

Each tab lists categorical and continuous columns together. See Features for details.

Categorical Color Mapping

When you select a categorical feature, each category receives a distinct color.

Legend

The map has no on-screen legend. The Detail Panel's category list is the color reference: each row shows a category's color box, its name and how many of its points pass the Subset and the current selection (hover a row for the filtered and total counts). A legend with the category names and colors is added only to PNG captures of the map.

Interacting with Categories

• Hover over a category in the Detail Panel to show only that category on the map; the other points are hidden until you move off. With a lasso or brush selection active, only the category's selected points are shown.

Customizing Category Colors

You can customize the color assigned to any category to better distinguish groups or match your publication standards.

How to Change a Category Color

1. Click the color box next to any category in the Detail Panel
2. A color picker popover appears with three selection methods:

Method	Description
Preset Palette	Choose from 20 curated colors designed for data visualization
HEX Input	Enter a specific HEX color code (e.g., #FF5733)
Native Picker	Click the color swatch to open your system's color picker

3. Select a color - the map updates immediately
4. Click outside the popover to close it

Identifying Custom Colors

Categories with custom colors display a highlighted border around their color box, making it easy to see which colors have been modified from the default colormap.

Resetting Colors

• Click the Reset button in the color picker to restore the category to its default colormap color
• This removes the custom color and re-applies the global categorical colormap

Color Persistence

Custom category colors are saved to your browser's local storage:

• Colors persist across sessions
• Colors are specific to each feature (changing colors for "cell_type" doesn't affect "cluster")
• Clearing browser data resets all custom colors

Continuous Color Mapping

When you select a continuous feature, values are mapped to a color gradient.

Color Gradient

The default gradient maps:

• Low values → One end of the color scale
• High values → Other end of the color scale

Legend

The map shows no colorbar on screen. In the Detail Panel, the histogram's bars are colored along the color scale, with the Min and Max values beneath it; hovering a bar shows only the points in that value range, the same way hovering a category does.

PNG captures of the map add a colorbar with:

• Color gradient bar
• Evenly-spaced tick marks with nicely-rounded value labels along the bar (not only the minimum and maximum)

The tick labels are generated to be readable round numbers and adapt to the colorbar height, so the legend reflects the full mapped value range rather than just its endpoints.

Adjusting Color Range

On the map, the color scale of a continuous feature spans its whole value range; there are no minimum and maximum controls. What you can adjust is the cutoff described below, which removes the cells at or below a chosen value, and the scale type, which changes how the values in between map to colors.

Why Adjust Range?

• Highlight differences - Try another scale type to see subtle variations
• Handle outliers - A few very high values compress the color scale; a Log1p or Sqrt scale spreads the lower values over more of the colors
• Focus on relevant values - Set the cutoff to a biologically meaningful threshold

Cutoff Adjustment

Use the Cutoff slider in the Detail Panel to remove the cells with low values. Only the cells above the value shown beside Apply, for example (> 1.25), are kept. Moving the slider also checks Apply; uncheck Apply to turn the cutoff off. To type a value instead, click that value.

• Adjust the cutoff percentage (0-50% of the value range) to filter out low-expressing cells
• Useful for highlighting cells with significant expression
• Applied before the color scale transformation

While Apply is checked, the cells at or below the cutoff are removed from the map and the plots, and left out of the counts and Download Selected Data. In that the cutoff behaves like a Subset condition rather than a color setting.

The cutoff is one setting for all features, not one per feature: coloring by another continuous feature applies the same percentage to it, and coloring by a categorical feature applies none. A Signature score has a cutoff of its own, in its Detail Panel, which removes cells the same way.

Colormap Selection

Portrai Explorer provides separate colormaps for continuous and categorical features.

Global Colormap Settings

The default colormaps are configured in Settings (accessible via the gear icon in the Activity Bar). Changes to the global colormap affect all visualizations throughout the application.

See Preferences for detailed configuration options.

Available Colormaps

Continuous Colormaps

Sequential - Best for expression data:

Colormap	Best For
Cool	General expression (default)
Viridis	Perceptually uniform
Inferno	High contrast, dark theme
Plasma	Vivid color range
Magma	Subtle gradients
Cividis	Color blindness friendly
Turbo	High contrast rainbow
Blues/Greens/Reds/Purples	Single-hue emphasis

Diverging - Best for data with a center point:

Colormap	Best For
Red-Blue	Fold change visualization
Red-Yellow-Green	Three-way comparison
Red-Yellow-Blue	Temperature-like scale
Brown-Blue-Green	Earth tones
Pink-Yellow-Green	Soft diverging
Spectral	Multi-color diverging

Categorical Colormaps

Colormap	Best For
Rainbow	Many categories (default)
Sinebow	Smooth color transitions
Turbo	High contrast distinct colors

Choosing a Colormap

Consider:

• Feature type - Use continuous colormaps for numeric values, categorical for discrete groups
• Accessibility - Viridis and Cividis work better for color blindness
• Contrast - Dark background may need different colors than light
• Consistency - Use global settings for uniform appearance across views

Signature Coloring

Color by computed signature scores instead of individual features.

How to Use

1. Create a signature with genes of interest

2. Select the signature for coloring

3. Choose a combination method:

   Method	Use Case
   Max	Highlight cells expressing any gene highly
   Min	Find cells expressing all genes
   Sum	Total expression across gene set
   Avg	Average expression level
   UMI Count	Normalized expression

4. The map colors by the computed score

Scale Types

For continuous data, different scale types affect how values map to colors.

Scale	Description	Use When
Linear	Direct mapping	Most cases (default)
Log	Natural logarithm	Wide value ranges (requires min ≥ 0)
Log2	Base-2 logarithm	Wide value ranges (requires min ≥ 0)
Log1p	log(x+1) transformation	Single-cell RNA-seq data
SymLog	Symmetric log	Data with zero or negative values
Sqrt	Square root mapping	Moderate compression
Power	Squared mapping	Emphasize large values

Changing Scale Type

1. Look for the scale selector in color settings
2. Choose the appropriate scale - each option shows a short description beneath its label to help you pick a transformation suited to your data
3. The coloring updates to reflect the new scale

TIP

Log and Log2 scales are disabled when the minimum value is negative. Use SymLog or Log1p for data that includes zero or negative values.

Tips for Effective Coloring

For Cell Type Analysis

1. Use categorical coloring with cell type features
2. Check that colors are distinguishable
3. Hover categories in the Detail Panel to verify identifications

For Gene Expression

1. Start with linear scale
2. Set a cutoff to focus on expressing cells
3. Try log scale if expression varies widely
4. Compare multiple genes by switching quickly

For Finding Patterns

1. Try different colormaps to see patterns
2. Try another scale type to maximize contrast
3. Combine with spatial/embedding views
4. Use subsets to reduce noise

Troubleshooting

All Points Same Color

• Check if feature has variation
• Try another scale type, for example Log1p when a few high values dominate
• Verify data is loaded correctly

Colors Too Similar

• Try a different colormap
• Use log scale for compressed ranges

No Legend on the Map

• The map draws no legend on screen; use the Detail Panel's category list or histogram as the color reference
• Ensure a feature is selected, so the Detail Panel has something to show
• Capture a PNG to get the map with a legend beside it

Related Topics

• Features - Browse available features
• Facet View - Compare the color scale across categories
• Signatures - Create gene groups
• Layer Settings - Adjust point appearance
• Image Adjustments - Modify background image