matrix viewer and 3.1.0 release

docs/CHANGELOG.md

@@ -14,6 +14,32 @@ The list of changes is generated automatically based on the commit messages them
 
 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.
 
+## [3.1.0](https://github.com/simwrapper/simwrapper/compare/v3.0.4...v3.1.0) (2024-04-24)
+
+
+### Features
+
+* New HDF5 Matrix viewer ([c52ab5b](https://github.com/simwrapper/simwrapper/commit/c52ab5b0acd4b24b99438f1d9a4d459406d0af66))
+* **shapefile:** Add experimental MATSim network support to shapefile map ([05d9d3f](https://github.com/simwrapper/simwrapper/commit/05d9d3f216ef8b382a66d76293960b26e62151ec))
+
+
+### Bug Fixes
+
+* annotations ([10bcd73](https://github.com/simwrapper/simwrapper/commit/10bcd73779a0bbd9d8560d781aa552875b6c6e65))
+* error handling on layout-manager ([c904f8e](https://github.com/simwrapper/simwrapper/commit/c904f8e49e6db1d34524b0d90ed9466c347ad0b7))
+* **gridmap:** Timeslider "off-by-one" error ([#337](https://github.com/simwrapper/simwrapper/issues/337)) ([f67380e](https://github.com/simwrapper/simwrapper/commit/f67380e7b9675204c5e0da9e174cfc2264177d72))
+* Manual breakpoints in gridlayer not being honored ([1d12c48](https://github.com/simwrapper/simwrapper/commit/1d12c482240bad9bdbc250181a8396fcf71d04b9)), closes [#344](https://github.com/simwrapper/simwrapper/issues/344)
+* Manual color breakpoints sometimes not honored ([9e07d4f](https://github.com/simwrapper/simwrapper/commit/9e07d4f2a767efff1836203181ddac9b12fd6f9a))
+* Map scale is wrong on non-retina screens ([fee654e](https://github.com/simwrapper/simwrapper/commit/fee654ed71297a0d2ffa33381da0c90037961390)), closes [#333](https://github.com/simwrapper/simwrapper/issues/333)
+* Restore missing error messages in single-panel mode ([775f6f9](https://github.com/simwrapper/simwrapper/commit/775f6f9c6cb57f3107b46fef31d1449f8c152b62))
+* **sankey:** Allow CSVs with any delimiter ,;\t ([2caf737](https://github.com/simwrapper/simwrapper/commit/2caf73750c76f9fd6446445796160218708247bc))
+* **shapefile:** filter boundaries/shapes when DATA filters match ([b6a582e](https://github.com/simwrapper/simwrapper/commit/b6a582ed28fd16ad0dbfdae3921d340b1fb50ab4))
+* **shapefile:** filter boundaries/shapes when DATA filters match ([a272479](https://github.com/simwrapper/simwrapper/commit/a2724792c50860fd7326e169e6ccd92375cafdbc))
+* **shapefile:** tooltips in YAML not displaying properly ([19f5b5a](https://github.com/simwrapper/simwrapper/commit/19f5b5adbffc6fe3cb946986afac1ff9c88e52a9))
+* **shapefile:** tooltips in YAML not displaying properly ([decf58b](https://github.com/simwrapper/simwrapper/commit/decf58b5484ded160a89a5d5c13288862c3897f3))
+* Show better error messages if YAML fails to parse when loading viz details ([#343](https://github.com/simwrapper/simwrapper/issues/343)) ([b622d17](https://github.com/simwrapper/simwrapper/commit/b622d176f2797e09bbf6a475c9fefd6117ce6564)), closes [#340](https://github.com/simwrapper/simwrapper/issues/340)
+* **transit:** Experimental AVRO large network file support for transit ([4496252](https://github.com/simwrapper/simwrapper/commit/4496252d7cfe6616fef082bdfff51a37039a6f5f))
+
 ### [3.0.4](https://github.com/simwrapper/simwrapper/compare/v3.0.3...v3.0.4) (2024-03-18)
 
 

docs/ref-matrix.md

@@ -0,0 +1,84 @@
+---
+id: matrix
+title: Matrix (HDF5) Viewer
+---
+
+![Heatmap chart example](assets/matrix.jpg)
+_Matrix viewer showing matrix data on a zonal map and as a tabular heatmap_
+
+The matrix viewer can display HDF5 matrix data as a table or tabular heatmap. In addition, data can be mapped onto a zonal GeoJSON boundary file for the common use cases of viewing aggregate zonal data such as skims and trip tables.
+
+## Usage
+
+- From the front page of SimWrapper, you can choose "Matrix Viewer" and then drag/drop your HDF5 files directly into the viewer
+
+The matrix viewer can also be preconfigured using YAML, and embedded in dashboards or displayed full-screen as such. See Dashboard documentation for general tips on creating dashboard configurations.
+
+- Use panel `type: matrix` in the dashboard configuration.
+- Each matrix panel is defined inside a **row** in a `dashboard-*.yaml` file.
+- Standard title, description, and width fields define the frame.
+- Alternatively a file of the pattern `viz-matrix-[more].yaml` can define a standalone matrix viewer
+
+---
+
+### Sample dashboard.yaml config snippet with a heatmap
+
+```yaml
+layout:
+  row1:
+    - type: matrix
+      title: "HIGHWAY skims 2020 AM comparison"
+      dataset: "HWYAMSKIM.project.h5"
+      basedata: "HWYAMSKIM.baseyear.h5"
+      shapes:
+        file: './geojson/zones1454.geojson'
+        id: 'TAZ'       # The geojson property field containing the TAZ column number
+      colors:
+        ramp: 'RdBu'    # Viridis, Rainbow, etc
+        inverted: false
+        scale: 'SymLog' # Linear, Log, SymLog, Sqrt.
+                        # SymLog is like Log, but works for scales that cross zero (diffs!)
+```
+
+---
+
+**dataset:** The HDF5-format file to be viewed
+
+**basedata:** An optional base from which to compare.  Calculations are always `dataset - base`.
+
+**shapes:** The `file` filename of the GeoJSON data set (optionally .gzipped), and the `id` name of the property containing the TAZ/Column number.
+
+_This viewer is a work in progress, more docs to come!_
+
+## Mapping matrix sizes to a specified GeoJSON
+
+Most users of SimWrapper have just a few zonal boundary systems and all of their matrix data corresponds to one of these boundaries.
+
+If you have your own install of SimWrapper, you can specific this relationship directly, so that you only need to tell it once that matrices with 2518 columns always get viewed in the 2518-zone system.  Unfortunately I can't include all of your zone systems in the general build of SimWrapper so this only works if you've got SimWrapper running locally.
+
+The file `/zones/zones.yaml` defines this as follows:
+
+**/zones/zones.yaml** - example
+```yaml
+# Zone system configurations for matrix plugin -- San Francisco example
+#
+# Only GeoJSON files are supported. Shapefiles are too slow and often have coordinate problems.
+# Use GeoJSON and pre-convert all coordinates to long/lat (WGS84 or EPSG:4326)
+#
+# URLs can be
+# - `/zones/filename.geojson` if you place the file in the /zones folder of the SimWrapper build
+# - full HTTP urls if the remote server allows external access
+
+# 'sizes' helps SimWrapper guess which zone systems are appropriate for which matrix sizes.
+
+SF-2454:
+  url: /zones/dist15.geojson.gz
+  lookup: TAZ
+  sizes: 981,2454,2475,3681,3717
+
+MTC-1454:
+  url: /zones/mtc1454.geojson.gz
+  lookup: TAZ1454
+  sizes: 1454,1475
+
+```

website/sidebars.json

@@ -22,6 +22,7 @@
       "flow-map",
       "grid-layer",
       "heatmap-charts",
+      "matrix",
       "pie-charts",
       "plotly",
       "sankey",