# FeatureColor

Auto-generated from the config schema in the source. See the [config guide](https://jbrowse.org/jb2/docs/config_guide) for concepts. Built into JBrowse core. [View source](https://github.com/GMOD/jbrowse-components/blob/main/packages/display-kit/src/colorConfigSchema.ts).

The feature displays' `encoding.color`: a CSS color or `jexl:`
callback in `value`, or a field whose values each take a range color, whose
numbers each take the color of the interval between cut points they fall
in, or whose numbers run along a color ramp, with a key. A string is the
field; a written field always paints. `scale.type: "identity"` keeps each
feature's color, whether a file's itemRgb or what a `value` callback
returns, and names the colors `scale.domain` lists in the key. Like UCSC's
`itemRgb on`, it paints an itemRgb of `0,0,0` or `0` black, which otherwise
reads as no color, and reads a comma-free itemRgb as a packed integer.

## Example usage

```js
{ type: 'LinearBasicDisplay', encoding: { color: { value: 'goldenrod' } } }
```

```js
{
  type: 'LinearBasicDisplay',
  encoding: {
    color: { field: 'gene_biotype', scale: { range: ['#1f77b4', '#ff7f0e'] } },
  },
}
```

```js
{
  type: 'LinearBasicDisplay',
  encoding: {
    color: {
      field: 'type',
      scale: {
        domain: ['prophage', 'plasmid'],
        range: ['#d95f02', '#1b9e77'],
        unknown: '#cccccc',
      },
    },
  },
}
```

```js
{
  type: 'LinearBasicDisplay',
  encoding: {
    color: {
      field: 'score',
      scale: {
        type: 'threshold',
        domain: [0.5, 0.9],
        range: ['#c6dbef', '#6baed6', '#08519c'],
      },
    },
  },
}
```

```js
{
  type: 'LinearBasicDisplay',
  encoding: { color: { field: 'score', scale: { scheme: 'viridis', domainMin: 0 } } },
}
```

```js
{
  type: 'LinearMultiRowFeatureDisplay',
  encoding: {
    color: {
      scale: {
        type: 'identity',
        domain: ['rgb(255,0,0)', 'rgb(0,128,0)'],
        names: ['Active TSS', 'Strong transcription'],
      },
    },
  },
}
```

## Preset fields

A `field` named here paints through its own scale while `scale.type` is unset, and `range` and `names` index its levels in order while `domain` is unwritten. Any other field is ordinal.

| Field | Scale | Levels | Names | Other defaults |
| --- | --- | --- | --- | --- |
| `strand` | ordinal | `1`, `-1`, `0` | Forward strand, Reverse strand, No strand | `range`: `tomato`, `cornflowerblue`, `goldenrod` |
| `svType` | ordinal | `DEL`, `DUP`, `INS`, `INV`, `CNV`, `TR`, `BND`, `CPX`, `OTHER` | Deletion, Duplication, Insertion, Inversion, Copy-number variable, Tandem repeat, Breakend / translocation, Complex, Other / mixed | `range`: `#e41a1c`, `#377eb8`, `#800080`, `#ff7f00`, `#7e6148`, `#e7298a`, `#17becf`, `#66a61e`, `#000000`; key "SV type" |
| `impact` | ordinal | `HIGH`, `MODERATE`, `LOW`, `MODIFIER`, `Unannotated` |  | `range`: `#d32f2f`, `#f57c00`, `#fbc02d`, `#9e9e9e`, `#607d8b`; key "Consequence impact" |
| `score` | linear |  |  |  |

## Config slots

A setting written to it replaces it whole: a member left out returns to its default. Slot types (`fileLocation`, `frozen`, ...) are explained in the [config slot types reference](https://jbrowse.org/jb2/docs/config_guides/slot_types). Slots a base configuration contributes are listed here too, so this table is the whole surface.

| Slot | Description |
| --- | --- |
| **value**<br>[`maybeColor`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | A CSS color, or a jexl callback over `feature` returning one. Unset, a feature's own BED itemRgb paints it if it has one, else goldenrod. Alignments' `value` is constant-only; here a callback stays, since the worker evaluates it per box, where a `field` reads the transcript.<br>_callback args:_ `feature` |
| **scale**<br>[FeatureColorScale sub-schema](#slot-scaletype) | How the field's values map to colors, Vega-Lite's scale object. |
| **legend**<br>[FeatureColorLegend sub-schema](#slot-legendtitle) | The key this channel draws. |
| **field**<br>[`featureField`](https://jbrowse.org/jb2/docs/config_guides/slot_types#featurefield) = <code>''</code> | a feature field, or a jexl expression over feature, whose values each take one range color, with a key; a transcript and its parts paint the transcript's value, or its gene's where the transcript has none; strand paints forward tomato and reverse cornflowerblue unless scale.domain or scale.range says otherwise |
| **scale.type**<br>[`maybeStringEnum`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) (ordinal, threshold, linear, log, identity) | ordinal a range color per value of field; threshold a range color per interval between the cut points in domain; linear or log a color along a ramp from domainMin to domainMax; identity paints each feature's own color, as a channel with no field does, except that an itemRgb of 0,0,0 or 0 paints black and a comma-free one reads as a packed integer, and the key names the colors in domain; unset is linear for score and ordinal for any other field |
| **scale.domain**<br>[`stringArray`](https://jbrowse.org/jb2/docs/config_guides/slot_types#stringarray) = <code>[]</code> | the values that take the range first, in order; a value left out takes a color no listed value or value met before it paints, the first time the track shows it, and keeps it. Under threshold, the ascending cut points, a value on a cut taking the interval above it. Under identity, the CSS colors the key names, in order |
| **scale.range**<br>[`colorArray`](https://jbrowse.org/jb2/docs/config_guides/slot_types#colorarray) = <code>[]</code> | CSS colors the domain takes, in order, a value past the end of the list sampling the scheme where one is set, else continuing into the default palette; under threshold one per interval, one more than the cuts, an interval left out sampling the scheme, else the default ramp; under linear or log the ramp's stops, winning over scheme |
| **scale.unknown**<br>[`maybeColor`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | color for a value missing from domain. Unset: the next palette color where the display deals one, and the levels a preset field names, such as strand's, keep their own colors. A color: that color. "": no color dealt, so a feature paints the no-value grey, a variant cell the alt hue, and a row keeps the color it already has |
| **scale.invalid**<br>[`maybeColor`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | color for a feature with no value under an ordinal scale's field; unset, the display's no-value color |
| **scale.names**<br>[`stringArray`](https://jbrowse.org/jb2/docs/config_guides/slot_types#stringarray) = <code>[]</code> | key name for each domain value, one each in order, or under threshold for each interval from the lowest; a value past the end of the list shows its own |
| **scale.scheme**<br>[`maybeStringEnum`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) (viridis, magma, inferno, cividis, juicebox, fall, reds, blues, redblue, purpleorange, redgreyblue, redyellowblue) | a named ramp: a ramp scale colors along it; a threshold scale that writes cuts gives each interval one color from end to end; an ordinal scale that lists a domain gives each value one color; range's colors, where it lists any, win over it |
| **scale.reverse**<br>[`maybeBoolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | turns the ramp round, so its last color paints the bottom of a ramp's domain or a threshold's lowest interval; unset follows the field's preset, else runs as written |
| **scale.domainMid**<br>[`maybeNumber`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | the value the ramp's middle stop sits at, so a diverging ramp centres somewhere other than the middle of the domain, both sides on one scale: the farther end of the domain reaches its end color and equal distances from the middle take equal colors; unset, the stops are evenly spaced across it |
| **scale.domainMin**<br>[`maybeNumber`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | the bottom of a ramp's domain; unset follows the loaded values |
| **scale.domainMax**<br>[`maybeNumber`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | the top of a ramp's domain; unset follows the loaded values |
| **scale.domainQuantile**<br>[`number`](https://jbrowse.org/jb2/docs/config_guides/slot_types#number) = <code>1</code> | the quantile an open end of a ramp follows over the loaded values: 1 their extremes, 0.99 clips the outermost 1% at each end, each sign measured on its own; a y scale fences at twice that span with fenceQuantile instead<br>_advanced_ |
| **legend.title**<br>[`maybeString`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | key title; unset keeps the display's own heading, "" draws none |
| **legend.descending**<br>[`maybeBoolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#the-maybe-types) | threshold key lists the highest interval first; unset follows the field's preset, else the lowest first |

