scales.md 4.26 KB
Newer Older
Tejesh's avatar
Tejesh committed
1
**g1.scale**
Tejesh's avatar
Tejesh committed
2
3
4

Scales is an abstraction over d3-scales and d3-scale-chromatic libraries using configurations. 

Tejesh's avatar
Tejesh committed
5
6
Background: Scales can be thought of functions that maps input (`domain`) of numbers/categoricals to output(`range`) of numbers/categoricals. The output range can be colors, height/width pixel values of a chart. 

Tejesh's avatar
Tejesh committed
7
8
9
10
11
12
13
14
15
```html
<script src="https://cdn.jsdelivr.net/combine/npm/d3-scale,npm/d3-scale-chromatic,npm/g1"></script>
```

External dependpencies: [d3-scale](https://github.com/d3/d3-scale/) and [d3-scale-chromatic](https://github.com/d3/d3-scale-chromatic)

[Read the documentation](https://learn.gramener.com/guide/g1/scales) for usage.
([source](docs/scales.md))

Tejesh's avatar
Tejesh committed
16
17
Scales are dictionaries with the following keys:

Tejesh's avatar
Tejesh committed
18
19
20
- `scale:` d3 scale to use. Defaults to `'linear'`.
- `domain`: a list that contains the scale's domain or `{metric: 'col_name'}`
- `range`:  a list that contains the scale's range or `{scheme: 'schemeName', count: k}`. `k` can be between 3-11 (Refer `k` value for schemes in https://github.com/d3/d3-scale-chromatic).
Tejesh's avatar
Tejesh committed
21
22


Tejesh's avatar
Tejesh committed
23
`scale` can take any of the values from below scale types.
Tejesh's avatar
Tejesh committed
24
25
26
27

**Scale Types**:

- **Quantitative Scales**
Tejesh's avatar
Tejesh committed
28
29
30
31
32
  - `Linear`
  - `Log`
  - `Pow`
  - `Sqrt`
  - `Sequential`
Tejesh's avatar
Tejesh committed
33
- **Discrete Scales**
Tejesh's avatar
Tejesh committed
34
35
36
  - `Ordinal`
  - `Band`
  - `Point`
Tejesh's avatar
Tejesh committed
37
- **Discretizing Scales**
Tejesh's avatar
Tejesh committed
38
39
40
  - `Quantile` 
  - `Quantize` 
  - `Threshold` 
41
42


Tejesh's avatar
Tejesh committed
43
44
45
46
Linear scale mapping numericals to colors (Red white Green)
```js
var numericals_to_color = g1.scale(data, {
    scale: 'linear', // default
Tejesh's avatar
Tejesh committed
47
    domain: [0, 50, 100],  // can be {metric: 'age'} to auto-calculate domain
Tejesh's avatar
Tejesh committed
48
49
50
51
52
53
54
    range: ['red', 'white', 'green']
})

numericals_to_color('0') // "#efedf5"
numericals_to_color('50') // "#bcbddc"
numericals_to_color('100') // "#756bb1"
```
55

Tejesh's avatar
Tejesh committed
56
57
To map qualitative data to color scheme

58
```js
Tejesh's avatar
Tejesh committed
59
var categorical_to_colorscheme = g1.scale(data, {
Tejesh's avatar
Tejesh committed
60
    domain: ['hyd', 'chennai', 'bnglr', 'delhi'], // can be {metric: 'city'} to auto-calculate domain
61
    scale: 'Ordinal',
Tejesh's avatar
Tejesh committed
62
    range: {scheme: 'purples', count: 3}
63
64
})

Tejesh's avatar
Tejesh committed
65
66
67
68
categorical_to_colorscheme('hyd') // "#756bb1"
categorical_to_colorscheme('chennai') // "#bcbddc"
categorical_to_colorscheme('bnglr') // "#efedf5"
categorical_to_colorscheme('delhi') // "#756bb1" (rotates to first color because count is 3)
69
70
71
72
73
```

To map qualitative data to *reverse* color scheme

```js
Tejesh's avatar
Tejesh committed
74
var categorical_to_colorscheme = g1.scale(data, {
Tejesh's avatar
docs    
Tejesh committed
75
    domain: [], // if left empty, first categorical value will be mapped to first color from range
76
    scale: 'Ordinal',
Tejesh's avatar
Tejesh committed
77
78
79
80
81
    range: {
        scheme: 'schemePurples',
        count: 3,
        reverse: true
    }
82
83
84
85
86
87
88
89
90
})

categorical_to_colorscheme('apple') // "#756bb1"
categorical_to_colorscheme('orange') // "#bcbddc"
categorical_to_colorscheme('grapes') // "#efedf5"
```



Tejesh's avatar
Tejesh committed
91
To map continuous data (numericals) to color schemes:
92
93
94

**Notes**:
- Quantile scale divides *total data points* to bins, with each bin containing equal number of data points.
Tejesh's avatar
Tejesh committed
95
- Quantile scale takes domain as entire dataset. Metric is mandatory and should be continuous data.
96
97
98

```js
var quantile_scale = g1.scale(data, {
Tejesh's avatar
Tejesh committed
99
    domain: {metric: 'age'},
100
    scale: 'Quantile',
Tejesh's avatar
Tejesh committed
101
    range: {scheme: 'BrBG', count: 3}
102
103
104
105
106
})
```


**Notes**:
Tejesh's avatar
Tejesh committed
107
- Quantize scale divides *the domain* into bins of equi value (not count).
108
109
110

```js

Tejesh's avatar
Tejesh committed
111
var quantize_scale = g1.scale([], {
112
113
    domain: [0, 100],
    scale: 'Quantize',
Tejesh's avatar
Tejesh committed
114
115
116
117
118
    range: {
        scheme: 'Purples',
        count: 3,
        reverse: true
    }
119
120
})

Tejesh's avatar
Tejesh committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
quantize_scale(15) // "#efedf5" [0 - 33.3]
quantize_scale(40) // "#bcbddc" [33.3 - 66.6]
quantize_scale(70) // "#756bb1" [66.6 - 100]


var quantize_scale = g1.scale(data, {
    domain: {metric: 'age'},
    scale: 'Quantize',
    range: {
        scheme: 'schemePurples',
        count: 3
    }
})
quantize_scale(15) // "#756bb1"
135
quantize_scale(40) // "#bcbddc"
Tejesh's avatar
Tejesh committed
136
137
quantize_scale(70) // "#efedf5"

138
139
140
141
142
143
```

**Notes**:
- Threshold scales should have `n+1` values in range, when `n` is the number of values in domain.

```js
Tejesh's avatar
Tejesh committed
144
var quantize_scale = g1.scale([], {
145
146
147
148
149
150
151
152
    scale: 'Threshold',
    domain: [35],
    range: ['red', 'green'] // <35 maps to Red, >35 maps to Green
})
quantize_scale(25) // 'red'
quantize_scale(75) // 'green'


Tejesh's avatar
Tejesh committed
153
var quantize_scale = g1.scale([], {
154
155
156
157
158
159
160
161
    scale: 'Threshold',
    domain: [35],
    range: ['red', 'green'], // <35 maps to Red, >35 maps to Green
    reverse: true
})
quantize_scale(25) // 'green'
quantize_scale(75) // 'red'
```