---
title: Color formatting
---

> [!WARNING]
> Legacy documentation: This documentation applies to **Legacy Deephaven Enterprise only** and does not apply to Core+.

> [!NOTE]
> For Core+ workers, see Community Core documentation for [column formatting](/core/docs/how-to-guides/format-columns/).

## formatColumns

Color formatting can be applied to the contents of an entire column using the `formatColumns` method:

`.formatColumns("columnName=<colorObject>")`

The `columnName` is the name of the column to format, and `<colorObject>` is any of the [valid color objects](#appendix-assigning-colors) available in Deephaven.

The following query will apply the color `VIVID_YELLOW` to all cells in the Sym column:

```python test-set=1
t = db.t("LearnDeephaven", "StockTrades").where("Date=`2017-08-21`")

t2 = t.formatColumns("Sym=VIVID_YELLOW")
```

```groovy test-set=1
t = db.t("LearnDeephaven","StockTrades").where("Date=`2017-08-21`")

t2 = t.formatColumns("Sym=VIVID_YELLOW")
```

![The `Sym` column appears in vivid yellow](../../assets/color-formatting/color1.png)

## Conditional Formatting

### Columns

Deephaven provides methods for applying conditional formatting to only certain rows and/or columns.

The following method formats cells in the named column when a specified condition exists:

`.formatColumnWhere("columnName", "<condition>", "colorValue")`

The following query applies the color `DEEP_GREEN` to the Sym column when the value in the Size column of the same row is greater than 25.

```python test-set=1
t3 = t.formatColumnWhere("Sym", "Size>25", "DEEP_GREEN")
```

```groovy test-set=1
t3 = t.formatColumnWhere("Sym", "Size>25", "DEEP_GREEN")
```

![Every row in the `Sym` column that matches the filter is colored deep green](../../assets/color-formatting/color2.png)

[Ternary statements](../table-operations/conditional.md) can also be used to color cells based on conditional statements. The following colors cells in the Sym column `BRIGHT_GREEN` if the value in the Diff column is positive, and `BRIGHT_RED` if otherwise:

```python
t6 = (
    db.t("LearnDeephaven", "StockQuotes")
    .where("Date=`2017-08-22`")
    .update("Diff = Ask-Bid")
)

t7 = t6.formatColumns("Sym = (Diff > 0) ? BRIGHT_GREEN : BRIGHT_RED")
```

```groovy
t6 =  db.t("LearnDeephaven","StockQuotes")
     .where("Date=`2017-08-22`")
     .update("Diff = Ask-Bid")

t7 = t6.formatColumns("Sym = (Diff > 0) ? BRIGHT_GREEN : BRIGHT_RED")
```

![The `t7` table](../../assets/color-formatting/color3.png)

### Rows

The `formatRowWhere` method formats entire rows when a specified condition exists:

`.formatRowWhere("<condition>", "<colorValue>")`

The following query applies the color `PALE_BLUE` to any row when the value in the Last column is less than 100.

```python test-set=2
t4 = db.t("LearnDeephaven", "StockTrades").where("Date=`2017-08-21`").headBy(2, "Sym")

t5 = t4.formatRowWhere("Last<100", "PALE_BLUE")
```

```groovy test-set=2
t4 = db.t("LearnDeephaven","StockTrades")
     .where("Date=`2017-08-21`")
     .headBy(2, "Sym")

t5 = t4.formatRowWhere("Last<100", "PALE_BLUE")
```

![The `t5` table, with rows where "Last" is less than 100 are pale blue](../../assets/color-formatting/color4.png)

The following colors the entire row `BRIGHT_YELLOW` if the Sym column is equal to the string "AAPL":

```python test-set=2
t8 = t4.formatRowWhere("Sym=`AAPL`", "BRIGHT_YELLOW")
```

```groovy test-set=2
t8 = t4.formatRowWhere("Sym=`AAPL`", "BRIGHT_YELLOW")
```

![The `t8` table, with rows that match the filter statement are now bright yellow](../../assets/color-formatting/color5.png)

The following colors all the cells in every other row `VIVID_PURPLE`:

```python test-set=2
t8 = t4.formatRowWhere("i % 2 == 0", "VIVID_PURPLE")
```

```groovy test-set=2
t8 = t4.formatRowWhere("i % 2 == 0", "VIVID_PURPLE")
```

![The `t8` table above, where rows that match the filter statement are now vivid purple](../../assets/color-formatting/color6.png)

### Combinations

Color methods can also be combined in a table.

The following query colors all cells in every other row `VIVID_PURPLE`, and colors the cells in column C `BRIGHT_YELLOW` in every odd row.

```python test-set=2
t9 = t4.formatRowWhere("i % 2 == 0", "VIVID_PURPLE").formatColumnWhere(
    "Sym", "i % 2 == 1", "BRIGHT_YELLOW"
)
```

```groovy test-set=2
t9 = t4.formatRowWhere("i % 2 == 0", "VIVID_PURPLE").formatColumnWhere("Sym", "i % 2 == 1", "BRIGHT_YELLOW")
```

![The `t9` table, with every other row colored vivid purple and the cells in the `Sym` column of every odd row colored bright yellow](../../assets/color-formatting/color7.png)

## Assigning Colors to Backgrounds and Foregrounds

The field of a cell is the background. The text/numbers showing in the cell is the foreground. Color objects can then be used with the following methods to assign individual color values or combinations to the background and/or foreground:

- `bg()` or `background()` - These methods set the background to a specific color, but do not apply any foreground color.
- `fg()` or `foreground()` - These methods set the foreground to a specific color, but do not apply any background color.
- `bgfg()` or `backgroundForeground()` - These methods set both the background and foreground to specific values.
- `bgfga()` or `backgroundForegroundAuto()` - These methods set the background to a specific color. Deephaven automatically chooses a contrasting foreground color.
- `fgo()` or `foregroundOverride()` - These methods are similar to `fg()` or `foreground()`. However, when either of these methods are used, the color selected will stay applied instead of the highlight color that is automatically assigned when the user highlights the cell or group of cells in the Deephaven console.
- `bgo()` or `backgroundOverride()` - These methods are similar to `bg()` or `background()`. However, when either of these methods are used, the color selected will stay applied instead of the highlight color that is automatically assigned when the user highlights the cell or group of cells in the Deephaven console.

> [!CAUTION]
> Overriding the foreground or background colors may result in not being able to see the highlighted content. Care in use is suggested.

The following query generates a table with an orange background using RGB values:

```python test-set=3
t = db.t("LearnDeephaven", "StockTrades").where("Date=`2017-08-21`")

t10 = t.formatRowWhere("true", "bg(colorRGB(255,93,0))")
```

```groovy test-set=3
t = db.t("LearnDeephaven","StockTrades").where("Date=`2017-08-21`")

t10 = t.formatRowWhere("true","bg(colorRGB(255,93,0))")
```

> [!CAUTION]
> If you want to use hex color specifications with `formatRow`, note that two different types of quotes are needed around the color.
>
> ``t10 = t.formatRowWhere("i % 7 == 0", "`#87CEFA`")``

The following query generates a table with a purple foreground using RGB values:

```python test-set=3
t11 = t.formatRowWhere("true", "fg(colorRGB(102,0,204))")
```

```groovy test-set=3
t11 = t.formatRowWhere("true","fg(colorRGB(102,0,204))")
```

The following query will color the Sym column with a hot pink background and a yellow foreground.

```python test-set=3
t12 = t.formatColumns("Sym = bgfg(colorRGB(255,105,80),colorRGB(255,255,0))")
```

```groovy test-set=3
t12 = t.formatColumns("Sym = bgfg(colorRGB(255,105,80),colorRGB(255,255,0))")
```

The following query generates a table with a navy blue background and automatically selects a contrasting foreground.

```python test-set=3
t13 = t.formatColumns("* = bgfga(colorRGB(0,0,128))")
```

```groovy test-set=3
t13 = t.formatColumns("* = bgfga(colorRGB(0,0,128))")
```

![`t10`, `t11`, `t12`, and `t14` from the above queries, displayed side-by-side](../../assets/color-formatting/color8.png)

### Heat Maps

Color-based formatting can also be used to create heat maps in Deephaven tables:

`heatmap(<colName>, <minimumValue>, <maximumValue>, <minimumBackgroundColor>, <maximumBackgroundColor>)`

The following query will apply color to the Price column as follows:

- When the value is less than or equal to 10.00, `BRIGHT_GREEN` will be used,
- When the value is greater than or equal to 100.00, `BRIGHT_RED` will be used, and
- An automatically interpolated color proportionally between `BRIGHT_GREEN` and `BRIGHT_RED` will be used for all other values between 10 and 100.

```python
t4 = db.t("LearnDeephaven", "StockTrades").where("Date=`2017-08-21`").headBy(2, "Sym")

t14 = t4.formatColumns("Last = heatmap(Last, 10.00, 100.00, BRIGHT_GREEN, BRIGHT_RED)")
```

```groovy
t4 = db.t("LearnDeephaven","StockTrades")
     .where("Date=`2017-08-21`")
     .headBy(2, "Sym")

t14 = t4.formatColumns("Last = heatmap(Last, 10.00, 100.00, BRIGHT_GREEN, BRIGHT_RED)")
```

![The `t14` table, with the `Last` column formatted with a heatmap](../../assets/color-formatting/color9.png)

Options are also available for `heatmapFg()` and `heatmapForeground()`. When either of these methods is used, the heatmap color pair listed in the argument is applied only to the foreground.

### Distinct Coloration

Colors can be applied to collections of values to create distinct and unique coloration for better visualization. Applying specific colors individually to each distinct value could be accomplished through iterative `formatColumns` methods. However, Deephaven offers a more convenient process using the `DistinctFormatter` method.

This object works by mapping input values to a list of predetermined and unique colors.

For example, the following query assigns unique colors to the values in the Exchange column.

```python
from deephaven import DistinctFormatter

t15 = (
    db.t("LearnDeephaven", "StockTrades")
    .where("Date=`2017-08-21`")
    .headBy(1, "Exchange")
)


colorMe = DistinctFormatter()
t16 = t5.formatColumns("Exchange = colorMe.getColor(Exchange)")
```

```groovy
import com.illumon.iris.db.util.DBColorUtilImpl.DistinctFormatter
t15 = db.t("LearnDeephaven","StockTrades")
     .where("Date=`2017-08-21`")
     .headBy(1, "Exchange")

colorMe = new DistinctFormatter();
t16 = t5.formatColumns("Exchange = colorMe.getColor(Exchange)")
```

![The table above, formatted so that each unique value in the `Exchange` column has a unique color](../../assets/color-formatting/color10.png)

## Combining Numeric and Color Formatting

The methods used above can also be combined by chaining the arguments to the `formatColumns` methods.

```python
t17 = (
    db.t("LearnDeephaven", "StockQuotes")
    .where("Date=`2017-08-25`")
    .update("Diff = Bid-Ask")
    .headBy(1, "USym")
)

t18 = t17.sort("Diff").formatColumns(
    "Diff=Decimal(`###.00`)", "Diff=heatmap(Diff, -1, 1, VIVID_RED, VIVID_GREEN)"
)
```

```groovy
t17 = db.t("LearnDeephaven", "StockQuotes").where("Date=`2017-08-25`").update("Diff = Bid-Ask").headBy(1, "USym")

