Skip to content

Commit 56ca54b

Browse files
tomstephentomstephen
committed
.
1 parent 4e92698 commit 56ca54b

2 files changed

Lines changed: 309 additions & 2 deletions

File tree

‎docs/ref-aequilibrae-map.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
id: aequilibrae-map
3+
title: AequilibraE Map
4+
---
5+
6+
![AequilibraE Map Example](assets/aequlibrae-map.png)
7+
8+
# Overview
9+
10+
The AequilibraE Map plugin displays geometries (points, lines, polygons) stored in an AequilibraE project SQLite database and allows styling using model and result attributes. Panels using this plugin are added inside dashboard YAML files; use `type: aequilibrae` for the panel.
11+
12+
# Usage
13+
14+
- Add the panel to a dashboard row in a `dashboard-*.yaml` file using `type: aequilibrae`.
15+
- The panel accepts either a direct `config` object from code or a path to a YAML visualization config via `yamlConfig` (parsed by the plugin).
16+
- Use `extraDatabases` when you need to join attributes from other SQLite files (e.g. a results DB).
17+
18+
# Properties
19+
20+
This section describes top-level panel properties and layer configuration. Fields are split into *Required* and *Optional* where appropriate.
21+
22+
## Dashboard panel properties
23+
24+
| Property | Usage |
25+
| --- | --- |
26+
| `type` | MUST be set to `aequilibrae` in `dashboard-*.yaml` files |
27+
| `title` | Panel title shown above the map |
28+
| `height` | Relative height of the panel (default depends on layout) |
29+
| `width` | Relative width of the panel |
30+
31+
## Required top-level properties
32+
33+
| Property | Type | Description |
34+
| --- | --- | --- |
35+
| `database` | string | Path to the main AequilibraE SQLite database (e.g. `project_database.sqlite`). In YAML visualizations this may be provided as `database` or `file` (both accepted). |
36+
37+
## Optional top-level properties
38+
39+
| Property | Type | Description |
40+
| --- | --- | --- |
41+
| `extraDatabases` | map<string,string> | Named map of additional SQLite DBs used for joins. Example: `results: results_database.sqlite` |
42+
| `center` | array or string | Map center as `[lon, lat]` or a string interpreted by the frontend. If omitted the viewer will compute a suitable center. |
43+
| `zoom` | number | Initial zoom level |
44+
| `projection` | string | Coordinate reference system, e.g. `"EPSG:32719"` |
45+
| `bearing` | number | Map rotation |
46+
| `pitch` | number | Map pitch |
47+
| `defaults` | object | Default style values applied to all layers (see below) |
48+
| `legend` | array | Explicit legend items (array of `{ label, color, size, shape, subtitle }`) |
49+
| `minimalProperties` | boolean | If true request a smaller set of feature properties to reduce payload |
50+
| `geometryLimit` | number | Limit number of geometries loaded (useful for very large DBs) |
51+
52+
---
53+
54+
## Layer definitions (`layers`)
55+
56+
Layers are defined under the `layers:` map. Each key is a layer id and contains configuration for a set of features.
57+
58+
Supported layer fields:
59+
60+
- `table` (string) — table name in the SQLite DB containing geometry and attributes.
61+
- `geometry` (string) — one of `point`, `line`, or `polygon`.
62+
- `sqlFilter` (string, optional) — SQL WHERE clause to filter rows, e.g. `"is_centroid=1"`.
63+
- `join` (object, optional) — join config to attach attributes from another table (see Joins).
64+
- `style` (object) — visual style settings (see Layer styles below).
65+
66+
Example minimal layer:
67+
68+
```yaml
69+
layers:
70+
links:
71+
table: links
72+
geometry: line
73+
style:
74+
lineColor: "#74BBCD"
75+
lineWidth: 0.5
76+
```
77+
78+
## Joins & `extraDatabases`
79+
80+
Provide additional databases at the top level using `extraDatabases`:
81+
82+
```yaml
83+
extraDatabases:
84+
results: results_database.sqlite
85+
```
86+
87+
Then in the geometry layer, reference the named database in a layer `join` to attach attributes from another table:
88+
89+
```yaml
90+
join:
91+
database: results # matches a key specified in extraDatabases
92+
table: base_case # table of the database to join
93+
leftKey: link_id # geometry database ("project_database.sqlite", typically)
94+
rightKey: link_id # joined database table
95+
type: left # optional: 'left' (default) or 'inner'
96+
```
97+
98+
After the join, columns from the joined table are available for styling (e.g. quantitative palettes using a result column).
99+
100+
## Layer styles
101+
102+
Style keys supported: `fillColor`, `lineColor`, `lineWidth`, `pointRadius`, `fillHeight`. (Note: client-side include/exclude filters were removed — use `sqlFilter` on the layer instead.)
103+
104+
### Colors (`fillColor`, `lineColor`)
105+
106+
Colors may be specified in three ways:
107+
108+
1. Static hex string: `"#FF6600"`
109+
2. Categorical mapping:
110+
111+
```yaml
112+
fillColor:
113+
column: is_centroid
114+
colors:
115+
1: "#FF6600"
116+
0: "#cacaca"
117+
```
118+
119+
3. Quantitative mapping (palette):
120+
121+
```yaml
122+
lineColor:
123+
column: Delay_factor_Max
124+
palette: Temps
125+
dataRange: [1,3]
126+
```
127+
128+
Fields supported for quantitative mapping: `column`, `palette`, `numColors`, `range`, `dataRange`.
129+
130+
Palettes are provided by [CARTOColor](https://carto.com/carto-colors/).
131+
132+
### Geometry sizes (`lineWidth`, `pointRadius`)
133+
134+
Geometry sizes can be defined in a few ways,
135+
136+
- a static number: `2`
137+
- a categorical mapping:
138+
139+
```yaml
140+
lineWidth:
141+
column: link_type
142+
widths:
143+
road: 20
144+
freeway: 80
145+
centroid_connector: 20
146+
```
147+
- or a continuous mapping:
148+
```yaml
149+
pointRadius:
150+
column: some_metric
151+
dataRange: [0, 100] # optional: clamp the input data range
152+
widthRange: [1, 50] # optional: set the output data range to map to
153+
```
154+
155+
### Filtering features
156+
157+
Use SQL-level filtering — `sqlFilter` on the layer — to restrict rows returned by the database. This prevents unwanted geometries (for example centroids) from being loaded into memory and rendered, and is the supported method for filtering.
158+
159+
Example: to exclude centroid nodes:
160+
161+
```yaml
162+
layers:
163+
nodes:
164+
table: nodes
165+
geometry: point
166+
sqlFilter: "is_centroid = 0" # only non-centroid nodes
167+
```
168+
169+
## Legend
170+
171+
- Legends are auto-generated from categorical/color/width mappings where possible.
172+
- You can provide an explicit `legend` array at the panel level to control labels/colors/sizes manually. Each legend item may include `label`, `color`, `size`, `shape`, `subtitle`.
173+
174+
Example explicit legend:
175+
176+
```yaml
177+
legend:
178+
- subtitle: "Link Types"
179+
- label: "Freeway"
180+
color: "#C3A34B"
181+
size: 4
182+
shape: line
183+
```
184+
185+
# Examples
186+
187+
Examples below are taken from the Chicago sample dashboards in this repository.
188+
189+
## Simple entire network
190+
191+
```yaml
192+
- type: aequilibrae
193+
title: "Entire Network"
194+
database: project_database.sqlite
195+
center: [-87.6298, 41.8781]
196+
zoom: 10
197+
defaults:
198+
fillColor: "#6f6f6f"
199+
lineColor: "#FF6600"
200+
lineWidth: 2
201+
pointRadius: 4
202+
layers:
203+
nodes:
204+
table: nodes
205+
geometry: point
206+
sqlFilter: "is_centroid = 0" # show only non-centroid nodes
207+
style:
208+
fillColor:
209+
column: is_centroid
210+
colors:
211+
1: "#FF6600"
212+
0: "#cacaca"
213+
links:
214+
table: links
215+
geometry: line
216+
style:
217+
lineColor: "#74BBCD"
218+
lineWidth: 0.5
219+
```
220+
221+
## Join with results DB and palette mapping
222+
223+
```yaml
224+
- type: aequilibrae
225+
title: "Delay Factor"
226+
database: project_database.sqlite
227+
extraDatabases:
228+
results: results_database.sqlite
229+
defaults:
230+
lineWidth: 4
231+
layers:
232+
links:
233+
table: links
234+
geometry: line
235+
join:
236+
database: results
237+
table: base_case
238+
leftKey: link_id
239+
rightKey: link_id
240+
type: left
241+
style:
242+
lineColor:
243+
column: Delay_factor_Max
244+
palette: Temps
245+
dataRange: [1,3]
246+
lineWidth:
247+
column: link_type
248+
widths:
249+
3: 20
250+
2: 40
251+
1: 20
252+
```
253+
254+
# Tips & Notes
255+
256+
- Use `sqlFilter` to reduce the number of features rendered and improve performance.
257+
- For very large datasets, set `geometryLimit` or `minimalProperties` to reduce memory and payload size.

‎docs/ref-tiles.md‎

Lines changed: 52 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,19 +16,69 @@ The Tiles plug in displays key data for a good overview.
1616
The tiles plug-in can only be included as panels in **Dashboards**. See Dashboard documentation for general tips on creating dashboard configurations.
1717

1818
- Each table viewer panel is defined inside a **row** in a `dashboard-*.yaml` file.
19-
- Use panel `type: csv` in the dashboard configuration.
19+
- Use panel `type: tile` in the dashboard configuration.
2020
- Standard title, description, and width fields define the frame.
2121

22+
Data for the tiles can be provided in a number of ways,
23+
24+
- As a `.csv` file
25+
- Hard-coded `title` and `value` pairs
26+
- As a sqlite table
27+
- As individual `title` and sqlite-query pairs
28+
29+
Additionally, the color palette for the tiles can be set via the `colors` parameter. Options are `pastel` (default), `vivid`, and `monochrome`.
30+
2231
---
2332

2433
### Sample dashboard.yaml config snippet
2534

35+
For data source from csv, a sqlite table, hardcoded and a series of sqlite queries,
36+
37+
```yaml
38+
layout:
39+
csv_row:
40+
- type: 'tile'
41+
title: Tiles Plug-in Example
42+
dataset: 'data.csv'
43+
sqlite_table_row:
44+
- type: 'tile'
45+
title: "My Tile Panel"
46+
dataset:
47+
database: project_database.sqlite
48+
query: "SELECT metric, value FROM metadata_table;"
49+
titleCol: metric (n.b., optional, these default to 'metric' and 'value')
50+
valueCol: value
51+
hardcoded_row:
52+
- type: 'tile'
53+
title: "My Tile Panel"
54+
dataset:
55+
- key: "Total trips"
56+
value: 54321
57+
- key: "Average speed"
58+
value: 23.4
59+
sqlite_queries_row:
60+
- type: 'tile'
61+
title: "My Tile Panel"
62+
dataset:
63+
- key: "Total trips"
64+
value:
65+
database: project_database.sqlite
66+
query: "SELECT COUNT(*) FROM trips;"
67+
- key: "Average speed"
68+
value:
69+
database: project_database.sqlite
70+
query: "SELECT AVG(speed) FROM trips;"
71+
```
72+
73+
To change the color palette.
74+
2675
```yaml
2776
layout:
28-
row1:
77+
csv_row:
2978
- type: 'tile'
3079
title: Tiles Plug-in Example
3180
dataset: 'data.csv'
81+
color: 'monochrome'
3282
```
3383
3484
---

0 commit comments

Comments
 (0)