You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/CHANGELOG.md
+30Lines changed: 30 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,6 +14,36 @@ The list of changes is generated automatically based on the commit messages them
14
14
15
15
All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
* Project site left-side navigation and dashboard layout improvements ([14f528d](https://github.com/simwrapper/simwrapper/commit/14f528d19f5f2752fbf0c4aee6b987748802e146))
37
+
* Subtabs YAML update for dashboard sections with subtabs ([1dda4b3](https://github.com/simwrapper/simwrapper/commit/1dda4b3a676d1917818bfb8230b077b1598a7acb))
38
+
* Top navigation bar for project pages via simwrapper-config.yaml ([dd51785](https://github.com/simwrapper/simwrapper/commit/dd517859dbf076ad131de46561acb3cff3a2cfec))
39
+
* Updated UI, cleaner dashboard looks, new project site features ([6e71517](https://github.com/simwrapper/simwrapper/commit/6e71517b4f13d8fbfa93edb5a8d26a4f9654a479))
***text:** Text/Markdown panels could be the wrong size ([ce44e1b](https://github.com/simwrapper/simwrapper/commit/ce44e1be8bbf8702f5b16e2c47b11b2d2340ca97))
|`width`| Relative width. The widths of all panels on a single row are summed, and the layout of each panel is then relative to that total width. (default: 1) |
42
42
@@ -52,41 +52,57 @@ Properties are written in either a standalone `viz-map*.yaml` file, or in a dash
52
52
|`pitch`| Map pitch (default: 0) |
53
53
|`bearing`| Map bearing/direction (default:0) |
54
54
55
-
### **shapes:** the boundaries/areas to be drawn
56
-
57
-
There are **two separate data types** required for an area map: the boundaries/shapes, and one the dataset (unless the shapefile self-contains all of the required data).
55
+
---
58
56
59
-
Both files must contain an matching identification column in order to **join the two datasets**together. In other words, the boundary IDs must be present (somewhere) in both datafiles. The names of the columns do not have to be identical, but it helps legibility. See below.
57
+
### **"shapes:"**the features (links, areas, etc) to be drawn
60
58
61
59
```yaml
62
60
shapes:
63
61
file: my-taz-shapefile.shp
64
62
join: id
63
+
keep: AB,LENGTH,TAZ,SQMILES
65
64
```
65
+
There are **two separate input types** required for a shapefile/geojson map: (1) the boundaries or shapes themselves, which can be geojson or shapefile format; and (2) additional datasets in CSV/DBF tabular format which contain columns of data that can be attached to the features. These datasets are optional, if the shapefile self-contains all of the required data.
66
+
67
+
All inputs must contain an _identification column_ in order to **join the datasets** together. In other words, the feature IDs must be present in both datafiles. The names of the columns do not have to be identical, but it helps legibility. See below.
68
+
69
+
70
+
**shapes** section can have the following properties:
66
71
67
-
Contains two subentries:
72
+
|Property | Usage|
73
+
| --- | --- |
74
+
|`file` | String. The filepath of the feature dataset. May include wildcards \* and ?. File can be in _geojson_ format, or a _shapefile_. File type is determined by the filename extension, which must end in either `.geojson` or `.shp` When loading shapefiles, an identically-named `.dbf` and `.prj` file will also be read from the same folder. Be sure to supply a .prj file containing a valid EPSG code if your data is not in lat/long format!|
75
+
|`join` | String. The name of the property containing unique shape IDs, or set to `id` if it is in the id field of the geojson itself.|
76
+
|`keep` | String (optional). Comma-separated list of fields to KEEP in memory from the shapefile properties. Some files are very large with many properties that you are not interested in. Use the `keep` property to list the only ones you actually need, in order to save memory and improve performance. If `keep` is not specified then all properties are retained.|
68
77
69
-
- **file:** String. The filepath containing the data. May include wildcards \* and ?. File can be in _geojson_ format, or a _shapefile_. File type is determined by suffix, so must end in either `.geojson` or `.shp` When loading shapefiles, an identically-named .dbf and .prj file will also be read from the same folder. Be sure to supply a .prj file containing a valid EPSG code if your data is not in lat/long format.
70
-
- **join:** String. The name of the data column containing shape IDs, or 'id' if it is in the id field of geojson.
71
78
72
-
### **datasets:** the dataset to be joined to the shapefile
79
+
### **datasets:** datasets to be joined to the features
73
80
74
81
```yaml
75
82
datasets:
83
+
population: "../pop/2025/population.csv"
76
84
transit-trips:
77
85
file: .summaries/transit-outputs.csv
78
-
join: TAZ
86
+
drop: bike,ped,MTCTAZ
87
+
keep: TAZ,TIME,pm_vol,orig,dest
79
88
```
80
89
81
-
Contains an object naming the dataset and providing its filename and join column:
90
+
`datasets:`defines any additional tabular datasets that are linked to the feature dataset from above. Every dataset is defined by a short keyword name followed by a colon, and then the needed properties are provided. In the example above, `population` and `transit-trips` keywords are defined. Use the keyword to refer to the dataset when defining colors and widths (see below).
91
+
92
+
- In simple cases a filename can be given directly, as in the `population` example above.
93
+
- Other properties can be defined to keep/drop certain columns, as in `transit-trips`.
94
+
95
+
**name of dataset:** Give the dataset a simple name, which will be used in the display settings below. e.g. `tazdata:`
82
96
83
-
- **name of dataset:** Give the dataset a simple name, which will be used in the display settings below. e.g. `tazdata`
84
-
- **file:** String. The filepath containing the data. May include wildcards \* and ?. File can be in _CSV or DBF_ format. Any filename not ending in `.dbf` will be parsed as a CSV file, using either commas, tabs, or spaces as delimiters.
85
-
- **join:** String. The name of the data column containing the shape IDs for joining.
97
+
Each subsection can have the following properties:
86
98
87
-
### **display:** define the color and value details
99
+
|Property | Usage|
100
+
| --- | --- |
101
+
|`file`| String. The filepath containing the data. May include wildcards \* and ?. File can be in _CSV or DBF_ format. Any filename not ending in `.dbf` will be parsed as a CSV file, using either commas, tabs, or spaces as delimiters.|
102
+
|`drop`| String (optional). Comma-separated list of column names to be dropped from memory; these columns will be unavailable to this visualization. This can save memory and improve performance.|
103
+
|`keep`| String (optional). Comma-separated list of column names to be kept in memory for this visualization. This can save memory and improve performance.|
88
104
89
-
For area maps, the `fill` section defines the color fill, and is (currently) the only section that is required. At a later date we may include borders, etc.
105
+
### **display:** define the symbology details: colors, widths, etc
90
106
91
107
```yaml
92
108
display:
@@ -101,38 +117,49 @@ display:
101
117
steps: 5
102
118
```
103
119
104
-
**dataset:** Name of the dataset from above which includes the data.
120
+
The `display` section is where you define the details of your map symbology:the line and fill colors, line widths, circle radii, difference calculations, and so on.
105
121
106
-
**filters:** (optional) List of any columns which can be used as category filters by the user interactively. Note that _active filters_ will be shown in the URL bar, so curated maps can be shared via URL.
122
+
Different map types allow different properties. This is an attempt at summarizing the capabilities; not all combinations work for every map type. There are many, many configuration options listed here, and they mimic the user interface options available in the configuration panel.
107
123
108
-
**columnName:** The column name (or names) containing values to be plotted. If multiple rows have a matching shape ID, all values will be summed together. (Other stats to be added)
124
+
**Instead of trying to write this YAML from scratch,** try creating a map interactively on the SimWrapper site, and then choosing `EXPORT` from the configuration panel. SimWrapper will produce a YAML file with most/all of your settings and save it in your browser's Downloads folder. You can move this to your data folder and modify as necessary.
109
125
110
-
**colorRamp:** Describe the colors themselves:
126
+
|Property | Usage|
127
+
| --- | --- |
128
+
|`dataset`| Name of the dataset from above which includes the data.|
129
+
|`columnName`| The column name (or names) containing values to be plotted. If multiple rows have a matching shape ID, all values will be summed together.|
130
+
|`colorRamp`| Describe the colors to be used:<br/>**ramp:** Name of the color ramp to use.<br/>Sequential: `Viridis``Plasma``Blues``Greens``Purples``Oranges`<br/>Diverging: `PRGn` `RdBu`<br/>Categorical: `Tableau10` `Paired`. Note categoricals only have ten or twelve categories.|
131
+
| | **reversed:** true/false|
132
+
| | **steps:** Number of steps in the ramp.|
133
+
| | **exponentColors:** Optional true/false. If true, values will be scaled exponentially before being drawn. This is often useful if values are concentrated in small areas, and much higher in value than in typical areas.|
134
+
| | **diff:** Example `col1 - col2` will activate diff mode|
135
+
| | **breakpoints:** Work in progress, comma-separated list of manual breakpoints for data values.|
- Categorical: `Tableau10``Paired`. Note categoricals only have ten or twelve categories.
116
-
- **reversed:** true/false
117
-
- **steps:** Number of steps in the ramp.
118
-
- **exponentColors:** Optional true/false. If true, values will be scaled exponentially before being drawn. This is often useful if values are concentrated in small areas, and much higher in value than in typical areas.
119
-
- **diff:** Example `col1 - col2` will activate diff mode
120
-
- _(todo: more examples needed )_
137
+
<!-- |`filters`| (optional) List of any columns which can be used as category filters by the user interactively. Note that _active filters_ will be shown in the URL bar, so curated maps can be shared via URL.|
138
+
-->
121
139
122
-
### filters
123
140
124
-
In the `filter` section, you can filter dataset with multiple expressions on numerical columns in any dataset. Keys are of the format `dataset.column: "filter"` and filter can be `==, !=, <, <=, >, >=`
141
+
### filters
125
142
126
143
```yaml
127
144
filters:
128
145
dataset1.trips: "> 0"
129
146
shapes.TAZ: "!=0"
130
147
```
131
148
132
-
_TODO: more filter examples needed_
149
+
In the `filter` section, you can filter dataset with multiple expressions on numerical columns in any dataset. Keys are of the format `dataset.column: "filter"` and filter can be `==, !=, <, <=, >, >=`
150
+
151
+
_More filter examples needed!_
133
152
134
153
### Tooltip
135
154
155
+
```yaml
156
+
tooltip:
157
+
- AM:TOT_VOL
158
+
- AM:TNC
159
+
- freeflow.shp:FACILITY_TYPE
160
+
- freeflow.shp:SPEED
161
+
```
162
+
136
163
By default, the tooltip shows all columns in the shapefile, as well as any columns that are actively being displayed as either a color or a width.
137
164
138
165
You can customize the tooltip to just show what you are interested as follows:
@@ -141,15 +168,6 @@ You can customize the tooltip to just show what you are interested as follows:
141
168
- Each entry is of format `datasetname:columnname`, so for example `AM_FLOWS:VEHICLE_VOL` will display the AM_FLOWS dataset and VEHICLE_VOL column.
142
169
- Use the shapefile/network filename for its columnar data, or the dataset "key" for joined datasets.
0 commit comments