t18 = t17.sort("Diff").formatColumns("Diff=Decimal(`###.00`)", "Diff=heatmap(Diff, -1, 1, VIVID_RED, VIVID_GREEN)")
```

This query will:

- sort the table in descending order based on the values in the Diff column ,
- format the values in the Diff column rounded to two decimal places, and
- apply a color heat map to the Diff column ranging from vivid red to vivid green as the values of the column move from most negative to most positive.

![The above table - sorted and formatted with a heat map in the `Diff` column](../../assets/color-formatting/color11.png)

## Appendix: Assigning Colors

Colors can be assigned in Deephaven tables or plots using strings or by using color objects.

### Named Color Values

There are 280 predefined color values available in Deephaven.

> [!NOTE]
> See:
> [Named Colors Chart](../../assets/color-formatting/Deephaven_Colors.pdf)

These predefined colors are referred to by their names, which must be typed in capital letters.

Because these values are considered strings, they must be enclosed in quotes. If the named color values are to be used within another string (i.e., a string within a string), the name must be enclosed in backticks.

_Examples_

`.pointColor("SKYBLUE")`

``.formatColumns("Date=`SKYBLUE`")``

### HEX (Hexadecimal)

Hexadecimal values are specified with three values that correspond to RRGGBB. Each value [RR (red), GG (green) and BB (blue)] are hexadecimal integers between 00 and FF, and they specify the intensity of the color. All Hex values are preceded with a pound sign, e.g., #0099FF.

Because these values are considered strings, they must be enclosed in quotes. If the HEX color values are to be used within another string (i.e., a string within a string), the name must be enclosed in backticks.

_Examples_

`.pointColor("#87CEFA")`

``.formatColumns("Date=`#87CEFA`")``

