What's Changed
This is a major update for the GerryTools package. Like the recent updates to GerryChain, this release comes with completely redone documentation to try and make the package more accessible to users.
In addition, the main tutorial notebooks that we had within the main repo have been updated to make sure that they work, and much of their content has been migrated to the main docs so that users have an easier time accessing them.
New Features
This update also comes with two new modules: `ben` and `mgrp`
The `ben` (binary-ensemble) module
This module is designed to help improve one of the biggest problems that we have in redistricting analysis: the storage of ensembles of plans. Here we use a Docker container to help give users relatively painless access to the [binary-ensemble](https://github.com/peterrrock2/binary-ensemble) tools without requiring the user to install the Cargo package manager or to know how to use the various CLI tools.
The `mgrp` (Metric Geometry Replication) module
This module is designed to help give users access to several of the different ensemble tools currently in use within the redistricting analysis community. Of note, we have made it possible to access three different methods for generating ensembles
of plans:
- Recom ([FRCW](https://github.com/mggg/frcw.rs)): This is our Rust implementation of the `gerrychain` which takes advantage of the ease of parallelization within Rust as well as the general resource management improvements that come with a compiled language to increase the speed of much of our basic functionality of our `gerrychain` library. Of note, this implementation now makes it possible to run Recom chains on the census-block level in a reasonable amount of time (the python code would often take several months to run even a 1M step chain on this level)
- Forest Recom ([MSMS](https://arxiv.org/pdf/2008.08054.pdf)): This method was put forward by a team at Duke and was coded [originally in Julia](https://git.math.duke.edu/gitlab/quantifyinggerrymandering/multiscalemapsampler-public). We have added some convenience classes that allow for this to be run using a python wrapper / Docker combination so that users do not need to go through the process of setting up, installing, and learning the Julia syntax if they do not already know it.
- Sequential Monte Carlo ([SMC](https://alarm-redist.org/redist/)) : This method was put forward by a team at Harvard and was originally coded in [R and C++](https://github.com/alarm-redist/redist). Again, we provide some convenience wrappers for the main `redist_map()` and `redist_smc()` methods used within their algorithm so that users do not need to go through the whole process of installing and setting up R Studio for their machine and learning R syntax if they do not already know it.
In addition, we have introduced a new standard format for the reporting of ensembles of plans. This is a JSONL format where each line is of the form:
{"assignment": <assignment-vector>, "sample": <sample-number-indexed-from-1>}
This format can be used for any of the above methods and has been chosen as the standard output for all three to help ensure consistency of reporting. In addition, this format is natively expected by the `ben` compression tool.
**Full Changelog**: https://github.com/mggg/gerrytools/compare/1.0.2...v1.2.0