### Applying Color with Color Objects

Color objects can be created using any of the color models listed below.

- [Predefined Color Variables](#predefined-color-variables)
- [String Values](#string-values)
- [RGB (Red, Green, Blue)](#rgb-red-green-blue)
- [RGBA (Red, Green, Blue, Alpha)](#rgba-red-green-blue-alpha)
- [HSL (Hue, Saturation, Lightness)](#hsl-hue-saturation-lightness)
- [HSLA (Hue, Saturation, Lightness, Alpha)](#hsla-hue-saturation-lightness-alpha)

#### Predefined Color Variables

Deephaven offers a set of predefined color variables that can be used as color objects in your queries:

`COLOR_<NAMEDCOLOR>`

The value used for `<NAMEDCOLOR>` can be any of the named color values described above. Examples include: `COLOR_RED`, `COLOR_GREEN`, `COLOR_VIVID_PURPLE`, etc. As with the named color values, the predefined color variables must be typed in capital letters.

_Examples_

`.lineColor(COLOR_SKYBLUE)`

`.formatColumns("Date=COLOR_SKYBLUE")`

#### String Values

Named color values and HEX color values can also be converted into color objects in Deephaven by enclosing their values (as strings) into the argument of the `color` method.

The syntax follows:

``color(`<COLORNAME>`)``

``color(`#RRGGBB`)``

_Examples_

``.lineColor(color(`SKYBLUE`))``

``.lineColor(color(`#87CEFA`))``

``.formatColumns("Date=color(`SKYBLUE`)")``

``.formatColumns("Date=color(`#87CEFA`)")``

#### RGB (Red, Green, Blue)

RGB values are represented numerically with comma-separated values for red, green and blue respectively, with each value expressed as integers in the range 0-255 or floats in the range 0-1.

RGB color values can be converted into color objects in Deephaven by enclosing their values into the argument of the `colorRGB` method.

The syntax follows:

`colorRGB(int r, int g, int b)`

`colorRGB(float r, float g, float b)`

_Examples_

`.lineColor(colorRGB(135, 206, 250))`

`.formatColumns("Date=colorRGB(135, 206, 250)")`

#### RGBA (Red, Green, Blue, Alpha)

The RGBA color model is based on RGB. However, RGBA provides an option for a fourth value to specify alpha (transparency). As with RGB, the numeric values can be specified using floats or ints. The numeric ranges for RGB remain the same. The alpha channel can range from 0 (fully transparent) to 255 (fully opaque) for ints, and 0.0 to 1.0 for floats.

RGBA color values can be converted into color objects in Deephaven by enclosing their values into the argument of the `colorRGB` method.

The syntax follows:

`colorRGB(int r, int g, int b, int a)`

`colorRGB(float r, float g, float b, float a)`

_Examples_

`.lineColor(colorRGB(255,0,0,100))`

`.formatColumns("Date=colorRGB(135, 206, 250, 50)")`

#### HSL (Hue, Saturation, Lightness)

HSL values are represented numerically with comma-separated values for hue, saturation and lightness respectively. Hue is the degree on the color wheel, and can range from 0 to 360. Saturation is the percentage of value. Lightness is also a percentage, with 0% being black, and 100% being white. The numeric values for HSL can only be specified using floats.

HSL color values can be converted into color objects in Deephaven by enclosing their values into the argument of the `colorHSL` method.
The syntax follows:

`colorHSL(float h, float s, float l)`

_Examples_

`.lineColor(colorHSL(0.56, 0.92, 1.75))`

`.formatColumns("Date=colorHSL(0.56f, 0.92f, 1.75f)")`

#### HSLA (Hue, Saturation, Lightness, Alpha)

The HSLA color model is based on HSL. However, HSLA provides an option for a fourth value to specify alpha (transparency). As with HSL, the numeric values must be specified using floats. The numeric ranges for HSL remain the same. The alpha channel can range from 0.0 (fully transparent) to 1.0 (fully opaque).

HSLA color values can be converted into color objects in Deephaven by enclosing their values into the argument of the `colorHSL` method.

The syntax follows:

`colorHSL(float h, float s, float l float a)`

_Examples_

`.lineColor(colorHSL(0.56, 0.92, 1.75, 0.75))`

`.formatColumns("Date=colorHSL(0.56f, 0.92f, 1.75f, 0.5f)")`